makemd/archive/00-documentation-layer.md

---

📌 Crawlful Hub 业务闭环（Business Loops）

说明：本闭环文档是战略层业务流程，关注“做什么、为什么做、顺序和决策点”，为下层模块功能和系统实现提供指引。

---

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

• 目标：收集多平台商品信息，确保数据完整、有效、可用于盈利分析。
• 流程：
  1. 多平台采集：
     • 抓取 Amazon、eBay、Shopee、1688 等平台商品信息
     • 支持 API 对接和爬虫采集两种方式
     • 采集字段：标题、价格、库存、SKU、图片、描述、评价等
  2. 数据清洗：
     • 去重：基于平台+productId 唯一约束
     • 格式化：统一字段格式和单位（长度 cm, 重量 kg, 体积 m³）
     • 字段标准化：规范属性名和值
     • 剔除无效商品：无库存、价格异常、描述缺失等
  3. 前置套利计算：
     • 评估单件盈利/亏损、ROI、定价区间
     • 考虑平台费、物流费、税费、汇率、售后成本、广告摊销
     • 决策是否刊登、调价或采购
• 决策点：
  • B2B 利润率 < 15% 禁止报价
  • B2C 利润率 < 20% 触发风控预警
  • 仅通过清洗和盈利分析的商品才进入刊登环节
• 输入：平台商品原始数据
• 输出：清洗后的可售商品数据，包含完整的套利分析结果

---

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

• 目标：将可售商品同步到各平台，建立销售基础。
• 流程：
  1. 商品准备：
     • ERP 商品 (SPU/SKU) 信息完善
     • 平台规则适配：标题、描述、图片等格式调整
     • 价格策略设置：基于套利分析结果
  2. 刊登执行：
     • 批量或单条商品刊登
     • 支持刊登任务重试、失败定位、全链路追踪（携带 traceId）
     • 实时同步刊登状态
     • 有 API 平台：走 Connector Bus 标准协议
     • 无 API 平台：走 No-API Bridge，采用 Collect -> Clean -> Review -> Publish 流程
  3. 刊登后管理：
     • 库存同步和价格更新
     • 商品状态监控
• 决策点：
  • 商品必须通过前置套利分析和清洗才能刊登
  • 无 API 平台必须走 No-API Bridge + PENDING_REVIEW
• 输入：清洗后的可售商品数据
• 输出：已刊登商品列表，包含平台状态和链接

---

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

• 目标：基于已刊登商品进行跨平台广告投放，提升销量和 ROI。
• 流程：
  1. 广告计划制定：
     • 确定预算、目标、渠道
     • 选择投放商品和关键词
     • 设定出价策略和投放时间
  2. 跨平台投放：
     • 支持 Amazon、eBay、Facebook、Google、TikTok 等平台广告投放
     • 实时监控广告效果
     • 自动调整出价和预算
  3. 效果分析与优化：
     • ROI 监控和效果反馈
     • A/B 测试不同广告策略
     • 基于数据调整广告计划
     • 独立站 DTC 策略：全链路归因分析 (Multi-touch Attribution)
• 决策点：
  • 广告投放依赖已刊登商品
  • 通过 ROI 数据指导后续调价和补货
  • 广告 ROI < 1 时停止投放
• 输入：已刊登商品列表
• 输出：广告投放报告和优化建议

---

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

• 目标：保证订单从生成到妥投的全链路履约。
• 流程：
  1. 订单获取与审核：
     • 平台订单拉取（支持 Webhook 推送）
     • 订单信息校验：地址、支付、商品状态
     • 异常订单标记和人工审核
  2. 订单处理：
     • 分仓：基于库存和地址选择最优仓库
     • 占库：锁定库存防止超卖
     • 扣库：实际减少库存
     • 发货：生成物流单和跟踪号
  3. 物流追踪与异常处理：
     • 实时物流状态更新
     • 异常处理与人工介入
     • 妥投确认
• 决策点：
  • 库存充足、地址和支付正常才发货
  • 严禁处理住宅地址订单（轻B模式）
• 输入：平台订单数据
• 输出：已发货订单，包含物流跟踪信息
• 状态机：PULLED → PENDING_REVIEW → CONFIRMED → ALLOCATED → READY_TO_SHIP → SHIPPED → DELIVERED → CLOSED

---

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

• 目标：处理退货、退款，保持库存和财务一致。
• 流程：
  1. 售后请求处理：
     • 接收平台售后请求
     • 分类处理：退货、退款、换货
     • 制定处理方案
  2. 退货处理：
     • 退货地址生成
     • 退货入仓
     • 质检：判定商品状态
     • 库存流水调整：根据质检结果
  3. 退款处理：
     • 退款审核
     • 平台退款操作
     • 财务记录更新
