Merge branch 'codex/backend-rewrite-spacetimedb' of http://82.157.175.59:3000/GenarrativeAI/Genarrative into codex/backend-rewrite-spacetimedb

docs/technical/API_ERROR_DETAILS_MESSAGE_DISPLAY_FIX_2026-04-25.md

@@ -0,0 +1,37 @@
+# API 错误 details.message 展示修复
+
+## 背景
+
+`POST /api/runtime/big-fish/agent/sessions/{sessionId}/actions` 在执行 `big_fish_publish_game` 时，Rust `api-server` 会把 SpacetimeDB 发布校验失败映射为统一 API envelope：
+
+```json
+{
+  "ok": false,
+  "data": null,
+  "error": {
+    "code": "BAD_REQUEST",
+    "message": "请求参数不合法",
+    "details": {
+      "message": "big_fish 发布校验未通过：还缺少 16 个基础动作",
+      "provider": "spacetimedb"
+    }
+  }
+}
+```
+
+其中 `error.message` 是通用错误分类文案，`error.details.message` 才是当前业务动作的可定位失败原因。前端通用请求解析此前只读取 `error.message`，导致界面只显示“请求参数不合法”。
+
+## 落地口径
+
+1. 所有通过 `parseApiErrorMessage(...)` 解析的 API 错误，优先展示 `error.details.message`。
+2. 当 `error.details.message` 不存在或为空时，再回退到 `error.message`。
+3. 当 envelope 外层也不存在有效文案时，继续沿用原有的顶层 `message`、错误码和原始响应兜底逻辑。
+4. `unwrapApiResponse(...)` 处理 `ok: false` envelope 时也复用同一优先级，避免成功响应解析路径和 HTTP 非 2xx 路径展示不一致。
+5. Big Fish 结果页发布失败属于阻断性动作错误，展示为独立模态窗口，不再挤在结果页内容流里，关闭后只清掉当前错误状态，不改变草稿与资源数据。
+
+## 验收
+
+1. `big_fish_publish_game` 返回发布校验失败时，界面应显示 `big_fish 发布校验未通过：还缺少 16 个基础动作`。
+2. 没有 `details.message` 的旧错误响应仍显示原 `error.message`。
+3. 非 JSON 错误响应仍显示原始响应文本。
+4. Big Fish 结果页错误以居中模态窗口展示，并可通过关闭按钮回到结果页继续补资源。

docs/technical/BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md

@@ -241,6 +241,7 @@
 1. 展示会话、草稿、资产槽位、运行快照。
 2. 发送聊天、action 和摇杆输入。
 3. 根据后端 snapshot 渲染实体。
+4. 当后端 snapshot 返回 `won` 或 `failed` 时，必须在玩法舞台中央显示清晰结算浮层；通关与失败都不能只依赖顶部状态标签或事件日志。
 
 前端禁止：
 

docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md

@@ -308,6 +308,7 @@
 2. 壳层文件内不再直接包含自动保存防抖实现。
 3. 壳层文件内不再直接包含 session -> result profile 编译细节。
 4. 壳层文件内不再直接处理 works/library/history/save 的多路请求编排。
+5. Agent 聊天工作区进入时必须如实展示后端 session 的 `progressPercent`。新会话后端初始值为 `0` 时，前端数字与进度条填充都必须保持 `0%`；只允许对大于 0 的值使用视觉最小宽度，避免用户误判聊天流程已经推进。
 
 ## 5.2 custom world 专属 client 拆分方案
 

docs/technical/PUZZLE_SINGLE_PLAYER_AND_REAL_IMAGE_PLAN_2026-04-24.md

@@ -15,7 +15,8 @@
 2. 交换拼图块、拖动拼图块、关卡是否拼完，全部由前端本地计算。
 3. 本地运行态不调用 `/api/runtime/puzzle/runs/*` 写回当前过程状态。
 4. 关闭玩法后，这次运行态直接失效，不做断点续玩，不做跨端同步。
-5. 后端仍然负责：
+5. 通关后的第一版接续只保证单次游玩闭环：本地生成一个临时 `recommendedNextProfileId`，点击“下一关”后沿用当前作品图片、作者和标签，重建下一关棋盘；正式的广场推荐池仍留给后端运行态版本恢复。
+6. 后端仍然负责：
    - Agent 会话
    - 结果页草稿编译
    - 正式候选图生成
@@ -47,6 +48,8 @@
 
 不能继续写到仓库本地 `public/generated-puzzle-covers/*`。
 
+这些路径只是前后端 DTO 里的兼容标识，不是浏览器可以直接裸读的公开资源地址。实际图片对象存放在私有 OSS 中，前端渲染前必须先通过 `/api/assets/read-url?legacyPublicPath=...` 换取签名读 URL；签名 URL 未返回或换签失败时，图片组件不能把 `/generated-puzzle-assets/*` 直接写入 `<img src>`，避免浏览器发起无签名、无鉴权请求。
+
 ### 4.2 运行态边界
 
 第一版单机运行态保留现有 DTO 结构，目的是不重做界面层。
@@ -55,7 +58,9 @@
 
 1. 进入玩法时从作品详情构造本地 `run`
 2. 交换 / 拖动 / 通关时由前端工具函数返回新的 `run`
-3. 当前不依赖后端 `start/swap/drag/next-level` 接口完成主链
+3. 通关时本地写入临时下一关 id，用于显示“下一关”按钮
+4. 点击下一关时重置棋盘、推进关卡序号，并按已通关数量切换 `3x3 / 4x4`
+5. 当前不依赖后端 `start/swap/drag/next-level` 接口完成主链
 
 ## 5. 当前实现判断标准
 
@@ -65,4 +70,5 @@
 2. 返回路径切到 `/generated-puzzle-assets/*`。
 3. 未配置 DashScope 或 OSS 时，接口明确返回 provider 级错误，而不是静默回退占位图。
 4. 玩家进入拼图玩法后，即使后端运行态接口不可用，也能在本地完成交换与拖动。
-5. 关闭玩法后不保留当前 run 进度。
+5. 玩家完成整张图后能看到通关态与“下一关”入口，点击后进入新棋盘。
+6. 关闭玩法后不保留当前 run 进度。

docs/technical/README.md

@@ -4,6 +4,7 @@
 
 ## 文档列表
 
+- [API_ERROR_DETAILS_MESSAGE_DISPLAY_FIX_2026-04-25.md](./API_ERROR_DETAILS_MESSAGE_DISPLAY_FIX_2026-04-25.md)：记录统一 API envelope 错误展示优先读取 `error.details.message` 的修复口径，避免 Big Fish 发布校验等业务错误只显示通用“请求参数不合法”。
 - [BIG_FISH_DIRECTION_TOUCH_CONTROL_2026-04-24.md](./BIG_FISH_DIRECTION_TOUCH_CONTROL_2026-04-24.md)：记录大鱼吃小鱼从固定摇杆改为屏幕首触点方向控制，并要求本地直达局在未操作时保持对象运动。
 - [RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md](./RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md)：记录 `server-rs` 无参数 `cargo build` 链接 `spacetime-module` 失败的根因，并冻结默认只构建原生 `api-server`、模块产物继续走 `spacetime build` 的命令边界。
 - [BIG_FISH_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md](./BIG_FISH_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md)：记录 `/big-fish` 大鱼吃小鱼玩法直达入口，明确复用现有 `BigFishRuntimeShell` 和本地占位运行态的调试边界。