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

@@ -19,18 +19,18 @@
### 关键里程碑
| 里程碑 | 状态 | 预计完成时间 | 实际完成时间 |
| ------ | ---- | ------------ | ------------ |
| 多商户业务闭环文档完善 | ✅ 已完成 | 2024-12-15 | 2024-12-15 |
| 服务编排地图SERVICE_MAP | ✅ 已完成 | 2024-12-16 | 2026-03-18 |
| 领域模型DOMAIN_MODEL | ✅ 已完成 | 2024-12-17 | 2026-03-18 |
| 状态机定义STATE_MACHINE | ✅ 已完成 | 2024-12-18 | 2026-03-18 |
| 功能开通服务实现 | ✅ 已完成 | 2024-12-19 | 2026-03-18 |
| 服务层代码实现与修复 | ✅ 已完成 | 2024-12-20 | 2026-03-18 |
| 前端服务启动 | ✅ 已完成 | 2024-12-21 | 2026-03-18 |
| 后端服务启动 | ✅ 已完成 | 2024-12-22 | 2026-03-18 |
| 前端优化 | ✅ 已完成 | 2024-12-23 | 2026-03-18 |
| 前端页面骨架创建 | ✅ 已完成 | 2024-12-24 | 2026-03-18 |
| 前端文档补充 | ✅ 已完成 | 2024-12-25 | 2026-03-18 |
| 系统集成测试 | ⏳ 待开始 | 2024-12-26 | - |
| 多商户业务闭环文档完善 | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 服务编排地图SERVICE_MAP | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 领域模型DOMAIN_MODEL | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 状态机定义STATE_MACHINE | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 功能开通服务实现 | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 服务层代码实现与修复 | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 前端服务启动 | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 后端服务启动 | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 前端优化 | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 前端页面骨架创建 | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 前端文档补充 | ✅ 已完成 | 2026-03-18 | 2026-03-18 |
| 系统集成测试 | 🔄 进行中 | 2026-03-19 | - |
## 📋 任务状态跟踪
@@ -86,14 +86,17 @@
49. ✅ 补充Business_ClosedLoops.md附录C前端组件规范组件分类、状态管理、API交互、路由权限
50. ✅ 补充Task_Overview.md附录A前端交互任务补充商品、订单、执行、数据、合规、设置交互任务
51. ✅ 补充Task_Overview.md附录B前端开发规范技术栈、项目结构、组件、状态、API、路由权限
52. ✅ 更新项目规则文档project-specific-rules.md加入逻辑集中化原则
53. ✅ 更新SERVICE_MAP.md强化服务层职责和调用规范
54. ✅ 更新Service_Design.md明确服务层设计规范和边界
### 进行中任务
1. 🔄 系统集成测试
2. 🔄 前端交互任务开发
### 待开始任务
1. ⏳ 性能测试和优化
2. ⏳ 安全测试
3. ⏳ 领取并完成前端交互任务附录A中的FE-INT系列任务
## 🏗️ 架构演进
@@ -123,6 +126,22 @@
/repository (数据层)
```
### 逻辑集中化原则
> **所有业务逻辑必须集中在 Service 层,禁止分散在 Controller、前端或数据库操作中。**
#### 逻辑分散的表现(禁止行为)
-**Controller 中写业务逻辑**Controller 只负责请求/响应和权限校验
-**前端直接写业务规则**:复杂计算、权限判断、状态流转禁止在 React 组件中实现
-**数据库操作分散**:不同模块禁止直接调用数据库,必须通过 Service 层
-**脚本或工具处理逻辑**AI 任务或异步脚本必须通过 Service 层统一调用
#### 逻辑分散的后果
1. **维护成本高**AI 或开发者需要理解多个模块才能做一件改动
2. **修改容易出错**:改动一处可能引起其他模块逻辑不一致
3. **难以快速迭代**:新功能闭环难以接入,因为逻辑散落在各处
4. **收费闭环风险**:分散逻辑导致支付、权限、账单、状态不一致,直接影响收益
5. **AI 维护困难**AI 无法一次性理解完整闭环,状态不一致,修改风险高
#### 服务层职责
一个服务 = 一个闭环
@@ -274,12 +293,20 @@
- **2026-03-18**补充Business_ClosedLoops.md附录A、B、C完善前端交互设计规范、页面映射和组件规范
- **2026-03-18**补充Task_Overview.md附录A、B完善前端交互任务和前端开发规范
- **2026-03-18**确认50个业务闭环保持不变仅在文档末尾添加附录不改变原有结构
- **2026-03-18**完成docs目录下所有文档的重新排版统一表格格式和文档结构
- **2026-03-18**:更新开发进度互通文档,调整任务状态和下一步计划
- **2026-03-18**分析逻辑分散问题确认其对AI维护的影响和解决方案
- **2026-03-18**更新项目规则文档project-specific-rules.md加入逻辑集中化原则
- **2026-03-18**更新SERVICE_MAP.md强化服务层职责和调用规范
- **2026-03-18**更新Service_Design.md明确服务层设计规范和边界
### 关键洞察
1. **服务闭环与收费的关系**:服务闭环跟收费没有必然关系,收费只是把问题放大了。只要存在"状态流转 + 多模块协同",就必须有服务闭环。
2. **不收费场景也需要服务闭环**:订单闭环、库存闭环、多商户分单等都需要服务层保证数据一致性。
3. **收费场景更容易暴露问题**:因为多了一条链(功能 → 支付 → 权限 → 使用 → 计费 → 结算),任何一个点错了都会直接损失钱。
4. **前端优化的重要性**:前端是用户直接接触的界面,其流畅性和功能完整性直接影响用户体验和系统的商业价值。
5. **逻辑集中化的必要性**逻辑分散导致AI难以维护状态不一致修改风险高。集中化逻辑到服务层 + 统一状态管理AI才能高效维护和迭代。
6. **服务层职责边界**Controller只负责请求/响应和权限校验Service层负责业务逻辑编排和状态流转Repository层负责数据库操作。明确职责边界是逻辑集中化的基础。
### AI开发建议
1. 优先进行系统集成测试,确保各服务之间的正确交互
@@ -289,19 +316,24 @@
5. 严格执行"业务闭环优先"原则,避免碎片化开发
6. 按照前端优化策略,逐步实现组件化、状态管理和性能优化
7. 确保前端与后端的良好集成,实现数据的实时同步和交互的流畅性
8. **严格执行逻辑集中化原则**:所有业务逻辑必须集中在 Service 层,禁止分散在 Controller、前端或数据库操作中
9. **明确服务层职责边界**Controller 只负责请求/响应和权限校验Service 层负责业务逻辑编排和状态流转Repository 层负责数据库操作
10. **统一状态管理**:前端使用全局 Model 或状态管理库,后端统一使用 STATE_MACHINE 定义的状态机,所有状态更新必须通过 Service 层
## 📝 下一步计划
### 短期计划(1-3天
### 短期计划(2026-03-19 至 2026-03-21
1. 完成系统集成测试,验证服务层功能
2. 优化数据库查询和缓存策略
3. 实现完整的错误处理和日志记录
4. 进行性能测试和优化
5. 实现安全测试,确保系统安全性
6. 领取并完成前端交互任务Task_Overview.md附录A中的FE-INT系列任务
7. 实现前端交互功能,包括筛选、排序、新增、编辑、定价、上架、同步等
6. 完成前端交互任务开发,包括筛选、排序、新增、编辑、定价、上架、同步等
7. **代码审查**检查所有Controller、Service、Repository代码确保符合逻辑集中化原则
8. **重构优化**将分散的业务逻辑迁移到Service层确保职责边界清晰
9. **测试验证**:验证逻辑集中化后的代码,确保功能正确性和数据一致性
### 中期计划(4-7天
### 中期计划(2026-03-22 至 2026-03-28
1. 完善前端与后端的集成,实现数据实时同步
2. 补充二级闭环(功能收费闭环、权限控制闭环、商户账单闭环)
3. 部署系统到测试环境
@@ -309,7 +341,7 @@
5. 完善前端组件库,实现组件复用
6. 实现前端状态管理,优化数据流
### 长期计划(8-14天
### 长期计划(2026-03-29 至 2026-04-11
1. 部署系统到生产环境
2. 监控系统运行状态
3. 持续优化和迭代系统功能
@@ -334,9 +366,10 @@
5. 避免逻辑分散,确保业务逻辑集中在服务层
### 架构风险
1. **逻辑分散风险**:如果在 Controller 中写业务逻辑会导致逻辑分散AI 无法维护
2. **收费必炸风险**:没有完整的服务闭环,后期收费功能必定出现问题
3. **数据一致性风险**:多商户场景下,没有服务层会导致商户归属混乱、结算错误
1. **逻辑分散风险**:如果在 Controller 中写业务逻辑会导致逻辑分散AI 无法维护。逻辑分散导致AI难以追踪业务流程、状态流转不统一、重复逻辑、难以保证一致性、代码依赖复杂。
2. **收费必炸风险**:没有完整的服务闭环,后期收费功能必定出现问题。分散逻辑导致支付、权限、账单、状态不一致,直接影响收益。
3. **数据一致性风险**:多商户场景下,没有服务层会导致商户归属混乱、结算错误
4. **AI维护困难风险**:逻辑分散让 AI 无法一次性理解完整闭环,状态不一致,修改风险高。集中化逻辑到服务层 + 统一状态管理AI 才能高效维护和迭代。
## 📞 联系方式