# 技术需求分析与架构设计

> **文档目的**：对 Crawlful Hub 项目进行技术需求分析和架构设计，为开发团队提供清晰的技术指导。
> **更新日期**：2026-03-17

## 1. 技术需求分析

### 1.1 功能需求

#### 核心业务模块

| 模块 | 功能点 | 优先级 | 技术实现要点 |
|------|--------|--------|-------------|
| **商品管理 (PIM)** | SPU/SKU管理 | P0 | 支持商品档案管理、多平台商品刊登、商品采集、产品裂变等 |
| | 多平台商品刊登 | P0 | 支持 TikTok Shop、Amazon、eBay、Shopee、Temu 等平台 |
| | 商品采集 | P1 | 支持 1688、速卖通、竞品采集等 |
| | 产品裂变 | P0 | 支持标题、图片、价格、SKU、描述等裂变 |
| **订单管理 (OMS)** | 多平台订单处理 | P0 | 支持自动拉取、订单详情获取、订单确认、发货回传等 |
| | 订单利润分析 | P0 | 计算每笔订单利润，包含采购成本、平台费、物流、税费等 |
| **库存管理 (WMS)** | 库存同步 | P0 | 各平台库存同步，防超卖 |
| | 库存预警 | P0 | 安全库存提醒 |
| | 库存分配 | P1 | 指定仓库库存 |
| **财务管理 (FIN)** | 财务对账 | P0 | 结算流水、费用流水、退款流水对账 |
| | 多币种对账 | P0 | 支持不同币种的对账 |
| | 平台费用监控 | P0 | 监控各平台费用 |
| **供应商管理 (SCM)** | 供应商产能监控 | P1 | 监控供应商产能情况 |
| **客户关系 (CRM)** | CRM客户管理 | P1 | 管理客户信息和订单 |

#### 平台接入需求

| 类型 | 平台 | 技术实现 |
|------|------|----------|
| **有 API 平台** | TikTok Shop | 通过官方 API 对接 |
| | Amazon | 通过 SP-API 对接 |
| | eBay | 通过官方 API 对接 |
| | Shopee | 通过官方 API 对接 |
| **无 API 平台** | Temu | 通过 No-API Bridge 对接 |
| | Taobao | 通过 No-API Bridge 对接 |

### 1.2 非功能需求

| 需求类型 | 具体要求 | 技术实现 |
|----------|----------|----------|
| **性能** | 核心接口响应 <200ms | 使用缓存、优化数据库查询 |
| | 内存占用符合 4096MB 限制 | 合理管理内存使用 |
| | 数据库慢查询 <100ms | 优化 SQL 查询，添加索引 |
| **可用性** | 99.9% 可用性 | 高可用架构设计 |
| | 健康检查接口 | 实现 /api/health 接口 |
| **安全性** | 环境变量管理 | 使用 .env 文件，忽略提交 |
| | 敏感密钥管理 | 使用 Vault 或类似服务 |
| | 跨租户数据隔离 | 基于 tenantId 进行数据隔离 |
| | SQL 注入防护 | 使用参数化查询 |
| **可扩展性** | 多租户模型 | 支持 Tenant -> Organization -> Shop -> User 四层级隔离 |
| | 插件系统 | 支持 Extension 扩展 |
| **可维护性** | 代码规范 | 遵循 ESLint、Prettier 规范 |
| | 文档完整 | 完善的技术文档 |

### 1.3 数据需求

#### 核心数据模型

