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

562 lines
23 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 业务闭环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`
***
### 🔹 业务闭环总览(文字版流程图)
```text
多平台采集 → 数据清洗 → 前置套利计算
商品刊登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. 所有业务操作均需遵循项目特定规则,确保系统安全和数据一致性。
**“闭环写入规则:只要逻辑上能闭环就写,落地方式后置”**