makemd/docs/LOOPS/01_Product.md

# 01 商品域业务闭环

> 本文档包含与商品相关的业务闭环：数据采集、商品刊登、素材管理、商品主数据、SKU变体

---

## 1️⃣ 数据采集与清洗闭环（Product Data Collection & Cleansing）

- **💰 钱流**：
  - 采集成本：API调用费用、代理IP费用、云服务费用
  - 利润评估：采购成本 → 平台费用 → 物流费用 → 税费 → 广告费用 → 净利润
- **🔄 状态变化**：
  - `RAW_DATA` → `CLEANED` → `ANALYZED` → `READY_FOR_LISTING`
- **🔥 触发条件**：
  - 定时任务：按配置的采集频率自动触发
  - 手动触发：用户手动发起采集任务
  - 事件触发：商品价格变动、库存变动等事件触发重新采集

***

## 2️⃣ 商品刊登闭环（Product Listing Loop）

- **目标**：将可售商品同步到各平台，建立销售基础（TOC）或生成报价单（TOB）。
- **流程**：
  1. **商品准备**：
     - ERP 商品信息完善
     - 平台规则适配：标题、描述、图片、批量折扣（TOB）
     - 价格策略设置：基于套利分析或阶梯价策略
  2. **刊登执行**：
     - 批量或单条刊登，支持失败重试和全链路追踪
     - API 平台：走 Connector Bus
     - 无 API 平台：No-API Bridge + PENDING_REVIEW
  3. **刊登后管理**：
     - 库存同步、价格更新、商品状态监控
- **决策点**：
  - 必须通过前置套利/利润分析
  - TOB 需遵循阶梯价审批策略
- **输入**：清洗后的可售商品数据
- **输出**：已刊登商品列表 + 平台状态 + 链接
- **💰 钱流**：
  - 刊登成本：平台费用、图片处理费用、人工费用
  - 定价策略：成本价 → 平台费用 → 物流费用 → 预期利润 → 最终售价
- **🔄 状态变化**：
  - `READY_FOR_LISTING` → `LISTING_IN_PROGRESS` → `LISTED` → `MONITORING` → `NEED_UPDATE` → `UPDATED`
- **🔥 触发条件**：
  - 手动触发：用户手动发起刊登任务
  - 事件触发：商品信息更新、价格变动、库存变动
  - 定时任务：定期检查商品状态，更新价格和库存

***

## 3️⃣ 素材管理闭环（Media & Asset Management Loop）

- **目标**：统一管理商品、广告、营销所需素材，支持 TOC 广告投放和 TOB 企业报价资料。
- **流程**：
  - 素材采集、处理、审核、分发
  - TOC：图片/视频用于广告和商品展示
  - TOB：商品资料、合同模板、报价单模板
- **决策点**：
  - 版权合规、平台规则、素材质量
- **输出**：素材库 + 元数据 + 使用统计
- **状态机**：`UPLOADED` → `PROCESSING` → `PENDING_REVIEW` → `APPROVED` → `IN_USE` → `ARCHIVED`/`REJECTED`

***

## 2️⃣3️⃣ 商品主数据闭环（Product Master Data Loop / MDM）

- **目标**：建立统一的商品主数据管理体系，确保数据一致性。
- **流程**：
  - 数据采集 → 标准化处理 → 主数据维护 → 数据分发
- **决策点**：
  - 数据标准制定
  - 数据质量评估
  - 数据同步策略
- **输入**：来自采集、供应链、刊登等闭环的商品数据
- **输出**：
  - 统一 SPU/SKU 体系
  - 标准化类目和属性结构
  - 多语言支持
  - 多平台映射关系

***

## 2️⃣4️⃣ SKU变体与结构闭环（SKU Variant & Structure Loop）

- **目标**：管理商品的变体和多平台SKU映射，确保库存和订单的一致性。
- **流程**：
  - SPU创建 → SKU生成 → 平台SKU映射 → 同步管理
- **决策点**：
  - 变体属性定义
  - 多平台SKU规则适配
  - 库存同步策略
- **输入**：商品主数据、平台SKU规则
- **输出**：
  - 多SKU结构（颜色/尺寸/套装）
  - 各平台SKU映射
  - 统一库存管理

***

## 7️⃣2️⃣ 多平台商品管理闭环（Multi-Platform Product Management Loop）

- **目标**：统一管理多平台商品，实现批量操作和跨平台同步，提高运营效率。
- **流程**：
  1. **多平台商品整合**：
     - 统一商品信息管理
     - 多平台商品关联映射
     - 商品状态集中监控
  2. **批量商品操作**：
     - 批量上架/下架
     - 批量价格调整
     - 批量信息优化
  3. **跨平台库存同步**：
     - 实时库存数据同步
     - 库存预警和分配
     - 多平台库存一致性保障
