wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
makemd/docs/ARCHIVE/01_Architecture/04_Service_Map.md
wurenzhi 2b86715c09 refactor: 优化代码结构并修复类型问题 
- 移除未使用的TabPane组件
- 修复类型定义和导入方式
- 优化mock数据源的环境变量判断逻辑
- 更新文档结构并归档旧文件
- 添加新的UI组件和Memo组件
- 调整API路径和响应处理
2026-03-23 12:41:35 +08:00

11 KiB
Raw Permalink 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

25. 商品管理闭环（Product Center）

25.1 SPU管理闭环

Flow: Frontend → ProductController.createSPU → ProductService.createSPU → SPURepository.save → EventBusService.publish('spu.created') → Response

25.2 SKU管理闭环

Flow: Frontend → ProductController.createSKU → ProductService.createSKU → SKURepository.save → EventBusService.publish('sku.created') → Response

25.3 Listing管理闭环

Flow: Frontend → ProductController.createListing → ProductService.createListing → ListingRepository.save → PlatformAPIService.publishProduct → EventBusService.publish('listing.created') → Response

26. 价格策略闭环（Price Strategy）

26.1 价格策略创建闭环

Flow: Frontend → PriceController.createStrategy → PriceService.createStrategy → PriceStrategyRepository.save → PriceService.recalculatePrices → ListingRepository.batchUpdate → Response

26.2 价格计算闭环

Flow: PriceService.calculateFinalPrice → PriceService.getBasePrice (SKU层) → PriceService.applyStrategy (策略层) → PriceService.applyOverride (Listing层) → Return Final Price

价格计算公式：

最终价格 = override_price || strategy计算结果 || base_price

26.3 批量调价闭环

Flow: Frontend / Scheduler → PriceController.batchAdjust → PriceService.batchAdjust → PriceStrategyRepository.findByScope → ListingRepository.findByScope → PlatformAPIService.updatePrice → ListingRepository.batchUpdate → EventBusService.publish('price.updated') → Response

27. SKU映射闭环（SKU Mapping）

27.1 自动映射闭环

Flow: Frontend / Scheduler → MappingController.autoMap → MappingService.autoMap → MappingService.calculateSimilarity → SKUMappingRepository.save → EventBusService.publish('mapping.created') → Response

27.2 手动映射闭环

Flow: Frontend → MappingController.manualMap → MappingService.validateMapping → SKUMappingRepository.save → EventBusService.publish('mapping.created') → Response

27.3 映射验证闭环

Flow: Scheduler → MappingService.verifyMappings → PlatformAPIService.fetchProductInfo → MappingService.compareAttributes → SKUMappingRepository.updateConfidence → Response

28. 店铺授权闭环（Shop Authorization）

28.1 OAuth授权闭环

Flow: Frontend → AuthController.initOAuth → AuthService.generateAuthUrl → PlatformOAuthService.authorize → AuthService.handleCallback → ShopAuthorizationRepository.save → EventBusService.publish('auth.completed') → Response

28.2 Agent授权闭环

Flow: Frontend → AuthController.initAgentAuth → AgentService.createSession → AgentService.captureCookies → ShopAuthorizationRepository.save → EventBusService.publish('auth.completed') → Response

28.3 授权状态检查闭环

Flow: Scheduler → AuthService.checkAuthStatus → AuthService.validateToken → ShopAuthorizationRepository.updateStatus → NotificationService.notifyExpiring → Response

29. 组织架构闭环（Organization）

29.1 组织创建闭环

Flow: Frontend → OrganizationController.create → OrganizationService.createOrg → OrganizationRepository.save → OrganizationService.updatePath → EventBusService.publish('org.created') → Response

29.2 数据范围构建闭环

Flow: Request → DataScopeMiddleware → DataScopeService.buildScope → OrganizationService.getUserOrg → OrganizationService.getDescendants → Return Scope Filter

30. 商品同步闭环（Product Sync）

30.1 全量同步闭环

Flow: Scheduler / Manual → SyncController.fullSync → SyncService.fullSync → PlatformAPIService.fetchAllProducts → ProductRepository.batchUpsert → ListingRepository.batchUpsert → EventBusService.publish('sync.completed') → Response

30.2 增量同步闭环

Flow: Scheduler → SyncController.incrementalSync → SyncService.incrementalSync → PlatformAPIService.fetchUpdatedProducts → ProductRepository.batchUpsert → ListingRepository.batchUpsert → EventBusService.publish('sync.completed') → Response

Reference in New Issue View Git Blame Copy Permalink