wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0c4b6aaa6d8aa6e87fe408982bfe47ba46bbac57
makemd/docs11/00-documentation-layer.md
wurenzhi 136c2fa579 feat: 初始化项目结构并添加核心功能模块 
- 新增文档模板和导航结构
- 实现服务器基础API路由和控制器
- 添加扩展插件配置和前端框架
- 引入多租户和权限管理模块
- 集成日志和数据库配置
- 添加核心业务模型和类型定义
2026-03-17 22:07:19 +08:00

470 lines
20 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 📌 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. **“闭环写入规则：只要逻辑上能闭环就写，落地方式后置”**
***
Reference in New Issue View Git Blame Copy Permalink