- **决策点**：
  - 平台选择与优先级
  - 同步策略与频率
  - 冲突处理机制
- **输入**：商品信息、平台数据、库存数据
- **输出**：
  - 统一商品管理界面
  - 跨平台同步状态
  - 批量操作结果
- **状态机**：`PRODUCT_CREATED` → `PLATFORM_MAPPED` → `SYNCHRONIZED` → `UPDATED`

***

## 相关KPI

### 数据采集与清洗闭环

| KPI 指标  | 描述         | 适用业务类型    |
| ------- | ---------- | --------- |
| 采集覆盖率   | 目标平台商品覆盖率  | TOC + TOB |
| 数据准确率   | 清洗后数据的准确性  | TOC + TOB |
| 套利分析准确率 | 前置套利计算的准确性 | TOC + TOB |

### 商品刊登闭环

| KPI 指标  | 描述          | 适用业务类型    |
| ------- | ----------- | --------- |
| 刊登成功率   | 成功刊登的商品比例   | TOC + TOB |
| 刊登时效    | 从准备到刊登完成的时间 | TOC + TOB |
| 平台审核通过率 | 平台审核通过的商品比例 | TOC + TOB |

### 素材管理闭环

| KPI 指标  | 描述           | 适用业务类型    |
| ------- | ------------ | --------- |
| 素材处理时效  | 从上传到可用的平均时间  | TOC + TOB |
| 素材审核通过率 | 通过审核的素材比例    | TOC + TOB |
| 素材转化率   | 使用素材带来的订单转化率 | TOC + TOB |
| 素材复用率   | 被多次使用的素材比例   | TOC + TOB |
| 版权合规率   | 无版权风险的素材比例   | TOC + TOB |

### 商品主数据闭环

| KPI 指标 | 描述           | 适用业务类型    |
| ------ | ------------ | --------- |
| 数据标准化率 | 标准化处理的商品数据比例 | TOC + TOB |
| 数据一致性  | 多平台数据一致性程度   | TOC + TOB |
| 主数据准确率 | 商品主数据的准确性    | TOC + TOB |
| 数据同步时效 | 数据从采集到同步的时间  | TOC + TOB |
| 数据质量评分 | 商品数据质量综合评分   | TOC + TOB |

### SKU变体与结构闭环

| KPI 指标   | 描述           | 适用业务类型    |
| -------- | ------------ | --------- |
| SKU映射准确率 | 多平台SKU映射的准确性 | TOC + TOB |
| SKU生成时效  | SKU生成的平均时间   | TOC + TOB |
| 变体管理效率   | 变体属性管理的效率    | TOC + TOB |
| 库存同步准确率  | 多SKU库存同步的准确性 | TOC + TOB |

### 多平台商品管理闭环

| KPI 指标  | 描述           | 适用业务类型    |
| ------- | ------------ | --------- |
| 多平台同步准确率 | 跨平台商品信息同步的准确性 | TOC + TOB |
| 批量操作成功率  | 批量商品操作的成功比例  | TOC + TOB |
| 库存同步时效   | 库存数据同步的平均时间  | TOC + TOB |
| 平台覆盖度    | 已管理平台占目标平台的比例 | TOC + TOB |
| 操作效率提升率  | 相比手动操作的效率提升比例 | TOC + TOB |

---

## 7️⃣3️⃣ 三层商品模型闭环（Three-Layer Product Model Loop）

> **设计原则**: SPU → SKU → Listing 三层结构，支持多平台统一管理

### 模型定义

```
SPU（产品层）
  │
  ├── SKU-001（库存单元层）
  │     ├── Listing-A（平台商品层）
  │     ├── Listing-B（平台商品层）
  │     └── Listing-C（平台商品层）
  │
  ├── SKU-002（库存单元层）
  │     └── Listing-D（平台商品层）
  │
  └── SKU-003（库存单元层）
        └── Listing-E（平台商品层）
```

### 各层职责

| 层级 | 职责 | 存储内容 |
|------|------|----------|
| **SPU** | 产品聚合 | 名称、品牌、类目、通用属性 |
| **SKU** | 库存管理 | 变体属性、成本价、基准价、重量 |
| **Listing** | 平台销售 | 标题、最终价格、库存、平台状态 |

### 业务价值

- **统一视图**: 一个SKU，多平台Listing
- **价格管理**: 支持跨平台差异化定价
- **库存同步**: 统一库存管理，多平台同步
- **数据分析**: 统一的商品维度数据统计

---

## 7️⃣4️⃣ 商品映射与刊登闭环（Product Mapping vs Listing Loop）

### 核心概念

