# Workflow API Contract

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

## ProjectSnapshot

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

```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`。