refactor: 优化代码结构并修复类型问题

- 移除未使用的TabPane组件 - 修复类型定义和导入方式 - 优化mock数据源的环境变量判断逻辑 - 更新文档结构并归档旧文件 - 添加新的UI组件和Memo组件 - 调整API路径和响应处理
2026-03-23 12:41:35 +08:00
parent a037843851
commit 2b86715c09
363 changed files with 39305 additions and 40622 deletions
--- a/docs/ARCHIVE/02_Backend/01_Design.md
+++ b/docs/ARCHIVE/02_Backend/01_Design.md
@@ -0,0 +1,557 @@
+# 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*
+
+---
+
+## 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 异常处理代码示例
+
+```typescript
+// 商品服务异常处理示例
+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% |