makemd/docs11/00-documentation-layer.md

# 📌 Crawlful Hub 业务闭环（TOC + TOB Unified Business Loops）

> **说明**：本闭环文档是战略层业务流程，关注“做什么、为什么做、顺序和决策点”，为下层模块功能和系统实现提供指引。TOC（零售/前端）和 TOB（B2B贸易）共享通用模块，特有流程用 `businessType` 标记。

## 📑 目录

1. [数据采集与清洗闭环](#1️⃣-数据采集与清洗闭环product-data-collection--cleansing)
2. [商品刊登闭环](#2️⃣-商品刊登闭环product-listing-loop)
3. [素材管理闭环](#3️⃣-素材管理闭环media--asset-management-loop)
4. [广告计划与营销闭环](#4️⃣-广告计划与营销闭环marketing--ad-management-loop)
5. [订单履约闭环](#5️⃣-订单履约闭环order-fulfillment-loop--oms)
6. [售后逆向闭环](#6️⃣-售后逆向闭环returns--refunds-loop)
7. [资金对账闭环](#7️⃣-资金对账闭环finance-reconciliation-loop)
8. [库存与仓储管理闭环](#8️⃣-库存与仓储管理闭环inventory--warehouse-management-loop--wms)
9. [供应链与供应商管理闭环](#9️⃣-供应链与供应商管理闭环supply-chain--supplier-management-loop)
10. [B2B / TOB 贸易管理闭环](#🔟-b2b--tob-贸易管理闭环b2b--tob-trade-management-loop)
11. [治理与审批中心闭环](#1️⃣1️⃣-治理与审批中心闭环governance--approval-center-loop)
12. [合规与证书管理闭环](#1️⃣2️⃣-合规与证书管理闭环compliance--certificate-management-loop)
13. [合规与风控闭环](#1️⃣3️⃣-合规与风控闭环compliance--risk-control-loop)
14. [报表与分析闭环](#1️⃣4️⃣-报表与分析闭环reporting--analytics-loop)
15. [统一闭环依赖](#🔹-统一闭环依赖toc--tob)
16. [闭环依赖关系](#🔗-闭环依赖关系toc--tob)
17. [关键绩效指标](#📊-关键绩效指标kpi)
18. [追踪与审计](#🔍-追踪与审计)
19. [业务审核状态机](#📋-业务审核状态机)
20. [说明](#💡-说明)

***

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

- **目标**：收集多平台商品信息，确保数据完整、有效、可用于盈利分析（TOC）或报价计算（TOB）。
- **流程**：
  1. **多平台采集**：
     - TOC：抓取 Amazon、eBay、Shopee、1688 等平台商品信息。
     - TOB：抓取供应商报价、批发价格、企业定制产品信息。
     - 支持 API 对接和爬虫采集。
     - 采集字段：标题、价格、库存、SKU、图片、描述、评价、供应商信息（TOB）。
  2. **数据清洗**：
     - 去重：平台+productId 唯一约束
     - 格式化：统一字段格式和单位
     - 字段标准化：规范属性名和值
     - 剔除无效商品：库存异常、价格异常、描述缺失
  3. **前置套利 / 利润评估**：
     - TOC：评估单件盈利、ROI、定价区间
     - TOB：评估阶梯价利润、批量折扣、信用额度风险
     - 考虑平台费、物流费、税费、汇率、售后成本、广告摊销
- **决策点**：
  - TOC：B2C 利润率 < 20% 触发风控
  - TOB：B2B 利润率 < 15% 禁止报价
- **输入**：平台商品原始数据
- **输出**：清洗后的可售商品/报价数据，包含完整套利/利润分析

***

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

- **目标**：将可售商品同步到各平台，建立销售基础（TOC）或生成报价单（TOB）。
- **流程**：
  1. **商品准备**：
     - ERP 商品信息完善
     - 平台规则适配：标题、描述、图片、批量折扣（TOB）
     - 价格策略设置：基于套利分析或阶梯价策略
  2. **刊登执行**：
     - 批量或单条刊登，支持失败重试和全链路追踪
     - API 平台：走 Connector Bus
     - 无 API 平台：No-API Bridge + PENDING\_REVIEW
  3. **刊登后管理**：
     - 库存同步、价格更新、商品状态监控
- **决策点**：
  - 必须通过前置套利/利润分析
  - TOB 需遵循阶梯价审批策略
- **输入**：清洗后的可售商品数据
- **输出**：已刊登商品列表 + 平台状态 + 链接

***

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

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

***

## 4️⃣ 广告计划与营销闭环（Marketing & Ad Management Loop）

- **目标**：提升销量和 ROI（TOC）或企业促销效率（TOB）。
- **流程**：
  - 广告计划制定、跨平台投放、效果分析与优化
  - TOB：批量报价、促销方案、邮件/企业营销
- **决策点**：
  - 广告 ROI < 1 停止投放
  - 企业营销需基于信用等级和合同审批
- **输入**：已刊登商品列表、素材
- **输出**：广告报告、优化建议

***

## 5️⃣ 订单履约闭环（Order Fulfillment Loop / OMS）

- **目标**：保证订单从生成到妥投的全链路履约。
- **流程**：
  - **公共流程**：订单获取与审核 → 分仓 → 占库 → 扣库 → 发货 → 物流追踪
  - **TOC**：标准订单处理流程
  - **TOB**：大额企业订单可分批发货、合同条款优先
- **状态机**：`PULLED` → `PENDING_REVIEW` → `CONFIRMED` → `ALLOCATED` → `READY_TO_SHIP` → `SHIPPED` → `DELIVERED` → `CLOSED`
- **输入**：平台订单数据
- **输出**：已发货订单，包含物流跟踪信息

***

## 6️⃣ 售后逆向闭环（Returns & Refunds Loop）

- **目标**：处理退货/退款，保持库存和财务一致。
- **流程**：
  - **公共流程**：售后请求处理 → 退货处理 → 退款处理
  - **TOC**：标准退货流程
  - **TOB**：按合同条款、批量退货、预付款冲抵
- **输入**：售后请求数据
- **输出**：处理完成的售后记录，包含库存和财务调整

***

## 7️⃣ 资金对账闭环（Finance Reconciliation Loop）

- **目标**：财务闭环，兼顾 TOC/TOB。
- **流程**：
  - 数据汇总 → 财务处理（多币种、VAT、汇率） → 差异分析与处理
- **决策点**：
  - 异常需人工复核
  - TOB 账期和信用额度影响结算
- **输出**：对账报告 + 差异处理记录

***

## 8️⃣ 库存与仓储管理闭环（Inventory & Warehouse Management Loop / WMS）

- **目标**：确保库存准确、仓储高效，支持全球供应链运作。
- **流程**：
  - **公共流程**：多仓库存管理 → 进出库管理 → 物流模式管理
  - **TOC**：按店铺和平台库存管理
  - **TOB**：按企业订单、批量调拨、FCL/3PL 管理
- **决策点**：
  - 库存不足时触发补货建议
  - 跨仓调拨决策：基于成本和时效
  - 安全库存预警阈值设置
- **输入**：订单数据、采购数据、物流数据
- **输出**：实时库存状态、仓储操作记录、库存预警

***

## 9️⃣ 供应链与供应商管理闭环（Supply Chain & Supplier Management Loop）

- **目标**：优化供应链流程，降低采购成本，确保供应稳定。
- **流程**：
  - **公共流程**：供应商管理 → 采购管理 → 补货建议
  - **TOC**：基于零售需求的采购计划
  - **TOB**：基于大宗订单生成采购计划
- **决策点**：
  - 供应商选择：基于综合评分
  - 采购价格：低于成本价预警
  - 补货时机：库存周转率优化
- **输入**：销售数据、库存数据、供应商数据
- **输出**：采购计划、供应商评估报告、成本节省分析

***

## 🔟 B2B / TOB 贸易管理闭环（B2B / TOB Trade Management Loop）

- **目标**：企业间交易管理
- **流程**：
  - 报价管理、信用管理、询盘转订单
- **决策点**：
  - 利润率 < 15% 禁止报价
  - 大额订单多级审批
  - 低信用等级客户需预付款
- **输出**：报价单、B2B 订单、信用评估报告

***

## 1️⃣1️⃣ 治理与审批中心闭环（Governance & Approval Center Loop）

- **目标**：敏感操作审批
- **适用**：
  - TOC：大额订单、价格变动、退款
  - TOB：大额企业订单、阶梯价审批、信用审批
- **输出**：审批结果、审计日志

***

## 1️⃣2️⃣ 合规与证书管理闭环（Compliance & Certificate Management Loop）

- **目标**：确保业务合规，自动生成所需证书。
- **流程**：
  - **公共流程**：自动化合规 → 信用分级 → 合规审计
  - **TOC**：商品合规检查和证书生成
  - **TOB**：出口合规、合同合规检查和证书生成
- **决策点**：
  - 不合规商品禁止销售
  - 信用等级低的合作伙伴需要额外审核
- **输入**：订单数据、商品数据、合作伙伴数据
- **输出**：电子证书、合规报告、信用评估

***

## 1️⃣3️⃣ 合规与风控闭环（Compliance & Risk Control Loop）

- **目标**：统一风控
- **输入**：全流程数据（TOC + TOB）
- **输出**：风险处理记录、规则优化

***

## 1️⃣4️⃣ 报表与分析闭环（Reporting & Analytics Loop）

- **目标**：数据可视化 + KPI 支撑 TOC/TOB 决策
- **流程**：
  - 数据汇总 → 指标计算 → 报表生成 → 数据大屏 → 闭环反馈
- **输出**：管理报表、异常预警、优化建议
- **状态机**：`RAW_DATA` → `PROCESSED` → `GENERATED` → `DISTRIBUTED` → `FEEDBACK_APPLIED`

***

### 🔹 统一闭环依赖（TOC + TOB）

```text
采集 → 清洗 → 套利/利润评估
        │
商品刊登 ← 素材管理
        │
广告/营销 (TOC) / 企业营销 (TOB)
        │
订单履约 (OMS) → 售后逆向
        │            │
        ▼            ▼
库存 & WMS ← 资金对账
        │
        ▼
供应链 & 补货
        │
        ▼
B2B/TOB 贸易管理 (TOB)
        │
        ▼
治理与审批中心
        │
        ▼
合规 & 证书
        │
        ▼
风控
        │
        ▼
报表 & 分析
```

**说明**：

- 实线箭头表示核心业务流程
- 括号内标注了TOC/TOB的主要差异点
- B2B/TOB贸易管理为TOB特有闭环

***

### 🔗 闭环依赖关系（TOC + TOB）

1. **数据采集与清洗闭环** → **商品刊登闭环**：提供清洗后的可售商品数据
2. **数据采集与清洗闭环** → **素材管理闭环**：提供采集的商品图片和视频素材
3. **商品刊登闭环** → **素材管理闭环**：触发素材需求，生成商品主图和详情图
4. **素材管理闭环** → **商品刊登闭环**：提供处理后的商品素材（图片、视频）
5. **素材管理闭环** → **广告计划与营销闭环**：提供广告投放所需的素材库
6. **商品刊登闭环** → **广告计划与营销闭环**：提供已刊登商品列表
7. **商品刊登闭环** → **订单履约闭环**：提供商品库存和状态信息
8. **订单履约闭环** → **售后逆向闭环**：提供订单和物流信息
9. **售后逆向闭环** → **资金对账闭环**：提供退款记录
10. **订单履约闭环** → **资金对账闭环**：提供销售记录
11. **广告计划与营销闭环** → **资金对账闭环**：提供广告费用记录
12. **订单履约闭环** → **库存与仓储管理闭环**：触发库存扣减和物流操作
13. **库存与仓储管理闭环** → **订单履约闭环**：提供库存状态和物流信息
14. **库存与仓储管理闭环** → **供应链与供应商管理闭环**：触发补货需求
15. **供应链与供应商管理闭环** → **库存与仓储管理闭环**：提供采购入库信息
16. **商品刊登闭环** → **B2B / TOB 贸易管理闭环**：提供商品信息用于报价
17. **B2B / TOB 贸易管理闭环** → **订单履约闭环**：生成 B2B 订单
18. **B2B / TOB 贸易管理闭环** → **资金对账闭环**：提供 B2B 交易记录
19. **所有敏感操作** → **治理与审批中心闭环**：触发审批流程
20. **治理与审批中心闭环** → **所有业务闭环**：提供审批结果
21. **订单履约闭环** → **合规与证书管理闭环**：触发证书生成
22. **合规与证书管理闭环** → **订单履约闭环**：提供合规证书
23. **所有闭环** → **合规与风控闭环**：提供全流程数据用于风险监控
24. **所有业务闭环** → **报表与分析闭环**：提供各闭环的输出数据用于报表生成和分析
25. **报表与分析闭环** → **所有业务闭环**：反馈数据异常、业务波动、优化建议，指导各闭环的操作调整

***

### 📊 关键绩效指标（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 指标   | 描述             | 适用业务类型 |
| -------- | -------------- | ------ |
| 广告 ROI   | 广告投入产出比        | TOC    |
| 点击率（CTR） | 广告点击次数与展示次数的比率 | TOC    |
| 转化率（CVR） | 点击广告后产生订单的比例   | TOC    |
| 企业营销效果   | 企业营销活动的转化率     | TOB    |

#### 订单履约闭环

| KPI 指标 | 描述          | 适用业务类型    |
| ------ | ----------- | --------- |
| 订单处理时效 | 从订单生成到发货的时间 | TOC + TOB |
| 发货准确率  | 正确发货的订单比例   | TOC + TOB |
| 妥投率    | 成功送达的订单比例   | TOC + TOB |
| 分批处理率  | 大额订单分批处理的比例 | TOB       |

#### 售后逆向闭环

| KPI 指标 | 描述            | 适用业务类型    |
| ------ | ------------- | --------- |
| 售后处理时效 | 从售后请求到处理完成的时间 | TOC + TOB |
| 退款成功率  | 成功退款的比例       | TOC + TOB |
| 退货率    | 退货订单占总订单的比例   | TOC + TOB |

#### 资金对账闭环

| KPI 指标 | 描述            | 适用业务类型    |
| ------ | ------------- | --------- |
| 对账准确率  | 对账差异率         | TOC + TOB |
| 对账时效   | 从数据汇总到对账完成的时间 | TOC + TOB |
| 异常处理率  | 需要人工处理的异常比例   | TOC + TOB |
| 账期遵守率  | 按合同约定账期结算的比例  | TOB       |

#### 库存与仓储管理闭环

| KPI 指标 | 描述            | 适用业务类型    |
| ------ | ------------- | --------- |
| 库存准确率  | 系统库存与实际库存的差异率 | TOC + TOB |
| 库存周转率  | 库存周转次数        | TOC + TOB |
| 仓储操作效率 | 每单处理时间        | TOC + TOB |
| 跨仓调拨时效 | 调拨完成时间        | TOC + TOB |

#### 供应链与供应商管理闭环

| KPI 指标   | 描述        | 适用业务类型    |
| -------- | --------- | --------- |
| 供应商准时交付率 | 按时交付的订单比例 | TOC + TOB |
| 采购成本降低率  | 采购成本下降百分比 | TOC + TOB |
| 供应商评分    | 供应商综合评估分数 | TOC + TOB |
| 补货准确率    | 补货计划的准确性  | TOC + TOB |

#### B2B / TOB 贸易管理闭环

| KPI 指标  | 描述         | 适用业务类型 |
| ------- | ---------- | ------ |
| B2B 利润率 | B2B 业务的利润率 | TOB    |
| 报价通过率   | 报价被客户接受的比例 | TOB    |
| 信用违约率   | 客户信用违约的比例  | TOB    |
| 询盘转化率   | 询盘转化为订单的比例 | TOB    |

#### 治理与审批中心闭环

| KPI 指标 | 描述          | 适用业务类型    |
| ------ | ----------- | --------- |
| 审批时效   | 从申请到审批完成的时间 | TOC + TOB |
| 审批准确率  | 审批结果的准确性    | TOC + TOB |
| 待办处理率  | 待办事项的处理比例   | TOC + TOB |

#### 合规与证书管理闭环

| KPI 指标  | 描述        | 适用业务类型    |
| ------- | --------- | --------- |
| 证书生成及时率 | 按时生成证书的比例 | TOC + TOB |
| 合规检查通过率 | 通过合规检查的比例 | TOC + TOB |
| 信用评级准确率 | 信用评级的准确性  | TOC + TOB |

#### 合规与风控闭环

| KPI 指标  | 描述         | 适用业务类型    |
| ------- | ---------- | --------- |
| 风险识别准确率 | 风险识别的准确性   | TOC + TOB |
| 风控处理时效  | 风险处理的时间    | TOC + TOB |
| 合规违规率   | 违规事件的比例    | TOC + TOB |
| 误报率     | 误判为风险的事件比例 | TOC + TOB |

#### 报表与分析闭环

| KPI 指标  | 描述              | 适用业务类型    |
| ------- | --------------- | --------- |
| 报表生成及时率 | 按时生成报表的比例       | TOC + TOB |
| 数据准确率   | 报表数据的准确性        | TOC + TOB |
| 分析洞察价值  | 分析结果对业务决策的价值    | TOC + TOB |
| 异常预警准确率 | 异常预警的准确性        | TOC + TOB |
| 报表生成时效  | 从数据汇总到报表完成的时间   | TOC + TOB |
| 数据完整率   | 报表覆盖业务闭环输出数据的比例 | TOC + TOB |
| KPI 准确率 | 计算指标与实际数据偏差率    | TOC + TOB |
| 异常响应率   | 异常报表触发优化措施的比例   | TOC + TOB |
| 大屏实时性   | 数据大屏数据更新延迟时间    | TOC + TOB |
| 决策支持率   | 报表建议被采纳并执行的比例   | TOC + TOB |

***

### 🔍 追踪与审计

- **追踪四元组**：
  - `tenantId`：租户 ID（业务隔离）
  - `shopId`：店铺 ID（平台/店铺隔离）
  - `taskId`：任务 ID（任务/规则触发归档）
  - `traceId`：链路追踪 ID（全链路唯一标识）
  - `businessType`：业务类型（TOC/TOB）
- **审计要求**：
  - 每一笔操作必须绑定 `traceId` 和 `businessType`
  - 所有功能需通过 Shadow-Test（最小冒烟测试）
  - 关键操作必须生成 AuditLog

***

### 📋 业务审核状态机

- **通用审核流程**：`SUBMITTED` (提交) → `PENDING_REVIEW` (人工审核) → `EXECUTED` / `REJECTED`
- **适用场景**：
  - TOC：大额订单、价格变动、退款
  - TOB：大额企业订单、阶梯价审批、信用审批

***

### 💡 说明

1. 业务闭环文档是**最高层文档**，不涉及具体前端或模块实现细节。
2. 下层模块功能、接口、算法、UI 都是这个闭环的落地实现。
3. 形成从**采集 → 决策 → 执行 → 反馈 → 风控**的完整业务链。
4. 每个闭环都有明确的输入、输出、流程和决策点，确保业务流程的完整性和可控性。
5. 各闭环之间通过数据流转和依赖关系形成完整的业务生态系统。
6. 所有业务操作均需遵循项目特定规则，确保系统安全和数据一致性。
7. **“闭环写入规则：只要逻辑上能闭环就写，落地方式后置”**

***