docs: 新增业务闭环文档并重构文档结构
新增业务闭环文档,包含商品主数据、SKU变体、订单拆分等关键闭环 重构文档目录结构,迁移旧文档至新路径 补充业务功能说明文档内容 更新全局文档索引和项目地图
This commit is contained in:
69
docs/01_Architecture/System_Architecture.md
Normal file
69
docs/01_Architecture/System_Architecture.md
Normal 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` 统一管理。
|
||||
Reference in New Issue
Block a user