API 参考 / blueprints

锁定 / 解锁块（CAS 并发）

POST /api/v1/orgs/{orgId}/blueprint-drafts/{draftId}/onepage/blocks/{blockId}/lock · toggleOnePageLock

锁定 / 解锁块。锁定块在整份或局部重生成中逐字不变（验收硬规则）。已确认版本只读。 version 不匹配 -> 409。仅 active Org Admin 可调用；普通成员 404。PAT 不可调用本端点。

本接口要求浏览器会话。Bearer API Token 无法调用——Token 的生命周期管理必须在网页端完成。

参数

orgId（必填）: string
draftId（必填）: string
blockId（必填）: string

请求体

locked（必填）: boolean
version（必填）: integer

响应字段 · 200

id（必填）: string
draftId（必填）: string
orgId（必填）: string
directionId（必填）: string
directionSetVersion: string
surveyVersionId: string
marketSnapshotId: string
promptVersion: string
modelId: string
blocks（必填）: OnePageBlock[]
blocks[].id（必填）: string
blocks[].title（必填）: string
blocks[].content（必填）: string
blocks[].locked（必填）: boolean
blocks[].source（必填）: enum —— 区块来源标记（区分 AI 初始 / AI 重生成 / 用户修改）。上屏三态标记来源（设计稿 g10：AI 生成 / 已锁定 / 用户已编辑）。不用颜色作唯一区分。；取值：ai_initial / ai_regen / user_edit
blocks[].evidenceRefs（必填）: string[]
status（必填）: enum —— OnePage 版本状态。状态机：editing（块可 locked）→ confirmed（永久只读）→ superseded（重分析产 v{n+1}，不覆盖创建时版本）。；取值：editing / confirmed / superseded
revision（必填）: integer
version（必填）: integer
createdBy: string
createdAt（必填）: string
updatedAt（必填）: string
confirmedAt: string

错误

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

请求示例（curl）

curl -X POST "https://workflow.games/api/v1/orgs/{orgId}/blueprint-drafts/{draftId}/onepage/blocks/{blockId}/lock" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"locked":true,"version":1}'

响应示例

HTTP/1.1 200
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "draftId": "018f3c2e-0000-7000-8000-000000000000",
  "orgId": "018f3c2e-0000-7000-8000-000000000000",
  "directionId": "018f3c2e-0000-7000-8000-000000000000",
  "blocks": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "title": "示例标题",
      "content": "示例文本",
      "locked": true,
      "source": "ai_initial",
      "evidenceRefs": [
        "示例文本"
      ]
    }
  ],
  "status": "editing",
  "revision": 1,
  "version": 1,
  "createdAt": "示例文本",
  "updatedAt": "2026-08-01"
}

合同真值：OpenAPI 3.1（0.1.0）。

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