wurenzhi
136c2fa579
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
341 lines
14 KiB
Markdown
341 lines
14 KiB
Markdown
# 技术需求分析与架构设计
|
||
|
||
> **文档目的**：对 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 设计和部署方案等。
|
||
|
||
在开发过程中，我们需要关注技术风险，采取相应的应对措施，确保系统的稳定性和可靠性。同时，我们需要按照开发计划有序推进，确保项目按时完成。 |