docs: 新增业务闭环文档并重构文档结构

新增业务闭环文档,包含商品主数据、SKU变体、订单拆分等关键闭环
重构文档目录结构,迁移旧文档至新路径
补充业务功能说明文档内容
更新全局文档索引和项目地图
This commit is contained in:
2026-03-18 00:35:00 +08:00
parent bdf6f6036d
commit 56b8a2e2f8
18 changed files with 4580 additions and 624 deletions

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 (最小冒烟测试)。

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` 统一管理。