makemd/docs/ARCHIVE/02_Backend/01_Design.md

Backend Design (Crawlful Hub)

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

---

1. 技术栈 (Tech Stack)

1.1 当前技术栈

层级	技术	版本	用途
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	单元测试

1.2 技术栈演进 (2026 Q4 目标)

层级	技术	版本	用途
Runtime	Node.js	22+	运行时环境
Language	TypeScript	5.x	开发语言
Framework	NestJS	10.x	Web 框架
Database	MySQL 8.0 + MongoDB	-	主数据库 + 文档数据库
ORM	Prisma	5.x	ORM 框架
Cache	Redis	7.0+	缓存 & 队列
Queue	BullMQ	5.x	异步任务队列
Testing	Jest + SuperTest	-	单元测试 + 集成测试
微服务	gRPC + Kubernetes	-	服务通信 & 容器编排

---

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 规范
• 数据库设计
• 系统架构
• 业务蓝图

---

11. 后端发展规划

11.1 架构规划

• 微服务架构: 将核心服务拆分为独立微服务，如商品服务、订单服务、财务服务等
• 服务网格: 引入 Istio 实现服务治理、流量管理和安全策略
• 容器化部署: 使用 Docker + Kubernetes 实现容器编排和自动扩缩容
• Serverless 集成: 部分无状态服务采用 Serverless 架构，降低运维成本
• API 网关: 统一 API 入口，实现认证、限流、监控等功能

11.2 服务能力扩展

服务	现有功能	计划扩展
商品服务	基础商品管理、套利分析	智能选品、商品生命周期管理、多平台自动同步
订单服务	订单管理、状态流转	智能审单、异常订单自动处理、多渠道订单聚合
财务服务	财务结算、税务计算	智能对账、多币种自动换算、税务报表自动生成
库存服务	库存管理、库存预测	智能补货建议、库存预测、多仓协同
营销服务	营销管理、广告自动化	智能广告优化、竞品分析、多平台营销协同
供应链服务	供应链管理、供应商管理	智能供应商评估、采购预测、供应链风险预警
物流服务	物流智能	智能物流路径规划、运费优化、实时轨迹监控

11.3 AI 能力规划

• 智能决策引擎: 基于机器学习的定价、选品、营销决策
• 自然语言处理: 客户服务、商品描述生成、评论分析
• 计算机视觉: 商品图片识别、质量检测、视觉寻源
• 预测分析: 销售预测、库存预测、风险预测
• 自动化运营: 智能客服、自动广告优化、自动库存管理

11.4 性能优化规划

• 数据库优化: 读写分离、分库分表、索引优化
• 缓存策略: 多级缓存、热点数据预加载
• 并发处理: 异步处理、批量操作、线程池优化
• 网络优化: HTTP/2、HTTP/3 支持，减少请求体积
• 监控体系: 全链路监控、性能指标采集、异常预警

11.5 安全增强

• 零信任架构: 基于身份的访问控制，最小权限原则
• 数据加密: 传输加密、存储加密、敏感数据保护
• 漏洞扫描: 定期安全扫描、漏洞修复
• 安全审计: 全操作审计、合规性检查
• 灾备方案: 多地域部署、数据备份、容灾演练

---

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

---

12. 商品中心异常处理（Product Center Exception Handling）

设计原则: 统一异常处理机制，确保商品、价格、库存、授权等核心业务的异常可追溯、可恢复

12.1 异常分类

异常类型	异常代码	说明	处理策略
商品异常	PRODUCT_*	商品相关异常	重试 + 人工审核
价格异常	PRICE_*	价格相关异常	回滚 + 告警
库存异常	INVENTORY_*	库存相关异常	补偿 + 预警
授权异常	AUTH_*	授权相关异常	刷新 + 降级
同步异常	SYNC_*	平台同步异常	重试 + 记录

12.2 商品异常处理

异常代码	异常场景	处理流程	恢复机制
PRODUCT_NOT_FOUND	商品不存在	记录日志 → 返回错误	-
PRODUCT_DUPLICATE	商品重复	检查唯一约束 → 返回冲突	-
PRODUCT_MAPPING_FAILED	SKU映射失败	记录日志 → 标记待处理	手动映射
PRODUCT_LISTING_FAILED	刊登失败	记录错误 → 重试队列	自动重试
PRODUCT_SYNC_FAILED	同步失败	记录差异 → 补偿队列	数据补偿

