datahub/docs/sku-mapping-business-guide.md

# SKU Mapping 业务场景说明

> 创建日期：2026-04-16
> 适用模块：`skus_mapping`、`skus_origin`

---

## 一、业务模型概述

SKU Mapping 是 Datahub 系统中连接客户内部 SKU 体系与电商平台 SKU 体系的桥梁。由于不同平台对 SKU 编码有格式限制（如不能以 `0` 开头、不能包含特殊字符等），系统需要维护一套映射关系，将客户的原始 SKU（`origin_sku`）转换为符合各平台规范的平台 SKU（`platform_outer_sku`）。

**核心实体**：

| 实体 | 表 | 说明 |
|------|------|------|
| Origin SKU | `skus_origin` | 客户内部 SKU 编码，公司级唯一 |
| SKU Mapping | `skus_mapping` | origin_sku → platform_outer_sku 的映射记录 |
| Platform | `platforms` | 电商平台（Shopee、Tmall 等）|
| Store | `stores` | 平台下的具体店铺 |

**映射粒度**：店铺级别 — 同一平台下不同店铺可使用不同的 `platform_outer_sku`。

---

## 二、核心业务场景

### 场景 1：普通映射（1:1）

最基础的场景。一个 `origin_sku` 在一个平台下映射到一个 `platform_outer_sku`。

```
origin_sku: "0032"  →  platform_outer_sku: "C03_0032"  (Shopee)
```

**数据示例**：

| origin_sku_id | platform_id | platform_outer_sku | bundled |
|---------------|-------------|-------------------|---------|
| 1 | 1 (Shopee) | C03_0032 | false |

### 场景 2：多平台映射（1:N）

同一个 `origin_sku` 在多个平台分别生成不同的 `platform_outer_sku`。

```
origin_sku: "0032"
  → Shopee:  "C03_0032"
  → Tmall:   "TM_0032"
  → Lazada:  "LZ_0032"
```

**数据示例**：

| origin_sku_id | platform_id | platform_outer_sku | bundled |
|---------------|-------------|-------------------|---------|
| 1 | 1 (Shopee) | C03_0032 | false |
| 1 | 2 (Tmall) | TM_0032 | false |
| 1 | 3 (Lazada) | LZ_0032 | false |

### 场景 3：同平台多规则映射

同一个 `origin_sku` 在同一个平台下有多个不同的 `platform_outer_sku`（例如不同店铺使用不同编码）。

```
origin_sku: "0032"
  → Shopee 店铺A: "C03_0032"
  → Shopee 店铺B: "SP_CUSTOM_0032"
```

**数据示例**：

| origin_sku_id | platform_id | store_id | platform_outer_sku | bundled |
|---------------|-------------|----------|-------------------|---------|
| 1 | 1 (Shopee) | 101 | C03_0032 | false |
| 1 | 1 (Shopee) | 102 | SP_CUSTOM_0032 | false |

> 唯一索引 `(origin_sku_id, platform_id, platform_outer_sku)` 允许此场景，但防止同一组合产生重复记录。

### 场景 4：组合商品（Bundle）

一个 `platform_outer_sku` 实际对应多个 `origin_sku`，标记 `bundled = true`。典型场景：平台上的"套装"由多个单品组成。

```
platform_outer_sku: "BUNDLE_SUMMER"
  → origin_sku: "SHIRT_001"（上衣）
  → origin_sku: "PANTS_002"（裤子）
  → origin_sku: "HAT_003"（帽子）
```

**数据示例**：

| origin_sku_id | platform_id | platform_outer_sku | bundled |
|---------------|-------------|-------------------|---------|
| 10 (SHIRT) | 1 (Shopee) | BUNDLE_SUMMER | true |
| 11 (PANTS) | 1 (Shopee) | BUNDLE_SUMMER | true |
| 12 (HAT) | 1 (Shopee) | BUNDLE_SUMMER | true |

