makemd/docs/ARCHIVE/01_Architecture/04_Service_Map.md

# 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