1

docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md

@@ -13,38 +13,43 @@
 
 ## 模型选项
 
-拼图图片生成支持三个选项：
+拼图图片生成支持两个选项：
 
 | 前端显示 | 请求值 | 上游 |
 | --- | --- | --- |
-| 原模型 | `original` | 继续使用现有 DashScope 文生图 / 图生图链路 |
 | `gpt-image-2` | `gpt-image-2` | APIMart `/v1/images/generations` |
 | `nanobanana2` | `gemini-3.1-flash-image-preview` | APIMart `/v1/images/generations` |
 
-默认值为 `original`。前端只负责展示和传递所选模型，不能把模型路由逻辑、上游请求体拼装或 API Key 暴露到浏览器。
+默认值为 `gpt-image-2`。前端只负责展示和传递所选模型，不能把模型路由逻辑、上游请求体拼装或 API Key 暴露到浏览器。历史草稿或旧请求中的空值、`original`、未知值统一按 `gpt-image-2` 处理，不再把拼图生图路由回 DashScope 原模型。
 
 ## 前端交互
 
 1. 拼图创作表单的“画面描述”输入框左下角显示当前调用模型。
 2. 拼图结果页关卡详情的“画面描述”输入框左下角同样显示当前调用模型。
-3. 点击模型标识弹出轻量选择菜单，支持 `原模型`、`gpt-image-2`、`nanobanana2` 三项。
+3. 点击模型标识弹出轻量选择菜单，只支持 `gpt-image-2`、`nanobanana2` 两项。
 4. 菜单只是模型选择控件，不写入说明性规则文案。
 5. 参考图入口继续在画面描述输入框右下角，模型选择在左下角，两者不得遮挡文本。
 6. 表单创建 session、自动保存表单草稿、首图生成失败重试时都要保留当前模型选择。
 7. 结果页关卡重新生成时将当前模型随 `generate_puzzle_images` action 传给后端。
+8. “生成草稿”和关卡详情“生成画面 / 重新生成画面”按钮文本右侧展示 `消耗2光点`。
+9. 关卡详情点击“生成画面 / 重新生成画面”后先弹出确认消耗光点弹窗，确认后开始请求；按钮区域切换为 30 秒倒计时进度条，并展示预计剩余生成完成时间。
 
 ## 后端路由
 
 1. `CreatePuzzleAgentSessionRequest` 与 `ExecutePuzzleAgentActionRequest` 增加可选 `imageModel` 字段；该字段不进入 SpacetimeDB reducer 输入结构。
 2. `compile_puzzle_draft_with_initial_cover` 与 `generate_puzzle_image_candidates` 增加图片模型参数。
 3. `imageModel` 归一化规则：
-   - 空值、`original` 或未知值统一回落为原 DashScope 链路；
+   - 空值、`original` 或未知值统一回落为 `gpt-image-2`；
    - `gpt-image-2` 走 APIMart；
    - `gemini-3.1-flash-image-preview` 走 APIMart，前端显示名为 `nanobanana2`。
 4. APIMart 文生图和图生图共用 `POST /v1/images/generations`。有参考图时，后端将参考图 Data URL 作为 `image_urls` 数组传入；若上游不接受该字段，错误按上游失败返回，不在前端降级伪造结果。
-5. APIMart 尺寸使用文档要求的比例写法 `1:1`；原 DashScope 继续使用像素写法 `1024*1024`。`gemini-3.1-flash-image-preview` 额外带 `resolution = "1K"`，对齐约 1024px 的拼图正方形素材。
-6. APIMart 生成成功后仍下载远程图片，沿用现有 OSS 私有对象、`asset_object` 和 `asset_entity_binding` 写入流程。
-7. APIMart 错误统一映射为 `502 UPSTREAM_ERROR`，`details.provider = "apimart"`，保留上游状态码、业务 message 和截断后的 raw excerpt。
+5. APIMart 尺寸使用文档要求的比例写法 `1:1`。`gemini-3.1-flash-image-preview` 额外带 `resolution = "1K"`，对齐约 1024px 的拼图正方形素材。
+6. APIMart 生成成功后仍下载远程图片，沿用现有 OSS 私有对象、`asset_object` 和 `asset_entity_binding` 写入流程。若图片已成功上传 OSS，但 Maincloud / SpacetimeDB 短暂返回 `503 Service Unavailable`，资产索引写入允许降级跳过，并返回本次生成图片；日志必须记录 `拼图图片资产索引写入因 SpacetimeDB 连接不可用而降级跳过`。
+7. `save_puzzle_generated_images` 写回草稿时若遇到 Maincloud 连接级 `503` 或断线，API 层基于本次生成结果合成 session 快照返回给前端，避免 APIMart 已成功出图却被后置持久化误报成服务不可用。余额不足、参数错误、上游生图失败仍按原错误返回，不做伪成功。
+8. 结果页 `generate_puzzle_images` 会携带当前作品信息和 `levelsJson`。当 Maincloud / SpacetimeDB 在读取 session 阶段就返回连接级 `503` 或断线时，后端必须先用这份结果页快照构造最小内存 session，再继续调用 APIMart；外部图片已经生成后仍按第 6、7 条处理持久化降级。余额不足、参数错误、缺少草稿快照、关卡不存在等业务错误不走此降级。
+9. APIMart 异步任务轮询按文档口径在提交后先等待 `10s`，再调用 `GET /v1/tasks/{task_id}`；图片地址提取同时支持 `url: "..."` 与 `url: ["..."]` 两种结构。
+10. APIMart 错误统一映射为 `502 UPSTREAM_ERROR`，`details.provider = "apimart"`，保留上游状态码、业务 message 和截断后的 raw excerpt。
+11. 拼图首图生成 `compile_puzzle_draft` 与关卡图片生成 `generate_puzzle_images` 每次预扣 `2` 光点；余额不足仍返回 `409 CONFLICT`，Maincloud 连接级 503 仍按既有降级策略处理。
 
 ## 环境变量
 
@@ -60,10 +65,11 @@ APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
 
 ## 验收
 
-1. 创作表单和关卡详情的画面描述框左下角能切换 `原模型`、`gpt-image-2`、`nanobanana2`。
+1. 创作表单和关卡详情的画面描述框左下角能切换 `gpt-image-2`、`nanobanana2`，默认显示 `gpt-image-2`。
 2. 点击“生成草稿”时，后端首图生成使用当前表单选择的模型。
 3. 点击“生成画面 / 重新生成画面”时，后端当前关卡图片生成使用关卡详情选择的模型。
-4. 选择 `original` 时，现有 DashScope 请求体、尺寸和错误处理保持兼容。
+4. 历史 `original` 或空模型值不会再触发 DashScope，统一按 `gpt-image-2` 请求 APIMart。
 5. 选择 APIMart 模型时，请求 `POST {APIMART_BASE_URL}/images/generations`，使用 `Authorization: Bearer {APIMART_API_KEY}`，`model` 等于请求值，`size = 1:1`。
-6. 不改 SpacetimeDB 表结构，因此无需更新 `migration.rs` 或重新生成 bindings。
-7. 后端改动后运行对应 Rust 测试，并按项目约束用 `npm run api-server:maincloud` 重启验证。
+6. “生成草稿”和关卡详情生图按钮展示 `消耗2光点`；关卡详情确认后展示 30 秒预计剩余进度条。
+7. 不改 SpacetimeDB 表结构，因此无需更新 `migration.rs` 或重新生成 bindings。
+8. 后端改动后运行对应 Rust 测试，并按项目约束用 `npm run api-server:maincloud` 重启验证。