| 数据模型 | 关键字段 | 说明 |
|----------|----------|------|
| **商品 (SPU/SKU)** | tenantId, productId/spuId, skuId, skuCode, attributes, costPrice, status | 作为刊登/库存/订单的统一主数据 |
| **平台映射** | tenantId, shopId, platform, erpSkuId, platformProductId, platformSkuId, mappingVersion | 避免“同一SKU多次重复刊登/重复拉单” |
| **订单** | tenantId, shopId, platformOrderId, orderId, status, buyer, amount, currency, createTime | 订单主表，状态机承载者 |
| **订单项** | orderId, skuId, platformSkuId, quantity, price, cost | 承接利润与库存扣减 |
| **库存流水** | tenantId, warehouseId, skuId, changeType, deltaQty, balanceQty, refType, refId, occurTime | 占库/扣库/回补/盘点统一落流水 |
| **运单/履约** | tenantId, orderId, shipmentId, carrier, trackingNo, labelUrl, status | 发货回传与轨迹同步承载者 |
| **售后/退货/质检** | tenantId, orderId, returnId, reason, status, inspectionResult, photos | 逆向闭环承载者 |
| **退款** | tenantId, orderId, refundId, amount, status, decisionStatus | 必须走门禁状态机 |
| **结算/费用** | tenantId, shopId, statementId, feeLines[], settledAmount, currency, status | 对账闭环承载者 |

### 1.4 安全需求

| 安全类型 | 具体要求 | 技术实现 |
|----------|----------|----------|
| **认证授权** | JWT 认证 | 实现基于 JWT 的认证机制 |
| | RBAC 权限模型 | 基于角色的访问控制 |
| | 预设角色 | ADMIN, MANAGER, OPERATOR, FINANCE, SOURCING, LOGISTICS, ANALYST |
| **数据安全** | 数据加密 | 敏感数据加密存储 |
| | 数据脱敏 | 敏感日志脱敏处理 |
| | 审计日志 | 全量操作流水线日志 |
| **API 安全** | 请求限流 | 基于 Redis 实现 API 速率限制 |
| | 防 CSRF | 实现 CSRF 防护 |
| | 防 XSS | 实现 XSS 防护 |

## 2. 架构设计

### 2.1 系统架构

#### 三层架构

```mermaid
flowchart TD
    subgraph Console[前端中控台]
        UI[用户界面]
        Components[业务组件]
        State[状态管理]
        Services[API服务层]
    end

    subgraph Hub[后端服务层]
        API[API路由]
        Core[核心业务逻辑]
        Domains[业务领域模型]
        Workers[异步任务]
        DB[数据库]
        Cache[缓存]
    end

    subgraph Extension[边缘执行层]
        WinNode[Win Node Agent]
        BrowserWorker[Browser Worker]
        Collect[数据采集]
    end

    UI --> Components
    Components --> State
    State --> Services
    Services --> API

    API --> Core
    Core --> Domains
    Core --> Workers
    Domains --> DB
    Core --> Cache

    Core --> WinNode
    WinNode --> BrowserWorker
    BrowserWorker --> Collect
    Collect --> Core
```

#### 核心模块关系

| 模块 | 职责 | 依赖关系 |
|------|------|----------|
| **API 路由层** | 处理 HTTP 请求，参数验证 | 依赖 Core 层 |
| **核心业务逻辑** | 业务规则处理，状态管理 | 依赖 Domains 层 |
| **业务领域模型** | 数据模型，业务实体 | 依赖 DB |
| **异步任务** | 处理耗时操作，如采集、同步 | 依赖 Core 层 |
| **边缘执行层** | 处理无 API 平台的操作 | 依赖 Core 层 |

### 2.2 目录结构

#### 前端目录结构

```
src/
├── components/          # 公共组件
│   ├── Business/        # 业务组件
│   └── Basic/           # 基础组件
├── pages/              # 页面组件
├── stores/              # Zustand 状态管理
├── services/            # API 服务层 (TanStack Query)
├── utils/               # 工具函数
├── hooks/               # 自定义 Hooks
├── types/               # TypeScript 类型定义
└── assets/             # 静态资源
```

#### 后端目录结构

