当前项目排期快照

GET /api/v1/schedule/snapshot · getScheduleSnapshot

返回 Gantt 所需的项目内快照。

按段裁剪（sections，B-00354）：默认返回全部段落，与此前行为完全一致。实测线上单次响应 475 KB（gzip 130 KB）/ 1.4–1.7 s，一次性下发全部工作项 + 需求 + relations + risks + ownerLoads —— 而项目概览页只需要统计量（stats / milestones / risks / ownerLoads），却和甘特一样被这堆明细阻塞。用 sections 只要需要的段，概览可以把体积砍掉九成。

可裁剪的只有三个明细数组：requirements / workItems / relations。 stats / criticalPath / ownerLoads / risks / milestones / releaseWindows / calendar 恒返回——前四者是服务端在全量图上算出来的派生量，与是否下发明细无关，所以裁剪不会让统计失真（这也是本端点不做「分页」的原因：关键路径与传播风险要看整张依赖图，切成页反而算不对）。

被裁掉的段落在响应里是空数组，但 includedSections 会如实列出本次真正下发了哪些段—— 调用方据此区分「这个段没要」和「这个段真的没有数据」，不会把裁剪当成空态。

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

参数

sections: string —— 逗号分隔的明细段落名，取值 `requirements` / `workItems` / `relations`。省略或留空 = 全部下发（默认，兼容既有调用方）。未知段落名返回 422，不静默忽略—— 拼错段名却拿到一份「少了几段」的快照，比报错难查得多。

响应字段 · 200

includedSections（必填）: string[]
requirements（必填）: Requirement[]
requirements[].id（必填）: string
requirements[].displayKey（必填）: string
requirements[].title（必填）: string
requirements[].description: string
requirements[].roomId（必填）: string
requirements[].status（必填）: string
requirements[].priority（必填）: enum；取值：P0 / P1 / P2 / P3
requirements[].risk（必填）: enum；取值：high / medium / low
requirements[].ownerId（必填）: string
requirements[].creatorId（必填）: string
requirements[].module（必填）: string
requirements[].category（必填）: string
requirements[].releaseWindowId（必填）: string
requirements[].startOn（必填）: string
requirements[].targetOn（必填）: string
requirements[].progress（必填）: integer
requirements[].estimateDays（必填）: integer
requirements[].stateEnteredAt（必填）: string
requirements[].createdAt（必填）: string
requirements[].updatedAt（必填）: string
workItems（必填）: WorkItem[]
workItems[].id（必填）: string
workItems[].displayKey（必填）: string
workItems[].requirementId（必填）: string
workItems[].roomId（必填）: string
workItems[].severity: enum；取值：blocker / major / minor
workItems[].resolution: enum；取值：fixed / wontfix / cannot_reproduce / duplicate
workItems[].parentId: string
workItems[].title（必填）: string
workItems[].description: string
workItems[].type（必填）: enum；取值：task / dev / qa / bug
workItems[].availableTransitions: WorkItemTransition[]
workItems[].availableTransitions[].toStateKey（必填）: string
workItems[].availableTransitions[].name（必填）: string
workItems[].availableTransitions[].allowed（必填）: boolean
workItems[].availableTransitions[].blockedReason: string
workItems[].availableTransitions[].guardCode: enum；取值：permission / missing_field / separation_of_duties / slot_empty / not_slot_member / not_visited / unknown
workItems[].availableTransitions[].requireReason: boolean
workItems[].availableTransitions[].href（必填）: string
workItems[].availableTransitions[].method（必填）: string
workItems[].status（必填）: string
workItems[].priority（必填）: enum；取值：P0 / P1 / P2 / P3
workItems[].ownerId（必填）: string
workItems[].creatorId（必填）: string
workItems[].role（必填）: string
workItems[].startOn（必填）: string
workItems[].dueOn（必填）: string
workItems[].estimateDays（必填）: integer
workItems[].progress（必填）: integer
workItems[].sortOrder（必填）: integer
workItems[].customFields: object
workItems[].workflowVersionId（必填）: string
workItems[].activeSlotKey（必填）: string
workItems[].activeUserId（必填）: string
workItems[].lastActorId: string
workItems[].stateEnteredAt（必填）: string
workItems[].slots: object
workItems[].createdAt（必填）: string
workItems[].updatedAt（必填）: string
relations（必填）: ScheduleRelation[]
relations[].id（必填）: string
relations[].sourceWorkItemId（必填）: string
relations[].targetWorkItemId（必填）: string
relations[].type（必填）: enum；取值：finish_to_start
relations[].lagDays（必填）: integer
relations[].createdAt（必填）: string
milestones（必填）: Milestone[]
milestones[].id（必填）: string
milestones[].displayKey（必填）: string
milestones[].title（必填）: string
milestones[].description: string —— 里程碑说明（可选，纯文本）。空串表示无说明。
milestones[].kind（必填）: enum；取值：review / integration / freeze / release / custom
milestones[].requirementIds（必填）: string[] —— 关联需求 id 列表（多对多，可为空表示项目级节点）。
milestones[].releaseWindowId: string
milestones[].targetOn（必填）: string
milestones[].status（必填）: enum；取值：planned / at_risk / done
milestones[].createdAt（必填）: string
milestones[].updatedAt（必填）: string
releaseWindows（必填）: ReleaseWindow[]
releaseWindows[].id（必填）: string
releaseWindows[].displayKey（必填）: string
releaseWindows[].name（必填）: string
releaseWindows[].kind（必填）: enum；取值：version / patch / hotfix
releaseWindows[].startOn（必填）: string
releaseWindows[].targetOn（必填）: string
releaseWindows[].freezeOn: string
releaseWindows[].bufferDays（必填）: integer
releaseWindows[].status（必填）: enum；取值：planned / active / shipped / archived
releaseWindows[].isCurrent（必填）: boolean —— 是否为项目当前版本；同一项目同一时刻至多一个 true，由"设为当前"命令互斥维护。
calendar（必填）: WorkingCalendar
calendar.timezone（必填）: string
calendar.workdays（必填）: integer[]
calendar.holidays（必填）: string[]
stats（必填）: ScheduleStats
stats.activeRequirements（必填）: integer
stats.taskCount（必填）: integer
stats.milestoneCount（必填）: integer
stats.criticalPathDays（必填）: integer
stats.highRiskCount（必填）: integer
stats.averageProgress（必填）: integer
stats.projectedEndOn（必填）: string
criticalPath（必填）: CriticalPathItem[]
criticalPath[].workItemId（必填）: string
criticalPath[].order（必填）: integer
ownerLoads（必填）: OwnerLoad[]
ownerLoads[].ownerId（必填）: string
ownerLoads[].workItemCount（必填）: integer
ownerLoads[].estimateDays（必填）: integer
risks（必填）: ScheduleRisk[]
risks[].id（必填）: string
risks[].kind（必填）: enum；取值：dependency / dependency_violation / milestone / freeze / workload
risks[].severity（必填）: enum；取值：low / medium / high
risks[].message（必填）: string
risks[].entityType（必填）: enum；取值：requirement / work_item / milestone / release_window
risks[].entityId（必填）: string
staffingCapacity: StaffingCapacity
staffingCapacity.milestoneId（必填）: string
staffingCapacity.memberCount（必填）: integer
staffingCapacity.windowWorkdays（必填）: integer
staffingCapacity.capacityDays（必填）: integer
pileupSignals: SchedulePileupSignal[]
pileupSignals[].bucket（必填）: enum；取值：backlog / unstarted / started / completed / canceled / triage / duplicate
pileupSignals[].count（必填）: integer
pileupSignals[].average（必填）: integer
pileupSignals[].message（必填）: string

