# 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 注释规范

```typescript
/**
 * [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 测试命令

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

---

## 9. 部署

### 9.1 环境变量

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

### 9.2 启动命令

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

---

## 10. 相关文档

- [API 规范](./API_Specs/)
- [数据库设计](./Database/)
- [系统架构](../01_Architecture/System_Architecture.md)
- [业务蓝图](../00_Business/Business_Blueprint.md)

---

## 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*
