acceptance-api

验收 — API

像真实客户端那样测试正在运行的服务。单元测试会根据代码自身的假设通过；这一步验证的是实际的线缆行为——状态码、JSON 结构，以及重新加载后仍然存在的副作用。

由 acceptance-check 使用验收台账中的一部分条目调用；也可以针对 API 变更直接运行，此时应先根据变更的验收标准（规范或涉及的端点）制定检查清单。无论哪种情况，都按顺序逐项完成。

1. 启动服务，并记录启动方式

阅读 docs/agents/project.md，查找 Run locally (dev) 条目。如果存在，按其中的命令启动后端。如果不存在：从代码仓库中找出启动命令（Cargo 二进制目标 / tauri / package.json 脚本 / Makefile），启动服务并确认它能响应（通过健康检查路由，或发送第一条清单请求并确认收到任何响应），然后将启动命令和就绪信号写入 project.md 的 ## Run locally (dev) 部分。完成条件：服务能响应请求，且 project.md 中记录了启动命令。

前置条件——身份验证、数据、环境。 如果某个端点需要身份验证（令牌、预置的测试账号）、夹具/种子数据或环境配置（环境变量、测试数据库），请查明代码仓库如何提供这些内容，并将其与启动命令一起记录在 project.md 中。验收运行如果因 401 或数据库为空而停滞，测到的是测试框架，而不是功能——应解决前置条件并注明，而非将该条目标记为无法验证。

2. 将每条检查清单转化为真实请求

对于台账中的每个 API 条目，写出客户端实际发送的请求——方法、路径、标头、请求体——以及预期响应：状态码、请求体字段（名称、大小写、ID 类型）和任何副作用。明确覆盖边界条件：字段为空/仅含空白 → 文档规定的错误；未知 ID → 文档规定的状态码；请求体格式错误；重复调用。

3. 对运行中的服务执行测试

发送每条请求（使用 curl / http / 脚本），并验证完整预期，而不只是 2xx：状态码、请求体结构，以及——如果验收标准要求“持久化”——使用新的 GET 请求读取数据；如果要求“跨重启保持”，则重启服务后再次读取。对每个条目，在台账中记录实际结果与预期结果。完成条件：每个 API 条目都有实测结果。

4. 修复故障

必须使用 debug 子技能——失败的请求已经构成一个可重放的修复循环。修复根本原因、添加回归测试，并重新运行该条目。

5. 升级为持久化测试

将测试过的请求转化为已提交的测试，确保其会请求服务（或通过实际接缝调用处理程序），并按照 docs/agents/project.md 中的约定标注需求 ID，使其加入验证套件，在本次运行后继续守护该行为。完成条件：持久化测试已提交、带有标注且通过。