```
server/src/
├── core/              # 核心功能、算力调度、隐私审计
├── domains/           # 业务领域模型
│   ├── product/       # 商品相关
│   ├── order/         # 订单相关
│   ├── inventory/     # 库存相关
│   ├── finance/       # 财务相关
│   ├── supplier/      # 供应商相关
│   └── customer/      # 客户相关
├── api/               # 外部与内部 API 路由
│   ├── controllers/   # 控制器
│   ├── routes/        # 路由定义
│   └── middleware/    # 中间件
├── workers/           # 异步任务与爬虫任务
├── utils/             # 工具函数
└── config/            # 配置文件
```

### 2.3 技术实现

#### 前端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| UmiJS | 4.x | 前端框架 |
| Ant Design | 5.x | UI 组件库 |
| Zustand | 4.x | 全局状态管理 |
| TanStack Query | 5.x | 服务端状态管理 |
| React Hook Form | 最新 | 表单管理 |
| Zod | 最新 | 表单验证 |
| AntV G2/G6 | 5.x | 数据可视化 |
| Axios | 最新 | HTTP 客户端 |

#### 后端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Node.js | v20+ | 运行环境 |
| TypeScript | 最新 | 开发语言 |
| MySQL | 8.0 | 数据库 |
| Redis | 6.0 | 缓存、队列 |
| Knex.js | 最新 | ORM |
| Express | 最新 | Web 框架 |
| JWT | 最新 | 认证 |
| BullMQ | 最新 | 任务队列 |

### 2.4 数据库设计

#### 核心表结构

| 表名 | 说明 | 关键字段 |
|------|------|----------|
| **cf_user** | 用户表 | id, username, password, role, tenant_id |
| **cf_tenant** | 租户表 | id, name, status |
| **cf_shop** | 店铺表 | id, tenant_id, platform, shop_name, api_credentials |
| **cf_product** | 商品表 | id, tenant_id, spu_id, sku_id, sku_code, attributes, cost_price, status |
| **cf_platform_mapping** | 平台映射表 | id, tenant_id, shop_id, platform, erp_sku_id, platform_product_id, platform_sku_id |
| **cf_order** | 订单表 | id, tenant_id, shop_id, platform_order_id, status, buyer, amount, currency |
| **cf_order_item** | 订单项表 | id, order_id, sku_id, platform_sku_id, quantity, price, cost |
| **cf_inventory_log** | 库存流水表 | id, tenant_id, warehouse_id, sku_id, change_type, delta_qty, balance_qty, ref_type, ref_id |
| **cf_shipment** | 运单表 | id, tenant_id, order_id, carrier, tracking_no, label_url, status |
| **cf_after_sales** | 售后表 | id, tenant_id, order_id, reason, status, inspection_result |
| **cf_refund** | 退款表 | id, tenant_id, order_id, amount, status, decision_status |
| **cf_statement** | 结算表 | id, tenant_id, shop_id, statement_id, settled_amount, currency, status |

### 2.5 API 设计

#### RESTful API 标准

| 方法 | 用途 | 示例 |
|------|------|------|
| GET | 查询 | GET /api/v1/orders |
| POST | 创建 | POST /api/v1/orders |
| PUT | 完整更新 | PUT /api/v1/orders/:id |
| PATCH | 部分更新 | PATCH /api/v1/orders/:id |
| DELETE | 删除 | DELETE /api/v1/orders/:id |

#### 响应结构

```typescript
// 成功响应
{
  "success": true,
  "data": { ... },
  "pagination": { "page": 1, "pageSize": 20, "total": 100 }
}

// 错误响应
{
  "success": false,
  "error": { "code": "ORDER_NOT_FOUND", "message": "订单不存在", "details": {} }
}
```

### 2.6 部署方案

#### 开发环境

| 组件 | 配置 |
|------|------|
| Node.js | v20+ |
| MySQL | 8.0 (本地或 Docker) |
| Redis | 6.0 (本地) |
| 前端 | UmiJS 开发服务器 |
| 后端 | Express 开发服务器 |

#### 生产环境

