# Workflow API Contract

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

## ProjectSnapshot

```json
{
  "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

```json
{
  "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`。