photonics-dhl API Contract — API 合同规范
保证前后端、服务间接口符合 Spec §16 的统一形态，并有幂等、并发与合同测试保护。
何时使用 / 何时不使用
- 使用：新增或修改 REST endpoint；新增领域事件；修改请求/响应 Schema；实现长任务（AI、上传、沙箱）接口。
- 不使用：进程内私有函数、纯前端组件内部状态。
检查清单（Spec §16）
- 模块化 REST/JSON：API 以模块化 REST/JSON 为主，endpoint 归属 §16 的核心模块（
/auth、/workspaces、/research-objects、/sdf、/branches、/commits、/versions、/issues、/pull-requests、/reviews、/publications、/search、/agent、/sandbox-jobs、/usage、/admin）。新模块需先说明为何现有模块装不下。 - 长任务模式：长任务不得同步阻塞响应；必须返回任务 ID，进度通过 SSE/WebSocket 推送（Spec §16、§9.3）。
- 幂等键：关键资源（发布、合并、支付/额度扣减类写操作）必须支持幂等键，重复提交不产生重复副作用（Spec §16）。
- 乐观锁：关键资源更新必须带乐观锁（版本号/etag），防止并发覆盖（Spec §16）。
- 事件可重试、消费者幂等：领域事件（如
research_object.created、version.published、sandbox_job.completed等，见 §16 关键事件表）必须可重试；每个事件消费者必须幂等（Spec §16）。 - 合同测试：前后端共享 Schema 必须有合同测试覆盖；改 Schema 必须同步更新合同测试（Spec §21.1 测试层：合同测试 = 前后端 Schema）。
- 权限检查在 API 层：每个 endpoint 必须做 Workspace 级越权检查，禁止只在前端隐藏入口（Spec §3.3 角色表、§17 防跨 Workspace 越权）。
验收前自问
- 这个写操作重发一次会发生什么？（幂等）
- 两个请求同时改同一资源会发生什么？（乐观锁）
- 前端类型和后端 Schema 漂移时哪条测试会红？（合同测试）
- 这个 endpoint 归到 §16 哪个核心模块？越权检查在哪一行？