> 唯一索引允许不同 `origin_sku_id` 共享同一 `platform_outer_sku`，因为三元组 `(origin_sku_id, platform_id, platform_outer_sku)` 各不相同。

---

## 三、使用流程指南

### 3.1 创建映射

1. **选择公司** → 加载该公司下的 Origin SKU 列表
2. **选择 Origin SKU** → 系统自动填充 `origin_sku` 快照字段
3. **选择平台** → 选择目标店铺（可选）
4. **生成 platform_outer_sku**：
   - **前缀模式**：`{prefix}_{origin_sku}`，如 `C03_0032`
   - **前缀+随机模式**：`{prefix}_{random}`，如 `C03_A7K2`
   - **手动模式**：用户直接输入
5. **唯一性预检** → 系统检查 `(origin_sku_id, platform_id, platform_outer_sku)` 是否已存在
6. **重复提示** → 如果同一 origin_sku 在该平台已有映射，提示用户可复用
7. **提交创建**

### 3.2 自动生成逻辑

调用 `POST /api/v1/sku-mappings/generate-sku` 接口时：
- 根据策略参数生成 `platform_outer_sku`
- 同时执行重复检测，返回该 origin_sku 在目标平台下的已有映射
- 前端展示生成结果和重复提示，由用户确认后提交

### 3.3 组合商品处理

创建组合商品映射时：
1. 开启 `bundled` 开关
2. 输入统一的 `platform_outer_sku`（如 `BUNDLE_SUMMER`）
3. 为套装中的每个 origin_sku 分别创建一条映射记录，均使用相同的 `platform_outer_sku` 和 `bundled = true`
4. 查询时可通过 `bundled` 筛选快速定位组合商品映射

---

## 四、实体关系图

```
┌──────────┐     1:N      ┌──────────────┐
│ Company  │─────────────▶│  SkuOrigin   │
│          │              │  (skus_origin)│
└──────────┘              └──────┬───────┘
     │                           │
     │                    origin_sku_id (FK, NOT NULL)
     │                           │
     │   1:N    ┌────────────────▼────────────────┐
     ├─────────▶│          SkuMapping              │
     │          │        (skus_mapping)             │
     │          │                                   │
     │          │  UK: (origin_sku_id, platform_id, │
     │          │       platform_outer_sku)          │
     │          └──────┬──────────┬────────────────┘
     │                 │          │
     │          platform_id    store_id (nullable)
     │                 │          │
     │          ┌──────▼──┐  ┌───▼─────┐
     └─────────▶│Platform │  │  Store  │
                └─────────┘  └─────────┘

组合商品关系：
  SkuOrigin A ──┐
  SkuOrigin B ──┼──▶ 同一 platform_outer_sku (bundled=true)
  SkuOrigin C ──┘
```

---

## 五、注意事项与约束

### 5.1 唯一性约束

- **数据库级**：唯一索引 `uk_origin_platform_sku (origin_sku_id, platform_id, platform_outer_sku)` 确保数据一致性
- **应用级**：Controller 层在 store/update 时执行唯一性预检，返回友好的 422 错误而非数据库异常

### 5.2 必填字段

V2 改进后，以下字段为必填：
- `origin_sku_id`：必须关联有效的 Origin SKU 记录
- `platform_outer_sku`：映射记录必须包含平台编码

### 5.3 数据隔离

- 所有查询通过 `DataScope` 中间件按 `company_id` 隔离
- 跨公司数据不可见

### 5.4 组合商品限制

- 组合商品映射的 `bundled` 字段应统一为 `true`
- 创建组合商品映射时，前端应引导用户为每个组成 SKU 分别创建记录
- 删除组合商品映射时，建议提示用户是否一并删除同组的其他映射

### 5.5 Origin SKU 快照

`skus_mapping.origin_sku` 字段存储的是创建映射时从 `skus_origin.sku` 复制的快照值，用于：
- 即使 Origin SKU 被修改，历史映射记录仍保留原始编码
- 订单匹配时使用快照值进行比对