feat: 初始化项目结构并添加核心功能模块

- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
2026-03-17 22:07:19 +08:00
parent c0870dce50
commit 136c2fa579
728 changed files with 107690 additions and 5614 deletions
--- a/archive/handover/technical-requirement-analysis.md
+++ b/archive/handover/technical-requirement-analysis.md
@@ -0,0 +1,341 @@
+# 技术需求分析与架构设计
+
+> **文档目的**：对 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 设计和部署方案等。
+
+在开发过程中，我们需要关注技术风险，采取相应的应对措施，确保系统的稳定性和可靠性。同时，我们需要按照开发计划有序推进，确保项目按时完成。