diff --git a/.trae/rules/project-specific-rules.md b/.trae/rules/project-specific-rules.md index d8a4403..696750e 100644 --- a/.trae/rules/project-specific-rules.md +++ b/.trae/rules/project-specific-rules.md @@ -225,9 +225,67 @@ Step 5: 完成后释放占用 --- -## 8. 追踪与日志 +## 8. 逻辑集中化原则（硬性约束） -### 8.1 五元组必填 +### 8.1 核心原则 +> **逻辑集中化 → 服务驱动**：所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中。 + +### 8.2 逻辑分散的表现（禁止行为） +- ❌ **Controller 中写业务逻辑**：Controller 只负责请求/响应和权限校验 +- ❌ **前端直接写业务规则**：复杂计算、权限判断、状态流转禁止在 React 组件中实现 +- ❌ **数据库操作分散**：不同模块禁止直接调用数据库，必须通过 Service 层 +- ❌ **脚本或工具处理逻辑**：AI 任务或异步脚本必须通过 Service 层统一调用 + +### 8.3 逻辑分散的后果 +1. **维护成本高**：AI 或开发者需要理解多个模块才能做一件改动 +2. **修改容易出错**：改动一处可能引起其他模块逻辑不一致 +3. **难以快速迭代**：新功能闭环难以接入，因为逻辑散落在各处 +4. **收费闭环风险**：分散逻辑导致支付、权限、账单、状态不一致，直接影响收益 +5. **AI 维护困难**：AI 无法一次性理解完整闭环，状态不一致，修改风险高 + +### 8.4 服务层职责（强制执行） +#### Controller 层职责 +- 接收 HTTP 请求和参数验证 +- 调用 Service 层处理业务逻辑 +- 返回响应给前端 +- 权限校验（通过 `authorize()` 中间件） + +#### Service 层职责（核心） +- 业务逻辑编排和状态流转 +- 多模块协同和数据一致性保证 +- 事务管理和异常处理 +- 调用 Repository 层或外部 API + +#### Repository 层职责 +- 数据库 CRUD 操作 +- 数据模型映射 +- 查询优化 + +### 8.5 状态管理统一 +- **前端状态**：使用全局 Model 或状态管理库（Umi Model、Redux 等） +- **后端状态**：统一使用 STATE_MACHINE 定义的状态机 +- **状态流转**：所有状态更新必须通过 Service 层，禁止在 Controller 或前端直接修改 + +### 8.6 核心逻辑复用 +- **公共函数**：权限、价格、库存、账单等逻辑必须封装为公共函数或工具库 +- **服务接口**：AI 只需调用 Service 接口，不直接处理业务逻辑 +- **避免重复**：不同模块禁止重复实现相同逻辑 + +### 8.7 可视化业务流程 +- **流程图**：为每个业务闭环绘制流程图，便于 AI 理解 +- **状态机图**：使用 STATE_MACHINE 记录完整闭环 +- **服务地图**：完善 SERVICE_MAP，明确服务调用链 + +### 8.8 违反逻辑集中化原则的后果 +- **代码审查不通过**：任何违反逻辑集中化原则的代码将被拒绝合并 +- **AI 任务失败**：AI 无法维护分散的逻辑，导致任务执行失败 +- **生产环境风险**：分散逻辑导致数据不一致，直接影响系统稳定性 + +--- + +## 9. 追踪与日志 + +### 9.1 五元组必填 所有任务与日志必须携带： ```typescript { @@ -239,23 +297,23 @@ Step 5: 完成后释放占用 } ``` -### 8.2 状态机门禁 +### 9.2 状态机门禁 - 发布、审核、对账流程必须落入统一 FSM - **禁止**: Controller 中硬编码流程分支 --- -## 9. 代码质量门禁 +## 10. 代码质量门禁 -### 9.1 命名规范 +### 10.1 命名规范 - **服务类**: 统一使用 `Service` 后缀 - **禁止**: `Manager`/`Helper` 等后缀 -### 9.2 注释规范 +### 10.2 注释规范 - **必须**: 每个服务类包含完整 JSDoc - **必须**: 明确标识任务ID和功能描述 -### 9.3 部署标准 +### 10.3 部署标准 `completed` 的标志： 1. ✅ 数据库表已初始化 2. ✅ 核心逻辑已闭环 @@ -273,6 +331,7 @@ Step 5: 完成后释放占用 | 安全权限 | 使用 `authorize()` 中间件 | 权限漏洞 | | 性能边界 | Worker并发≤10, 内存≤4GB | 系统崩溃 | | 追踪日志 | 五元组必填 | 无法追溯 | +| **逻辑集中化** | **所有业务逻辑必须在Service层** | **AI维护困难，数据不一致** | | **任务领取** | **优先领任务包，最小2个任务** | **碎片化等待** | | **协作防撞** | **必须声明占用，先声明优先** | **重复开发** | diff --git a/docs/00_Business/Business_ClosedLoops.md b/docs/00_Business/Business_ClosedLoops.md index 6aca2fe..7ee2cb0 100644 --- a/docs/00_Business/Business_ClosedLoops.md +++ b/docs/00_Business/Business_ClosedLoops.md @@ -1663,230 +1663,230 @@ export default function(initialState: InitialState) { #### 数据采集与清洗闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| ------- | ---------- | --------- | -| 采集覆盖率 | 目标平台商品覆盖率 | TOC + TOB | -| 数据准确率 | 清洗后数据的准确性 | TOC + TOB | -| 套利分析准确率 | 前置套利计算的准确性 | TOC + TOB | +| KPI 指标 | 描述 | 适用业务类型 | +| ----------- | -------------------- | ----------- | +| 采集覆盖率 | 目标平台商品覆盖率 | TOC + TOB | +| 数据准确率 | 清洗后数据的准确性 | TOC + TOB | +| 套利分析准确率 | 前置套利计算的准确性 | TOC + TOB | #### 商品刊登闭环 -| 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 | #### 广告计划与营销闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| -------- | -------------- | ------ | -| 广告 ROI | 广告投入产出比 | TOC | -| 点击率（CTR） | 广告点击次数与展示次数的比率 | TOC | -| 转化率（CVR） | 点击广告后产生订单的比例 | 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 | +| 分批处理率 | 大额订单分批处理的比例 | TOB | #### 售后逆向闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| ------ | ------------- | --------- | -| 售后处理时效 | 从售后请求到处理完成的时间 | TOC + TOB | -| 退款成功率 | 成功退款的比例 | TOC + TOB | -| 退货率 | 退货订单占总订单的比例 | TOC + TOB | +| KPI 指标 | 描述 | 适用业务类型 | +| ---------- | -------------------- | ----------- | +| 售后处理时效 | 从售后请求到处理完成的时间 | TOC + TOB | +| 退款成功率 | 成功退款的比例 | TOC + TOB | +| 退货率 | 退货订单占总订单的比例 | TOC + TOB | #### 资金对账闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| ------ | ------------- | --------- | -| 对账准确率 | 对账差异率 | TOC + TOB | -| 对账时效 | 从数据汇总到对账完成的时间 | TOC + TOB | -| 异常处理率 | 需要人工处理的异常比例 | TOC + TOB | -| 账期遵守率 | 按合同约定账期结算的比例 | 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 | #### 供应链与供应商管理闭环 -| 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 指标 | 描述 | 适用业务类型 | +| ---------- | -------------------- | ----------- | +| 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 | +| 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 | #### 报表与分析闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| ------- | --------------- | --------- | -| 报表生成及时率 | 按时生成报表的比例 | TOC + TOB | -| 数据准确率 | 报表数据的准确性 | TOC + TOB | -| 分析洞察价值 | 分析结果对业务决策的价值 | TOC + TOB | -| 异常预警准确率 | 异常预警的准确性 | 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 | #### 定价与利润决策闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| ------- | ------------- | --------- | -| 定价准确率 | 建议售价与最优价格的偏差率 | TOC + TOB | -| 利润率达标率 | 达到目标利润率的商品比例 | TOC + TOB | -| 定价决策时效 | 从成本数据到定价决策的时间 | 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 | +| KPI 指标 | 描述 | 适用业务类型 | +| ------------- | ---------------------- | ----------- | +| 店铺健康评分 | 店铺整体健康状态评分 | TOC + TOB | +| 风险预警准确率 | 风险预警的准确性 | TOC + TOB | +| 干预措施有效性 | 干预后店铺健康度改善程度 | TOC + TOB | +| 违规率 | 违规事件发生频率 | TOC + TOB | +| 账号稳定性 | 账号正常运行时间比例 | TOC + TOB | #### 店铺隔离与自动化闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| --------- | ------------- | --------- | -| 店铺隔离成功率 | 成功隔离的店铺比例 | TOC + TOB | -| 自动化操作成功率 | 成功执行的自动化操作比例 | TOC + TOB | -| 异常恢复时长 | 异常从发生到恢复的时间 | TOC + TOB | -| 脚本异常率 | 脚本执行异常的比例 | TOC + TOB | -| 功能覆盖率 | 自动化覆盖的业务功能比例 | TOC + TOB | -| 镜像可用性 | 镜像正常运行时间比例 | TOC + TOB | -| 云API调用成功率 | 云服务商API调用成功率 | TOC + TOB | -| 资源利用率 | 镜像资源使用效率 | TOC + TOB | -| 自动登录成功率 | 镜像自动登录成功率 | TOC + TOB | -| 多云切换成功率 | 云服务商切换成功率 | TOC + TOB | -| 成本优化率 | 多云部署带来的成本优化比例 | TOC + TOB | +| KPI 指标 | 描述 | 适用业务类型 | +| --------------- | ---------------------- | ----------- | +| 店铺隔离成功率 | 成功隔离的店铺比例 | TOC + TOB | +| 自动化操作成功率 | 成功执行的自动化操作比例 | TOC + TOB | +| 异常恢复时长 | 异常从发生到恢复的时间 | TOC + TOB | +| 脚本异常率 | 脚本执行异常的比例 | TOC + TOB | +| 功能覆盖率 | 自动化覆盖的业务功能比例 | TOC + TOB | +| 镜像可用性 | 镜像正常运行时间比例 | TOC + TOB | +| 云API调用成功率 | 云服务商API调用成功率 | TOC + TOB | +| 资源利用率 | 镜像资源使用效率 | TOC + TOB | +| 自动登录成功率 | 镜像自动登录成功率 | 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 指标 | 描述 | 适用业务类型 | +| -------------- | ---------------------- | ----------- | +| SKU映射准确率 | 多平台SKU映射的准确性 | TOC + TOB | +| SKU生成时效 | SKU生成的平均时间 | TOC + TOB | +| 变体管理效率 | 变体属性管理的效率 | TOC + TOB | +| 库存同步准确率 | 多SKU库存同步的准确性 | TOC + TOB | #### 订单拆分与合并闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| -------- | -------------- | --------- | -| 拆分/合并准确率 | 订单拆分/合并的准确性 | TOC + TOB | -| 拆分/合并时效 | 订单拆分/合并的处理时间 | TOC + TOB | -| 物流成本优化率 | 拆分/合并带来的物流成本节约 | TOC + TOB | -| 客户满意度 | 拆分/合并订单的客户满意度 | TOC + TOB | +| KPI 指标 | 描述 | 适用业务类型 | +| -------------- | ---------------------- | ----------- | +| 拆分/合并准确率 | 订单拆分/合并的准确性 | TOC + TOB | +| 拆分/合并时效 | 订单拆分/合并的处理时间 | TOC + TOB | +| 物流成本优化率 | 拆分/合并带来的物流成本节约 | TOC + TOB | +| 客户满意度 | 拆分/合并订单的客户满意度 | TOC + TOB | #### 异常订单处理闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| ------ | ------------ | --------- | -| 异常处理率 | 成功处理的异常订单比例 | TOC + TOB | -| 异常处理时效 | 异常订单处理的平均时间 | TOC + TOB | -| 异常解决率 | 成功解决的异常订单比例 | TOC + TOB | -| 客户满意度 | 异常订单处理的客户满意度 | TOC + TOB | +| KPI 指标 | 描述 | 适用业务类型 | +| ---------- | -------------------- | ----------- | +| 异常处理率 | 成功处理的异常订单比例 | TOC + TOB | +| 异常处理时效 | 异常订单处理的平均时间 | TOC + TOB | +| 异常解决率 | 成功解决的异常订单比例 | TOC + TOB | +| 客户满意度 | 异常订单处理的客户满意度 | TOC + TOB | #### 物流策略与渠道选择闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| ------- | ---------- | --------- | -| 物流成本节约率 | 物流成本节约的比例 | TOC + TOB | -| 物流时效达标率 | 按时送达的订单比例 | TOC + TOB | -| 渠道选择准确率 | 物流渠道选择的准确性 | TOC + TOB | -| 物流跟踪覆盖率 | 可跟踪的物流订单比例 | TOC + TOB | +| KPI 指标 | 描述 | 适用业务类型 | +| ----------- | -------------------- | ----------- | +| 物流成本节约率 | 物流成本节约的比例 | TOC + TOB | +| 物流时效达标率 | 按时送达的订单比例 | TOC + TOB | +| 渠道选择准确率 | 物流渠道选择的准确性 | TOC + TOB | +| 物流跟踪覆盖率 | 可跟踪的物流订单比例 | TOC + TOB | #### 利润核算闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| ------- | ------------ | --------- | -| 利润计算准确率 | 利润计算的准确性 | TOC + TOB | -| 利润核算时效 | 利润核算的平均时间 | TOC + TOB | -| 成本分摊准确性 | 成本分摊的准确性 | TOC + TOB | -| 利润率达标率 | 达到目标利润率的订单比例 | TOC + TOB | +| KPI 指标 | 描述 | 适用业务类型 | +| ----------- | -------------------- | ----------- | +| 利润计算准确率 | 利润计算的准确性 | TOC + TOB | +| 利润核算时效 | 利润核算的平均时间 | TOC + TOB | +| 成本分摊准确性 | 成本分摊的准确性 | TOC + TOB | +| 利润率达标率 | 达到目标利润率的订单比例 | TOC + TOB | #### 用户/客户资产闭环 -| KPI 指标 | 描述 | 适用业务类型 | -| ------- | ------------- | --------- | -| 用户画像准确率 | 用户画像与实际行为的匹配度 | TOC + TOB | -| 客户价值提升率 | 客户平均价值增长比例 | TOC + TOB | -| 复购率 | 客户重复购买比例 | TOC + TOB | +| KPI 指标 | 描述 | 适用业务类型 | +| ----------- | ---------------------- | ----------- | +| 用户画像准确率 | 用户画像与实际行为的匹配度 | TOC + TOB | +| 客户价值提升率 | 客户平均价值增长比例 | TOC + TOB | +| 复购率 | 客户重复购买比例 | TOC + TOB | | 客户留存率 | 客户持续活跃的比例 | TOC + TOB | | 营销转化率 | 营销活动的转化效果 | TOC + TOB | diff --git a/docs/00_Business/Task_Overview.md b/docs/00_Business/Task_Overview.md index de06b6a..7086752 100644 --- a/docs/00_Business/Task_Overview.md +++ b/docs/00_Business/Task_Overview.md @@ -12,8 +12,8 @@ | -------------- | ----------- | -------------------------------------- | --------------------------------------------------------------------------------------- | ---------------- | ------ | | AI-Frontend-5 | 售后逆向闭环 | FE-SR001, FE-SR002, FE-SR003 | ReturnApply.tsx, RefundProcess.tsx, CustomerService.tsx | 2026-03-18 10:00 | ✅ 已完成 | | AI-Frontend-6 | B2B贸易管理闭环 | FE-TOB001, FE-TOB002, FE-TOB003 | EnterpriseQuote.tsx, BatchOrder.tsx, ContractManage.tsx | 2026-03-18 11:00 | ✅ 已完成 | -| AI-Backend-8 | 合规与证书管理闭环 | FE-COM001, FE-COM002, FE-COM003 | CertificateManage.tsx, ComplianceCheck.tsx | 2025-03-18 17:00 | ✅ 已完成 | -| AI-Analysis-3 | 广告计划与营销闭环 | AI-AD001, AI-AD002, AI-AD003 | AdOptimizationService.ts, BiddingStrategyService.ts, AdPredictionService.ts | 2025-03-18 21:00 | ✅ 已完成 | +| AI-Backend-8 | 合规与证书管理闭环 | FE-COM001, FE-COM002, FE-COM003 | CertificateManage.tsx, ComplianceCheck.tsx | 2026-03-18 17:00 | ✅ 已完成 | +| AI-Analysis-3 | 广告计划与营销闭环 | AI-AD001, AI-AD002, AI-AD003 | AdOptimizationService.ts, BiddingStrategyService.ts, AdPredictionService.ts | 2026-03-18 21:00 | ✅ 已完成 | | AI-Frontend-8 | 物流策略闭环 | FE-LOG001, FE-LOG002, FE-LOG003 | LogisticsSelect.tsx, LogisticsTrack.tsx, FreightCalc.tsx | 2026-03-18 12:00 | ✅ 已完成 | | AI-Frontend-9 | 订单履约闭环 | FE-O001, FE-O002, FE-O003, FE-O004 | OrderList.tsx, OrderDetail.tsx, OrderAggregation.tsx, ExceptionOrder.tsx | 2026-03-18 12:30 | ✅ 已完成 | | AI-Backend-9 | 商品刊登闭环 | FE-P002, FE-P003, FE-P004 | ProductDetail.tsx, ProductPublishForm.tsx, MaterialUpload.tsx | 2026-03-18 22:00 | ✅ 已完成 | @@ -28,8 +28,8 @@ | AI-Test-10 | 测试用例与质量保证 | OP-IT001, OP-IT002, OP-IT003, OP-IT004 | api.integration.test.ts, plugin.integration.test.ts, e2e.test.ts, tuple-tracing.test.ts | 2026-03-18 14:00 | ✅ 已完成 | | AI-Test-11 | 压力测试与安全测试 | OP-ST001, OP-ST003 | stress.test.ts, rbac.test.ts | 2026-03-18 15:00 | ✅ 已完成 | | AI-Plugin-12 | 广告计划与营销闭环插件 | PL-AD001, PL-AD002 | AdOperation.plugin.ts | 2026-03-18 23:30 | ✅ 已完成 | -| AI-Plugin-13 | 数据采集与自动化闭环 | PL-C002, PL-A001, PL-A002 | DOMParser.ts, FingerprintManager.ts, AutoShipService.ts | 2025-03-18 22:00 | ✅ 已完成 | -| AI-Plugin-13 | 物流策略与渠道选择闭环 | PL-A003 | LogisticsSyncService.ts | 2025-03-19 10:00 | ✅ 已完成 | +| AI-Plugin-13 | 数据采集与自动化闭环 | PL-C002, PL-A001, PL-A002 | DOMParser.ts, FingerprintManager.ts, AutoShipService.ts | 2026-03-18 22:00 | ✅ 已完成 | +| AI-Plugin-13 | 物流策略与渠道选择闭环 | PL-A003 | LogisticsSyncService.ts | 2026-03-19 10:00 | ✅ 已完成 | | AI-Plugin-4 | 物流策略闭环插件 | PL-LOG001, PL-LOG002 | LogisticsSync.plugin.ts | 2026-03-18 20:40 | ✅ 已完成 | | AI-Decision-1 | 定价与利润决策闭环 | AI-D001, AI-D002 | PricingDecisionService.ts, ExceptionAutoFixService.ts | 2026-03-18 23:30 | ✅ 已完成 | diff --git a/docs/01_Architecture/SERVICE_MAP.md b/docs/01_Architecture/SERVICE_MAP.md index d1d7a8b..4d69461 100644 --- a/docs/01_Architecture/SERVICE_MAP.md +++ b/docs/01_Architecture/SERVICE_MAP.md @@ -1,12 +1,41 @@ # SERVICE_MAP（服务编排总图） ## 设计原则 -- 所有业务必须通过 Service 层 -- Controller 不允许直接操作数据库 -- 一个业务 = 一条 Service Flow -- 服务调用必须遵循 STATE_MACHINE 定义的状态流转 -- 涉及收费的业务必须接入 BILLING 系统 -- 所有接口必须经过权限校验 + +### 核心原则（逻辑集中化） +> **所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中。** + +### 强制约束 +- ✅ **所有业务必须通过 Service 层**：禁止 Controller 直接操作数据库 +- ✅ **Controller 职责明确**：只负责请求/响应和权限校验 +- ✅ **一个业务 = 一条 Service Flow**：每个业务操作对应一个完整的服务流程 +- ✅ **服务调用必须遵循 STATE_MACHINE**：状态流转必须符合状态机定义 +- ✅ **涉及收费的业务必须接入 BILLING 系统**：支付、权限、账单必须闭环 +- ✅ **所有接口必须经过权限校验**：使用 `authorize()` 中间件 + +### 禁止行为 +- ❌ **Controller 中写业务逻辑**：业务决策、状态变化、数据校验必须在 Service 层 +- ❌ **前端直接写业务规则**：复杂计算、权限判断、状态流转禁止在 React 组件中实现 +- ❌ **数据库操作分散**：不同模块禁止直接调用数据库，必须通过 Service 层 +- ❌ **脚本或工具处理逻辑**：AI 任务或异步脚本必须通过 Service 层统一调用 + +### 服务层职责边界 +#### Controller 层职责 +- 接收 HTTP 请求和参数验证 +- 调用 Service 层处理业务逻辑 +- 返回响应给前端 +- 权限校验（通过 `authorize()` 中间件） + +#### Service 层职责（核心） +- 业务逻辑编排和状态流转 +- 多模块协同和数据一致性保证 +- 事务管理和异常处理 +- 调用 Repository 层或外部 API + +#### Repository 层职责 +- 数据库 CRUD 操作 +- 数据模型映射 +- 查询优化 --- diff --git a/docs/02_Backend/Service_Design.md b/docs/02_Backend/Service_Design.md index db7f794..0d5415d 100644 --- a/docs/02_Backend/Service_Design.md +++ b/docs/02_Backend/Service_Design.md @@ -8,13 +8,23 @@ ## 1. 服务层架构 -### 1.1 核心原则 +### 1.1 核心原则（逻辑集中化） -- **每个业务操作对应一个 Service**：前端的每个用户操作都必须有对应的后端 Service 处理 -- **服务编排**：通过 Service 层串联多个模块，实现业务流程的完整执行 -- **单一职责**：每个 Service 只负责一个核心业务领域 -- **依赖注入**：通过依赖注入实现服务间的解耦 -- **事务管理**：重要操作必须在事务中执行，确保数据一致性 +> **逻辑集中化 → 服务驱动**：所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中。 + +#### 强制约束 +- ✅ **每个业务操作对应一个 Service**：前端的每个用户操作都必须有对应的后端 Service 处理 +- ✅ **服务编排**：通过 Service 层串联多个模块，实现业务流程的完整执行 +- ✅ **单一职责**：每个 Service 只负责一个核心业务领域 +- ✅ **依赖注入**：通过依赖注入实现服务间的解耦 +- ✅ **事务管理**：重要操作必须在事务中执行，确保数据一致性 +- ✅ **状态管理统一**：所有状态更新必须通过 Service 层，禁止在 Controller 或前端直接修改 + +#### 禁止行为 +- ❌ **Controller 中写业务逻辑**：Controller 只负责请求/响应和权限校验，业务决策、状态变化、数据校验必须在 Service 层 +- ❌ **前端直接写业务规则**：复杂计算、权限判断、状态流转禁止在 React 组件中实现 +- ❌ **数据库操作分散**：不同模块禁止直接调用数据库，必须通过 Service 层 +- ❌ **脚本或工具处理逻辑**：AI 任务或异步脚本必须通过 Service 层统一调用 ### 1.2 服务层级结构 @@ -22,6 +32,26 @@ Controller → Service (核心编排) → Repository / External API → 数据库/外部系统 ``` +#### Controller 层职责（强制执行） +- 接收 HTTP 请求和参数验证 +- 调用 Service 层处理业务逻辑 +- 返回响应给前端 +- 权限校验（通过 `authorize()` 中间件） +- **禁止**：业务决策、状态变化、数据校验 + +#### Service 层职责（核心） +- 业务逻辑编排和状态流转 +- 多模块协同和数据一致性保证 +- 事务管理和异常处理 +- 调用 Repository 层或外部 API +- **必须**：所有业务逻辑必须在此层实现 + +#### Repository 层职责 +- 数据库 CRUD 操作 +- 数据模型映射 +- 查询优化 +- **禁止**：业务逻辑处理 + --- ## 2. 核心服务列表 diff --git a/docs/Development_Progress.md b/docs/Development_Progress.md index 0ac8cdb..f3eb6f8 100644 --- a/docs/Development_Progress.md +++ b/docs/Development_Progress.md @@ -19,18 +19,18 @@ ### 关键里程碑 | 里程碑 | 状态 | 预计完成时间 | 实际完成时间 | | ------ | ---- | ------------ | ------------ | -| 多商户业务闭环文档完善 | ✅ 已完成 | 2024-12-15 | 2024-12-15 | -| 服务编排地图（SERVICE_MAP） | ✅ 已完成 | 2024-12-16 | 2026-03-18 | -| 领域模型（DOMAIN_MODEL） | ✅ 已完成 | 2024-12-17 | 2026-03-18 | -| 状态机定义（STATE_MACHINE） | ✅ 已完成 | 2024-12-18 | 2026-03-18 | -| 功能开通服务实现 | ✅ 已完成 | 2024-12-19 | 2026-03-18 | -| 服务层代码实现与修复 | ✅ 已完成 | 2024-12-20 | 2026-03-18 | -| 前端服务启动 | ✅ 已完成 | 2024-12-21 | 2026-03-18 | -| 后端服务启动 | ✅ 已完成 | 2024-12-22 | 2026-03-18 | -| 前端优化 | ✅ 已完成 | 2024-12-23 | 2026-03-18 | -| 前端页面骨架创建 | ✅ 已完成 | 2024-12-24 | 2026-03-18 | -| 前端文档补充 | ✅ 已完成 | 2024-12-25 | 2026-03-18 | -| 系统集成测试 | ⏳ 待开始 | 2024-12-26 | - | +| 多商户业务闭环文档完善 | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 服务编排地图（SERVICE_MAP） | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 领域模型（DOMAIN_MODEL） | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 状态机定义（STATE_MACHINE） | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 功能开通服务实现 | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 服务层代码实现与修复 | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 前端服务启动 | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 后端服务启动 | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 前端优化 | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 前端页面骨架创建 | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 前端文档补充 | ✅ 已完成 | 2026-03-18 | 2026-03-18 | +| 系统集成测试 | 🔄 进行中 | 2026-03-19 | - | ## 📋 任务状态跟踪 @@ -86,14 +86,17 @@ 49. ✅ 补充Business_ClosedLoops.md附录C：前端组件规范（组件分类、状态管理、API交互、路由权限） 50. ✅ 补充Task_Overview.md附录A：前端交互任务补充（商品、订单、执行、数据、合规、设置交互任务） 51. ✅ 补充Task_Overview.md附录B：前端开发规范（技术栈、项目结构、组件、状态、API、路由权限） +52. ✅ 更新项目规则文档（project-specific-rules.md），加入逻辑集中化原则 +53. ✅ 更新SERVICE_MAP.md，强化服务层职责和调用规范 +54. ✅ 更新Service_Design.md，明确服务层设计规范和边界 ### 进行中任务 1. 🔄 系统集成测试 +2. 🔄 前端交互任务开发 ### 待开始任务 1. ⏳ 性能测试和优化 2. ⏳ 安全测试 -3. ⏳ 领取并完成前端交互任务（附录A中的FE-INT系列任务） ## 🏗️ 架构演进 @@ -123,6 +126,22 @@ /repository （数据层） ``` +### 逻辑集中化原则 +> **所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中。** + +#### 逻辑分散的表现（禁止行为） +- ❌ **Controller 中写业务逻辑**：Controller 只负责请求/响应和权限校验 +- ❌ **前端直接写业务规则**：复杂计算、权限判断、状态流转禁止在 React 组件中实现 +- ❌ **数据库操作分散**：不同模块禁止直接调用数据库，必须通过 Service 层 +- ❌ **脚本或工具处理逻辑**：AI 任务或异步脚本必须通过 Service 层统一调用 + +#### 逻辑分散的后果 +1. **维护成本高**：AI 或开发者需要理解多个模块才能做一件改动 +2. **修改容易出错**：改动一处可能引起其他模块逻辑不一致 +3. **难以快速迭代**：新功能闭环难以接入，因为逻辑散落在各处 +4. **收费闭环风险**：分散逻辑导致支付、权限、账单、状态不一致，直接影响收益 +5. **AI 维护困难**：AI 无法一次性理解完整闭环，状态不一致，修改风险高 + #### 服务层职责 一个服务 = 一个闭环 @@ -274,12 +293,20 @@ - **2026-03-18**：补充Business_ClosedLoops.md附录A、B、C，完善前端交互设计规范、页面映射和组件规范 - **2026-03-18**：补充Task_Overview.md附录A、B，完善前端交互任务和前端开发规范 - **2026-03-18**：确认50个业务闭环保持不变，仅在文档末尾添加附录，不改变原有结构 +- **2026-03-18**：完成docs目录下所有文档的重新排版，统一表格格式和文档结构 +- **2026-03-18**：更新开发进度互通文档，调整任务状态和下一步计划 +- **2026-03-18**：分析逻辑分散问题，确认其对AI维护的影响和解决方案 +- **2026-03-18**：更新项目规则文档（project-specific-rules.md），加入逻辑集中化原则 +- **2026-03-18**：更新SERVICE_MAP.md，强化服务层职责和调用规范 +- **2026-03-18**：更新Service_Design.md，明确服务层设计规范和边界 ### 关键洞察 1. **服务闭环与收费的关系**：服务闭环跟收费没有必然关系，收费只是把问题放大了。只要存在"状态流转 + 多模块协同"，就必须有服务闭环。 2. **不收费场景也需要服务闭环**：订单闭环、库存闭环、多商户分单等都需要服务层保证数据一致性。 3. **收费场景更容易暴露问题**：因为多了一条链（功能 → 支付 → 权限 → 使用 → 计费 → 结算），任何一个点错了都会直接损失钱。 4. **前端优化的重要性**：前端是用户直接接触的界面，其流畅性和功能完整性直接影响用户体验和系统的商业价值。 +5. **逻辑集中化的必要性**：逻辑分散导致AI难以维护，状态不一致，修改风险高。集中化逻辑到服务层 + 统一状态管理，AI才能高效维护和迭代。 +6. **服务层职责边界**：Controller只负责请求/响应和权限校验，Service层负责业务逻辑编排和状态流转，Repository层负责数据库操作。明确职责边界是逻辑集中化的基础。 ### AI开发建议 1. 优先进行系统集成测试，确保各服务之间的正确交互 @@ -289,19 +316,24 @@ 5. 严格执行"业务闭环优先"原则，避免碎片化开发 6. 按照前端优化策略，逐步实现组件化、状态管理和性能优化 7. 确保前端与后端的良好集成，实现数据的实时同步和交互的流畅性 +8. **严格执行逻辑集中化原则**：所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中 +9. **明确服务层职责边界**：Controller 只负责请求/响应和权限校验，Service 层负责业务逻辑编排和状态流转，Repository 层负责数据库操作 +10. **统一状态管理**：前端使用全局 Model 或状态管理库，后端统一使用 STATE_MACHINE 定义的状态机，所有状态更新必须通过 Service 层 ## 📝 下一步计划 -### 短期计划（1-3天） +### 短期计划（2026-03-19 至 2026-03-21） 1. 完成系统集成测试，验证服务层功能 2. 优化数据库查询和缓存策略 3. 实现完整的错误处理和日志记录 4. 进行性能测试和优化 5. 实现安全测试，确保系统安全性 -6. 领取并完成前端交互任务（Task_Overview.md附录A中的FE-INT系列任务） -7. 实现前端交互功能，包括筛选、排序、新增、编辑、定价、上架、同步等 +6. 完成前端交互任务开发，包括筛选、排序、新增、编辑、定价、上架、同步等 +7. **代码审查**：检查所有Controller、Service、Repository代码，确保符合逻辑集中化原则 +8. **重构优化**：将分散的业务逻辑迁移到Service层，确保职责边界清晰 +9. **测试验证**：验证逻辑集中化后的代码，确保功能正确性和数据一致性 -### 中期计划（4-7天） +### 中期计划（2026-03-22 至 2026-03-28） 1. 完善前端与后端的集成，实现数据实时同步 2. 补充二级闭环（功能收费闭环、权限控制闭环、商户账单闭环） 3. 部署系统到测试环境 @@ -309,7 +341,7 @@ 5. 完善前端组件库，实现组件复用 6. 实现前端状态管理，优化数据流 -### 长期计划（8-14天） +### 长期计划（2026-03-29 至 2026-04-11） 1. 部署系统到生产环境 2. 监控系统运行状态 3. 持续优化和迭代系统功能 @@ -334,9 +366,10 @@ 5. 避免逻辑分散，确保业务逻辑集中在服务层 ### 架构风险 -1. **逻辑分散风险**：如果在 Controller 中写业务逻辑，会导致逻辑分散，AI 无法维护 -2. **收费必炸风险**：没有完整的服务闭环，后期收费功能必定出现问题 -3. **数据一致性风险**：多商户场景下，没有服务层会导致商户归属混乱、结算错误 +1. **逻辑分散风险**：如果在 Controller 中写业务逻辑，会导致逻辑分散，AI 无法维护。逻辑分散导致AI难以追踪业务流程、状态流转不统一、重复逻辑、难以保证一致性、代码依赖复杂。 +2. **收费必炸风险**：没有完整的服务闭环，后期收费功能必定出现问题。分散逻辑导致支付、权限、账单、状态不一致，直接影响收益。 +3. **数据一致性风险**：多商户场景下，没有服务层会导致商户归属混乱、结算错误。 +4. **AI维护困难风险**：逻辑分散让 AI 无法一次性理解完整闭环，状态不一致，修改风险高。集中化逻辑到服务层 + 统一状态管理，AI 才能高效维护和迭代。 ## 📞 联系方式 diff --git a/docs/临时修改建议 copy.MD b/docs/临时修改建议 copy.MD index e69de29..f588ebc 100644 --- a/docs/临时修改建议 copy.MD +++ b/docs/临时修改建议 copy.MD @@ -0,0 +1,100 @@ +我把“逻辑分散 → AI难维护”这个问题拆开，详细分析下原因、表现和影响，以及可行的解决思路。 + +--- + +## 1️⃣ 问题本质 + +**逻辑分散**指的是业务逻辑没有集中在服务层，而散布在不同模块中，例如： + +* **Controller 中写逻辑**：Controller 除了接收请求和返回响应，还处理业务决策、状态变化、数据校验。 +* **前端直接写逻辑**：复杂计算、权限判断、状态流转直接在 React 组件或页面中实现。 +* **数据库操作分散**：不同模块直接调用数据库，导致状态更新不统一。 +* **脚本或工具处理逻辑**：AI 任务或异步脚本单独处理业务逻辑，没有统一调用入口。 + +--- + +## 2️⃣ AI 维护难的原因 + +AI 的核心优势是**理解和处理规则化逻辑**，逻辑分散导致 AI 难维护主要有以下几个原因： + +1. **难以追踪业务流程** + + * 业务步骤可能跨多个文件或模块，AI 无法一次性获取完整流程。 + * 例如，订单闭环：支付、库存锁定、订单创建、账单生成分别在不同文件处理，AI 需要先分析依赖关系，再理解流程。 + +2. **状态流转不统一** + + * 状态可能在多个地方更新，缺乏中心化状态管理。 + * AI 很难判断状态真实值和变化条件，导致任务调度或逻辑判断出错。 + +3. **重复逻辑** + + * 不同模块可能重复实现相同逻辑（如权限判断、价格计算）。 + * AI 难以判断哪个逻辑是“权威版本”，容易修改错地方。 + +4. **难以保证一致性** + + * 分散逻辑容易导致边缘情况处理不统一（例如异常、支付失败、库存不足）。 + * AI 在优化或修复逻辑时，可能漏掉某些分散的处理点。 + +5. **代码依赖复杂** + + * 分散逻辑意味着调用链不清晰，AI 在修改或推理时必须解析跨文件依赖。 + * 对于大型多商户系统，这种复杂度呈指数级增长。 + +--- + +## 3️⃣ 典型表现 + +* Controller 内部有大量 `if/else` + 异步调用 +* 前端页面直接处理业务规则（如价格、折扣、库存判断） +* 数据库更新在多个 Service/Repository 之外被调用 +* AI 执行任务时，需要在不同模块中查找状态和规则 + +--- + +## 4️⃣ 后果 + +1. **维护成本高** + + * AI 或开发者需要理解多个模块才能做一件改动。 +2. **修改容易出错** + + * 改动一处可能引起其他模块逻辑不一致。 +3. **难以快速迭代** + + * 新功能闭环难以接入，因为逻辑散落在各处。 +4. **收费闭环风险** + + * 分散逻辑导致支付、权限、账单、状态不一致，直接影响收益。 + +--- + +## 5️⃣ 解决策略 + +**核心原则：逻辑集中化 → 服务驱动** + +1. **服务层集中业务逻辑** + + * Controller 只负责请求/响应和权限校验。 + * Service 层负责业务闭环、状态流转和多模块协同。 + +2. **状态管理统一** + + * 前端使用全局 Model 或状态管理库（Umi Model、Redux 等）。 + * 后端统一使用状态机或闭环处理状态。 + +3. **复用核心逻辑** + + * 公共函数或工具库统一处理权限、价格、库存、账单等逻辑。 + * AI 只需调用 Service 接口，不直接处理业务逻辑。 + +4. **可视化业务流程** + + * 使用流程图或状态机图记录完整闭环，让 AI 可快速理解流程。 + * 前端交互和后端服务逻辑保持一致。 + +--- + +💡 **总结一句话**： +逻辑分散让 AI 无法一次性理解完整闭环，状态不一致，修改风险高；集中化逻辑到服务层 + 统一状态管理，AI 才能高效维护和迭代。 diff --git a/docs11/00-documentation-layer.md b/docs11/00-documentation-layer.md deleted file mode 100644 index b0070b1..0000000 --- a/docs11/00-documentation-layer.md +++ /dev/null @@ -1,964 +0,0 @@ -# 📌 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. [定价与利润决策闭环](#1️⃣5️⃣-定价与利润决策闭环pricing--profit-decision-loop) -16. [账号/店铺健康度闭环](#1️⃣6️⃣-账号/店铺健康度闭环accountshop-health-loop) -17. [店铺隔离与自动化闭环](#1️⃣7️⃣-店铺隔离与自动化闭环shop-isolation--automation-loop) -18. [订单集中管理闭环](#1️⃣8️⃣-订单集中管理闭环order-centralized-management-loop) -19. [客户/商家押金与账户管理闭环](#1️⃣9️⃣-客户商家押金与账户管理闭环customer-merchant-deposit--account-management-loop) -20. [商家选择发货闭环](#2️⃣0️⃣-商家选择发货闭环merchant-selective-fulfillment-loop) -21. [回款与财务闭环](#2️⃣1️⃣-回款与财务闭环payment--financial-reconciliation-loop) -22. [海外仓/本土仓 & 多品类支持闭环](#2️⃣2️⃣-海外仓本土仓--多品类支持闭环overseaslocal-warehouse--multi-category-support-loop) -23. [商品主数据闭环](#2️⃣3️⃣-商品主数据闭环product-master-data-loop--mdm) -24. [SKU变体与结构闭环](#2️⃣4️⃣-sku变体与结构闭环sku-variant--structure-loop) -25. [订单拆分与合并闭环](#2️⃣5️⃣-订单拆分与合并闭环order-split--merge-loop) -26. [异常订单处理闭环](#2️⃣6️⃣-异常订单处理闭环exception-order-handling-loop) -27. [物流策略与渠道选择闭环](#2️⃣7️⃣-物流策略与渠道选择闭环logistics-strategy--channel-selection-loop) -28. [利润核算闭环](#2️⃣8️⃣-利润核算闭环profit-calculation-loop) -29. [用户/客户资产闭环](#2️⃣9️⃣-用户客户资产闭环usercustomer-asset-loop) -30. [A/B测试与策略优化闭环](#3️⃣0️⃣-ab测试与策略优化闭环ab-testing--strategy-optimization-loop) -31. [统一闭环依赖](#🔹-统一闭环依赖toc--tob) -32. [闭环依赖关系](#🔗-闭环依赖关系toc--tob) -33. [关键绩效指标](#📊-关键绩效指标kpi) -34. [追踪与审计](#🔍-追踪与审计) -35. [业务审核状态机](#📋-业务审核状态机) -36. [说明](#💡-说明) - -*** - -## 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` - -*** - -## 1️⃣5️⃣ 定价与利润决策闭环（Pricing & Profit Decision Loop） - -- **目标**：基于成本、市场和业务目标，自动生成定价策略和利润优化建议。 -- **流程**： - - 成本数据收集 → 市场分析 → 定价策略生成 → 利润预测 → 决策执行 -- **决策点**： - - 利润率红线控制（B2C < 20% 预警，B2B < 15% 禁止） - - 价格弹性分析 - - 竞争定价策略 -- **输入**：商品成本、运费、平台费、广告预估、市场竞争数据 -- **输出**： - - 建议售价 - - 建议 ROI - - 上架决策（开/关） - - 广告投放 ROI 区间 - - 最大可承受 CPA - -*** - -## 1️⃣6️⃣ 账号/店铺健康度闭环（Account/Shop Health Loop） - -- **目标**：监控和维护店铺健康状态，预防封号、限流等风险。 -- **流程**： - - 数据采集 → 健康度评估 → 风险预警 → 干预措施 -- **决策点**： - - 健康度阈值设定 - - 风险等级划分 - - 干预策略制定 -- **输入**：违规记录、发货延迟、差评率、退款率、账号活动数据 -- **输出**： - - 店铺健康评分 - - 风险预警 - - 干预建议（暂停广告、限制上新、下架高风险商品） - -*** - -## 1️⃣7️⃣ 店铺隔离与自动化闭环（Shop Isolation & Automation Loop） - -- **目标**： - 1. 确保每个 TOC / TOB 店铺环境隔离，防止账号关联导致封禁 - 2. 自动化执行 API 不支持或无 API 的操作（刊登、采集、调价、库存同步等） - 3. 支持多云环境，可灵活选择云服务商（阿里云、腾讯云、AWS、Azure 等） -- **流程**： - 1. **镜像/虚拟机管理** - - 每个店铺对应独立云镜像或虚拟机（Win/Linux 可选） - - 云商 API 对接： - - 镜像购买 / 续费 - - 快照 / 重置 - - 开机 / 关机 / 重启 - - 支持多云商切换，可根据价格、性能、地理位置灵活部署 - 2. **预置环境配置** - - 浏览器、自动化脚本、指纹管理工具、VPN 或固定 IP 配置 - - 自动登录店铺账户，无需人工干预 - 3. **任务调度与自动化执行** - - 脚本调度可使用 JS / Python / 后端 API 方式控制 - - 支持平台无 API 操作（如商品采集、库存更新、手动刊登模拟等） - - 自动执行任务后状态反馈至任务调度闭环，并记录日志 - 4. **监控与异常自愈** - - 云镜像健康监控（在线状态、资源使用、脚本异常） - - 自动重启 / 快照恢复 / 切换备用镜像 - - 异常信息反馈至异常检测与自愈闭环 -- **决策点**： - - 店铺隔离等级（独立镜像、不同 IP、不同指纹） - - 云商选择与成本控制 - - 异常处理策略（自动恢复或人工介入） -- **输入**： - - 店铺列表、业务需求（采集、刊登、广告等） - - 云商账户与资源配置 - - 自动化脚本 / 后端控制接口 -- **输出**： - - 各店铺独立镜像环境 - - 自动化执行日志与状态报告 - - 异常修复记录 -- **闭环价值**： - 1. 高度隔离，降低账号封禁与关联风险 - 2. 自动化落地，提高效率与可扩展性 - 3. 支持多云部署，增强业务弹性和成本优化能力 - -*** - -## 1️⃣8️⃣ 订单集中管理闭环（Order Centralized Management Loop） - -- **目标**：跨平台订单统一抓取、集中展示和管理，支持 TOC/TOB 订单流转。 -- **流程**： - 1. **多平台订单采集** - - 支持 TikTok、Shopee、Temu 等平台订单抓取 - - 通过 API 或自动化脚本采集 - 2. **订单集中展示** - - 产品信息：名称、数量、实收价格、订单时间、状态 - - 支持平台/客户/品类/订单状态筛选 - - 可选漏斗分析：订单流转、发货完成率 - 3. **订单状态管理** - - 状态流转：`available → requested → shipped → completed` - - 订单分配与跟踪 -- **决策点**： - - 订单抓取频率 - - 订单优先级设置 - - 异常订单处理策略 -- **输入**： - - 多平台订单数据 - - 店铺信息 - - 客户/商家信息 -- **输出**： - - 集中管理的订单数据 - - 订单状态报告 - - 异常订单标记 - -*** - -## 1️⃣9️⃣ 客户/商家押金与账户管理闭环（Customer/Merchant Deposit & Account Management Loop） - -- **目标**：管理客户预缴押金、账户余额，支持订单抵扣和提现。 -- **流程**： - 1. **押金管理** - - 客户预缴押金（例：100 元抵 2 单） - - 押金余额、已抵扣订单数量记录 - 2. **账户管理** - - 客户可查看：可申请发货订单、历史回款、押金/余额状态 - - 自动扣减押金或余额完成发货操作 - 3. **提现管理** - - 检查账户余额 → 生成提现单 → 审核 → 打款 -- **决策点**： - - 押金抵扣规则 - - 提现审核流程 - - 余额管理策略 -- **输入**： - - 客户押金信息 - - 订单数据 - - 提现申请 -- **输出**： - - 押金/余额状态 - - 提现处理结果 - - 财务流水记录 - -*** - -## 2️⃣0️⃣ 商家选择发货闭环（Merchant Selective Fulfillment Loop） - -- **目标**：商家可选择自己有库存的订单发货，剩余由平台/公司发货。 -- **流程**： - 1. **订单选择** - - 商家登录落地页选择自己有货的订单发货 - 2. **系统检查** - - 押金或余额是否足够覆盖订单 - - 时效性（保证订单不过期） - 3. **订单状态更新** - - 状态流转：`available → requested → shipped → completed` - - 剩余无货订单由平台/公司自己发货 -- **决策点**： - - 订单分配规则 - - 库存检查策略 - - 时效保证机制 -- **输入**： - - 商家库存信息 - - 订单数据 - - 押金/余额状态 -- **输出**： - - 订单分配结果 - - 发货状态更新 - - 异常订单标记 - -*** - -## 2️⃣1️⃣ 回款与财务闭环（Payment & Financial Reconciliation Loop） - -- **目标**：管理客户付款、押金抵扣、回款记录和提现，确保财务透明。 -- **流程**： - 1. **收款管理** - - 客户付款到店铺账户或系统自动扣押金/余额 - 2. **财务流水记录** - - 类型（押金/回款/提现）、金额、订单ID、状态 - - 状态流转：`pending → approved → completed` - 3. **财务对账** - - 店铺收入 ↔ 客户账户余额 - - 异常订单/回款标记 → 自动或人工处理 -- **决策点**： - - 回款确认机制 - - 对账频率 - - 异常处理流程 -- **输入**： - - 客户付款信息 - - 订单数据 - - 押金/余额状态 -- **输出**： - - 财务流水记录 - - 对账结果 - - 提现处理结果 - -*** - -## 2️⃣2️⃣ 海外仓/本土仓 & 多品类支持闭环（Overseas/Local Warehouse & Multi-Category Support Loop） - -- **目标**：统一管理海外仓和本土仓库存，支持多品类分配和上下游分析。 -- **流程**： - 1. **库存管理** - - 海外仓和本土仓库存统一管理 - - 可按品类、仓库位置、时效性分配发货 - 2. **上下游分析** - - 供应商价格对比 - - 成本/利润/ROI 分析 - - 同行发货/库存策略参考 -- **决策点**： - - 仓库选择策略 - - 品类分配规则 - - 供应链优化策略 -- **输入**： - - 仓库库存数据 - - 供应商信息 - - 订单数据 -- **输出**： - - 库存分配方案 - - 供应链分析报告 - - 成本优化建议 - -*** - -## 2️⃣3️⃣ 商品主数据闭环（Product Master Data Loop / MDM） - -- **目标**：建立统一的商品主数据管理体系，确保数据一致性。 -- **流程**： - - 数据采集 → 标准化处理 → 主数据维护 → 数据分发 -- **决策点**： - - 数据标准制定 - - 数据质量评估 - - 数据同步策略 -- **输入**：来自采集、供应链、刊登等闭环的商品数据 -- **输出**： - - 统一 SPU/SKU 体系 - - 标准化类目和属性结构 - - 多语言支持 - - 多平台映射关系 - -*** - -## 1️⃣9️⃣ SKU变体与结构闭环（SKU Variant & Structure Loop） - -- **目标**：管理商品的变体和多平台SKU映射，确保库存和订单的一致性。 -- **流程**： - - SPU创建 → SKU生成 → 平台SKU映射 → 同步管理 -- **决策点**： - - 变体属性定义 - - 多平台SKU规则适配 - - 库存同步策略 -- **输入**：商品主数据、平台SKU规则 -- **输出**： - - 多SKU结构（颜色/尺寸/套装） - - 各平台SKU映射 - - 统一库存管理 - -*** - -## 2️⃣0️⃣ 订单拆分与合并闭环（Order Split & Merge Loop） - -- **目标**：处理多仓发货、多订单合并、部分缺货等场景，优化物流成本和时效。 -- **流程**： - - 订单分析 → 拆分/合并决策 → 子订单生成 → 履约执行 -- **决策点**： - - 拆分类型（仓/SKU/库存） - - 合并条件 - - 优先级策略 -- **输入**：订单数据、库存状态、物流成本 -- **输出**： - - 子订单 - - 合并订单 - - 物流方案 - -*** - -## 2️⃣1️⃣ 异常订单处理闭环（Exception Order Handling Loop） - -- **目标**：处理地址错误、海关卡单、物流丢件、无法发货等履约异常。 -- **流程**： - - 异常检测 → 分类处理 → 解决方案执行 → 结果反馈 -- **决策点**： - - 异常类型识别 - - 处理优先级 - - 人工介入条件 -- **输入**：订单数据、物流状态、异常事件 -- **输出**： - - 异常处理结果 - - 售后触发 - - 风控预警 - -*** - -## 2️⃣2️⃣ 物流策略与渠道选择闭环（Logistics Strategy & Channel Selection Loop） - -- **目标**：基于成本、时效和可靠性，选择最优物流方案。 -- **流程**： - - 订单分析 → 物流渠道评估 → 方案选择 → 执行监控 -- **决策点**： - - 仓选择 - - 物流方式（空运/海运/快递） - - 渠道选择 -- **输入**：订单数据、库存分布、物流成本、时效要求 -- **输出**： - - 物流渠道选择 - - 成本估算 - - 时效承诺 - -*** - -## 2️⃣3️⃣ 利润核算闭环（Profit Calculation Loop） - -- **目标**：精确计算真实利润，支持定价和决策优化。 -- **流程**： - - 成本汇总 → 收入匹配 → 利润计算 → 分析报告 -- **决策点**： - - 成本分摊规则 - - 汇率处理 - - 利润阈值设定 -- **输入**：商品成本、运费、广告费、平台佣金、税费、汇率数据 -- **输出**： - - 订单级利润 - - 商品级利润 - - 店铺级利润 - - 利润分析报告 - -*** - -## 2️⃣4️⃣ 用户/客户资产闭环（User/Customer Asset Loop） - -- **目标**：沉淀和管理用户资产，支持精准营销和客户价值提升。 -- **流程**： - - 数据采集 → 用户画像构建 → 行为分析 → 资产运营 -- **决策点**： - - 用户分层策略 - - 营销触达规则 - - 客户价值评估 -- **输入**：订单数据、浏览行为、购买历史、售后记录 -- **输出**： - - 用户画像 - - 复购行为分析 - - 国家偏好分析 - - 客户价值评估 - - 营销建议 - -*** - -## 2️⃣5️⃣ A/B测试与策略优化闭环（A/B Testing & Strategy Optimization Loop） - -- **目标**：通过实验验证和数据驱动，持续优化业务策略。 -- **流程**： - - 测试设计 → 实验执行 → 数据收集 → 结果分析 → 策略调整 -- **决策点**： - - 测试假设设定 - - 样本量确定 - - 显著性水平设定 -- **输入**：广告策略、商品定价、页面设计、营销文案 -- **输出**： - - 测试结果分析 - - 策略优化建议 - - 最优方案推荐 - -*** - -### 🔹 统一闭环依赖（TOC + TOB） - -```text -[数据采集] ↓[数据清洗] ↓[套利/利润评估] ↓[商品主数据] ↓[SKU变体与结构] ↓[商品刊登] ←→ [素材管理] ↓[定价与利润决策] ↓[广告/营销 (TOC) / 企业营销 (TOB)] ↓[订单履约 (OMS)] ↓[订单拆分与合并] ↓[异常订单处理] ↓[物流策略与渠道选择] ↓[库存 & WMS] ←→ [供应链 & 补货] ↓[售后逆向] ↓[资金对账] ↓[利润核算] ↓[B2B/TOB 贸易管理 (TOB)] ↓[用户/客户资产] ↓[A/B测试 & 策略优化] ↓[治理与审批中心] ↓[合规 & 证书] ↓[风控] ↓[报表 & 分析] ↺（反馈所有环节） - -外挂三条线： -用户资产 ← 订单 / 售后 → 广告 / B2B -店铺健康度 ← 所有行为 → 限制商品 / 广告 -店铺隔离与自动化 ← 店铺操作 → 所有店铺相关行为 -``` - -**说明**： - -- 实线箭头表示核心业务流程 -- 括号内标注了TOC/TOB的主要差异点 -- B2B/TOB贸易管理为TOB特有闭环 -- 横切能力：账号/店铺健康度贯穿所有业务闭环 - -*** - -### 🔗 闭环依赖关系（TOC + TOB） - -1. **数据采集与清洗闭环** → **商品主数据闭环**：提供原始商品数据 -2. **数据采集与清洗闭环** → **素材管理闭环**：提供采集的商品图片和视频素材 -3. **数据采集与清洗闭环** → **定价与利润决策闭环**：提供成本和市场数据 -4. **商品主数据闭环** → **SKU变体与结构闭环**：提供商品基础信息 -5. **SKU变体与结构闭环** → **商品刊登闭环**：提供多SKU结构和平台映射 -6. **商品刊登闭环** → **素材管理闭环**：触发素材需求，生成商品主图和详情图 -7. **素材管理闭环** → **商品刊登闭环**：提供处理后的商品素材（图片、视频） -8. **素材管理闭环** → **广告计划与营销闭环**：提供广告投放所需的素材库 -9. **商品刊登闭环** → **广告计划与营销闭环**：提供已刊登商品列表 -10. **商品刊登闭环** → **订单履约闭环**：提供商品库存和状态信息 -11. **商品刊登闭环** → **定价与利润决策闭环**：提供商品成本信息 -12. **定价与利润决策闭环** → **商品刊登闭环**：提供建议售价和上架决策 -13. **定价与利润决策闭环** → **广告计划与营销闭环**：提供可投放 ROI 区间和最大可承受 CPA -14. **订单履约闭环** → **订单拆分与合并闭环**：提供订单数据用于拆分/合并 -15. **订单拆分与合并闭环** → **物流策略与渠道选择闭环**：提供拆分/合并后的订单数据 -16. **物流策略与渠道选择闭环** → **订单履约闭环**：提供物流方案 -17. **订单履约闭环** → **异常订单处理闭环**：提供异常订单数据 -18. **异常订单处理闭环** → **售后逆向闭环**：触发售后处理 -19. **异常订单处理闭环** → **合规与风控闭环**：提供风控预警 -20. **订单履约闭环** → **售后逆向闭环**：提供订单和物流信息 -21. **售后逆向闭环** → **资金对账闭环**：提供退款记录 -22. **订单履约闭环** → **资金对账闭环**：提供销售记录 -23. **广告计划与营销闭环** → **资金对账闭环**：提供广告费用记录 -24. **订单履约闭环** → **库存与仓储管理闭环**：触发库存扣减和物流操作 -25. **库存与仓储管理闭环** → **订单履约闭环**：提供库存状态和物流信息 -26. **库存与仓储管理闭环** → **供应链与供应商管理闭环**：触发补货需求 -27. **供应链与供应商管理闭环** → **库存与仓储管理闭环**：提供采购入库信息 -28. **供应链与供应商管理闭环** → **商品主数据闭环**：提供供应商商品数据 -29. **商品刊登闭环** → **B2B / TOB 贸易管理闭环**：提供商品信息用于报价 -30. **B2B / TOB 贸易管理闭环** → **订单履约闭环**：生成 B2B 订单 -31. **B2B / TOB 贸易管理闭环** → **资金对账闭环**：提供 B2B 交易记录 -32. **资金对账闭环** → **利润核算闭环**：提供收入和成本数据 -33. **利润核算闭环** → **报表与分析闭环**：提供利润数据 -34. **订单履约闭环** → **用户/客户资产闭环**：提供订单和用户行为数据 -35. **售后逆向闭环** → **用户/客户资产闭环**：提供售后记录 -36. **用户/客户资产闭环** → **广告计划与营销闭环**：提供用户画像和营销建议 -37. **用户/客户资产闭环** → **B2B / TOB 贸易管理闭环**：提供企业客户信息 -38. **广告计划与营销闭环** → **A/B测试与策略优化闭环**：提供广告策略数据 -39. **商品刊登闭环** → **A/B测试与策略优化闭环**：提供商品定价和展示数据 -40. **A/B测试与策略优化闭环** → **报表与分析闭环**：提供测试结果和优化建议 -41. **所有敏感操作** → **治理与审批中心闭环**：触发审批流程 -42. **治理与审批中心闭环** → **所有业务闭环**：提供审批结果 -43. **订单履约闭环** → **合规与证书管理闭环**：触发证书生成 -44. **合规与证书管理闭环** → **订单履约闭环**：提供合规证书 -45. **所有业务闭环** → **账号/店铺健康度闭环**：提供违规记录、发货延迟、差评率、退款率等数据 -46. **账号/店铺健康度闭环** → **广告计划与营销闭环**：提供是否暂停广告、降预算的决策 -47. **账号/店铺健康度闭环** → **商品刊登闭环**：提供是否限制上新、下架高风险商品的决策 -48. **所有店铺操作** → **店铺隔离与自动化闭环**：提供店铺操作数据 -49. **店铺隔离与自动化闭环** → **所有店铺相关行为**：提供隔离环境和自动化执行能力 -50. **所有闭环** → **合规与风控闭环**：提供全流程数据用于风险监控 -51. **所有业务闭环** → **报表与分析闭环**：提供各闭环的输出数据用于报表生成和分析 -52. **报表与分析闭环** → **所有业务闭环**：反馈数据异常、业务波动、优化建议，指导各闭环的操作调整 - -*** - -### 📊 关键绩效指标（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 | - -#### 定价与利润决策闭环 - -| KPI 指标 | 描述 | 适用业务类型 | -| ------- | ------------- | --------- | -| 定价准确率 | 建议售价与最优价格的偏差率 | TOC + TOB | -| 利润率达标率 | 达到目标利润率的商品比例 | TOC + TOB | -| 定价决策时效 | 从成本数据到定价决策的时间 | 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 | -| 镜像可用性 | 镜像正常运行时间比例 | TOC + TOB | -| 云API调用成功率 | 云服务商API调用成功率 | 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 | - -#### 异常订单处理闭环 - -| KPI 指标 | 描述 | 适用业务类型 | -| ------ | ------------ | --------- | -| 异常处理率 | 成功处理的异常订单比例 | TOC + TOB | -| 异常处理时效 | 异常订单处理的平均时间 | TOC + TOB | -| 异常解决率 | 成功解决的异常订单比例 | TOC + TOB | -| 客户满意度 | 异常订单处理的客户满意度 | TOC + TOB | - -#### 物流策略与渠道选择闭环 - -| KPI 指标 | 描述 | 适用业务类型 | -| ------- | ---------- | --------- | -| 物流成本节约率 | 物流成本节约的比例 | TOC + TOB | -| 物流时效达标率 | 按时送达的订单比例 | 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 | - -#### A/B测试与策略优化闭环 - -| KPI 指标 | 描述 | 适用业务类型 | -| ------- | ------------ | --------- | -| 测试执行效率 | 测试从设计到完成的时间 | TOC + TOB | -| 测试结果显著性 | 测试结果的统计显著性 | 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. **“闭环写入规则：只要逻辑上能闭环就写，落地方式后置”** -8. **系统层级结构**： - - L1（业务闭环）：交易系统核心流程 - - L2（系统决策层）：定价、风控、健康度等系统级能力 - - L3（数据中台层）：商品主数据、成本基准等数据管理能力 - - L4（自动化与增长）：任务调度、A/B测试、用户资产等高级能力 -9. **横切能力**：账号健康度、任务调度、权限审计等能力贯穿所有业务闭环，确保系统稳定性和安全性。 - -*** - diff --git a/docs11/01-business-core/business-blueprint.md b/docs11/01-business-core/business-blueprint.md deleted file mode 100644 index 786975e..0000000 --- a/docs11/01-business-core/business-blueprint.md +++ /dev/null @@ -1,115 +0,0 @@ -# 🏢 Business Blueprint (Crawlful Hub) - -> **定位**：Crawlful Hub 业务核心蓝图 - 包含项目目标、技术栈、核心业务模块、状态机及行业标杆参考。 -> **更新日期**: 2026-03-17 - ---- - -## 1. 项目概述 (Project Overview) - -**项目名称**: Crawlful Hub (跨境电商增长中台) - -**项目目标**: -- 实现多渠道电商运营管理（TOC/TOB）。 -- 提供从商品采集到财务对账的完整业务闭环。 -- 提升跨境贸易运营效率与利差套利能力。 - -**主要技术栈**: -- **语言**: TypeScript -- **前端框架**: UmiJS 4.x, Ant Design 5.x -- **后端框架**: Node.js 20+ -- **数据库**: MySQL 8.0 (cf_ 前缀) -- **缓存**: Redis 6.0 - ---- - -## 2. 核心业务模块 (Core Business Modules) - -### 2.1 闭环总览 ⭐⭐⭐ - -#### 闭环验收标准 (P0) -- **商品刊登闭环**: ERP 商品 → 平台可售。要求全链路追踪 (traceId)。 -- **订单履约闭环**: 平台订单 → 妥投。状态机完整，异常可介入。 -- **售后逆向闭环**: 售后请求 → 退款完成。状态流转清晰。 -- **资金对账闭环**: platform 结算流水 → 差异关闭。汇率明确，可回溯。 -- **合规风控闭环**: 风险信号 → 拦截/复核。审计留痕。 - -#### 追踪四元组 (Tracking Quad) -- `tenantId`: 租户 ID (业务隔离) -- `shopId`: 店铺 ID (平台/店铺隔离) -- `taskId`: 任务 ID (任务/规则触发归档) -- `traceId`: 链路追踪 ID (全链路唯一标识) - -### 2.2 模块功能详述 - -#### 1. 商品管理 (PIM) & 跨平台套利 (Arbitrage) -- **跨平台套利雷达**: 自动识别 1688 (价格洼地) 与 Amazon/Temu/eBay (价格高地) 的利差。支持视觉寻源与多模态匹配。 -- **套利净利引擎**: 统一计算口径 `售价 - 采购 - 平台费 - 物流 - 税费 - 汇率对冲 - 售后损耗 - 广告摊销`。 -- **风险门禁**: B2C 利润率 < 20% 触发预警，利润率 < 15% 或 ROI < 20% 标记为高风险，< 5% 强制拦截。 -- **SPU/SKU 管理**: 支持独立站 (Shopify/WooCommerce) 与平台电商的多维度属性映射。 -- **刊登任务**: 支持无 API 平台 (TikTok/Temu) 模拟执行与官方 API 刊登。 - -#### 2. 订单管理 (OMS) & TOB 业务 -- **多渠道归集**: 聚合平台订单与独立站 (DTC) 订单。 -- **TOB 报价红线**: B2B 利润率 < 15% 严禁报价，支持大宗贸易的阶梯价设置与询盘转化。 -- **分账引擎**: 针对 TOB 业务支持主权级信用池 (Sovereign Credit Pool) 与跨境结算审计。 -- **利润核算**: 实时计算单笔订单净利，关联广告支出实现全链路 ROI 溯源。 - -#### 3. 库存与仓储 (WMS) -- **多仓协同**: 实时同步全球多仓库存，支持独立站与平台库存共享/隔离策略。 -- **补货算法**: `(销量预测 * 采购周期 + 安全库存 - 在途)`。支持基于利差热力图的智能补货决策。 -- **入/出库流**: ASN 预报、QC 质检、波次拣货。 - -#### 4. 财务与结算 -- **成本归集**: 采购、头程/尾程物流、佣金、广告。 -- **多币种对账**: ZKP 隐私审计，自动差异匹配。 -- **汇率避险**: 联动多币种汇率避险接口，锁定汇率风险，记录汇兑损益。 - -#### 5. 营销与广告 (MKT) -- **跨平台投放**: 统一管理 Facebook, Google, TikTok 广告。 -- **独立站 DTC 策略**: 针对独立站流量进行全链路归因分析 (Multi-touch Attribution)。 -- **动态优化**: 基于 ROAS 自动调整预算，监控盈亏平衡点 (Break-even ROAS)。 -- **套利闭环回流**: 从选品建议到真实销量回流，持续迭代套利策略。 - ---- - -## 3. 关键业务状态机 (State Machines) - -### 3.1 订单状态机 -- `PULLED` → `PENDING_REVIEW` → `CONFIRMED` → `ALLOCATED` → `READY_TO_SHIP` → `SHIPPED` → `DELIVERED` → `CLOSED` - -### 3.2 业务审核状态机 -- `SUBMITTED` (提交) → `PENDING_REVIEW` (人工审核) → `EXECUTED` / `REJECTED` - ---- - -## 4. 行业标杆复刻方案 (Benchmarks) - -- **ERP 系统**: 像素级还原易仓、店小秘核心逻辑。 -- **TikTok 运营**: 实现 91 妙手同级的无 API 履约与采集能力。 -- **数据分析**: 船长 BI 级的数据归集与可视化看板。 - ---- - -## 5. 项目结构与目录映射 (Directory Map) - -``` -project - ├─ .trae/rules/ # 编码与项目特定规则 - ├─ docs/ # 分类文档 (业务、数据、架构、规范、质量) - ├─ server/src/ # 后端服务 (api, service, repository, domains, workers) - ├─ extension/src/ # 浏览器插件 (background, content) - ├─ console/src/ # 前端控制台 (pages, components, services, stores) -``` - ---- - -## 6. 实施指南摘要 (Implementation Guides) - -### 6.1 TOC 加速架构 -- **快速上线**: 提供 Amazon/AliExpress 基础订单同步。 -- **ConsumerOrderService**: 专责 TOC 订单流。 - -### 6.2 非 SaaS 多租户隔离 -- **数据独占**: `tenant_id` 逻辑隔离，行级安全校验。 -- **资源配额**: 严格限制并发 Worker 与 API 速率。 diff --git a/docs11/01-business-core/业务9.md b/docs11/01-business-core/业务9.md deleted file mode 100644 index 1e06095..0000000 --- a/docs11/01-business-core/业务9.md +++ /dev/null @@ -1,77 +0,0 @@ - ---- - -## 9. 套利与定价分析 (ARB / Pricing) — TOC + TOB + 汇率支持 - -### 核心定位 - -* **零售（TOC） + 批发/整柜（TOB）套利分析** -* 覆盖 **生产 → 拿货 → 平台销售**全链路 -* 支持 **定价推荐、ROI 模拟、利润预测、汇率自动换算** -* 支持跨国、跨仓、多币种利润计算 - -### 核心功能 - -1. **成本与利润测算** - - * 支持 **固定成本与浮动成本**组合（采购、生产、物流、平台费、广告、关税等） - * **汇率换算**：自动获取实时汇率，将外币成本/售价换算成目标结算币种 - * 输出每 SKU 或整柜商品 **售价/ROI/签收利润** - -2. **定价推荐与模拟** - - * 自动推荐售价区间以满足目标毛利率或 ROI 红线 - * 支持多币种定价、不同平台价格差异 - * 可以模拟不同库存、销量、物流方式和汇率波动下的利润 - -3. **套利机会发现** - - * **跨平台零售套利**：采集价格或手动录入成本分析价差 - * **跨阶段 TOB 套利**：生产采购成本 vs 批发/整柜售价 - * **跨国家 / 跨仓套利**：结合汇率、关税、仓储成本、物流费用计算净利润 - -4. **供应链阶段利润分析** - - * **生产阶段**：原材料采购、工厂成本、生产周期成本 - * **拿货阶段**：整柜成本、运输成本、报关费用、税费（多币种换算） - * **零售阶段**：平台费用、广告投入、物流派送、售后成本 - -5. **多维度分析报表** - - * 商品维度、阶段维度、平台 / 渠道维度、时间维度 - * 汇率敏感性分析：利润随汇率变化的浮动曲线 - ---- - -### 业务流示意（文字版） - -```text -生产阶段 / 原材料采购（支持多币种） - │ - ▼ -拿货 / 整柜阶段（FCL/TOB） - │ - ▼ -套利分析模块（TOB + TOC + 汇率换算） - ├─ 成本测算（固定/浮动/汇率调整） - ├─ 定价推荐 & ROI 模拟 - ├─ 跨平台 / 跨阶段套利机会 - └─ 汇率敏感性分析 & 全链路利润报表 - │ - ▼ -商品刊登 / 调价执行（多平台 / 多币种） - │ - ▼ -OMS / WMS / 财务 / 营销全链路闭环 -``` - ---- - -💡 **特点说明** - -* 汇率处理贯穿 **TOB 和 TOC 全链路** -* 支持多币种采购、整柜成本、平台销售价格统一计算 -* 可进行 **利润随汇率波动的敏感性分析**，为定价策略提供数据支持 -* 套利模块成为全链路利润智能分析引擎，同时支撑 **零售、批发、整柜、跨国贸易** - ---- diff --git a/docs11/02-data-api/data-api-specs.md b/docs11/02-data-api/data-api-specs.md deleted file mode 100644 index b859a2f..0000000 --- a/docs11/02-data-api/data-api-specs.md +++ /dev/null @@ -1,88 +0,0 @@ -# 📊 Data & API Specifications (Crawlful Hub) - -> **定位**：Crawlful Hub 数据架构与接口规格书 - 包含数据库 Schema、核心业务流程及全量 API 定义。 -> **更新日期**: 2026-03-17 - ---- - -## 1. 数据库结构 (Data Schema) - -### 1.1 命名规范 -- **表前缀**: `cf_` (crawlful) -- **字段命名**: snake_case -- **金額字段**: `decimal(10,2)` 或更高精度。 -- **物理单位**: 长度 (cm), 重量 (kg), 体积 (m³)。 - -### 1.2 核心表定义 - -#### 租户与用户 -- `cf_tenant`: 租户 ID、名称、配额、状态。 -- `cf_user`: 邮箱、密码哈希、角色 (ADMIN/MANAGER 等)、租户 ID。 - -#### 店铺与商品 -- `cf_shop`: 租户 ID、平台 (AMAZON/TIKTOK 等)、授权 Token。 -- `cf_product`: 租户 ID、源平台 ID、标题、描述、JSON 图片列表。 -- `cf_product_sku`: SKU 编码、属性 JSON、成本价、零售价、重量/尺寸。 - -#### 订单与库存 -- `cf_inventory`: SKU ID、仓库 ID、总数量、可用/预留数量。 -- `cf_order`: 平台订单号、总金额、货币、利润/利润率、状态。 -- `cf_order_item`: 订单项、SKU ID、单价、数量。 - -#### 供应链与财务 -- `cf_supplier`: 供应商名称、联系方式、评分、状态。 -- `cf_purchase_order`: 采购单号、供应商 ID、总金额、状态。 -- `cf_finance_reconciliation`: 对账周期、总销售/利润、差异状态。 - ---- - -## 2. 核心业务流程 (Business Processes) - -### 2.1 商品采集与刊登 (Collection & Listing) -1. **采集**: 用户输入 URL → Extension 解析 DOM → 发送至 Hub 草稿箱。 -2. **刊登**: 选择草稿 → 平台适配器转换字段 → 调用平台 API 发布 → 记录刊登历史。 - -### 2.2 订单履约与财务 (Fulfillment & Finance) -1. **订单**: 平台 Webhook 推送 → 解析并入库 → 利润审计 (红线校验) → 状态流转。 -2. **库存**: 平台同步 → 更新本地库存 → 低于阈值自动触发补货提醒。 -3. **对账**: 拉取平台账单 → 自动差异匹配 → 生成报告 → 人工审核异常项。 - ---- - -## 3. 全量 API 端点映射 (API Map) - -### 3.1 基础管理 -- `POST /api/auth/login`: 用户登录。 -- `GET /api/users`: 获取用户列表。 -- `GET /api/shops`: 获取授权店铺。 - -### 3.2 商品与库存 (Product & Inventory) -- `GET /api/products`: 获取商品列表。 -- `POST /api/products/publish`: 发布商品到平台。 -- `GET /api/inventory/aging`: 库存老化分析。 -- `GET /api/inventory/forecast`: 库存预测。 - -### 3.3 订单与支付 (Order & Payment) -- `GET /api/orders`: 获取订单列表。 -- `PUT /api/orders/:id/status`: 更新订单状态。 -- `POST /api/payments`: 创建支付订单。 -- `POST /api/payments/callback`: 处理支付回调。 - -### 3.4 财务管理 (Finance) -- `GET /api/finance/reconciliation`: 财务对账。 - ---- - -## 4. 通用响应与状态码 - -### 响应格式 -```typescript -{ - "success": true, - "data": { ... }, - "error": "optional error message" -} -``` - -### 常用状态码 -- `200`: 成功 | `401`: 未授权 | `403`: 禁止访问 | `404`: 资源不存在 | `500`: 服务器错误。 diff --git a/docs11/03-architecture-tech/module-blueprints.md b/docs11/03-architecture-tech/module-blueprints.md deleted file mode 100644 index 18b95a5..0000000 --- a/docs11/03-architecture-tech/module-blueprints.md +++ /dev/null @@ -1,72 +0,0 @@ -# 🎨 Module Blueprints (Crawlful Hub) - -> **定位**：Crawlful Hub 业务模块前端集成蓝图 - 包含核心业务功能的前端实现与交互设计。 -> **更新日期**: 2026-03-17 - ---- - -## 1. 订单管理模块 (OMS) - -### 1.1 订单工作台 (oms-workbench.md) -- **场景**: 统一订单归集、分润与基础状态流转。 -- **功能**: 多渠道筛选、批量审核/发货、异常标记。 - -### 1.2 订单利润分析 (order-profit-analysis.md) -- **核心逻辑**: 销售收入 - 采购成本 - 平台费 - 物流 - 税费。 -- **交互**: 订单列表下钻、利润红线预警。 - -### 1.3 物流健康状态 (logistics-health-ui.md) -- **监控**: 多渠道实时轨迹遥测、异常节点告警 (48h+ 停留)。 - ---- - -## 2. 财务管理模块 (FIN) - -### 2.1 财务对账 (finance-recon.md) -- **场景**: 平台账单拉取、自动差异匹配、对账差异关闭。 -- **机制**: ZKP 隐私审计，差异项可回溯到订单明细。 - -### 2.2 多币种对账 (multi-currency-recon.md) -- **功能**: 多币种换算口径、汇率自动同步。 - -### 2.3 平台费用监控 (platform-fee-watcher-ui.md) -- **场景**: 实时监控平台收取的各类佣金、广告投入与退款流水。 - ---- - -## 3. 库存管理模块 (WMS) - -### 3.1 库存老化分析 (inventory-aging-ui.md) -- **功能**: 分析周转天数、识别呆滞库存。 - -### 3.2 库存预测与补货 (inventory-forecast-replenishment.md) -- **算法**: `(销量预测 * 采购周期 + 安全库存 - 在途)`。 - -### 3.3 库存计划 (stock-planner-ui.md) -- **场景**: 基于销售预测与仓库健康度制定采购需求池。 - ---- - -## 4. 供应商与客户管理 (SCM/CRM) - -### 4.1 供应商产能监控 (supplier-capacity-watch.md) -- **场景**: 评估供应商交付准时率、质量评分与实时产能状态。 - -### 4.2 CRM 客户管理 (crm-hub.md) -- **功能**: 客户 360 视图、订单历史、客诉记录与信用分级。 - ---- - -## 5. 营销与广告管理 (MKT) - -### 5.1 广告计划看板 (ad-campaign-dashboard.md) -- **场景**: 跨平台广告投放监控与预算动态优化。 -- **功能**: ROAS 实时监控、自动调价建议、亏损活动预警。 - ---- - -## 6. 交付标准 (Delivery Standards) - -- **UI/UX**: 符合 Ant Design 5.x 规范，具备加载状态与错误处理。 -- **API**: 每一个按钮点击必须生成 `AuditLog`，携带 `traceId`。 -- **校验**: 所有功能需通过 Shadow-Test (最小冒烟测试)。 diff --git a/docs11/03-architecture-tech/system-architecture.md b/docs11/03-architecture-tech/system-architecture.md deleted file mode 100644 index 99fea57..0000000 --- a/docs11/03-architecture-tech/system-architecture.md +++ /dev/null @@ -1,69 +0,0 @@ -# 🏗 System Architecture (Crawlful Hub) - -> **定位**：Crawlful Hub 系统架构与设计蓝图 - 包含后端、前端、插件、事件总线及项目依赖规则。 -> **更新日期**: 2026-03-17 - ---- - -## 1. 架构总览 (Architecture Overview) - -### 1.1 核心目标 -- **业务闭环**：构建完整的跨境电商贸易管理系统。 -- **高可用性**：确保多渠道订单与库存同步的准确性与稳定性。 - -### 1.2 三层系统架构 -- **Console (前端中控台)**：统一登录、订单管理、商品刊登、财务对账、经营报表。 -- **Hub (后端服务层)**：业务逻辑处理、数据持久化、任务调度、消息通知。 -- **Extension (边缘执行层)**： - - 插件负责轻量采集、DOM 解析与自动化执行； - - 负责指纹隔离与环境自检。 - ---- - -## 2. 后端技术架构 (Backend Infra) - -### 2.1 技术栈与目录 -- **Runtime**: Node.js v20+, TypeScript (Strict Mode). -- **Domains (领域)**: Trade, Finance, Product, Logistics, Supplier. -- **Service (逻辑)**: 领域操作、仓储协调、定价计算。 -- **Repository (存储)**: 数据库查询 (Knex.js)、缓存策略 (Redis)。 - -### 2.2 事件总线架构 (Event Bus) -- **机制**: 异步通信、削峰填谷、系统解耦。 -- **应用**: 跨域同步（如：订单创建后触发库存预留、财务预记账）。 - ---- - -## 3. 前端与插件设计 (Frontend & Extension) - -### 3.1 前端控制台 (Console) -- **核心模式**: 业务审核工作流 (Business-Review-Workflow)。 -- **状态管理**: **Zustand** (全局状态) + **TanStack Query** (服务端缓存)。 -- **全链路溯源**: 每一笔操作必须绑定 `traceId`，UI 可视化操作链路。 - -### 3.2 插件端 (Extension) -- **采集引擎**: 多平台适配器 (1688, Amazon, Shopee)。 -- **执行逻辑**: 接收 Hub 指令，在浏览器侧模拟点击、填充表单。 -- **安全**: 独立 Proxy 配置、指纹隔离、速率限制。 - ---- - -## 4. 项目结构与依赖规则 (Project Structure) - -### 4.1 允许的依赖方向 (Allowed) -- `API` → `Service` → `Repository` → `Models` -- `Service` → `Utils` -- `Domains` → `Service` - -### 4.2 禁止的依赖方向 (Forbidden) -- **Repository ✗ Service**: 下层不能依赖上层。 -- **API ✗ Repository**: 接口层严禁直接操作数据库。 -- **Service ✗ API**: 业务逻辑层不应感知 HTTP 请求。 - ---- - -## 5. 关键状态机与流程 (State Machines) - -- **有 API 平台**: 走 `Connector Bus` 标准协议。 -- **无 API 平台**: 走 `No-API Bridge`，采用 `Collect -> Clean -> Review -> Publish` 流程。 -- **统一发布编排**: 由 `PublishOrchestrator` 统一管理。 diff --git a/docs11/04-standards-governance/governance-standards.md b/docs11/04-standards-governance/governance-standards.md deleted file mode 100644 index 0f48f04..0000000 --- a/docs11/04-standards-governance/governance-standards.md +++ /dev/null @@ -1,63 +0,0 @@ -# 📋 Governance & Standards (Crawlful Hub) - -> **定位**：Crawlful Hub 治理与开发规范 - 包含开发风格、协作协议、任务规格及运维治理。 -> **更新日期**: 2026-03-17 - ---- - -## 1. 开发规范 (Development Standards) - -### 1.1 核心准则 -- **职责单一**: 一个文件只包含一个类或一组高度相关的函数。 -- **Zero-Mock**: 严禁在生产代码中使用硬编码的模拟数据。 -- **契约优先**: 接口定义应先于实现。 - -### 1.2 代码风格与规模限制 -- **命名**: 文件使用 `kebab-case`，组件 `PascalCase`，变量 `camelCase`。 -- **严格模式**: 开启 TypeScript `strict: true`，严禁使用 `any`。 -- **限制**: 单文件 ≤ 1500 行，单函数 ≤ 120 行，UI 组件 ≤ 300 行。 - ---- - -## 2. 任务规格与代码注释 (Task & JSDoc) - -### 2.1 任务规格模板 (Task Template) -- **ID**: `[FE/BE/EX]_[序号]` (FE: 前端, BE: 后端, EX: 插件)。 -- **验收**: 功能测试通过、符合规范、文档同步更新。 - -### 2.2 代码注释 (JSDoc) -每个服务类必须包含完整的 JSDoc，明确标注任务 ID： -```typescript -/** - * [BE_60] 订单自动对账服务 (Order Reconciliation) - * @description 核心逻辑：比对平台结算单与系统订单差异。 - * @version 1.0 - */ -export class ReconciliationService { ... } -``` - ---- - -## 3. 协作协议 (Collaboration Protocol) - -### 3.1 核心原则 -- **原子性认领**: 认领前必须先修改状态，防止并发冲突。 -- **超时释放**: 2 小时未更新进度，任务自动释放。 -- **状态定义**: ⏳ `pending` (待办), 🔒 `claimed` (已认领), 🚧 `in_progress` (进行中), ✅ `completed` (已完成)。 - -### 3.2 协作流程 -1. **检查**: 确认任务状态为 `pending`。 -2. **锁定**: 修改状态为 `claimed [负责人] @ HH:MM`。 -3. **归档**: 完成后更新看板与相关文档。 - ---- - -## 4. 运维治理与风险 (Ops & Governance) - -### 4.1 上线前检查 (Deployment Checklist) -- 数据库表初始化 (cf_ 前缀)。 -- 核心逻辑闭环、通过代码校验。 -- 产出配套的最小冒烟测试。 - -### 4.2 风险登记 (Risk Registry) -- 记录系统风险、缓解措施与负责人。 diff --git a/docs11/05-quality-optimization/quality-optimization.md b/docs11/05-quality-optimization/quality-optimization.md deleted file mode 100644 index 077730c..0000000 --- a/docs11/05-quality-optimization/quality-optimization.md +++ /dev/null @@ -1,44 +0,0 @@ -# 💎 Quality & Optimization (Crawlful Hub) - -> **定位**：Crawlful Hub 质量保障与内容优化 - 包含前端交付标准、UX 检查清单及文档内容分析报告。 -> **更新日期**: 2026-03-17 - ---- - -## 1. 前端交付质量标准 (Frontend Delivery) - -### 1.1 UI/UX 规范 -- **框架**: UmiJS 4.x, Ant Design 5.x. -- **交互模式**: 业务审核工作流 (Business-Review-Workflow). -- **Red Lines (严禁事项)**: 严禁 Mock 数据、严禁越权修改、严禁敏感数据暴露。 - -### 1.2 性能优化 -- **加载**: Code Splitting, Lazy Loading. -- **请求**: TanStack Query 缓存, 减少重渲染. - ---- - -## 2. 用户体验检查清单 (UX Checklist) - -### 2.1 加载与响应 -- [ ] 异步操作展示 Loading 状态。 -- [ ] 长时操作展示进度。 -- [ ] 按钮点击反馈即时。 - -### 2.2 错误与异常 -- [ ] 4xx 错误展示具体根因分析，而非模糊的“系统错误”。 -- [ ] 5xx 错误展示友好提示并记录 `traceId`。 - ---- - -## 3. 文档内容分析报告 (Document Review) - -### 3.1 质量与优化 -- **命名规范**: 文件名必须使用小写短横线 (kebab-case)。 -- **分类存放**: `docs/blueprints/`, `docs/quality/` 等。 -- **引用闭环**: 文档内引用必须使用完整 Markdown 链接。 -- **原子化更新**: 每次功能变更必须同步更新对应蓝图。 - -### 3.2 文档地图 -- 建议维护 `doc-index.md` 索引，确保全量文档导航。 -- 定期审查文档结构，确保与物理文件系统保持一致。 diff --git a/docs11/Crawlful_Hub_Task_Overview_Full_v1.md b/docs11/Crawlful_Hub_Task_Overview_Full_v1.md deleted file mode 100644 index 694ae43..0000000 --- a/docs11/Crawlful_Hub_Task_Overview_Full_v1.md +++ /dev/null @@ -1,37 +0,0 @@ -# 🗂 Crawlful Hub 任务总览 (Task Overview) - -> **说明**：带优先级颜色、时间、负责人字段，用于项目进度跟踪与多方协作。 - -| 任务 ID | 模块 | 描述 | 状态 | 优先级 | 依赖 | 预计耗时 | 开始时间 | 完结时间 | 负责人 | -| ----- | ---- | ---------- | --------- | ---- | --------- | ---- | ---- | ---- | --- | -| P001 | 商品管理 | 实现商品上架接口 | ✅ completed | 🔴 高 | - | 2h | 2026-03-16 | 2026-03-16 | Operator-1 | -| P002 | 商品管理 | 商品列表分页接口 | ✅ completed | 🟠 中 | P001 | 1h | 2026-03-16 | 2026-03-16 | Operator-2 | -| P003 | 商品管理 | 商品详情接口 | ✅ completed | 🟠 中 | P001 | 1.5h | 2026-03-16 | 2026-03-16 | Operator-3 | -| P004 | 商品管理 | 商品图片上传逻辑 | ✅ completed | 🟠 中 | P001 | 2h | 2026-03-16 | 2026-03-16 | Operator-1 | -| O001 | 订单管理 | 订单归集逻辑 | 🚧 in_progress | 🔴 高 | P001 | 3h | 2026-03-17 | - | Operator-2 | -| O002 | 订单管理 | 订单状态更新接口 | 🚧 in_progress | 🟠 中 | O001 | 1.5h | 2026-03-17 | - | Operator-2 | -| O003 | 订单管理 | 订单异常处理 | ⏳ pending | 🟠 中 | O001 | 2h | - | - | - | -| O004 | 订单管理 | 订单导出功能 | ⏳ pending | 🟢 低 | O002 | 1h | - | - | - | -| F001 | 财务管理 | 对账接口 | 🚧 in_progress | 🔴 高 | O002 | 2h | 2026-03-17 | - | Operator-3 | -| F002 | 财务管理 | 发票生成逻辑 | ⏳ pending | 🟠 中 | F001 | 2h | - | - | - | -| F003 | 财务管理 | 财务报表导出 | ⏳ pending | 🟠 中 | F001 | 1.5h | - | - | - | -| FE001 | 前端 | 商品列表页面渲染 | ✅ completed | 🔴 高 | P001 | 4h | 2026-03-16 | 2026-03-16 | Operator-1 | -| FE002 | 前端 | 商品详情页面渲染 | ⏳ pending | 🟠 中 | P003 | 3h | - | - | - | -| FE003 | 前端 | 订单列表页面 | 🚧 in_progress | 🔴 高 | O001 | 3h | 2026-03-17 | - | Operator-1 | -| FE004 | 前端 | 订单详情页面 | ⏳ pending | 🟠 中 | O002 | 3h | - | - | - | -| EX001 | 插件端 | 无 API 平台采集 | ✅ completed | 🔴 高 | - | 3h | 2026-03-16 | 2026-03-16 | Operator-1 | -| EX002 | 插件端 | DOM 解析逻辑 | 🚧 in_progress | 🟠 中 | EX001 | 2h | 2026-03-17 | - | Operator-2 | -| EX003 | 插件端 | 任务状态回传 | ⏳ pending | 🔴 高 | EX001 | 2h | - | - | - | -| S001 | 认证服务 | 用户登录与鉴权 | ✅ completed | 🔴 高 | - | 3h | 2026-03-17 | 2026-03-17 | Operator-1 | -| I001 | 库存管理 | 库存同步引擎 | ✅ completed | 🔴 高 | P001 | 2h | 2026-03-16 | 2026-03-16 | Operator-3 | - ---- - -✅ **特点**： - -1. 高优先级用 🔴，中优先级 🟠，低优先级 🟢 -2. 可填充 **开始时间/完结时间/负责人** -3. 状态列规则：`pending → claimed → in_progress → completed/failed` -4. 依赖列可快速判断任务执行顺序 - ---- diff --git a/docs11/README.md b/docs11/README.md deleted file mode 100644 index e916cd9..0000000 --- a/docs11/README.md +++ /dev/null @@ -1,71 +0,0 @@ -# Docs11 - 文档目录 - -## 📋 项目简介 - -本目录包含项目的详细文档，按照不同的主题进行组织。 - -## 🚀 核心文档 - -### 1. 业务核心 -- **文件**: `01-business-core/business-blueprint.md` -- **功能**: 业务蓝图 -- **文件**: `01-business-core/业务9.md` -- **功能**: 业务相关文档 - -### 2. 数据API -- **文件**: `02-data-api/data-api-specs.md` -- **功能**: 数据API规范 - -### 3. 架构技术 -- **文件**: `03-architecture-tech/module-blueprints.md` -- **功能**: 模块蓝图 -- **文件**: `03-architecture-tech/system-architecture.md` -- **功能**: 系统架构 - -### 4. 标准治理 -- **文件**: `04-standards-governance/governance-standards.md` -- **功能**: 治理标准 - -### 5. 质量优化 -- **文件**: `05-quality-optimization/quality-optimization.md` -- **功能**: 质量优化 - -### 6. 其他文档 -- **文件**: `00-documentation-layer.md` -- **功能**: 文档分层 -- **文件**: `Crawlful_Hub_Task_Overview_Full_v1.md` -- **功能**: 任务总览完整版 -- **文件**: `doc-index.md` -- **功能**: 文档索引 -- **文件**: `业务功能.md` -- **功能**: 业务功能 -- **文件**: `临时修改建议 copy.MD` -- **功能**: 临时修改建议 - -## 📁 项目结构 - -``` -docs11/ -├── 01-business-core/ # 业务核心 -│ ├── business-blueprint.md # 业务蓝图 -│ └── 业务9.md # 业务相关文档 -├── 02-data-api/ # 数据API -│ └── data-api-specs.md # 数据API规范 -├── 03-architecture-tech/ # 架构技术 -│ ├── module-blueprints.md # 模块蓝图 -│ └── system-architecture.md # 系统架构 -├── 04-standards-governance/ # 标准治理 -│ └── governance-standards.md # 治理标准 -├── 05-quality-optimization/ # 质量优化 -│ └── quality-optimization.md # 质量优化 -├── 00-documentation-layer.md # 文档分层 -├── Crawlful_Hub_Task_Overview_Full_v1.md # 任务总览完整版 -├── doc-index.md # 文档索引 -├── 业务功能.md # 业务功能 -├── 临时修改建议 copy.MD # 临时修改建议 -└── README.md # 项目说明 -``` - -## 🤝 贡献 - -欢迎贡献文档和提出建议！请先阅读项目文档，然后提交 Pull Request。 diff --git a/docs11/doc-index.md b/docs11/doc-index.md deleted file mode 100644 index cd98ae6..0000000 --- a/docs11/doc-index.md +++ /dev/null @@ -1,56 +0,0 @@ -# 📚 Crawlful Hub Documentation Index - -> **说明**: 本文件是项目的深度索引，将全量文档聚合为核心蓝图与规格书，帮助开发者快速定位。 -> **核心任务表**: [Crawlful_Hub_Task_Overview_Full_v1.md](Crawlful_Hub_Task_Overview_Full_v1.md) (唯一业务到模块任务表) - ---- - -## 1️⃣ 业务核心 (01-business-core) -> 业务战略、功能蓝图、行业标杆 - -| 文件 | 说明 | -|------|------| -| [business-blueprint.md](01-business-core/business-blueprint.md) | **核心蓝图**: 包含项目目标、业务闭环、模块功能及标杆参考 (Merged) | -| [业务功能.md](业务功能.md) | **功能详述**: 聚合了订单、库存、财务、调价、广告等全量业务操作细节 (Updated) | - ---- - -## 2️⃣ 数据与 API (02-data-api) -> 数据 Schema、业务流程、接口规格 - -| 文件 | 说明 | -|------|------| -| [data-api-specs.md](02-data-api/data-api-specs.md) | **数据接口规格**: 包含数据库 Schema、核心业务流程图及全量 API 映射 (Merged) | - ---- - -## 3️⃣ 架构与技术 (03-architecture-tech) -> 系统架构、模块蓝图、技术栈 - -| 文件 | 说明 | -|------|------| -| [system-architecture.md](03-architecture-tech/system-architecture.md) | **系统架构**: 包含后端、前端、插件架构设计及依赖规则 (Merged) | -| [module-blueprints.md](03-architecture-tech/module-blueprints.md) | **功能蓝图**: 包含 OMS, WMS, Finance, MKT 等模块的前端集成蓝图 (Merged) | - ---- - -## 4️⃣ 规范与治理 (04-standards-governance) -> 开发标准、协作协议、运维治理 - -| 文件 | 说明 | -|------|------| -| [governance-standards.md](04-standards-governance/governance-standards.md) | **治理规范**: 包含开发标准、JSDoc 规范、协作协议及风险治理 (Refactored) | - ---- - -## 5️⃣ 质量与优化 (05-quality-optimization) -> 交付标准、体验检查、文档报告 - -| 文件 | 说明 | -|------|------| -| [quality-optimization.md](05-quality-optimization/quality-optimization.md) | **质量标准**: 包含前端交付质量标准、UX 检查清单及文档优化报告 (Merged) | - ---- - -### 📂 归档 (Archive) -- [archive/](archive/) - 历史方案、旧版任务记录 diff --git a/docs11/业务功能.md b/docs11/业务功能.md deleted file mode 100644 index 0f3f7fa..0000000 --- a/docs11/业务功能.md +++ /dev/null @@ -1,195 +0,0 @@ -# 📦 Crawlful Hub 业务功能汇总（Business Functions） - -> **定位**：核心业务功能规格书，整合了各模块及操作逻辑，排除 AGI 技术架构，仅保留业务逻辑。 - -*** - -## 1. 核心业务闭环 (Business Loops) - -- **商品刊登闭环**: ERP 商品 (SPU/SKU) → 平台可售。支持刊登任务重试、失败定位、全链路追踪。 -- **订单履约闭环**: 平台订单拉取 → 妥投/关闭。支持分仓/占库/扣库、发货回传、异常人工介入。 -- **售后逆向闭环**: 售后请求 → 退款完成。包含退货入仓、质检、库存流水调整、退款门禁审核。 -- **资金对账闭环**: 平台结算/费用/退款流水 → 差异关闭。汇率换算明确，可回溯到订单/费用明细。 -- **合规风控闭环**: 风险信号 → 放行/拦截/复核。全链路审计，门禁状态可视化。 - -*** - -## 2. 订单管理系统 (OMS) - -- **多源订单归集**: 跨平台订单统一归集，按 `tenantId` 隔离。 -- **自动审单**: 地址、库存、风险验证规则引擎自动审核。 -- **异常处理**: 缺货、地址异常、支付失败进入异常队列，支持人工介入。 -- **批量操作**: 审核、发货、标记、打印面单。 - -*** - -## 3. 库存与仓储管理 (WMS) - -- **多仓库存管理**: 多仓库库存统一视角，支持仓际调拨。 -- **全球仓储管理**: 多国仓、在途库存、跨仓调拨、安全库存预警。 -- **实时同步**: 平台库存实时对账，乐观锁防止超卖。 -- **进出库流水**: ASN 预报、盲收/点收、QC 质检、循环盘点、报损记录。 -- **物流模式管理**: - - 整柜出海 (FCL Shipping) - - 自有仓出货 - - 第三方仓出货 (3PL) - - 直发客户 (D2C / Dropship) - -*** - -## 4. 财务管理 (FIN) - -- **利润实时核算**: 销售收入 - 采购成本 - 物流 - 平台费 - 广告。 -- **成本归集**: 头程/尾程物流、平台佣金、广告投入。 -- **多币种对账**: 支持 VAT 计提，汇率自动同步。 -- **ROI 看板**: 实时显示业务决策对财务贡献。 - -*** - -## 5. 供应链与供应商管理 - -- **供应商档案**: 信用分级、联系方式、评分管理。 -- **采购管理**: - - 1688 一键代采、实时比价 - - 多供应商询价、MOQ、交期对比 -- **补货建议**: `(销量预测 * 采购周期 + 安全库存 - 在途)` 自动生成。 - -*** - -## 6. 营销与调价建议 (MKT) - -- **智能调价 (Dynamic Pricing)**: 市场竞争响应，推荐最优价格。 -- **广告计划管理**: 跨平台广告统一管理，动态预算调优，健康度监控，ROI 精准核算。 -- **全链路归因**: 广告投放 → 流量 → 订单转化。 - -*** - -## 7. 治理与审批中心 - -- **通用审批中心**: 大额订单、价格变更、退款等敏感操作多级审核。 -- **UI 布局**: 待办/已办统计，审批日志，核准/拒绝动作。 - -*** - -## 8. 合规与证书管理 - -- **自动化合规**: 订单数据生成 CE、FDA、原产地证等电子证书。 -- **信用分级**: 基于配送员履约率、争议率的信用体系。 - -*** - - - -## 9. 套利与定价分析 (ARB / Pricing) — TOC + TOB 全链路 - -### 核心定位 - -* 支持 **零售（TOC）** 和 **批发/整柜（TOB）** 套利分析。 -* 覆盖 **从生产/采购阶段 → 拿货/整柜阶段 → 零售/平台销售阶段** 的利润分析。 -* 提供 **定价推荐、ROI 模拟、利润预测和风险提示**。 - -### 核心功能 - -1. **成本与利润测算** - - * **TOC**：单件商品成本 + 平台费 + 物流 + 广告 → 售价 / ROI / 利润预测 - * **TOB**：整柜成本、批量采购成本、关税、物流 → 单件拆算利润、ROI - * 支持 **固定成本与浮动成本**组合计算（如汇率、运费波动、关税变化） - -2. **定价推荐与模拟** - - * 自动推荐售价区间以满足目标毛利率或 ROI 红线 - * 支持批量调价、不同平台定价差异、整柜与零售拆算定价 - * 可模拟不同库存、销量、物流方式下的利润变化 - -3. **套利机会发现** - - * **跨平台零售套利**：基于采集价格或手动录入的成本分析价差 - * **跨阶段 TOB 套利**：生产采购成本 vs 平台/批发售价，输出净利和 ROI - * **跨国家/跨仓套利**：考虑关税、仓储成本、物流方式的最优利润路径 - -4. **供应链阶段利润分析** - - * **生产阶段**：原材料采购、工厂成本、生产周期成本 - * **拿货阶段**：整柜成本、运输成本、报关费用、税费 - * **零售阶段**：平台费用、广告投入、物流派送、售后成本 - * 支持全链路可视化报表，显示每个环节对利润的贡献 - -5. **多维度分析报表** - - * **商品维度**：每 SKU/整柜商品成本、售价、ROI、利润预测 - * **阶段维度**：生产 → 拿货 → 零售，每阶段成本、利润占比 - * **平台 / 渠道维度**：各平台毛利率、利润贡献度、风险提示 - * **时间维度**：预测未来收益、库存消耗、套利机会变化 - ---- - -### 业务流示意（文字版） - -```text -生产阶段 / 原材料采购 - │ - ▼ -拿货 / 整柜阶段 - │ - ▼ -套利分析模块（TOB + TOC） - ├─ 成本测算（固定/浮动） - ├─ 定价推荐 & ROI 模拟 - ├─ 跨平台 / 跨阶段套利机会 - └─ 全链路利润分析报表 - │ - ▼ -商品刊登 / 调价执行 - │ - ▼ -OMS / WMS / 财务 / 营销全链路闭环 -``` - ---- - -💡 **说明**： - -* 套利模块不再仅局限于零售价格分析，而是 **全链路利润智能分析引擎** -* TOB & TOC 都可用同一个套利模块，只是输入数据和分析粒度不同 -* 定价推荐和 ROI 模拟可以贯穿 **生产、拿货、整柜、零售**每个环节 -* 为全链路决策提供支持：采购、库存、销售、物流、营销 - ---- - - -## 10. B2B / TOB 贸易管理 - -- **报价红线控制**: 利润率低于阈值自动拦截，支持多级审批。 -- **阶梯价策略**: 采购数量触发阶梯折扣。 -- **信用池**: 基于历史履约记录的结算额度与审计。 -- **询盘管理**: 多渠道整合询盘，支持跟进与转化。 - -*** - -## 11. 产品采集与数据分析 - -- **多平台采集**: Amazon, eBay, Shopee, 1688 等平台商品信息抓取。 -- **数据标准化**: SKU 属性、价格、库存统一格式化。 -- **分析支持**: ARB、PIM、营销调价、库存补货预测的数据基础。 - -*** - -## 12. 行业标杆映射 - -| 业务领域 | 标杆参考 | 核心复刻重点 | -| :------------ | :-------------------- | :-------------- | -| **商品 (PIM)** | 91妙手、店小秘 | 多平台刊登与库存统一 | -| **套利 (ARB)** | 船长BI、Helium 10 | 跨平台寻源与实时利润测算 | -| **订单 (OMS)** | 易仓、积加 | 多源归集与自动化审单 | -| **独立站 (DTC)** | Shopify | 流量归因与多租户隔离 | -| **仓储 (WMS)** | Flexport | 路径规划与多仓协同 | -| **财务 (FIN)** | 出海匠 | 全口径利润审计与回款跟踪 | -| **营销 (MKT)** | 蝉妈妈 | 趋势分析与数据可视化 | -| **供应链 / 采购** | 1688 + 供应商管理工具 | 补货建议、采购比价、供应商信用 | -| **物流模式** | FCL / Own / 3PL / D2C | 全球物流路径、调拨、直发客户 | -| **审批与合规** | 内部审批 & 电子证书 | 敏感操作审核、证书生成 | -| **B2B 贸易管理** | 内部 TOB 系统 | 阶梯价、信用池、询盘管理 | - -*** -