API 参考 / requirement-rooms

需求室规则概览

GET /api/v1/rooms/{roomId}/overview · getRoomOverview

在当前项目的 TenantTx/RLS 快照内返回需求、子任务、验收与缺陷的全量精确计数， 以及 room-overview/v1 规则派生的阶段和带来源的下一步导航建议。 阶段与建议均为确定性只读派生：不写 Room.status、不更新 Room.updatedAt、 不产 ChangeSet/Event、不调用 LLM，也不执行任何建议动作。 调用方必须同时具备需求室、需求（含子任务）与缺陷三个模块的 read 等级； 任一模块不足时整份概览返回 403，不返回部分数字或伪造阶段。

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

参数

roomId（必填）
string

响应字段 · 200

phase（必填）
enum —— room-overview/v1 只读派生阶段；不是 Room.status，不落库、不可手工修改；命中优先级固定为 completed → in_progress → needs_definition → ready → empty。；取值：empty / needs_definition / ready / in_progress / completed
rulesVersion（必填）
enum；取值：room-overview/v1
requirementBuckets（必填）
RoomOverviewRequirementBuckets
requirementBuckets.total（必填）
integer
requirementBuckets.backlog（必填）
integer
requirementBuckets.unstarted（必填）
integer
requirementBuckets.started（必填）
integer
requirementBuckets.completed（必填）
integer
requirementBuckets.canceled（必填）
integer
requirementBuckets.triage（必填）
integer
requirementBuckets.duplicate（必填）
integer
workItems（必填）
RoomOverviewWorkItemCounts
workItems.total（必填）
integer
workItems.active（必填）
integer
workItems.closed（必填）
integer
acceptance（必填）
RoomOverviewAcceptanceCounts
acceptance.missingRequirementCount（必填）
integer
acceptance.blockedItemCount（必填）
integer
acceptance.notPassedItemCount（必填）
integer
bugs（必填）
RoomOverviewBugCounts
bugs.unresolvedCount（必填）
integer
bugs.unresolvedBlockerCount（必填）
integer
nextActions（必填）
RoomOverviewNextAction[]
nextActions[].kind（必填）
enum；取值：add_requirement / add_acceptance_criteria / fix_blocked_acceptance / start_ready_requirement / continue_started_object / resolve_blocker_bug / resolve_open_bug
nextActions[].label（必填）
string
nextActions[].totalCount（必填）
integer
nextActions[].sources（必填）
RoomOverviewSourceRef[]
nextActions[].sources[].objectType（必填）
enum；取值：requirement / work_item / bug / acceptance_item
nextActions[].sources[].id（必填）
string
nextActions[].sources[].displayKey（必填）
string
nextActions[].sources[].title（必填）
string
nextActions[].sources[].deepLink（必填）
string
nextActions[].sources[].requirementId
string
nextActions[].sources[].acceptanceItemId
string
nextActions[].truncated（必填）
boolean
nextActions[].collectionLink（必填）
string —— 截断时定位完整问题对象集合的只读深链；不执行 mutation。
nextActions[].collectionSourceIds（必填）
string[] —— 完整受影响对象 id 集合，不受 sources 预览上限影响；验收问题返回其所属 Requirement id。

错误

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/rooms/{roomId}/overview" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "phase": "empty",
  "rulesVersion": "room-overview/v1",
  "requirementBuckets": {
    "total": 1,
    "backlog": 1,
    "unstarted": 1,
    "started": 1,
    "completed": 1,
    "canceled": 1,
    "triage": 1,
    "duplicate": 1
  },
  "workItems": {
    "total": 1,
    "active": 1,
    "closed": 1
  },
  "acceptance": {
    "missingRequirementCount": 1,
    "blockedItemCount": 1,
    "notPassedItemCount": 1
  },
  "bugs": {
    "unresolvedCount": 1,
    "unresolvedBlockerCount": 1
  },
  "nextActions": [
    {
      "kind": "add_requirement",
      "label": "示例文本",
      "totalCount": 1,
      "sources": [
        {}
      ],
      "truncated": true,
      "collectionLink": "https://example.com",
      "collectionSourceIds": [
        "018f3c2e-0000-7000-8000-000000000000"
      ]
    }
  ]
}

合同真值：OpenAPI 3.1（0.1.0）。

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

Workflow 正在加载…