# 系统架构

> **入口**: [_index.md](_index.md)

---

## 1. 系统层级

```
┌─────────────────────────────────────────────────────────────┐
│                      前端控制台                              │
│              (UmiJS + Ant Design + TypeScript)              │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP/WebSocket
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                      后端服务                                │
│              (Node.js + Express + TypeScript)               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ Controller  │→ │  Service    │→ │ Repository  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────┬───────────────────────────────────┘
                          │ Message Queue
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                      运营代理                                │
│              (Node.js + Puppeteer)                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ Task Runner │→ │  Connector  │→ │   Browser   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────┬───────────────────────────────────┘
                          │ Platform API / Scraping
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                    第三方平台                                │
│     Shopify │ Amazon │ TikTok │ Shopee │ Temu │ ...        │
└─────────────────────────────────────────────────────────────┘
```

---

## 2. 核心组件

### 2.1 前端控制台

| 组件 | 技术 | 职责 |
|------|------|------|
| 路由 | UmiJS | 页面路由、权限控制 |
| 状态 | Umi Model | 全局状态管理 |
| UI | Ant Design | 组件库、布局 |
| 请求 | axios | API调用、拦截器 |

### 2.2 后端服务

| 组件 | 技术 | 职责 |
|------|------|------|
| 路由 | Express Router | 路由定义、中间件 |
| 控制器 | Controller | 请求处理、参数校验 |
| 服务 | Service | 业务逻辑、事务管理 |
| 数据访问 | Knex.js | 数据库操作 |
| 缓存 | Redis | 缓存、会话、队列 |
| 队列 | BullMQ | 异步任务处理 |

### 2.3 运营代理

| 组件 | 技术 | 职责 |
|------|------|------|
| 任务调度 | BullMQ Worker | 任务执行、重试 |
| 浏览器 | Puppeteer | 页面操作、数据采集 |
| 代理管理 | Proxy Manager | 代理池、IP轮换 |
| 指纹管理 | Fingerprint | 浏览器指纹、防检测 |

---

## 3. 通信机制

### 3.1 前端 ↔ 后端

```
HTTP REST API
├── 认证: JWT Token
├── 请求: JSON
└── 响应: JSON

WebSocket
├── 实时通知
├── 任务进度
└── 系统事件
```

### 3.2 后端 ↔ 运营代理

```
Redis Message Queue
├── 任务下发
├── 结果回传
└── 状态同步
```

### 3.3 运营代理 ↔ 平台

```
Platform API
├── 官方API (Shopify, Amazon)
├── 非官方API (TikTok, Shopee)
└── 页面采集 (Temu, 1688)
```

---

## 4. 数据流

### 4.1 商品采集流程

```
用户请求 → Controller → CollectionService
    ↓
创建采集任务 → Redis Queue → Agent Worker
    ↓
Connector → 平台API/页面 → 解析数据
    ↓
回传数据 → ProductService → 存储数据库
    ↓
WebSocket通知 → 前端更新
```

### 4.2 订单履约流程

```
订单创建 → OrderService → 库存检查
    ↓
InventoryService → 库存扣减
    ↓
FulfillmentService → 物流创建
    ↓
通知用户 → WebSocket/SMS/Email
```

---

## 5. 部署架构

```
┌─────────────────────────────────────────────────────────────┐
│                        负载均衡                              │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ↓               ↓               ↓
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ 前端实例 │    │ 前端实例 │    │ 前端实例 │
    └──────────┘    └──────────┘    └──────────┘
          │               │               │
          └───────────────┼───────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                        API网关                               │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ↓               ↓               ↓
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ 后端实例 │    │ 后端实例 │    │ 后端实例 │
    └──────────┘    └──────────┘    └──────────┘
          │               │               │
          └───────────────┼───────────────┘
                          ↓
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │  MySQL   │    │  Redis   │    │  Agent   │
    └──────────┘    └──────────┘    └──────────┘
```

---

## 6. 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 前端框架 | UmiJS | 4.x |
| UI组件库 | Ant Design | 5.x |
| 后端框架 | Express | 4.x |
| 数据库 | MySQL | 8.0 |
| 缓存 | Redis | 6.x |
| 队列 | BullMQ | 4.x |
| 浏览器 | Puppeteer | 21.x |

---

*最后更新: 2026-03-22*