• 决策点：
  • 退货质量、审核状态决定退款是否通过
  • 设备标记：Commercial Use Only, Non-Returnable
• 输入：售后请求数据
• 输出：处理完成的售后记录，包含库存和财务调整

---

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

• 目标：确保财务流水、平台结算和费用差异可追溯和闭环。
• 流程：
  1. 数据汇总：
     • 平台结算流水汇总
     • 费用记录汇总
     • 退款流水汇总
  2. 财务处理：
     • 多币种、汇率换算
     • VAT 计提
     • 费用分摊
     • 汇率避险：联动多币种汇率避险接口，锁定汇率风险
  3. 差异分析与处理：
     • 系统自动对账
     • 差异识别和分类
     • 异常处理和人工复核
     • 对账结果关闭
• 决策点：
  • 差异是否可解释，异常需人工复核
• 输入：平台结算数据、费用记录、退款记录
• 输出：对账报告和差异处理记录

---

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

• 目标：统一管理商品、广告、营销所需的图片、音频、视频素材，确保素材质量和合规性。
• 流程：
  1. 素材采集与上传：
     • 多渠道素材采集：平台商品图片、供应商素材、自制素材
     • 批量上传和自动分类
     • 支持拖拽上传和 URL 导入
  2. 素材处理与优化：
     • 图片处理：压缩、裁剪、水印添加、格式转换
     • 视频处理：剪辑、压缩、格式转换、字幕添加
     • 音频处理：降噪、格式转换、音量调整
     • AI 辅助：智能裁剪、背景移除、质量评估
  3. 素材审核与合规检查：
     • 版权检查：确保素材无侵权风险
     • 平台规则适配：检查是否符合各平台素材规范
     • 敏感内容检测：自动识别违规内容
     • 人工审核：关键素材需要人工确认
  4. 素材分发与应用：
     • 商品刊登：自动关联商品主图、详情图
     • 广告投放：提供广告素材库和智能推荐
     • 营销活动：支持活动素材包管理
     • 跨平台同步：一键分发到多个平台
  5. 素材生命周期管理：
     • 版本控制：支持素材版本管理和回滚
     • 使用统计：追踪素材使用效果和转化率
     • 定期清理：自动清理过期和未使用素材
     • 备份归档：重要素材自动备份
• 决策点：
  • 版权合规的素材才能进入素材库
  • 平台规则不合规的素材需要重新处理
  • 低质量素材（模糊、失真等）需要优化或替换
  • 高转化率素材优先推荐使用
• 输入：原始素材文件（图片、音频、视频）
• 输出：处理后的可用素材库，包含素材元数据和使用统计
• 素材类型：
  • 图片素材：商品主图、详情图、广告图、包装图、Logo 等
  • 视频素材：商品展示视频、广告视频、教程视频、开箱视频等
  • 音频素材：广告音频、产品介绍音频、背景音乐等
• 状态机：UPLOADED → PROCESSING → PENDING_REVIEW → APPROVED → IN_USE → ARCHIVED / REJECTED

---

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

• 目标：风险信号及时发现和处理，保障业务安全。
• 流程：
  1. 风险监控：
     • 多维度风险指标监控
     • 异常信号触发
     • 风险等级评估
  2. 风险处理：
     • 系统自动放行/拦截
     • 多级复核流程
     • 风险缓解措施
  3. 审计与记录：
     • 全链路审计与操作记录
     • 风险事件分析
     • 风控规则优化
• 决策点：
  • 风险等级、门禁规则决定放行或阻断
  • 所有 Agent 决策必须遵循 SUGGESTED -> PENDING_REVIEW -> EXECUTED/REJECTED 状态机
• 输入：全业务流程数据
• 输出：风险处理记录和风控规则优化建议

---

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

• 目标：确保库存准确、仓储高效，支持全球供应链运作。
• 流程：
  1. 多仓库存管理：
     • 多仓库库存统一视角，支持仓际调拨
     • 全球仓储管理：多国仓、在途库存、跨仓调拨、安全库存预警
     • 实时同步：平台库存实时对账，乐观锁防止超卖
  2. 进出库管理：
     • ASN 预报、盲收/点收、QC 质检、循环盘点、报损记录
     • 库存流水：完整记录库存变动，支持回溯
  3. 物流模式管理：
     • 整柜出海 (FCL Shipping)
     • 自有仓出货
     • 第三方仓出货 (3PL)
     • 直发客户 (D2C / Dropship)
• 决策点：
  • 库存不足时触发补货建议
  • 跨仓调拨决策：基于成本和时效
  • 安全库存预警阈值设置
• 输入：订单数据、采购数据、物流数据
• 输出：实时库存状态、仓储操作记录、库存预警

---

🔟 供应链与供应商管理闭环（Supply Chain & Supplier Management Loop）

