Files

wurenzhi eafa1bbe94 feat: 添加货币和汇率管理功能

refactor: 重构前端路由和登录逻辑

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

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

chore: 更新依赖项和配置文件

2026-03-19 19:08:15 +08:00

7.4 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

2. 跨境电商闭环

Flow: Frontend → CrossBorderController.manageProduct → CrossBorderService.checkCompliance → CrossBorderService.calculateTariff → PlatformIntegrationService.integrateWithSellbrite → PlatformIntegrationService.integrateWithShoplazza → PlatformIntegrationService.integrateWithSaleSmartly → InventorySyncService.syncMultiPlatformInventory → LogisticsService.selectLogisticsChannel → CustomsService.generateCustomsDocuments → PaymentService.processCrossBorderPayment → MarketingService.integrateOmniChannelMarketing → CustomerService.manageCrossBorderCommunication → 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

18. 多语言服务闭环

Flow: Frontend → I18nController.switchLanguage → I18nService.setUserLanguage → LanguageRepository.updateUserPreference → Response

19. 翻译管理闭环

Flow: Frontend / Backend → TranslationController.createTranslation → TranslationService.requestTranslation → ExternalTranslationApi.translate → TranslationService.reviewTranslation → TranslationRepository.save → I18nService.refreshLanguageCache → Response

20. 多语言内容发布闭环

Flow: Frontend → ContentController.createContent → ContentService.saveContent → TranslationService.autoTranslate → TranslationService.requestReview → TranslationService.approveTranslation → ContentService.publishMultiLanguageContent → Response

21. 货币管理闭环

Flow: Frontend / Backend → CurrencyController.getCurrencies → CurrencyService.getCurrencies → CurrencyRepository.findAll → Response

22. 汇率更新闭环

Flow: Scheduler → ExchangeRateService.updateExchangeRates → ExternalExchangeRateApi.fetchRates → ExchangeRateRepository.save → RedisService.setCache → Response

23. 货币转换闭环

Flow: Frontend / Backend → CurrencyConversionController.convert → CurrencyConversionService.convert → ExchangeRateService.getExchangeRate → CurrencyConversionService.calculate → Response

24. 多货币计算闭环

Flow: Frontend / Backend → CurrencyCalculationController.calculatePrice → CurrencyCalculationService.calculatePrice → CurrencyConversionService.convert → PricingService.applyMarkup → Response

7.4 KiB Raw Blame History Unescape Escape