API 参考 / requirements

创建需求验收项

POST /api/v1/requirements/{requirementId}/acceptance-items · createRequirementAcceptanceItem

为当前需求创建一条验收项；actor 与 project 只来自 session/Host 上下文。

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

参数

requirementId（必填）: string
Idempotency-Key: string —— 幂等键（建议用 UUID，最长 255 字符）。重复提交同键且请求体一致时返回首次创建的结果（200）而不新建对象；请求体不一致返回 409。有效期 24 小时。

请求体

text（必填）: string
acceptanceTypeId: string
statusId（必填）: string
sourceKind: enum；取值：manual / requirement / work_item / ai
sourceRef: string
sortOrder: integer
reason: string

响应字段 · 201

id（必填）: string
requirementId（必填）: string
text（必填）: string
systemSemantic（必填）: enum；取值：not_started / in_progress / blocked / needs_changes / passed / failed / closed
acceptanceTypeId（必填）: string
statusId（必填）: string
sourceKind（必填）: enum；取值：manual / requirement / work_item / ai
sourceRef（必填）: string
sortOrder（必填）: integer
createdAt（必填）: string
updatedAt（必填）: string

响应字段 · 200

id（必填）: string
requirementId（必填）: string
text（必填）: string
systemSemantic（必填）: enum；取值：not_started / in_progress / blocked / needs_changes / passed / failed / closed
acceptanceTypeId（必填）: string
statusId（必填）: string
sourceKind（必填）: enum；取值：manual / requirement / work_item / ai
sourceRef（必填）: string
sortOrder（必填）: integer
createdAt（必填）: string
updatedAt（必填）: string

错误

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

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/requirements/{requirementId}/acceptance-items" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"text":"示例文本","statusId":"018f3c2e-0000-7000-8000-000000000000","acceptanceTypeId":"018f3c2e-0000-7000-8000-000000000000"}'

响应示例

HTTP/1.1 201
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "requirementId": "018f3c2e-0000-7000-8000-000000000000",
  "text": "示例文本",
  "systemSemantic": "not_started",
  "acceptanceTypeId": "018f3c2e-0000-7000-8000-000000000000",
  "statusId": "018f3c2e-0000-7000-8000-000000000000",
  "sourceKind": "manual",
  "sourceRef": "示例文本",
  "sortOrder": 1,
  "createdAt": "示例文本",
  "updatedAt": "2026-08-01"
}

合同真值：OpenAPI 3.1（0.1.0）。

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