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。