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:
@@ -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 才能高效维护和迭代。
|
||||
|
||||
## 📞 联系方式
|
||||
|
||||
|
||||
Reference in New Issue
Block a user