42 lines
1.3 KiB
Markdown
42 lines
1.3 KiB
Markdown
# 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`。
|