Genarrative/docs/technical/API_ERROR_DETAILS_MESSAGE_DISPLAY_FIX_2026-04-25.md

API 错误 details.message 展示修复

背景

POST /api/runtime/big-fish/agent/sessions/{sessionId}/actions 在执行 big_fish_publish_game 时，Rust api-server 会把 SpacetimeDB 发布校验失败映射为统一 API envelope：

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