makemd/archive/handover/technical-requirement-analysis.md

技术需求分析与架构设计

文档目的：对 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 系统架构

三层架构

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

响应结构

// 成功响应
{
  "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 设计和部署方案等。

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