12.3 价格异常处理

异常代码	异常场景	处理流程	恢复机制
PRICE_BELOW_COST	价格低于成本	阻止操作 → 告警	人工审核
PRICE_BELOW_MARGIN	利润率低于红线	阻止操作 → 风控审核	审批流程
PRICE_SYNC_FAILED	价格同步失败	回滚本地 → 重试队列	自动重试
PRICE_STRATEGY_CONFLICT	策略冲突	优先级判断 → 记录日志	策略调整
PRICE_CALCULATION_ERROR	价格计算错误	使用基准价 → 告警	人工修正

12.4 库存异常处理

异常代码	异常场景	处理流程	恢复机制
INVENTORY_INSUFFICIENT	库存不足	阻止操作 → 预警	补货提醒
INVENTORY_OVERSOLD	超卖	订单挂起 → 人工处理	补货/取消
INVENTORY_SYNC_FAILED	库存同步失败	记录差异 → 补偿队列	数据补偿
INVENTORY_DISCREPANCY	库存差异	记录差异 → 告警	人工核对
INVENTORY_NEGATIVE	负库存	阻止操作 → 告警	库存调整

12.5 授权异常处理

异常代码	异常场景	处理流程	恢复机制
AUTH_TOKEN_EXPIRED	Token过期	自动刷新 → 重试	重新授权
AUTH_REFRESH_FAILED	刷新失败	标记过期 → 告警	人工授权
AUTH_PERMISSION_DENIED	权限不足	记录日志 → 返回错误	权限申请
AUTH_RATE_LIMITED	API限流	延迟重试 → 降级	队列处理
AUTH_PLATFORM_ERROR	平台错误	记录错误 → 降级	平台恢复

12.6 异常处理流程

异常发生
    ↓
异常捕获（try-catch / 全局异常处理器）
    ↓
异常分类（根据异常代码）
    ↓
异常处理（根据处理策略）
    ├── 可恢复异常 → 重试 / 补偿
    ├── 需人工介入 → 告警 / 工单
    └── 不可恢复 → 记录 / 返回错误
    ↓
异常记录（日志 + 数据库）
    ↓
异常通知（相关责任人）

12.7 异常处理代码示例

// 商品服务异常处理示例
async createProduct(productData: ProductCreateDto): Promise<Product> {
  try {
    // 1. 检查商品唯一性
    const existing = await this.productRepository.findByName(productData.name);
    if (existing) {
      throw new ProductException('PRODUCT_DUPLICATE', '商品已存在');
    }
    
    // 2. 创建商品
    const product = await this.productRepository.create(productData);
    
    // 3. 同步到平台
    await this.syncToPlatforms(product);
    
    return product;
  } catch (error) {
    // 记录异常
    await this.exceptionService.log({
      code: error.code || 'PRODUCT_UNKNOWN',
      message: error.message,
      context: { productData },
      stack: error.stack
    });
    
    // 根据异常类型处理
    if (error instanceof RetryableException) {
      await this.retryQueue.add('product-sync', { productId: product.id });
    }
    
    throw error;
  }
}

// 价格服务异常处理示例
async updatePrice(skuId: string, newPrice: number): Promise<void> {
  const sku = await this.skuRepository.findById(skuId);
  
  // 利润红线检查
  const margin = this.calculateMargin(sku, newPrice);
  if (margin < this.getMarginThreshold(sku.businessType)) {
    throw new PriceException('PRICE_BELOW_MARGIN', 
      `利润率 ${margin}% 低于红线 ${this.getMarginThreshold(sku.businessType)}%`);
  }
  
  // 乐观锁更新
  const updated = await this.skuRepository.updateWithVersion(skuId, {
    basePrice: newPrice,
    version: sku.version + 1
  });
  
  if (!updated) {
    throw new ConcurrentUpdateException('SKU已被其他操作修改，请重试');
  }
}

12.8 异常监控与告警

监控指标	正常范围	预警阈值	告警阈值
异常发生率	<1%	>3%	>5%
异常恢复率	>95%	<90%	<80%
异常处理时长	<5分钟	>15分钟	>30分钟
重试成功率	>90%	<80%	<70%