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:
@@ -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个任务** | **碎片化等待** |
|
||||
| **协作防撞** | **必须声明占用,先声明优先** | **重复开发** |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user