Workflow API Contract

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

ProjectSnapshot

{
  "project_id": "demo-apartment",
  "name": "11-2-104 住宅概念方案",
  "stage": "plan_review",
  "revision": 3,
  "plan": {},
  "scene": {},
  "style": {},
  "brief": {},
  "directions": [],
  "renders": [],
  "events": [],
  "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。

Product Workflow

POST /v1/projects/{project_id}/spatial-analysis：裁剪已选户型并调用空间理解模型；模型异常时返回 degraded=true 的可编辑房间草案。
POST /v1/projects/{project_id}/style-directions：保存需求访谈并调用总调度模型生成三套 Style DNA。
POST /v1/projects/{project_id}/chat：多轮设计对话，返回回复并把可识别的偏好更新到 brief。
POST /v1/projects/{project_id}/renders：调用模型池中的真实生图模型，下载并验证结果后写入渲染桶。
GET /v1/projects/{project_id}/renders/{asset_id}：读取已持久化效果图。
POST /v1/projects/{project_id}/renders/{asset_id}/edit：以历史效果图为参考执行文字修改，生成新的版本资产。

生图和编辑接口只在用户主动操作时调用收费模型。所有生成资产先验证为真实图片，再写入 MinIO 并加入 ProjectSnapshot.renders。

2.8 KiB Raw Blame History Unescape Escape