ShaoHua
4fe0b5a963
本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范 移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
144 lines
5.8 KiB
Markdown
144 lines
5.8 KiB
Markdown
# 研发工单全流程规范（必须遵守）
|
||
|
||
> 适用范围：本规则属于 **全局规则**（跨项目通用），覆盖研发工单从术语定义、拆分输出到新增约束的全流程。
|
||
|
||
> ⚠️ 术语澄清（必读）
|
||
>
|
||
> 本项目存在两类"任务"概念，必须严格区分：
|
||
>
|
||
> | 术语 | 含义 | 适用范围 |
|
||
> |---|---|---|
|
||
> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的**编码工作项** | 本规则的全部内容 |
|
||
> | **Todo 待办项（Todo Item）** | Hua.Todo 项目**业务领域**中用户创建的待办事项 | 业务代码、产品文档 |
|
||
>
|
||
> 在代码、文档与对话中，凡涉及编码侧拆分时，**必须使用"研发工单"或"工单"**，禁止使用"任务"二字。
|
||
> 业务侧 `Task` / `SubTask` 等代码标识符**保持不变**（已固化于 API、DB、UI）。
|
||
|
||
---
|
||
|
||
## 一、研发工单拆分规范
|
||
|
||
### 1.1 适用时机
|
||
|
||
- 当需求需要先通读项目/产品/技术文档再开始实现时，必须先输出**研发工单拆分文档**
|
||
|
||
### 1.2 输出要求
|
||
|
||
1. **先读完所有相关文档**：包括 `docs/`、`docs/project/` 下与本次需求相关的内容
|
||
2. **先写工单拆分，再动手实现**：研发工单拆分产出是后续执行的入口与对齐依据
|
||
3. **新增专属文件夹**：在 `docs/project` 下新建 `研发工单-<主题>-<日期或版本>` 文件夹
|
||
4. **可并行工单拆分**：能同步执行的工单必须拆到不同 Markdown 文件中
|
||
5. **文件带序号**：按执行顺序编号（`01-xxx.md`、`02-xxx.md`）
|
||
|
||
### 1.3 每个研发工单文件必须包含
|
||
|
||
- 目标 / 范围（做什么、不做什么）
|
||
- 前置条件（依赖哪些结论 / 接口 / 文档）
|
||
- 验收标准（可执行的验证点）
|
||
- 风险与回滚（如有）
|
||
|
||
### 1.4 子工单完成标记要求
|
||
|
||
- 子工单完成后，必须在 `00-工单总览.md` 中标注"已完成"
|
||
- 维护"待验证表"，记录每个子工单的"待验证 / 已验证"状态
|
||
|
||
### 1.5 并行冲突规避要求
|
||
|
||
当工单会被分发到多个 solo 窗口并行推进时，每个研发工单文件必须额外包含 Touch List、共享文件策略与编译绿线策略。详细规约见 [05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md)。
|
||
|
||
### 1.6 推荐结构
|
||
|
||
```
|
||
docs/project/研发工单-<主题>-<版本>/
|
||
├── 00-工单总览.md # 背景、目标、关键决策、并行分组、待验证表
|
||
├── 01-并行工单A.md
|
||
├── 02-并行工单B.md
|
||
└── 03-串行工单C.md
|
||
```
|
||
|
||
---
|
||
|
||
## 二、新增工单约束
|
||
|
||
> 核心原则：**新增工单时，不得修改、覆盖、重排、删除任何已有工单文件。**
|
||
|
||
### 2.1 已有文件不可触碰
|
||
|
||
| 操作 | 是否允许 | 说明 |
|
||
|---|---|---|
|
||
| 修改已有工单的 `.md` 内容 | ❌ 禁止 | 即使发现格式、措辞可优化 |
|
||
| 重命名已有工单文件 | ❌ 禁止 | |
|
||
| 删除已有工单文件 | ❌ 禁止 | |
|
||
| 重排已有工单的序号 | ❌ 禁止 | 除非用户明确要求整体重构 |
|
||
| 修改 `00-工单总览.md` 中已有条目 | ❌ 禁止 | 只能追加新条目 |
|
||
| 在 `00-工单总览.md` 中追加新条目 | ✅ 允许 | |
|
||
| 修改 `.trae/rules/项目/04-即时状态记忆.md` 中已有快照行 | ❌ 禁止 | 只能追加新版本行 |
|
||
| 新增章节到 `04-即时状态记忆.md` | ✅ 允许 | |
|
||
|
||
### 2.2 子工单拆分格式
|
||
|
||
```
|
||
NN-NN-标题.md
|
||
```
|
||
|
||
- 前两位：主工单序号，后两位：子工单序号
|
||
- 示例：`03-01-会议数据模型与API.md`
|
||
|
||
### 2.3 新增工单的序号确定
|
||
|
||
1. 列出目标文件夹中已有文件
|
||
2. 找出最大主序号
|
||
3. 新增工单的主序号 = 最大主序号 + 1
|
||
4. 子工单的子序号从 `01` 开始递增
|
||
|
||
### 2.4 可追加修改的文件（例外）
|
||
|
||
| 文件 | 允许 | 不允许 |
|
||
|---|---|---|
|
||
| `00-工单总览.md` | 追加新条目 | 改写已有条目 |
|
||
| `.trae/rules/项目/04-即时状态记忆.md` | 新增版本章节 | 修改已有快照行 |
|
||
| `.trae/索引.md` | 追加新规则链接 | 修改已有条目 |
|
||
|
||
---
|
||
|
||
## 三、与业务侧 Todo 待办项的边界
|
||
|
||
- 代码、注释、提交信息中描述**编码工作**时：使用"研发工单 / 工单 / 子工单"
|
||
- 代码、注释、提交信息中描述**业务功能**时：使用"Todo 待办项 / Todo Item / 父子任务（业务实体）"
|
||
- 文档命名前缀：
|
||
- 编码侧：`研发工单-<主题>-<版本>/`
|
||
- 业务侧：遵循 `docs/` 既有命名习惯
|
||
- 提交信息示例：
|
||
- ✅ `feat(todo): 新增 Todo 待办项截止日期字段（研发工单 02-后端模型）`
|
||
- ❌ `feat: 完成任务 02`（"任务"歧义）
|
||
|
||
---
|
||
|
||
## 四、检查清单
|
||
|
||
### 研发工单拆分检查
|
||
|
||
1. [ ] 是否已阅读完所有相关文档？
|
||
2. [ ] 是否在 `docs/project` 下新建了专属文件夹（命名以"研发工单-"开头）？
|
||
3. [ ] 是否产出 `00-工单总览.md`？
|
||
4. [ ] 是否将可并行工单拆分为不同 md 文件？
|
||
5. [ ] 是否所有 md 文件都带有连续序号？
|
||
6. [ ] 子工单完成后是否在总览中标注"已完成"并更新待验证表？
|
||
|
||
### 新增工单检查
|
||
|
||
1. [ ] 新增工单的序号是否为当前最大主序号 + 1？
|
||
2. [ ] 子工单是否使用了 `NN-NN-标题.md` 格式？
|
||
3. [ ] 是否**未修改**任何已有工单文件的内容？
|
||
4. [ ] 是否**未修改** `00-工单总览.md` 和 `04-即时状态记忆.md` 中已有条目？
|
||
|
||
### 并行冲突检查
|
||
|
||
> 详见 [05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md#最小检查清单)。
|
||
|
||
---
|
||
|
||
**关联规则**：[05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md)、[07-代码实现与测试先行规范.md](./07-代码实现与测试先行规范.md)
|
||
|
||
> 工单进入代码实现阶段时，必须遵循"测试先行（ATDD）"工作流：先依据本规范的验收标准编写验收测试用例，再实现代码，测试全部通过后才算工单完成。详见 [07-代码实现与测试先行规范.md](./07-代码实现与测试先行规范.md)。
|