• 目标：优化供应链流程，降低采购成本，确保供应稳定。
• 流程：
  1. 供应商管理：
     • 供应商档案：信用分级、联系方式、评分管理
     • 供应商评估：质量、交期、价格、服务
  2. 采购管理：
     • 1688 一键代采、实时比价
     • 多供应商询价、MOQ、交期对比
     • 采购订单管理和跟踪
  3. 补货建议：
     • 基于销量预测、采购周期、安全库存自动生成补货计划
     • 智能推荐最优采购渠道和数量
• 决策点：
  • 供应商选择：基于综合评分
  • 采购价格：低于成本价预警
  • 补货时机：库存周转率优化
• 输入：销售数据、库存数据、供应商数据
• 输出：采购计划、供应商评估报告、成本节省分析

---

1️⃣1️⃣ B2B / TOB 贸易管理闭环（B2B / TOB Trade Management Loop）

• 目标：管理企业间贸易，确保利润红线和交易安全。
• 流程：
  1. 报价管理：
     • 利润率低于阈值自动拦截，支持多级审批
     • 阶梯价策略：采购数量触发阶梯折扣
  2. 信用管理：
     • 信用池：基于历史履约记录的结算额度与审计
     • 信用分级：影响报价和结算条件
  3. 询盘管理：
     • 多渠道整合询盘，支持跟进与转化
     • 询盘转订单的全流程管理
• 决策点：
  • B2B 利润率 < 15% 禁止报价
  • 大额订单需要多级审批
  • 信用等级低的客户需要预付款
• 输入：询盘数据、客户信用数据、采购需求
• 输出：报价单、订单、信用评估报告

---

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

• 目标：规范业务流程，确保敏感操作得到适当审批。
• 流程：
  1. 通用审批中心：
     • 大额订单、价格变更、退款等敏感操作多级审核
     • 待办/已办统计，审批日志，核准/拒绝动作
  2. 审批流程管理：
     • 自定义审批流程和权限
     • 审批状态跟踪和提醒
  3. 决策记录与审计：
     • 完整的审批历史和决策理由
     • 与风控系统集成，确保合规性
• 决策点：
  • 审批权限：基于角色和层级
  • 审批时效：超时自动提醒
  • 审批结果：影响业务流程下一步
• 输入：审批请求数据
• 输出：审批结果、审计日志

---

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

• 目标：确保业务合规，自动生成所需证书。
• 流程：
  1. 自动化合规：
     • 订单数据生成 CE、FDA、原产地证等电子证书
     • 合规检查：确保商品符合目标市场法规
  2. 信用分级：
     • 基于配送员履约率、争议率的信用体系
     • 供应商和客户信用评估
  3. 合规审计：
     • 定期合规检查和报告
     • 异常合规问题的处理和跟踪
• 决策点：
  • 不合规商品禁止销售
  • 信用等级低的合作伙伴需要额外审核
• 输入：订单数据、商品数据、合作伙伴数据
• 输出：电子证书、合规报告、信用评估

---

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

• 目标：将业务数据转化为可视化报表和分析洞察，为管理层和业务决策提供闭环支持。
• 流程：
  1. 数据汇总：
     • 汇总各闭环输出数据：商品、订单、库存、财务、广告、售后、风控、供应链、B2B贸易
     • 按租户（tenantId）、店铺（shopId）、时间段、商品维度整理
  2. 数据处理与指标计算：
     • KPI 计算：销售额、毛利、ROI、库存周转率、广告效果、退货率、供应链效率、B2B利润率等
     • 异常标记：如数据缺失、异常波动
     • 可视化预处理：生成图表数据、趋势分析、预测数据
  3. 报表生成与分发：
     • 生成多维度报表：按商品、平台、时间、渠道、仓库、供应商、客户等
     • 支持定期发送和按需查询
     • 提供管理层和运营人员决策参考
  4. 数据大屏实时展示：
     • 实时数据监控：销售、订单、库存、广告、供应链、B2B贸易等关键指标实时更新
     • 可视化大屏：多维度数据可视化，支持钻取和交互
     • 异常告警：关键指标异常时实时告警
     • 移动端适配：支持手机和平板访问
  5. 反馈与闭环优化：
     • 数据异常、业务波动、KPI 变化反馈到对应闭环（采集、刊登、营销、履约、财务、风控、库存、供应链、B2B贸易）
     • 指导调价、补货、广告投放、库存调整、供应商选择等操作
• 决策点：
  • 数据完整性：缺失或异常数据必须标记并反馈
  • KPI 门槛触发：关键指标异常时触发人工或自动优化
  • 报表结果用于指导闭环操作，而非仅做记录
