wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a03784385158416b6c80b01871f529667b7d6318
makemd/docs/02_Backend/01_Design.md
wurenzhi eafa1bbe94 feat: 添加货币和汇率管理功能 
refactor: 重构前端路由和登录逻辑

docs: 更新业务闭环、任务和架构文档

style: 调整代码格式和文件结构

chore: 更新依赖项和配置文件
2026-03-19 19:08:15 +08:00

13 KiB
Raw Blame History

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. 相关文档

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

Reference in New Issue View Git Blame Copy Permalink