错误

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

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/schedule/snapshot?sections=…" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "includedSections": [
    "示例文本"
  ],
  "requirements": [
    {
      "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"
    }
  ],
  "workItems": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "displayKey": "示例文本",
      "requirementId": "018f3c2e-0000-7000-8000-000000000000",
      "roomId": "018f3c2e-0000-7000-8000-000000000000",
      "title": "示例标题",
      "type": "task",
      "status": "示例文本",
      "priority": "P0",
      "ownerId": "018f3c2e-0000-7000-8000-000000000000",
      "creatorId": "018f3c2e-0000-7000-8000-000000000000",
      "role": "示例文本",
      "startOn": "2026-08-01",
      "dueOn": "2026-08-01",
      "estimateDays": 1,
      "progress": 1,
      "sortOrder": 1,
      "workflowVersionId": "018f3c2e-0000-7000-8000-000000000000",
      "activeSlotKey": "示例文本",
      "activeUserId": "018f3c2e-0000-7000-8000-000000000000",
      "stateEnteredAt": "示例文本",
      "createdAt": "示例文本",
      "updatedAt": "2026-08-01"
    }
  ],
  "relations": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "sourceWorkItemId": "018f3c2e-0000-7000-8000-000000000000",
      "targetWorkItemId": "018f3c2e-0000-7000-8000-000000000000",
      "type": "finish_to_start",
      "lagDays": 1,
      "createdAt": "示例文本"
    }
  ],
  "milestones": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "displayKey": "示例文本",
      "title": "示例标题",
      "kind": "review",
      "requirementIds": [
        "018f3c2e-0000-7000-8000-000000000000"
      ],
      "targetOn": "2026-08-01",
      "status": "planned",
      "createdAt": "示例文本",
      "updatedAt": "2026-08-01"
    }
  ],
  "releaseWindows": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "displayKey": "示例文本",
      "name": "示例标题",
      "kind": "version",
      "startOn": "2026-08-01",
      "targetOn": "2026-08-01",
      "bufferDays": 1,
      "status": "planned",
      "isCurrent": true
    }
  ],
  "calendar": {
    "timezone": "示例文本",
    "workdays": [
      1
    ],
    "holidays": [
      "示例文本"
    ]
  },
  "stats": {
    "activeRequirements": 1,
    "taskCount": 1,
    "milestoneCount": 1,
    "criticalPathDays": 1,
    "highRiskCount": 1,
    "averageProgress": 1,
    "projectedEndOn": "2026-08-01"
  },
  "criticalPath": [
    {
      "workItemId": "018f3c2e-0000-7000-8000-000000000000",
      "order": 1
    }
  ],
  "ownerLoads": [
    {
      "ownerId": "018f3c2e-0000-7000-8000-000000000000",
      "workItemCount": 1,
      "estimateDays": 1
    }
  ],
  "risks": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "kind": "dependency",
      "severity": "low",
      "message": "示例文本",
      "entityType": "requirement",
      "entityId": "018f3c2e-0000-7000-8000-000000000000"
    }
  ]
}

合同真值：OpenAPI 3.1（0.1.0）。

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