04-开发新功能

需求澄清
  -> 现有模式探索
  -> 接口、数据与错误设计
  -> 分步计划
  -> 先补契约和测试
  -> 实现最小闭环
  -> 跨文件验证
  -> 兼容性与差异审查
  -> 交付说明

pwd
git status --short --branch
git branch --show-current
codex --version

请先只读探索，不要修改、创建或删除任何文件，也不要提交或联网。
读取项目说明、构建脚本、相关路由、数据模型和现有测试。
最后给出：入口文件、调用链、相似功能、测试命令和需要我确认的问题。

在修改前，请从现有代码中确认：
1. 任务的主键字段叫什么，创建者字段叫什么。
2. 任务状态目前是否已经存在，允许哪些值。
3. 当前认证信息如何进入控制器或服务层。
4. 项目使用什么迁移工具、测试框架和响应错误格式。
5. 列表接口是否会暴露新增字段，客户端是否依赖严格响应结构。

对无法从代码确定的事项列出问题，不要猜测。

- [ ] 已登录任务所有者调用完成接口得到 200。
- [ ] 响应中的 completed 为 true，持久化后再次查询仍为 true。
- [ ] 未登录请求得到项目既有的认证错误格式。
- [ ] 不存在的任务得到 404，且不写入数据。
- [ ] 其他用户的任务得到 403，且不改变任务。
- [ ] 重复调用保持成功且不重复生成副作用。
- [ ] 旧的创建、列表和详情测试仍然通过。
- [ ] 格式检查、类型检查、单元测试和项目构建通过。

请探索新增任务完成接口所需的现有模式，只读不要改文件。
重点对照一个已有的任务更新接口和一个需要权限检查的接口。
请按表格输出：
- 文件路径和职责
- 请求如何进入控制器、服务和数据层
- 认证与资源所有权在哪里判断
- 成功和失败响应如何统一生成
- 现有测试如何构造用户、任务和数据库
- 建议复用的函数或模式
- 你无法确定、需要我确认的事项
每个结论都附上文件路径和符号名。

入口：src/routes/tasks.ts::patchTask
业务：src/services/task-service.ts::updateTask
权限：src/policies/task-policy.ts::canEdit
数据：src/models/task.ts，迁移目录 migrations/
错误：src/http/errors.ts::toResponse
测试：tests/tasks/update-task.test.ts，使用 createUser/createTask 夹具

建议：复用 updateTask 的事务和权限入口，为 completed 增加明确的输入校验；
不要在新路由中直接访问 ORM。需要确认：列表响应新增字段是否允许旧客户端忽略。

PATCH /api/tasks/42/complete
Authorization: Bearer <token>
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "title": "整理发布清单",
  "completed": true,
  "createdAt": "2026-09-05T09:00:00Z"
}

{
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "任务不存在"
  }
}

请先检查任务表、模型映射和迁移约定，提出新增 completed 字段的方案。
说明旧记录如何获得默认值、应用发布与迁移的先后关系、回滚会损失什么，
以及是否需要分阶段发布。此步骤只给方案，不修改文件。

请为任务完成接口列出错误矩阵：触发条件、HTTP 状态、稳定错误码、
用户可见消息、日志字段、是否允许重试、是否发生写入。
对照项目现有错误处理中间件，不要新造响应格式。

try:
    task.completed = true
except Exception:
    return {"ok": false}

如果测试或构建失败，请停止扩大范围，贴出完整命令和错误摘要，
说明失败属于代码、环境、依赖还是测试假设。先提出最小修复方案，
不要删除失败测试、降低断言、跳过检查或修改无关配置。

请根据刚才的探索结果制定实现计划，先不要修改文件。
计划必须逐步列出：目标、涉及文件、关键符号、验证命令、预期结果和回滚点。
要求尽量复用现有模式，保持旧接口兼容，不引入第三方依赖。
如果存在未决需求，先列出问题，不要用假设替代答案。

步骤 1：确认任务状态模型、权限策略和错误格式；输出文件证据。
步骤 2：添加 completed 字段迁移和模型默认值；运行迁移检查与模型测试。
步骤 3：在服务层增加幂等的完成操作；补成功、重复、资源不存在和权限测试。
步骤 4：接入 PATCH 路由和响应序列化；补请求级测试。
步骤 5：更新列表或详情响应的契约测试；确认旧创建请求仍通过。
步骤 6：运行格式、类型、单元、集成和构建检查。
步骤 7：审查 diff、生成交付摘要；未经明确批准不提交、不推送、不部署。

测试：任务所有者调用 PATCH /api/tasks/42/complete
预期：200，响应 completed=true，重新查询仍为 true

测试：其他用户调用相同接口
预期：403，任务值保持 false

测试：重复调用
预期：第二次仍为 200，不产生重复事件或重复通知

现在只实现服务层完成操作，暂不接路由。
复用现有任务更新、权限和事务模式。
完成后只运行服务层相关测试，并报告新增和未通过的用例。

