docs: 重构并删除docs11目录，更新项目文档结构
删除旧的docs11目录及其所有内容，包括： - 业务蓝图文档(business-blueprint.md) - 数据API规范(data-api-specs.md) - 系统架构文档(system-architecture.md) - 模块蓝图文档(module-blueprints.md) - 治理标准文档(governance-standards.md) - 质量标准文档(quality-optimization.md) - 任务总览文档(Crawlful_Hub_Task_Overview_Full_v1.md) - README.md等文件 同时更新了docs目录下的现有文档： - 更新SERVICE_MAP.md强化服务层职责和调用规范 - 更新Service_Design.md明确服务层设计规范和边界 - 更新项目规则文档加入逻辑集中化原则 - 统一调整了文档表格格式和结构
This commit is contained in:
@@ -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个任务** | **碎片化等待** |
|
||||
| **协作防撞** | **必须声明占用，先声明优先** | **重复开发** |
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
|
||||
@@ -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 | ✅ 已完成 |
|
||||
|
||||
|
||||
@@ -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 操作
|
||||
- 数据模型映射
|
||||
- 查询优化
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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. 核心服务列表
|
||||
|
||||
@@ -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 才能高效维护和迭代。
|
||||
|
||||
## 📞 联系方式
|
||||
|
||||
|
||||
@@ -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 才能高效维护和迭代。
|
||||
|
||||
@@ -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. **横切能力**：账号健康度、任务调度、权限审计等能力贯穿所有业务闭环，确保系统稳定性和安全性。
|
||||
|
||||
***
|
||||
|
||||
@@ -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 速率。
|
||||
@@ -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 全链路**
|
||||
* 支持多币种采购、整柜成本、平台销售价格统一计算
|
||||
* 可进行 **利润随汇率波动的敏感性分析**，为定价策略提供数据支持
|
||||
* 套利模块成为全链路利润智能分析引擎，同时支撑 **零售、批发、整柜、跨国贸易**
|
||||
|
||||
---
|
||||
@@ -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`: 服务器错误。
|
||||
@@ -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 (最小冒烟测试)。
|
||||
@@ -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` 统一管理。
|
||||
@@ -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)
|
||||
- 记录系统风险、缓解措施与负责人。
|
||||
@@ -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` 索引，确保全量文档导航。
|
||||
- 定期审查文档结构，确保与物理文件系统保持一致。
|
||||
@@ -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. 依赖列可快速判断任务执行顺序
|
||||
|
||||
---
|
||||
@@ -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。
|
||||
@@ -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/) - 历史方案、旧版任务记录
|
||||
195
docs11/业务功能.md
195
docs11/业务功能.md
@@ -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 系统 | 阶梯价、信用池、询盘管理 |
|
||||
|
||||
***
|
||||
|
||||
Reference in New Issue
Block a user