wurenzhi
cd55097dbf
删除旧的docs11目录及其所有内容，包括： - 业务蓝图文档(business-blueprint.md) - 数据API规范(data-api-specs.md) - 系统架构文档(system-architecture.md) - 模块蓝图文档(module-blueprints.md) - 治理标准文档(governance-standards.md) - 质量标准文档(quality-optimization.md) - 任务总览文档(Crawlful_Hub_Task_Overview_Full_v1.md) - README.md等文件 同时更新了docs目录下的现有文档： - 更新SERVICE_MAP.md强化服务层职责和调用规范 - 更新Service_Design.md明确服务层设计规范和边界 - 更新项目规则文档加入逻辑集中化原则 - 统一调整了文档表格格式和结构
157 lines
3.5 KiB
Markdown
157 lines
3.5 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
|
||
→ 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 / System
|
||
→ ExceptionController.handle
|
||
→ ExceptionService.process
|
||
→ NotificationService.alert
|
||
→ SettlementService.adjust
|
||
→ Response
|