fix: show big fish publish errors in modal

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/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` 和本地占位运行态的调试边界。