• 输入：各业务闭环输出数据（采集、刊登、广告、订单、售后、财务、风控、库存、供应链、B2B贸易）
• 输出：
  • 管理报表：销售、库存、利润、广告、退货、财务、供应链、B2B贸易汇总
  • KPI 趋势分析
  • 异常预警与优化建议
  • 数据大屏：实时业务监控大屏
• 状态机：RAW_DATA → PROCESSED → GENERATED → DISTRIBUTED → FEEDBACK_APPLIED
• 追踪要求：每份报表必须绑定 tenantId、shopId、reportId、traceId

---

🔹 业务闭环总览（文字版流程图）

多平台采集 → 数据清洗 → 前置套利计算
        │
        ▼
商品刊登（ERP → 平台可售）
        │
        ▼
素材管理（图片/音频/视频）
        │
        ▼
广告计划 / 营销投放
        │
        ▼
订单履约（OMS）
        │
        ▼
售后逆向处理（退货 / 退款）
        │
        ▼
资金对账与财务闭环
        │
        ▼
库存与仓储管理（WMS）
        │
        ▼
供应链与供应商管理
        │
        ▼
B2B / 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）

1. 数据采集与清洗闭环：
   • 采集覆盖率：目标平台商品覆盖率
   • 数据准确率：清洗后数据的准确性
   • 套利分析准确率：前置套利计算的准确性
2. 商品刊登闭环：
   • 刊登成功率：成功刊登的商品比例
   • 刊登时效：从准备到刊登完成的时间
   • 平台审核通过率：平台审核通过的商品比例
3. 素材管理闭环：
   • 素材处理时效：从上传到可用的平均时间
   • 素材审核通过率：通过审核的素材比例
   • 素材转化率：使用素材带来的订单转化率
   • 素材复用率：被多次使用的素材比例
   • 版权合规率：无版权风险的素材比例
4. 广告计划与营销闭环：
   • 广告 ROI：广告投入产出比
   • 点击率（CTR）：广告点击次数与展示次数的比率
   • 转化率（CVR）：点击广告后产生订单的比例
5. 订单履约闭环：
   • 订单处理时效：从订单生成到发货的时间
   • 发货准确率：正确发货的订单比例
   • 妥投率：成功送达的订单比例
6. 售后逆向闭环：
   • 售后处理时效：从售后请求到处理完成的时间
   • 退款成功率：成功退款的比例
   • 退货率：退货订单占总订单的比例
7. 资金对账闭环：
   • 对账准确率：对账差异率
   • 对账时效：从数据汇总到对账完成的时间
   • 异常处理率：需要人工处理的异常比例
8. 库存与仓储管理闭环：
   • 库存准确率：系统库存与实际库存的差异率
   • 库存周转率：库存周转次数
   • 仓储操作效率：每单处理时间
   • 跨仓调拨时效：调拨完成时间
9. 供应链与供应商管理闭环：
   • 供应商准时交付率：按时交付的订单比例
   • 采购成本降低率：采购成本下降百分比
   • 供应商评分：供应商综合评估分数
   • 补货准确率：补货计划的准确性
10. B2B / TOB 贸易管理闭环：
    • B2B 利润率：B2B 业务的利润率
    • 报价通过率：报价被客户接受的比例
    • 信用违约率：客户信用违约的比例
    • 询盘转化率：询盘转化为订单的比例
11. 治理与审批中心闭环：
    • 审批时效：从申请到审批完成的时间
    • 审批准确率：审批结果的准确性
    • 待办处理率：待办事项的处理比例
12. 合规与证书管理闭环：
    • 证书生成及时率：按时生成证书的比例
    • 合规检查通过率：通过合规检查的比例
    • 信用评级准确率：信用评级的准确性
13. 合规与风控闭环：
    • 风险识别准确率：风险识别的准确性
    • 风控处理时效：风险处理的时间
    • 合规违规率：违规事件的比例
    • 误报率：误判为风险的事件比例
14. 报表与分析闭环：
    • 报表生成及时率：按时生成报表的比例
    • 数据准确率：报表数据的准确性
    • 分析洞察价值：分析结果对业务决策的价值
    • 异常预警准确率：异常预警的准确性
    • 报表生成时效：从数据汇总到报表完成的时间
    • 数据完整率：报表覆盖业务闭环输出数据的比例
    • KPI 准确率：计算指标与实际数据偏差率
    • 异常响应率：异常报表触发优化措施的比例
    • 大屏实时性：数据大屏数据更新延迟时间
    • 决策支持率：报表建议被采纳并执行的比例

---

🔍 追踪与审计

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

---

📋 业务审核状态机

• 通用审核流程：SUBMITTED (提交) → PENDING_REVIEW (人工审核) → EXECUTED / REJECTED
• 适用场景：大额订单、价格变更、退款等敏感操作

---

💡 说明：

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