wurenzhi
2b86715c09
- 移除未使用的TabPane组件 - 修复类型定义和导入方式 - 优化mock数据源的环境变量判断逻辑 - 更新文档结构并归档旧文件 - 添加新的UI组件和Memo组件 - 调整API路径和响应处理
549 lines
11 KiB
Markdown
549 lines
11 KiB
Markdown
# 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
|