zhuangxiu/contracts/workflow-contract.md

Workflow API Contract

后端的 Pydantic 模型是运行时事实来源，前端 TypeScript 类型保持同名字段。

ProjectSnapshot

{
  "project_id": "demo-apartment",
  "name": "11-2-104 住宅概念方案",
  "stage": "plan_review",
  "revision": 3,
  "plan": {},
  "scene": {},
  "style": {},
  "available_commands": ["confirm_plan"],
  "updated_at": "2026-08-01T12:00:00Z"
}

CommandRequest

{
  "command": "confirm_plan",
  "expected_revision": 3,
  "payload": {}
}

expected_revision 用于乐观锁。若客户端基于旧版本提交，服务端返回 409 Conflict，避免覆盖其他修改。

Settings 与 Readiness

• GET /v1/settings：返回分类、非敏感值、每项是否已配置、测试结果和工作流就绪状态。
• PUT /v1/settings：增量更新运行期设置；空密钥表示保留原值。
• POST /v1/settings/test：保存后测试指定集成，不执行收费的模型生成任务。
• POST /v1/settings/generate-secret：生成内部服务令牌，不生成第三方 API Key。
• GET /v1/readiness：供前端决定是否解锁设计工作流。

任何密钥字段都不会出现在 values 中，只会在 configured 中返回布尔值。必备配置未完成或测试未通过时，上传与命令接口返回 503 和 SETTINGS_INCOMPLETE。

Project Ingestion

• GET /v1/projects：按更新时间返回持久化项目。
• POST /v1/projects/ingest：以 multipart/form-data 上传 file，可选 project_name；当前接受 25 MB 以内 PDF。
• GET /v1/projects/{project_id}/preview：从 MinIO 派生文件桶读取 PDF 首页预览。
• 新项目初始阶段为 region_selection，plan.regions 提供归一化的 [x0, y0, x1, y1] 候选区域。
• select_region 必须引用真实存在的候选区域 ID，成功后修订号递增并进入 plan_review。