API 参考 / requirements

执行需求状态转移

POST /api/v1/requirements/{requirementId}/transition · executeRequirementTransition

经可配置工作流引擎执行一次需求状态转移（ADR-0009）：校验守卫（分权 permission_guard）→ 强制 require_reason 边的变更原因 → CAS 写状态 + state_entered_at → 产 requirement.updated 事件。端点级鉴权 manage_requirements；逐动作分权（通过/驳回需 manage_schedule）由引擎守卫判定：无权返回 403。 CAS 并发冲突返回 409；拓扑非法 / 缺 require_reason / 需求未钉版本返回 422。这是需求状态流转的唯一入口（ADR-0009 切换完成：旧 /review 命令已删除，PATCH /requirements/{id} 不再接受 status 写入）。

鉴权：项目 API Token（Authorization: Bearer wfp_…）。详见 Agent 接入。

参数

requirementId（必填）: string

请求体

toStateKey（必填）: string
reason: string

响应字段 · 200

id（必填）: string
displayKey（必填）: string
title（必填）: string
description: string
roomId（必填）: string
status（必填）: string
priority（必填）: enum；取值：P0 / P1 / P2 / P3
risk（必填）: enum；取值：high / medium / low
ownerId（必填）: string
creatorId（必填）: string
module（必填）: string
category（必填）: string
releaseWindowId（必填）: string
startOn（必填）: string
targetOn（必填）: string
progress（必填）: integer
estimateDays（必填）: integer
stateEnteredAt（必填）: string
createdAt（必填）: string
updatedAt（必填）: string

错误

403：Problem 错误响应
404：Problem 错误响应
409：Problem 错误响应
422：Problem 错误响应

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/requirements/{requirementId}/transition" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"toStateKey":"示例文本","reason":"操作原因(会记入变更流)"}'

响应示例

HTTP/1.1 200
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "displayKey": "示例文本",
  "title": "示例标题",
  "roomId": "018f3c2e-0000-7000-8000-000000000000",
  "status": "示例文本",
  "priority": "P0",
  "risk": "high",
  "ownerId": "018f3c2e-0000-7000-8000-000000000000",
  "creatorId": "018f3c2e-0000-7000-8000-000000000000",
  "module": "示例文本",
  "category": "示例文本",
  "releaseWindowId": "018f3c2e-0000-7000-8000-000000000000",
  "startOn": "2026-08-01",
  "targetOn": "2026-08-01",
  "progress": 1,
  "estimateDays": 1,
  "stateEnteredAt": "示例文本",
  "createdAt": "示例文本",
  "updatedAt": "2026-08-01"
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引