| 维度 | 商品映射（Mapping） | 商品刊登（Listing） |
|------|---------------------|----------------------------|
| **本质** | 关系绑定 | 创建商品 + 发布到平台 |
| **动作** | 不创建新商品 | 创建新Listing |
| **方向** | 双向绑定 | 单向（系统→平台） |
| **触发时机** | 已有商品需要统一管理 | 新品上架、批量铺货 |
| **结果** | 系统知道"平台SKU = 主SKU" | 平台新增商品 |

### 核心判断公式

> 这个动作有没有在平台创建新商品？
> - 有 → 刊登
> - 没有 → 映射

### 业务场景

| 场景 | 操作 | 用途 |
|------|------|------|
| 平台已有商品需要统一管理 | 映射 | 统一库存、利润分析、AI调价 |
| 新品上架、批量铺货 | 刊登 | 上新、自动铺货、跨平台分发 |

### 流程对比

**映射流程**：
```
平台已有商品 → 抓取 → 绑定到系统SKU → 完成映射
用途：统一管理库存、做利润分析、AI调价
```

**刊登流程**：
```
选品 → AI生成内容 → 发布到平台 → 创建Listing
用途：上新、自动铺货、跨平台分发
```

---

## 7️⃣5️⃣ 三层价格体系闭环（Three-Layer Price System Loop）

### 价格层级

```
┌─────────────────────────────────────────┐
│ 1️⃣ 基准价层（Base Price Layer）         │
│    SKU.base_price                       │
│    用途：统一锚点、人工理解               │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│ 2️⃣ 策略层（Strategy Layer）             │
│    PriceStrategy:                        │
│    - scope: 平台/店铺/Listing            │
│    - type: multiplier/fixed/dynamic     │
│    用途：规则定义、批量控制               │
└──────────────┬──────────────────────────┘
               │
               ↓
┌─────────────────────────────────────────┐
│ 3️⃣ Listing层（Final Price Layer）       │
│    PlatformListing.price                │
│    用途：真正赚钱的地方                   │
└─────────────────────────────────────────┘
```

### 价格计算公式

```
最终价格 = override_price || strategy计算结果 || base_price
```

### 价格策略类型

| 类型 | 说明 | 计算方式 |
|------|------|----------|
| **MULTIPLIER** | 倍率定价 | 最终价 = 基准价 × 倍率 |
| **FIXED** | 固定定价 | 最终价 = 固定值 |
| **DYNAMIC** | 动态定价 | AI根据市场动态计算 |

### 多平台定价示例

```
主SKU: SKU-001（蓝牙耳机）
├── TikTok主店（东南亚） → 基准价 $99 → 策略: × 1.0 = $99
├── TikTok美国店（美国） → 基准价 $99 → 策略: × 1.1 = $109
├── Shopee旗舰店（马来） → 基准价 $99 → 策略: × 0.9 = $89
├── Shopify独立站（全球） → 基准价 $99 → 策略: × 1.15 = $114
└── B2B批发（国内） → 基准价 $99 → 策略: × 0.5 = $50
```

---

## 7️⃣6️⃣ 组织权限与数据范围闭环（Organization & Data Scope Loop）

### 核心原则

> ❗ 权限 = 能做什么（Permission）
> ❗ 数据范围 = 能操作谁的数据（Scope）
> 👉 两者必须同时存在

### 组织层级结构

```
平台（Platform）
    ↓
商户/公司（Tenant/Organization）
    ↓
组织结构（Org Tree）
    ├── 部门A（主管）
    │     ├── 组A1（组长）
    │     │     ├── 员工1
    │     │     └── 员工2
    │     └── 组A2（组长）
    │           └── 员工3
    └── 部门B（主管）
          └── ...
```

### 数据范围类型

| 范围类型 | 英文 | 说明 |
|---------|------|------|
| **SELF** | Self | 只看自己 |
| **TEAM** | Team | 看自己组 |
| **DEPT** | Department | 看自己部门 |
| **ORG** | Organization | 看整个公司 |
| **ALL** | All | 全平台（超管） |

### 店铺角色权限

| 角色 | 描述 | 权限范围 |
|------|------|----------|
| **owner** | 拥有者 | 删除店铺、管理授权、管理成员、所有权限 |
| **admin** | 管理员 | 管理商品、管理价格、管理订单、不可删除店铺 |
| **operator** | 运营 | 刊登、改价、查看数据 |
| **viewer** | 只读 | 查看数据、不可操作 |

### 授权模型

**核心原则**：
> ❗ 授权属于店铺，不属于用户
> ❗ 店铺属于主体（Owner），用户只是被授权使用

**授权类型**：

| 类型 | 适用平台 | 存储内容 |
|------|----------|----------|
| **API授权** | Shopify、Amazon | access_token, refresh_token, expire_time |
| **Agent授权** | TikTok、Shopee | cookies, proxy, device_id, user_agent |