wurenzhi/makemd

Files

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

新增业务闭环文档，包含商品主数据、SKU变体、订单拆分等关键闭环
重构文档目录结构，迁移旧文档至新路径
补充业务功能说明文档内容
更新全局文档索引和项目地图

2026-03-18 00:35:00 +08:00

2.6 KiB

Raw Blame History

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