Files

wurenzhi cd55097dbf docs: 重构并删除docs11目录，更新项目文档结构

删除旧的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明确服务层设计规范和边界
- 更新项目规则文档加入逻辑集中化原则
- 统一调整了文档表格格式和结构

2026-03-18 21:51:52 +08:00

3.5 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 → 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

3.5 KiB Raw Blame History Unescape Escape