init with react+axum+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 结果页错误以居中模态窗口展示，并可通过关闭按钮回到结果页继续补资源。