PATCH /api/tasks/42/complete 200
{
  "id": 42,
  "completed": true
}

PATCH /api/tasks/999/complete 404
{
  "error": {"code": "TASK_NOT_FOUND", "message": "任务不存在"}
}

本阶段改动文件：
- path/to/file: 原因

未改动但检查过的文件：
- path/to/related-file: 为什么不需要改

下一步：...
验证：命令、退出码、测试数量

请对照任务创建、列表、详情和更新的现有测试，列出本功能可能破坏的兼容性。
每项给出证据、风险等级、测试或迁移措施。没有证据的结论标为“待确认”。

请按项目已有脚本从快到慢运行验证。
每条命令报告：命令、退出码、测试数量、失败摘要和是否修改了文件。
任何失败都先停下来分类，不要跳过、删除或弱化检查。

格式检查：通过，退出码 0
服务测试：通过，12 passed
API 测试：通过，8 passed
回归测试：通过，旧接口 31 passed
类型检查：通过，退出码 0
构建：通过，退出码 0

git status --short
git diff --stat
git diff --check
git diff

请只审查当前 diff，不修改文件。
按严重程度列出功能遗漏、权限问题、数据迁移风险、兼容性风险、
错误处理缺口和测试缺口。每条引用文件和符号，并说明如何验证。
如果没有发现问题，也要列出未覆盖的假设。

功能：新增任务完成接口
变更文件：列出实际路径及每个文件的原因
接口：方法、路径、认证要求、成功和失败状态
数据：迁移名称、默认值、执行顺序、回滚限制
验证：命令、退出码、测试数量
兼容性：旧接口和旧数据的结论
未验证：例如真实外部服务未连接、生产迁移未执行
风险：并发、缓存、客户端版本或权限方面的剩余风险
回滚：代码回滚、迁移回滚和数据恢复步骤

请先展示最终 diff、测试结果和交付摘要。
不要执行 git add、git commit、git push 或部署。
等我确认后再进行下一步。

我要给现有任务管理系统增加“标记任务完成”功能。

背景：目前用户可以创建、查看和更新自己的任务，但没有明确的完成操作。

目标：已登录用户可以调用 PATCH /api/tasks/{id}/complete，将自己拥有的任务
标记为完成。成功返回现有任务响应格式，并包含 completed=true。

范围：检查并按现有模式修改任务模型/迁移、服务层、路由、响应类型、相关前端
和测试。先找出真实文件路径再修改。保留项目开始前已有的工作区改动。

业务规则：
- 新任务默认 completed=false。
- 任务所有者成功得到 200。
- 重复调用保持幂等，不重复生成副作用。
- 任务不存在得到项目既有的 404 错误格式。
- 其他用户操作得到项目既有的 403 错误格式。
- 未登录沿用现有认证错误。

兼容性：已有创建、列表、详情和更新请求继续通过；不要改变旧字段含义，
不要引入第三方依赖。确认旧客户端能否接受新增 completed 字段。

工作方式：
1. 先只读探索 README、项目规则、相似更新接口、权限策略、迁移、类型和测试。
2. 输出文件地图、调用链、复用点和未决问题，暂不编辑。
3. 得到确认后给出分步计划，每步列文件、验证命令和回滚点。
4. 先补服务和 API 契约测试，再实现最小闭环。
5. 分阶段运行格式、类型、单元、集成、回归和构建检查。
6. 任何失败都贴命令和错误摘要，停止扩大范围；不要删除测试、跳过检查、
   修改无关配置或降低断言。
7. 最后展示 git status、git diff --stat、git diff --check、完整测试结果和交付摘要。
8. 不要提交、推送、部署或执行生产迁移。

我要实现：[用户可观察的功能]
背景：[当前行为和问题]
目标：[成功后具体发生什么]
范围：[允许修改的模块/文件]
非目标：[本次明确不做的事]
约束：[接口、依赖、性能、安全、兼容性要求]
验收：[可测的成功和失败标准]

先列出你无法从仓库确定的问题，不要猜测，不要修改文件。

只读检查与目标功能最相似的入口、服务、模型、错误处理和测试。
输出真实文件路径、符号、调用链、可复用模式和风险。
不要创建或修改文件；结论附证据。

给出分步实现计划。每步包含：目标、文件和符号、验证命令、预期输出、
失败处理和回滚点。保持旧行为兼容，优先复用现有模式。

只实现计划中的第 N 步。
先读取该步涉及的现有代码，保持命名、错误格式和测试风格一致。
完成后运行该步验证，报告改动文件、命令、退出码和未决问题。
不要扩大范围，不要提交。

只审查当前 diff，不修改文件。
检查需求覆盖、权限、接口契约、数据迁移、错误处理、并发/幂等、兼容性、
测试质量和敏感信息。按严重程度列出问题并引用文件和符号。
同时列出已验证项、未验证假设和建议的交付/回滚步骤。