Files

wurenzhi aa2cf560c6 feat: 添加汇率服务和缓存服务，优化数据源和日志服务

refactor: 重构数据源工厂和类型定义，提升代码可维护性

fix: 修复类型转换和状态机文档中的错误

docs: 更新服务架构文档，添加新的服务闭环流程

test: 添加汇率服务单元测试

chore: 清理无用代码和注释，优化代码结构

2026-03-19 14:19:01 +08:00

5.2 KiB

Raw Blame History

SERVICE_MAP（服务编排总图）

设计原则

核心原则（逻辑集中化）

所有业务逻辑必须集中在 Service 层，禁止分散在 Controller、前端或数据库操作中。

强制约束

✅ 所有业务必须通过 Service 层：禁止 Controller 直接操作数据库
✅ Controller 职责明确：只负责请求/响应和权限校验
✅ 一个业务 = 一条 Service Flow：每个业务操作对应一个完整的服务流程
✅ 服务调用必须遵循 STATE_MACHINE：状态流转必须符合状态机定义
✅ 涉及收费的业务必须接入 BILLING 系统：支付、权限、账单必须闭环
✅ 所有接口必须经过权限校验：使用 authorize() 中间件

禁止行为

❌ Controller 中写业务逻辑：业务决策、状态变化、数据校验必须在 Service 层
❌ 前端直接写业务规则：复杂计算、权限判断、状态流转禁止在 React 组件中实现
❌ 数据库操作分散：不同模块禁止直接调用数据库，必须通过 Service 层
❌ 脚本或工具处理逻辑：AI 任务或异步脚本必须通过 Service 层统一调用

服务层职责边界

Controller 层职责

接收 HTTP 请求和参数验证
调用 Service 层处理业务逻辑
返回响应给前端
权限校验（通过 authorize() 中间件）

Service 层职责（核心）

业务逻辑编排和状态流转
多模块协同和数据一致性保证
事务管理和异常处理
调用 Repository 层或外部 API

Repository 层职责

数据库 CRUD 操作
数据模型映射
查询优化

1. 功能开通闭环（收费核心）

Flow: Frontend → FeatureController.openFeature → FeatureService.checkAccess → PaymentService.createPayment → PaymentCallbackService.confirm → FeatureService.activateFeature → PermissionService.grant → BillingService.record → Response

2. 多商户订单闭环

Flow: Frontend → OrderController.create → OrderService.createOrder → OrderService.splitByMerchant → InventoryService.lockStock → OrderRepository.save → Response

3. 订单履约闭环

Flow: OrderService.confirm → ShipmentService.createShipment → OrderService.updateStatus → NotificationService.send

4. 结算闭环

Flow: Scheduler / Manual Trigger → SettlementService.calculate → SettlementService.generateBill → PaymentService.payout → BillingService.record

5. 权限校验闭环（所有接口必须经过）

Flow: Request → AuthMiddleware → PermissionService.check → Controller

6. 商户管理闭环

Flow: Frontend → MerchantController.create → MerchantService.register → VerificationService.verify → RBACService.assignRole → Response

7. 店铺管理闭环

Flow: Frontend → StoreController.create → StoreService.createStore → ProductService.setupProducts → InventoryService.initializeInventory → Response

8. 商户数据与分析闭环

Flow: Scheduler / Manual Trigger → AnalyticsService.collectData → ReportService.generateReport → NotificationService.sendReport → Response

9. 多商户库存同步闭环

Flow: Merchant Portal → InventoryController.sync → InventorySyncService.syncMerchantInventory → InventoryService.updateStock → ProductService.updateProductStatus → Response

10. 自动选品闭环

Flow: Frontend / Scheduler → ProductSelectionController.execute → ProductSelectionService.executeSelection → ProductSelectionService.calculateScore → ProductPoolRepository.save → AutoListingService.createListingTask → Response

11. 自动上架闭环

Flow: Scheduler / Manual Trigger → AutoListingController.batchList → AutoListingService.batchListProducts → PlatformApiService.publishProduct → ListingTaskRepository.updateStatus → NotificationService.notifyListingResult → Response

12. AI决策日志闭环

Flow: AI Service / Controller → AIDecisionLogService.createLog → AI Decision Execution → AIDecisionLogService.updateExecutionStatus → [Optional] AIDecisionLogService.recordHumanIntervention → Response

13. 多租户数据隔离闭环

Flow: Request → HierarchyAuthMiddleware.create → HierarchyAuthMiddleware.buildContext → DataIsolationService.buildIsolationQuery → Service Layer Operations → Response

14. 层级管理闭环

Flow: Frontend → HierarchyController → HierarchyService.createDepartment / createShop → DataIsolationService.validateHierarchy → EventBusService.publish → Response

15. 订单多店铺聚合闭环

Flow: Frontend → OrderController → OrderAggregationService.getAggregationStats → DataIsolationService.buildIsolationQuery → RedisService.get/set (缓存) → Response

16. 订单同步闭环

Flow: Frontend → OrderController.syncShopOrders → OrderAggregationService.syncShopOrders → PlatformAPI.fetchOrders → OrderRepository.upsert → EventBusService.publish('order.sync.completed') → Response

17. 异常处理闭环

Flow: Frontend / System → ExceptionController.handle → ExceptionService.process → NotificationService.alert → SettlementService.adjust → Response

5.2 KiB Raw Blame History Unescape Escape