ShaoHua
4fe0b5a963
本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范 移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
3.2 KiB
3.2 KiB
代码实现与测试先行规范（必须遵守）
全局规则。规定何时必须写测试 + 怎么写（ATDD：验收测试驱动开发）。与 04-研发工单全流程规范.md 配套：04 管工单拆分，本规范管实现与验收。
一、触发条件（什么时候必须写测试）
用户表述满足以下任一条件时，必须执行测试先行：
| 触发条件 | 示例 |
|---|---|
| 明确指出 bug（"修正"/"修复"/"不应该"/"404"） | "登录按钮点不了""/sync 404""数据丢了" |
| 要求新增功能 | "加一个导出按钮""新增 XX 端点" |
| 要求修改现有行为 | "把优先级改成默认高""去掉确认弹窗" |
豁免（无需测试先行，但改动后必须跑已有测试）：
| 场景 | 示例 |
|---|---|
| 纯配置 | appsettings.json 默认值、连接字符串 |
| 纯格式化/注释 | ESLint 自动修复、XML doc 补充 |
| 依赖升级无 API 变更 | NuGet/npm 补丁版本 |
| 文档/规则更新 | 新增 .trae/rules/ 文件 |
判定原则：改动出错用户能感知 → 不可豁免。
二、强制流程
- 提炼验收点：从用户描述提取 Given-When-Then 验收场景（主:分支:异常 ≈ 1:2:2）
- RED：写验收测试，实跑确认失败（失败原因 = 被测功能缺失，非 setup 错误）
- GREEN：写最小量代码使测试通过
- REFACTOR：重构优化，重跑测试仍 GREEN
不得跳过任何步骤。
三、验收测试用例规范
格式（Given-When-Then）：
Given [前置条件]
When [操作]
Then [预期结果]
示例：Given 本地 3 个未完成待办 / When POST /api/task 创建"写周报" / Then 返回 201 且共 4 条
要求：
- 命名体现场景：
CreateTask_EmptyTitle_Returns400 - 一个测试只验证一个行为点
- 断言可量化
- 至少覆盖集成测试层（不满足于纯单元测试）
四、工单完成判定（全部满足才标记"已完成"）
- 所有验收测试通过
- 原有测试无回归
- 04-即时状态记忆.md 或
00-工单总览.md待验证表标注"已验证" - 按 03-文档同步规范.md 同步文档
五、Git Checkpoint 提交（推荐）
| 阶段 | 提交信息 |
|---|---|
| RED | test(workitem): 为 <工单> 添加失败的验收测试 |
| GREEN | feat(workitem): 实现 <工单> 使验收测试通过 |
| REFACTOR | refactor(workitem): 重构 <模块> 保持测试通过 |
流程完成前不得 squash。提交信息禁用歧义"任务"二字。
六、检查清单
- 触发条件满足？豁免类是否确认无行为变更？
- 提炼了 Given-When-Then 验收场景？
- RED 实跑确认失败，失败原因 = 功能缺失？
- GREEN 最小代码通过测试？
- REFACTOR 后测试仍 GREEN？
- 场景覆盖主/分支/异常？
- 原有测试无回归？
- 工单完成四条件全部满足？