makemd/docs/02_Backend/Backend_Design.md

Backend Design (Crawlful Hub)

定位：Crawlful Hub 后端架构设计文档 - 包含技术栈、目录结构、核心服务及依赖规则。 更新日期: 2026-03-18

---

1. 技术栈 (Tech Stack)

层级	技术	版本	用途
Runtime	Node.js	20+	运行时环境
Language	TypeScript	5.x	开发语言 (strict: true)
Framework	Express.js	4.x	Web 框架
Database	MySQL	8.0	主数据库 (cf_ 前缀)
ORM	Knex.js	3.x	SQL 构建器
Cache	Redis	6.0	缓存 & 队列
Queue	BullMQ	5.x	异步任务队列
Testing	Jest	29.x	单元测试

---

2. 目录结构 (Directory Structure)

server/src/
│
├─ api/                          # API 层
│   ├─ controllers/             # 控制器 (HTTP 请求处理)
│   │   ├─ ProductController.ts
│   │   ├─ OrderController.ts
│   │   ├─ AuthController.ts
│   │   └─ ...
│   ├─ middlewares/             # 中间件
│   │   ├─ auth.middleware.ts
│   │   ├─ tenant.middleware.ts
│   │   └─ trace.middleware.ts
│   └─ routes/                  # 路由定义
│       ├─ product.routes.ts
│       ├─ order.routes.ts
│       └─ ...
│
├─ services/                     # 服务层 (业务逻辑)
│   ├─ ProductService.ts        # 商品服务
│   ├─ OrderService.ts          # 订单服务
│   ├─ FinanceService.ts        # 财务服务
│   ├─ InventoryService.ts      # 库存服务
│   ├─ AuthService.ts           # 认证服务
│   └─ ... (200+ 服务类)
│
├─ domains/                      # 领域层 (按业务域组织)
│   ├─ Trade/                   # 交易域
│   │   ├─ ConsumerOrderService.ts
│   │   ├─ TradeService.ts
│   │   └─ ...
│   ├─ Analytics/               # 分析域
│   │   ├─ ReportService.ts
│   │   ├─ AnalyticsService.ts
│   │   └─ ...
│   └─ Tenant/                  # 租户域
│       ├─ TenantService.ts
│       └─ ...
│
├─ models/                       # 数据模型
│   ├─ Product.ts
│   ├─ User.ts
│   ├─ Order.ts
│   └─ ...
│
├─ core/                         # 核心基础设施
│   ├─ ai/                      # AI 引擎
│   │   └─ FingerprintEngine.ts
│   ├─ pipeline/                # 流水线引擎
│   │   ├─ PipelineEngine.ts
│   │   └─ PipelineTypes.ts
│   ├─ telemetry/               # 遥测服务
│   │   ├─ GlobalTracingService.ts
│   │   ├─ PredictiveHealthService.ts
│   │   └─ ...
│   └─ workers/                 # Worker 管理
│       └─ WorkerHub.ts
│
├─ workers/                      # 任务 Worker
│   ├─ PlatformSyncWorker.ts  # 平台API数据同步（有API平台）
│   └─ WorkerHub.ts
│
├─ shared/                       # 共享资源
│   ├─ types/                   # 类型定义
│   │   ├─ contracts/
│   │   └─ ...
│   └─ contracts/               # 接口契约
│       └─ business-contracts.ts
│
├─ utils/                        # 工具函数
│   ├─ logger.ts
│   ├─ RedisService.ts
│   └─ SignatureUtils.ts
│
├─ config/                       # 配置文件
│   └─ database.ts
│
└─ plugins/                      # 插件
    └─ RedisQuota.plugin.ts

---

3. 分层架构 (Layered Architecture)

3.1 依赖规则

API (Controllers)
    ↓ (调用)
Services (业务逻辑)
    ↓ (调用)
Domains (领域服务)
    ↓ (调用)
Models / Repository (数据访问)

3.2 允许的依赖

从	到	说明
api/controllers	services	Controller 调用 Service
services	domains	Service 调用 Domain
services	models	Service 直接操作 Model
domains	services	Domain 可调用 Service
domains	models	Domain 直接操作 Model
core	services	核心可调用 Service
workers	services	Worker 调用 Service

3.3 禁止的依赖

从	到	原因
api/controllers	models	禁止跨层访问
models	services	下层不能依赖上层
services	api	业务层不应感知 HTTP

---

4. 核心服务清单 (Core Services)

4.1 商品管理 (PIM)

服务	文件	功能
ProductService	services/ProductService.ts	商品 CRUD
PlatformApiService	services/PlatformApiService.ts	平台API对接（有API平台）
DynamicPricingService	services/DynamicPricingService.ts	动态定价
ArbitrageService	services/ArbitrageService.ts	套利分析
VisualSourcingService	services/VisualSourcingService.ts	视觉寻源

