wurenzhi
72cd7f6f45
删除不再需要的归档文件和过时的文档模板，包括多个README、安全策略、前端集成蓝图等文件，同时移除了未使用的业务文档和项目结构文件。 优化项目结构，移除冗余文件，保持代码库整洁。主要删除archive/handover目录下的多个文件及doc目录下的部分文档模板。
350 lines
9.7 KiB
Markdown
350 lines
9.7 KiB
Markdown
# 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 注释规范
|
||
|
||
```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)
|
||
|
||
---
|
||
|
||
*本文档基于代码自动生成，最后更新: 2026-03-18*
|