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明确服务层设计规范和边界
- 更新项目规则文档加入逻辑集中化原则
- 统一调整了文档表格格式和结构
This commit is contained in:
2026-03-18 21:51:52 +08:00
parent 96373deb2f
commit cd55097dbf
19 changed files with 450 additions and 2050 deletions

View File

@@ -0,0 +1,100 @@
我把“逻辑分散 → AI难维护”这个问题拆开详细分析下原因、表现和影响以及可行的解决思路。
---
## 1⃣ 问题本质
**逻辑分散**指的是业务逻辑没有集中在服务层,而散布在不同模块中,例如:
* **Controller 中写逻辑**Controller 除了接收请求和返回响应,还处理业务决策、状态变化、数据校验。
* **前端直接写逻辑**:复杂计算、权限判断、状态流转直接在 React 组件或页面中实现。
* **数据库操作分散**:不同模块直接调用数据库,导致状态更新不统一。
* **脚本或工具处理逻辑**AI 任务或异步脚本单独处理业务逻辑,没有统一调用入口。
---
## 2⃣ AI 维护难的原因
AI 的核心优势是**理解和处理规则化逻辑**,逻辑分散导致 AI 难维护主要有以下几个原因:
1. **难以追踪业务流程**
* 业务步骤可能跨多个文件或模块AI 无法一次性获取完整流程。
* 例如订单闭环支付、库存锁定、订单创建、账单生成分别在不同文件处理AI 需要先分析依赖关系,再理解流程。
2. **状态流转不统一**
* 状态可能在多个地方更新,缺乏中心化状态管理。
* AI 很难判断状态真实值和变化条件,导致任务调度或逻辑判断出错。
3. **重复逻辑**
* 不同模块可能重复实现相同逻辑(如权限判断、价格计算)。
* AI 难以判断哪个逻辑是“权威版本”,容易修改错地方。
4. **难以保证一致性**
* 分散逻辑容易导致边缘情况处理不统一(例如异常、支付失败、库存不足)。
* AI 在优化或修复逻辑时,可能漏掉某些分散的处理点。
5. **代码依赖复杂**
* 分散逻辑意味着调用链不清晰AI 在修改或推理时必须解析跨文件依赖。
* 对于大型多商户系统,这种复杂度呈指数级增长。
---
## 3⃣ 典型表现
* Controller 内部有大量 `if/else` + 异步调用
* 前端页面直接处理业务规则(如价格、折扣、库存判断)
* 数据库更新在多个 Service/Repository 之外被调用
* AI 执行任务时,需要在不同模块中查找状态和规则
---
## 4⃣ 后果
1. **维护成本高**
* AI 或开发者需要理解多个模块才能做一件改动。
2. **修改容易出错**
* 改动一处可能引起其他模块逻辑不一致。
3. **难以快速迭代**
* 新功能闭环难以接入,因为逻辑散落在各处。
4. **收费闭环风险**
* 分散逻辑导致支付、权限、账单、状态不一致,直接影响收益。
---
## 5⃣ 解决策略
**核心原则:逻辑集中化 → 服务驱动**
1. **服务层集中业务逻辑**
* Controller 只负责请求/响应和权限校验。
* Service 层负责业务闭环、状态流转和多模块协同。
2. **状态管理统一**
* 前端使用全局 Model 或状态管理库Umi Model、Redux 等)。
* 后端统一使用状态机或闭环处理状态。
3. **复用核心逻辑**
* 公共函数或工具库统一处理权限、价格、库存、账单等逻辑。
* AI 只需调用 Service 接口,不直接处理业务逻辑。
4. **可视化业务流程**
* 使用流程图或状态机图记录完整闭环,让 AI 可快速理解流程。
* 前端交互和后端服务逻辑保持一致。
---
💡 **总结一句话**
逻辑分散让 AI 无法一次性理解完整闭环,状态不一致,修改风险高;集中化逻辑到服务层 + 统一状态管理AI 才能高效维护和迭代。