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