wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 初始化项目结构并添加核心功能模块

Browse Source 
- 新增文档模板和导航结构
- 实现服务器基础API路由和控制器
- 添加扩展插件配置和前端框架
- 引入多租户和权限管理模块
- 集成日志和数据库配置
- 添加核心业务模型和类型定义
This commit is contained in:
wurenzhi
2026-03-17 22:07:19 +08:00
parent c0870dce50
commit 136c2fa579
728 changed files with 107690 additions and 5614 deletions
Download Patch File Download Diff File Expand all files Collapse all files

469
docs11/00-documentation-layer.md Normal file
View File

@@ -0,0 +1,469 @@
# 📌 Crawlful Hub 业务闭环（TOC + TOB Unified Business Loops）
> **说明**：本闭环文档是战略层业务流程，关注“做什么、为什么做、顺序和决策点”，为下层模块功能和系统实现提供指引。TOC（零售/前端）和 TOB（B2B贸易）共享通用模块，特有流程用 `businessType` 标记。
## 📑 目录
1. [数据采集与清洗闭环](#1️⃣-数据采集与清洗闭环product-data-collection--cleansing)
2. [商品刊登闭环](#2️⃣-商品刊登闭环product-listing-loop)
3. [素材管理闭环](#3️⃣-素材管理闭环media--asset-management-loop)
4. [广告计划与营销闭环](#4️⃣-广告计划与营销闭环marketing--ad-management-loop)
5. [订单履约闭环](#5️⃣-订单履约闭环order-fulfillment-loop--oms)
6. [售后逆向闭环](#6️⃣-售后逆向闭环returns--refunds-loop)
7. [资金对账闭环](#7️⃣-资金对账闭环finance-reconciliation-loop)
8. [库存与仓储管理闭环](#8️⃣-库存与仓储管理闭环inventory--warehouse-management-loop--wms)
9. [供应链与供应商管理闭环](#9️⃣-供应链与供应商管理闭环supply-chain--supplier-management-loop)
10. [B2B / TOB 贸易管理闭环](#🔟-b2b--tob-贸易管理闭环b2b--tob-trade-management-loop)
11. [治理与审批中心闭环](#1️⃣1️⃣-治理与审批中心闭环governance--approval-center-loop)
12. [合规与证书管理闭环](#1️⃣2️⃣-合规与证书管理闭环compliance--certificate-management-loop)
13. [合规与风控闭环](#1️⃣3️⃣-合规与风控闭环compliance--risk-control-loop)
14. [报表与分析闭环](#1️⃣4️⃣-报表与分析闭环reporting--analytics-loop)
15. [统一闭环依赖](#🔹-统一闭环依赖toc--tob)
16. [闭环依赖关系](#🔗-闭环依赖关系toc--tob)
17. [关键绩效指标](#📊-关键绩效指标kpi)
18. [追踪与审计](#🔍-追踪与审计)
19. [业务审核状态机](#📋-业务审核状态机)
20. [说明](#💡-说明)
***
## 1️⃣ 数据采集与清洗闭环（Product Data Collection & Cleansing）
- **目标**：收集多平台商品信息，确保数据完整、有效、可用于盈利分析（TOC）或报价计算（TOB）。
- **流程**：
1. **多平台采集**：
- TOC：抓取 Amazon、eBay、Shopee、1688 等平台商品信息。
- TOB：抓取供应商报价、批发价格、企业定制产品信息。
- 支持 API 对接和爬虫采集。
- 采集字段：标题、价格、库存、SKU、图片、描述、评价、供应商信息（TOB）。
2. **数据清洗**：
- 去重：平台+productId 唯一约束
- 格式化：统一字段格式和单位
- 字段标准化：规范属性名和值
- 剔除无效商品：库存异常、价格异常、描述缺失
3. **前置套利 / 利润评估**：
- TOC：评估单件盈利、ROI、定价区间
- TOB：评估阶梯价利润、批量折扣、信用额度风险
- 考虑平台费、物流费、税费、汇率、售后成本、广告摊销
- **决策点**：
- TOC：B2C 利润率 < 20% 触发风控
- TOB：B2B 利润率 < 15% 禁止报价
- **输入**：平台商品原始数据
- **输出**：清洗后的可售商品/报价数据，包含完整套利/利润分析
***
## 2️⃣ 商品刊登闭环（Product Listing Loop）
- **目标**：将可售商品同步到各平台，建立销售基础（TOC）或生成报价单（TOB）。
- **流程**：
1. **商品准备**：
- ERP 商品信息完善
- 平台规则适配：标题、描述、图片、批量折扣（TOB）
- 价格策略设置：基于套利分析或阶梯价策略
2. **刊登执行**：
- 批量或单条刊登，支持失败重试和全链路追踪
- API 平台：走 Connector Bus
- 无 API 平台：No-API Bridge + PENDING\_REVIEW
3. **刊登后管理**：
- 库存同步、价格更新、商品状态监控
- **决策点**：
- 必须通过前置套利/利润分析
- TOB 需遵循阶梯价审批策略
- **输入**：清洗后的可售商品数据
- **输出**：已刊登商品列表 + 平台状态 + 链接
***
## 3️⃣ 素材管理闭环（Media & Asset Management Loop）
- **目标**：统一管理商品、广告、营销所需素材，支持 TOC 广告投放和 TOB 企业报价资料。
- **流程**：
- 素材采集、处理、审核、分发
- TOC：图片/视频用于广告和商品展示
- TOB：商品资料、合同模板、报价单模板
- **决策点**：
- 版权合规、平台规则、素材质量
- **输出**：素材库 + 元数据 + 使用统计
- **状态机**：`UPLOADED` → `PROCESSING` → `PENDING_REVIEW` → `APPROVED` → `IN_USE` → `ARCHIVED`/`REJECTED`
***
## 4️⃣ 广告计划与营销闭环（Marketing & Ad Management Loop）
- **目标**：提升销量和 ROI（TOC）或企业促销效率（TOB）。
- **流程**：
- 广告计划制定、跨平台投放、效果分析与优化
- TOB：批量报价、促销方案、邮件/企业营销
- **决策点**：
- 广告 ROI < 1 停止投放
- 企业营销需基于信用等级和合同审批
- **输入**：已刊登商品列表、素材
- **输出**：广告报告、优化建议
***
## 5️⃣ 订单履约闭环（Order Fulfillment Loop / OMS）
- **目标**：保证订单从生成到妥投的全链路履约。
- **流程**：
- **公共流程**：订单获取与审核 → 分仓 → 占库 → 扣库 → 发货 → 物流追踪
- **TOC**：标准订单处理流程
- **TOB**：大额企业订单可分批发货、合同条款优先
- **状态机**：`PULLED` → `PENDING_REVIEW` → `CONFIRMED` → `ALLOCATED` → `READY_TO_SHIP` → `SHIPPED` → `DELIVERED` → `CLOSED`
- **输入**：平台订单数据
- **输出**：已发货订单，包含物流跟踪信息
***
## 6️⃣ 售后逆向闭环（Returns & Refunds Loop）
- **目标**：处理退货/退款，保持库存和财务一致。
- **流程**：
- **公共流程**：售后请求处理 → 退货处理 → 退款处理
- **TOC**：标准退货流程
- **TOB**：按合同条款、批量退货、预付款冲抵
- **输入**：售后请求数据
- **输出**：处理完成的售后记录，包含库存和财务调整
***
## 7️⃣ 资金对账闭环（Finance Reconciliation Loop）
- **目标**：财务闭环，兼顾 TOC/TOB。
- **流程**：
- 数据汇总 → 财务处理（多币种、VAT、汇率） → 差异分析与处理
- **决策点**：
- 异常需人工复核
- TOB 账期和信用额度影响结算
- **输出**：对账报告 + 差异处理记录
***
## 8️⃣ 库存与仓储管理闭环（Inventory & Warehouse Management Loop / WMS）
- **目标**：确保库存准确、仓储高效，支持全球供应链运作。
- **流程**：
- **公共流程**：多仓库存管理 → 进出库管理 → 物流模式管理
- **TOC**：按店铺和平台库存管理
- **TOB**：按企业订单、批量调拨、FCL/3PL 管理
- **决策点**：
- 库存不足时触发补货建议
- 跨仓调拨决策：基于成本和时效
- 安全库存预警阈值设置
- **输入**：订单数据、采购数据、物流数据
- **输出**：实时库存状态、仓储操作记录、库存预警
***
## 9️⃣ 供应链与供应商管理闭环（Supply Chain & Supplier Management Loop）
- **目标**：优化供应链流程，降低采购成本，确保供应稳定。
- **流程**：
- **公共流程**：供应商管理 → 采购管理 → 补货建议
- **TOC**：基于零售需求的采购计划
- **TOB**：基于大宗订单生成采购计划
- **决策点**：
- 供应商选择：基于综合评分
- 采购价格：低于成本价预警
- 补货时机：库存周转率优化
- **输入**：销售数据、库存数据、供应商数据
- **输出**：采购计划、供应商评估报告、成本节省分析
***
## 🔟 B2B / TOB 贸易管理闭环（B2B / TOB Trade Management Loop）
- **目标**：企业间交易管理
- **流程**：
- 报价管理、信用管理、询盘转订单
- **决策点**：
- 利润率 < 15% 禁止报价
- 大额订单多级审批
- 低信用等级客户需预付款
- **输出**：报价单、B2B 订单、信用评估报告
***
## 1️⃣1️⃣ 治理与审批中心闭环（Governance & Approval Center Loop）
- **目标**：敏感操作审批
- **适用**：
- TOC：大额订单、价格变动、退款
- TOB：大额企业订单、阶梯价审批、信用审批
- **输出**：审批结果、审计日志
***
## 1️⃣2️⃣ 合规与证书管理闭环（Compliance & Certificate Management Loop）
- **目标**：确保业务合规，自动生成所需证书。
- **流程**：
- **公共流程**：自动化合规 → 信用分级 → 合规审计
- **TOC**：商品合规检查和证书生成
- **TOB**：出口合规、合同合规检查和证书生成
- **决策点**：
- 不合规商品禁止销售
- 信用等级低的合作伙伴需要额外审核
- **输入**：订单数据、商品数据、合作伙伴数据
- **输出**：电子证书、合规报告、信用评估
***
## 1️⃣3️⃣ 合规与风控闭环（Compliance & Risk Control Loop）
- **目标**：统一风控
- **输入**：全流程数据（TOC + TOB）
- **输出**：风险处理记录、规则优化
***
## 1️⃣4️⃣ 报表与分析闭环（Reporting & Analytics Loop）
- **目标**：数据可视化 + KPI 支撑 TOC/TOB 决策
- **流程**：
- 数据汇总 → 指标计算 → 报表生成 → 数据大屏 → 闭环反馈
- **输出**：管理报表、异常预警、优化建议
- **状态机**：`RAW_DATA` → `PROCESSED` → `GENERATED` → `DISTRIBUTED` → `FEEDBACK_APPLIED`
***
### 🔹 统一闭环依赖（TOC + TOB）
```text
采集 → 清洗 → 套利/利润评估
│
商品刊登 ← 素材管理
│
广告/营销 (TOC) / 企业营销 (TOB)
│
订单履约 (OMS) → 售后逆向
│ │
▼ ▼
库存 & WMS ← 资金对账
│
▼
供应链 & 补货
│
▼
B2B/TOB 贸易管理 (TOB)
│
▼
治理与审批中心
│
▼
合规 & 证书
│
▼
风控
│
▼
报表 & 分析
```
**说明**：
- 实线箭头表示核心业务流程
- 括号内标注了TOC/TOB的主要差异点
- B2B/TOB贸易管理为TOB特有闭环
***
### 🔗 闭环依赖关系（TOC + TOB）
1. **数据采集与清洗闭环** → **商品刊登闭环**：提供清洗后的可售商品数据
2. **数据采集与清洗闭环** → **素材管理闭环**：提供采集的商品图片和视频素材
3. **商品刊登闭环** → **素材管理闭环**：触发素材需求，生成商品主图和详情图
4. **素材管理闭环** → **商品刊登闭环**：提供处理后的商品素材（图片、视频）
5. **素材管理闭环** → **广告计划与营销闭环**：提供广告投放所需的素材库
6. **商品刊登闭环** → **广告计划与营销闭环**：提供已刊登商品列表
7. **商品刊登闭环** → **订单履约闭环**：提供商品库存和状态信息
8. **订单履约闭环** → **售后逆向闭环**：提供订单和物流信息
9. **售后逆向闭环** → **资金对账闭环**：提供退款记录
10. **订单履约闭环** → **资金对账闭环**：提供销售记录
11. **广告计划与营销闭环** → **资金对账闭环**：提供广告费用记录
12. **订单履约闭环** → **库存与仓储管理闭环**：触发库存扣减和物流操作
13. **库存与仓储管理闭环** → **订单履约闭环**：提供库存状态和物流信息
14. **库存与仓储管理闭环** → **供应链与供应商管理闭环**：触发补货需求
15. **供应链与供应商管理闭环** → **库存与仓储管理闭环**：提供采购入库信息
16. **商品刊登闭环** → **B2B / TOB 贸易管理闭环**：提供商品信息用于报价
17. **B2B / TOB 贸易管理闭环** → **订单履约闭环**：生成 B2B 订单
18. **B2B / TOB 贸易管理闭环** → **资金对账闭环**：提供 B2B 交易记录
19. **所有敏感操作** → **治理与审批中心闭环**：触发审批流程
20. **治理与审批中心闭环** → **所有业务闭环**：提供审批结果
21. **订单履约闭环** → **合规与证书管理闭环**：触发证书生成
22. **合规与证书管理闭环** → **订单履约闭环**：提供合规证书
23. **所有闭环** → **合规与风控闭环**：提供全流程数据用于风险监控
24. **所有业务闭环** → **报表与分析闭环**：提供各闭环的输出数据用于报表生成和分析
25. **报表与分析闭环** → **所有业务闭环**：反馈数据异常、业务波动、优化建议，指导各闭环的操作调整
***
### 📊 关键绩效指标（KPI）
#### 数据采集与清洗闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------- | ---------- | --------- |
| 采集覆盖率 | 目标平台商品覆盖率 | TOC + TOB |
| 数据准确率 | 清洗后数据的准确性 | TOC + TOB |
| 套利分析准确率 | 前置套利计算的准确性 | TOC + TOB |
#### 商品刊登闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------- | ----------- | --------- |
| 刊登成功率 | 成功刊登的商品比例 | TOC + TOB |
| 刊登时效 | 从准备到刊登完成的时间 | TOC + TOB |
| 平台审核通过率 | 平台审核通过的商品比例 | TOC + TOB |
#### 素材管理闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------- | ------------ | --------- |
| 素材处理时效 | 从上传到可用的平均时间 | TOC + TOB |
| 素材审核通过率 | 通过审核的素材比例 | TOC + TOB |
| 素材转化率 | 使用素材带来的订单转化率 | TOC + TOB |
| 素材复用率 | 被多次使用的素材比例 | TOC + TOB |
| 版权合规率 | 无版权风险的素材比例 | TOC + TOB |
#### 广告计划与营销闭环
| KPI 指标 | 描述 | 适用业务类型 |
| -------- | -------------- | ------ |
| 广告 ROI | 广告投入产出比 | TOC |
| 点击率（CTR） | 广告点击次数与展示次数的比率 | TOC |
| 转化率（CVR） | 点击广告后产生订单的比例 | TOC |
| 企业营销效果 | 企业营销活动的转化率 | TOB |
#### 订单履约闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------ | ----------- | --------- |
| 订单处理时效 | 从订单生成到发货的时间 | TOC + TOB |
| 发货准确率 | 正确发货的订单比例 | TOC + TOB |
| 妥投率 | 成功送达的订单比例 | TOC + TOB |
| 分批处理率 | 大额订单分批处理的比例 | TOB |
#### 售后逆向闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------ | ------------- | --------- |
| 售后处理时效 | 从售后请求到处理完成的时间 | TOC + TOB |
| 退款成功率 | 成功退款的比例 | TOC + TOB |
| 退货率 | 退货订单占总订单的比例 | TOC + TOB |
#### 资金对账闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------ | ------------- | --------- |
| 对账准确率 | 对账差异率 | TOC + TOB |
| 对账时效 | 从数据汇总到对账完成的时间 | TOC + TOB |
| 异常处理率 | 需要人工处理的异常比例 | TOC + TOB |
| 账期遵守率 | 按合同约定账期结算的比例 | TOB |
#### 库存与仓储管理闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------ | ------------- | --------- |
| 库存准确率 | 系统库存与实际库存的差异率 | TOC + TOB |
| 库存周转率 | 库存周转次数 | TOC + TOB |
| 仓储操作效率 | 每单处理时间 | TOC + TOB |
| 跨仓调拨时效 | 调拨完成时间 | TOC + TOB |
#### 供应链与供应商管理闭环
| KPI 指标 | 描述 | 适用业务类型 |
| -------- | --------- | --------- |
| 供应商准时交付率 | 按时交付的订单比例 | TOC + TOB |
| 采购成本降低率 | 采购成本下降百分比 | TOC + TOB |
| 供应商评分 | 供应商综合评估分数 | TOC + TOB |
| 补货准确率 | 补货计划的准确性 | TOC + TOB |
#### B2B / TOB 贸易管理闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------- | ---------- | ------ |
| B2B 利润率 | B2B 业务的利润率 | TOB |
| 报价通过率 | 报价被客户接受的比例 | TOB |
| 信用违约率 | 客户信用违约的比例 | TOB |
| 询盘转化率 | 询盘转化为订单的比例 | TOB |
#### 治理与审批中心闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------ | ----------- | --------- |
| 审批时效 | 从申请到审批完成的时间 | TOC + TOB |
| 审批准确率 | 审批结果的准确性 | TOC + TOB |
| 待办处理率 | 待办事项的处理比例 | TOC + TOB |
#### 合规与证书管理闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------- | --------- | --------- |
| 证书生成及时率 | 按时生成证书的比例 | TOC + TOB |
| 合规检查通过率 | 通过合规检查的比例 | TOC + TOB |
| 信用评级准确率 | 信用评级的准确性 | TOC + TOB |
#### 合规与风控闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------- | ---------- | --------- |
| 风险识别准确率 | 风险识别的准确性 | TOC + TOB |
| 风控处理时效 | 风险处理的时间 | TOC + TOB |
| 合规违规率 | 违规事件的比例 | TOC + TOB |
| 误报率 | 误判为风险的事件比例 | TOC + TOB |
#### 报表与分析闭环
| KPI 指标 | 描述 | 适用业务类型 |
| ------- | --------------- | --------- |
| 报表生成及时率 | 按时生成报表的比例 | TOC + TOB |
| 数据准确率 | 报表数据的准确性 | TOC + TOB |
| 分析洞察价值 | 分析结果对业务决策的价值 | TOC + TOB |
| 异常预警准确率 | 异常预警的准确性 | TOC + TOB |
| 报表生成时效 | 从数据汇总到报表完成的时间 | TOC + TOB |
| 数据完整率 | 报表覆盖业务闭环输出数据的比例 | TOC + TOB |
| KPI 准确率 | 计算指标与实际数据偏差率 | TOC + TOB |
| 异常响应率 | 异常报表触发优化措施的比例 | TOC + TOB |
| 大屏实时性 | 数据大屏数据更新延迟时间 | TOC + TOB |
| 决策支持率 | 报表建议被采纳并执行的比例 | TOC + TOB |
***
### 🔍 追踪与审计
- **追踪四元组**：
- `tenantId`：租户 ID（业务隔离）
- `shopId`：店铺 ID（平台/店铺隔离）
- `taskId`：任务 ID（任务/规则触发归档）
- `traceId`：链路追踪 ID（全链路唯一标识）
- `businessType`：业务类型（TOC/TOB）
- **审计要求**：
- 每一笔操作必须绑定 `traceId` 和 `businessType`
- 所有功能需通过 Shadow-Test（最小冒烟测试）
- 关键操作必须生成 AuditLog
***
### 📋 业务审核状态机
- **通用审核流程**：`SUBMITTED` (提交) → `PENDING_REVIEW` (人工审核) → `EXECUTED` / `REJECTED`
- **适用场景**：
- TOC：大额订单、价格变动、退款
- TOB：大额企业订单、阶梯价审批、信用审批
***
### 💡 说明
1. 业务闭环文档是**最高层文档**，不涉及具体前端或模块实现细节。
2. 下层模块功能、接口、算法、UI 都是这个闭环的落地实现。
3. 形成从**采集 → 决策 → 执行 → 反馈 → 风控**的完整业务链。
4. 每个闭环都有明确的输入、输出、流程和决策点，确保业务流程的完整性和可控性。
5. 各闭环之间通过数据流转和依赖关系形成完整的业务生态系统。
6. 所有业务操作均需遵循项目特定规则，确保系统安全和数据一致性。
7. **“闭环写入规则：只要逻辑上能闭环就写，落地方式后置”**
***

115
docs11/01-business-core/business-blueprint.md Normal file
View File

@@ -0,0 +1,115 @@
# 🏢 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 速率。

77
docs11/01-business-core/业务9.md Normal file
View File

@@ -0,0 +1,77 @@
---
## 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 全链路**
* 支持多币种采购、整柜成本、平台销售价格统一计算
* 可进行 **利润随汇率波动的敏感性分析**，为定价策略提供数据支持
* 套利模块成为全链路利润智能分析引擎，同时支撑 **零售、批发、整柜、跨国贸易**
---

88
docs11/02-data-api/data-api-specs.md Normal file
View File

@@ -0,0 +1,88 @@
# 📊 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`: 服务器错误。

72
docs11/03-architecture-tech/module-blueprints.md Normal file
View File

@@ -0,0 +1,72 @@
# 🎨 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 (最小冒烟测试)。

69
docs11/03-architecture-tech/system-architecture.md Normal file
View File

@@ -0,0 +1,69 @@
# 🏗 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` 统一管理。

63
docs11/04-standards-governance/governance-standards.md Normal file
View File

@@ -0,0 +1,63 @@
# 📋 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)
- 记录系统风险、缓解措施与负责人。

44
docs11/05-quality-optimization/quality-optimization.md Normal file
View File

@@ -0,0 +1,44 @@
# 💎 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` 索引，确保全量文档导航。
- 定期审查文档结构，确保与物理文件系统保持一致。

37
docs11/Crawlful_Hub_Task_Overview_Full_v1.md Normal file
View File

@@ -0,0 +1,37 @@
# 🗂 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. 依赖列可快速判断任务执行顺序
---

56
docs11/doc-index.md Normal file
View File

@@ -0,0 +1,56 @@
# 📚 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 Normal file
View File

@@ -0,0 +1,195 @@
# 📦 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 系统 | 阶梯价、信用池、询盘管理 |
***

374
docs11/临时修改建议.MD Normal file
View File

@@ -0,0 +1,374 @@
你这套已经是**完整一阶业务闭环图**了（覆盖交易流 + 资金流 + 物流 + 信息流）。
我不帮你重复，而是直接指出**“你现在缺的，是二阶系统闭环（系统级能力层）”**——这些往往是后期系统崩掉或做不大的根本原因。
下面我按**架构缺口**给你补。
---
# 🧠 一、你缺的核心：3个“横切闭环”（最关键）
这些不是业务模块，而是**系统能力层**。
---
## 1️⃣ **定价与利润决策闭环（你提过套利，但还没闭环）**
### ❗你现在的问题
你有：
* 采集
* 成本
* ROI
但缺：
👉 **自动决策 → 反向驱动业务**
---
### ✅ 应该补：
**26️⃣ 商品刊登闭环 → 定价与利润闭环**
→ 提供商品成本 / 运费 / 平台费 / 广告预估
**27️⃣ 定价与利润闭环 → 商品刊登闭环**
→ 输出：
* 建议售价
* 建议ROI
* 是否上架（开/关）
**28️⃣ 定价与利润闭环 → 广告闭环**
→ 输出：
* 可投放ROI区间
* 最大可承受CPA
---
### 💡 本质
你现在是：
> “人决定卖什么”
应该变成：
> **系统决定这个东西能不能卖**
---
## 2️⃣ **账号 / 店铺健康度闭环（极其重要，很多人没做）**
你现在完全没这个，这是大坑。
---
### ❗现实问题
跨境电商核心风险：
* 封号
* 限流
* 降权
* 违规
---
### ✅ 应该补：
**29️⃣ 所有业务闭环 → 店铺健康度闭环**
→ 提供：
* 违规记录
* 发货延迟
* 差评率
* 退款率
**30️⃣ 店铺健康度闭环 → 广告闭环**
→ 决定：
* 是否暂停广告
* 降预算
**31️⃣ 店铺健康度闭环 → 商品刊登闭环**
→ 决定：
* 是否限制上新
* 是否下架高风险商品
---
### 💡 本质
这是你的：
> **“生死开关系统”**
---
## 3️⃣ **任务调度 / 自动化执行闭环（你有AI，但没调度中枢）**
你现在是：
👉 各模块“能做事”
但缺：
👉 **谁在什么时候触发它做事**
---
### ✅ 应该补：
**32️⃣ 所有闭环 → 任务调度中心闭环**
→ 提供事件：
* 新商品
* 有订单
* 库存不足
* ROI变化
**33️⃣ 任务调度中心 → 所有闭环**
→ 触发：
* 自动刊登
* 自动补货
* 自动调价
* 自动开广告
---
### 💡 本质
这是你的：
> **系统操作系统（OS层）**
---
# ⚙️ 二、你缺的“数据中台层闭环”
你现在是“模块之间传数据”，但没有**统一数据抽象层**
---
## 4️⃣ **数据标准化 / 商品主数据闭环（MDM）**
### ❗问题
现在：
* 商品数据分散在各闭环
* SKU可能不统一
---
### ✅ 应该补：
**34️⃣ 数据采集 / 供应链 / 刊登 → 商品主数据闭环**
**35️⃣ 商品主数据闭环 → 所有业务闭环**
输出统一：
* SPU / SKU
* 类目
* 属性结构
* 多语言
* 多平台映射
---
### 💡 本质
这是：
> **整个系统的“数据库大脑”**
---
## 5️⃣ **价格 / 汇率 /成本基准闭环（你提到汇率，但没体系）**
---
### ✅ 应该补：
**36️⃣ 外部数据（汇率/物流/平台费） → 成本基准闭环**
**37️⃣ 成本基准闭环 →**
* 定价闭环
* 广告闭环
* 报表闭环
---
### 💡 本质
这是：
> **全局统一“钱”的计算标准**
---
# 📊 三、你缺的“增长系统闭环”
---
## 6️⃣ **用户 / 客户资产闭环（TOC + TOB 都缺）**
你现在完全没有“用户层”。
---
### ✅ 应该补：
**38️⃣ 订单履约闭环 → 用户资产闭环**
→ 沉淀：
* 用户画像
* 复购行为
* 国家偏好
**39️⃣ 用户资产闭环 → 广告闭环**
→ 做：
* 再营销
* 类似人群
**40️⃣ 用户资产闭环 → B2B闭环**
→ 转化：
* 大客户
* 批发客户
---
### 💡 本质
你现在是：
> 做“订单”
应该升级为：
> 做“用户资产”
---
## 7️⃣ **A/B测试与策略优化闭环**
---
### ✅ 应该补：
**41️⃣ 广告 / 商品 / 定价 → A/B测试闭环**
**42️⃣ A/B测试闭环 → 报表闭环 / 决策系统**
---
### 💡 本质
让系统具备：
> **自我进化能力**
---
# 🔐 四、你缺的“安全与系统稳定闭环”
---
## 8️⃣ **权限与审计闭环（不是审批，是审计）**
你有审批，但缺：
👉 **谁做了什么**
---
### ✅ 应该补：
**43️⃣ 所有操作 → 审计日志闭环**
**44️⃣ 审计日志闭环 → 风控 / 合规**
---
---
## 9️⃣ **异常检测与自愈闭环（SRE思维）**
---
### ✅ 应该补：
**45️⃣ 所有闭环 → 异常监控闭环**
检测：
* API失败
* 刊登失败
* 广告异常
* ROI突变
**46️⃣ 异常监控 → 任务调度中心**
→ 自动：
* 重试
* 切换账号
* 暂停投放
---
### 💡 本质
这是：
> **系统能不能无人值守的关键**
---
# 🧩 五、总结（你现在的层级）
你当前是：
### ✅ L1（已完成）
* 业务闭环（交易系统）
---
### ❌ L2（缺失）
* 系统决策层（定价 / 风控 / 健康度）
* 数据中台层（商品 / 成本）
* 自动化调度层
---
### ❌ L3（高级能力）
* 用户资产
* 增长系统
* 自优化系统
---
# 🚀 给你一个最终判断
如果你只做现在这25条：
👉 你是一个 **“可用的ERP + 电商系统”**
如果你补上我这套：
👉 你会变成一个
**“自动赚钱系统（半无人化电商操作系统）”**
---
如果你愿意，我可以帮你下一步做一件更关键的事：
👉 把这些闭环 **压缩成 5 个核心中枢（真正可落地架构）**
否则你现在这个结构——**AI也很难协同开发，会炸**。