# 研发工单全流程规范（必须遵守）

> 适用范围：本规则属于 **全局规则**（跨项目通用），覆盖研发工单从术语定义、拆分输出到新增约束的全流程。

> ⚠️ 术语澄清（必读）
>
> 本项目存在两类"任务"概念，必须严格区分：
>
> | 术语 | 含义 | 适用范围 |
> |---|---|---|
> | **研发工单（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)。