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

@@ -225,9 +225,67 @@ Step 5: 完成后释放占用
---
## 8. 追踪与日志
## 8. 逻辑集中化原则(硬性约束)
### 8.1 五元组必填
### 8.1 核心原则
> **逻辑集中化 → 服务驱动**:所有业务逻辑必须集中在 Service 层,禁止分散在 Controller、前端或数据库操作中。
### 8.2 逻辑分散的表现(禁止行为)
-**Controller 中写业务逻辑**Controller 只负责请求/响应和权限校验
-**前端直接写业务规则**:复杂计算、权限判断、状态流转禁止在 React 组件中实现
-**数据库操作分散**:不同模块禁止直接调用数据库,必须通过 Service 层
-**脚本或工具处理逻辑**AI 任务或异步脚本必须通过 Service 层统一调用
### 8.3 逻辑分散的后果
1. **维护成本高**AI 或开发者需要理解多个模块才能做一件改动
2. **修改容易出错**:改动一处可能引起其他模块逻辑不一致
3. **难以快速迭代**:新功能闭环难以接入,因为逻辑散落在各处
4. **收费闭环风险**:分散逻辑导致支付、权限、账单、状态不一致,直接影响收益
5. **AI 维护困难**AI 无法一次性理解完整闭环,状态不一致,修改风险高
### 8.4 服务层职责(强制执行)
#### Controller 层职责
- 接收 HTTP 请求和参数验证
- 调用 Service 层处理业务逻辑
- 返回响应给前端
- 权限校验(通过 `authorize()` 中间件)
#### Service 层职责(核心)
- 业务逻辑编排和状态流转
- 多模块协同和数据一致性保证
- 事务管理和异常处理
- 调用 Repository 层或外部 API
#### Repository 层职责
- 数据库 CRUD 操作
- 数据模型映射
- 查询优化
### 8.5 状态管理统一
- **前端状态**:使用全局 Model 或状态管理库Umi Model、Redux 等)
- **后端状态**:统一使用 STATE_MACHINE 定义的状态机
- **状态流转**:所有状态更新必须通过 Service 层,禁止在 Controller 或前端直接修改
### 8.6 核心逻辑复用
- **公共函数**:权限、价格、库存、账单等逻辑必须封装为公共函数或工具库
- **服务接口**AI 只需调用 Service 接口,不直接处理业务逻辑
- **避免重复**:不同模块禁止重复实现相同逻辑
### 8.7 可视化业务流程
- **流程图**:为每个业务闭环绘制流程图,便于 AI 理解
- **状态机图**:使用 STATE_MACHINE 记录完整闭环
- **服务地图**:完善 SERVICE_MAP明确服务调用链
### 8.8 违反逻辑集中化原则的后果
- **代码审查不通过**:任何违反逻辑集中化原则的代码将被拒绝合并
- **AI 任务失败**AI 无法维护分散的逻辑,导致任务执行失败
- **生产环境风险**:分散逻辑导致数据不一致,直接影响系统稳定性
---
## 9. 追踪与日志
### 9.1 五元组必填
所有任务与日志必须携带:
```typescript
{
@@ -239,23 +297,23 @@ Step 5: 完成后释放占用
}
```
### 8.2 状态机门禁
### 9.2 状态机门禁
- 发布、审核、对账流程必须落入统一 FSM
- **禁止**: Controller 中硬编码流程分支
---
## 9. 代码质量门禁
## 10. 代码质量门禁
### 9.1 命名规范
### 10.1 命名规范
- **服务类**: 统一使用 `Service` 后缀
- **禁止**: `Manager`/`Helper` 等后缀
### 9.2 注释规范
### 10.2 注释规范
- **必须**: 每个服务类包含完整 JSDoc
- **必须**: 明确标识任务ID和功能描述
### 9.3 部署标准
### 10.3 部署标准
`completed` 的标志:
1. ✅ 数据库表已初始化
2. ✅ 核心逻辑已闭环
@@ -273,6 +331,7 @@ Step 5: 完成后释放占用
| 安全权限 | 使用 `authorize()` 中间件 | 权限漏洞 |
| 性能边界 | Worker并发≤10, 内存≤4GB | 系统崩溃 |
| 追踪日志 | 五元组必填 | 无法追溯 |
| **逻辑集中化** | **所有业务逻辑必须在Service层** | **AI维护困难数据不一致** |
| **任务领取** | **优先领任务包最小2个任务** | **碎片化等待** |
| **协作防撞** | **必须声明占用,先声明优先** | **重复开发** |