4.2 订单管理 (OMS)

服务	文件	功能
OrderService	services/OrderService.ts	订单管理
ConsumerOrderService	domains/Trade/ConsumerOrderService.ts	TOC 订单流
PaymentService	services/PaymentService.ts	支付处理
AuditService	services/AuditService.ts	审计日志

4.3 财务管理 (FIN)

服务	文件	功能
FinanceService	services/FinanceService.ts	财务结算
TaxService	services/TaxService.ts	税务计算
FXHedgingService	services/FXHedgingService.ts	汇率对冲
MultiCurrencyFinanceService	services/MultiCurrencyFinanceService.ts	多币种财务

4.4 库存管理 (WMS)

服务	文件	功能
InventoryService	services/InventoryService.ts	库存管理
InventoryForecastService	services/InventoryForecastService.ts	库存预测
WarehouseService	services/WarehouseService.ts	仓库管理
InventoryAgingService	services/InventoryAgingService.ts	库存老化分析

4.5 营销广告 (MKT)

服务	文件	功能
MarketingService	services/MarketingService.ts	营销管理
AdAutoService	services/AdAutoService.ts	广告自动化
CompetitorService	services/CompetitorService.ts	竞品监控
PlatformFeeWatcher	services/PlatformFeeWatcher.ts	平台费用监控

4.6 AI 服务

服务	文件	功能
AIService	services/AIService.ts	AI 核心服务
AgentSwarmService	services/AgentSwarmService.ts	多 AI 协作
AdviceService	domains/Strategy/AdviceService.ts	策略建议

4.7 供应链 (SCM)

服务	文件	功能
SupplyChainService	services/SupplyChainService.ts	供应链管理
SupplierService	services/SupplierService.ts	供应商管理
LogisticsIntelligenceService	services/LogisticsIntelligenceService.ts	物流智能

---

5. 基础设施 (Infrastructure)

5.1 数据库 (MySQL)

• 表前缀: cf_ (如 cf_product, cf_order)
• ORM: Knex.js
• 连接池: 默认配置
• 迁移: 代码中自动建表 (db.schema.hasTable 前置校验)

5.2 缓存 (Redis)

• 用途: 缓存、会话、速率限制
• 端口: 6379
• 服务类: RedisService.ts

5.3 队列 (BullMQ)

• 用途: 异步任务处理
• Worker: PlatformSyncWorker.ts (有API平台同步), WorkerHub.ts
• 并发限制: ≤ 10

5.4 资源限制

• 内存: Node.js 进程限制 --max-old-space-size=4096 (4GB)
• 图片处理: Sharp 必须开启 sequentialRead
• API 速率: 基于 Redis 的速率限制

5.4 遥测 (Telemetry)

• 全局追踪: GlobalTracingService
• 健康预测: PredictiveHealthService
• 网络拓扑: NetworkTopologyService

---

6. 安全与权限

6.1 认证 (Auth)

• 服务: AuthService.ts
• 方式: JWT + OAuth2 + MFA
• 中间件: auth.middleware.ts

6.2 权限 (RBAC)

• 角色: ADMIN, MANAGER, OPERATOR, FINANCE, SOURCING, LOGISTICS, ANALYST
• 中间件: authorize(permission)
• 数据隔离:
  • tenantId: 租户隔离
  • parentId: 层级过滤（非 ADMIN 用户必须）
• ⚠️ 禁止: Controller 中硬编码 role === 'ADMIN'

6.3 审计 (Audit)

• 服务: AuditService.ts
• 五元组: tenantId/shopId/taskId/traceId/businessType
• 日志: 所有操作记录到 cf_audit_logs

---

7. 开发规范

7.1 命名规范

• 服务类: XxxService 后缀。禁止使用 Manager/Helper 等后缀
• 控制器: XxxController 后缀
• 模型: 大驼峰，单数形式
• 文件: 大驼峰 (PascalCase)

7.2 注释规范

/**
 * [TASK_ID] 服务名称
 * @description 功能描述
 * @version 1.0
 */
export class XxxService { ... }

7.3 错误处理

• 使用 try-catch 包裹异步操作
• 返回标准错误格式: { success: false, error: string }
• 记录错误日志

---

8. 测试

8.1 测试结构

services/__tests__/
├─ EventBusService.test.ts
├─ PaymentService.test.ts
├─ OrderService.test.ts
└─ ...

8.2 测试命令

npm test          # 运行所有测试
npm test -- --watch  # 监听模式

---

9. 部署

9.1 环境变量

DATABASE_URL=mysql://user:pass@host:3306/db
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret
PORT=3000

9.2 启动命令

npm run dev       # 开发模式
npm run build     # 构建
npm start         # 生产模式

---

10. 相关文档

• API 规范
• 数据库设计
• 系统架构
• 业务蓝图

---

本文档基于代码自动生成，最后更新: 2026-03-18