| 组件 | 配置 |
|------|------|
| 前端 | 阿里云 OSS + CDN |
| 后端 | 阿里云 ECS |
| 数据库 | 阿里云 RDS (MySQL 8.0) |
| 缓存 | 阿里云 Redis |
| 监控 | 阿里云 SLS + Prometheus |

#### 部署流程

1. **代码构建**：前端和后端代码构建
2. **资源部署**：前端静态资源部署到 OSS，后端代码部署到 ECS
3. **数据库迁移**：执行数据库迁移脚本
4. **服务启动**：启动后端服务
5. **健康检查**：验证服务是否正常运行

## 3. 技术风险评估

| 风险类型 | 具体风险 | 影响程度 | 应对措施 |
|----------|----------|----------|----------|
| **平台 API 变更** | 第三方平台 API 变更导致集成失败 | 高 | 建立 API 监控机制，定期检查 API 状态 |
| **无 API 平台反爬** | 无 API 平台的反爬机制导致采集失败 | 高 | 实现智能反爬策略，如代理 IP 池、UA 轮换、指纹隔离 |
| **数据一致性** | 多平台数据同步不一致 | 高 | 实现分布式事务，确保数据一致性 |
| **性能瓶颈** | 大量订单或商品数据导致系统性能下降 | 中 | 优化数据库查询，使用缓存，实现异步处理 |
| **安全漏洞** | 系统存在安全漏洞 | 高 | 定期进行安全审计，使用安全扫描工具 |

## 4. 技术选型理由

| 技术 | 选型理由 |
|------|----------|
| **Node.js** | 高性能、事件驱动，适合处理大量并发请求 |
| **TypeScript** | 类型安全，提高代码质量和可维护性 |
| **MySQL** | 成熟稳定，适合关系型数据存储 |
| **Redis** | 高性能缓存，适合存储会话和热点数据 |
| **UmiJS** | 开箱即用，集成了路由、构建等功能 |
| **Ant Design** | 组件丰富，设计美观，适合企业级应用 |
| **Zustand** | 轻量级状态管理，易于使用 |
| **TanStack Query** | 强大的服务端状态管理，支持缓存和同步 |

## 5. 开发计划

### 5.1 里程碑

| 阶段 | 目标 | 时间预估 |
|------|------|----------|
| **需求分析与架构设计** | 完成技术需求分析和架构设计 | 1 周 |
| **核心功能开发** | 实现商品管理、订单管理、库存管理等核心功能 | 8 周 |
| **平台接入** | 完成各平台 API 接入 | 4 周 |
| **测试与优化** | 进行功能测试、性能测试和安全测试 | 2 周 |
| **部署上线** | 部署到生产环境并进行监控 | 1 周 |

### 5.2 关键技术点

1. **多平台商品刊登**：实现统一的商品发布接口，支持多平台适配
2. **订单履约闭环**：实现从订单拉取到发货回传的完整流程
3. **库存同步机制**：确保各平台库存数据一致，防止超卖
4. **财务对账系统**：实现多币种对账，支持差异处理
5. **No-API 平台接入**：实现智能爬虫和数据解析
6. **多租户隔离**：确保不同租户数据安全隔离
7. **性能优化**：优化系统性能，确保高并发场景下的稳定性

## 6. 结论

Crawlful Hub 项目是一个功能丰富、技术复杂度较高的企业级贸易 ERP 系统。通过合理的技术选型和架构设计，我们可以构建一个稳定、高效、安全的系统，满足企业级用户的需求。

本技术需求分析和架构设计文档为开发团队提供了清晰的技术指导，包括功能需求、非功能需求、数据需求、安全需求以及系统架构、目录结构、技术实现、数据库设计、API 设计和部署方案等。

在开发过程中，我们需要关注技术风险，采取相应的应对措施，确保系统的稳定性和可靠性。同时，我们需要按照开发计划有序推进，确保项目按时完成。