feat(api): 实现三端统一的JSON API响应契约

- 新增`api_response.py`统一响应封装工具类，提供标准成功/错误响应构造方法
- 重构WonderQ-Admin全局异常处理器，将所有异常转换为标准响应格式
- 修改所有公共和管理端接口的返回逻辑，统一使用`code`（与HTTP状态码一致）、`msg`和`data`的三层结构
- 新增`api-response-contract.md`文档，定义完整的三端统一JSON响应规范
- 更新所有领域API文档，明确业务数据需位于`data`字段内，补充响应格式说明
- 为WonderQ-MiniAPP和WonderQ-Admin-UI新增响应解析逻辑和类型定义，自动完成协议校验和错误处理
- 更新所有测试用例，适配新的响应结构确保接口符合契约要求
- 新增`module-config-api.md`模块配置API文档，补充站点模块配置的接口约定
- 更新项目README文档，调整文档分类顺序将响应契约置于首位

WonderQ-Admin-UI/src/api.ts

@@ -283,6 +283,22 @@ export type SiteItemPatch = {
 const API_BASE = import.meta.env.VITE_API_BASE_URL ?? "";
 const TOKEN_KEY = "miniapp_admin_token";
 
+export type ApiResponse<T> = {
+  code: number;
+  msg: string;
+  data: T;
+  errorCode?: string;
+  details?: unknown;
+};
+
+export type ApiErrorResponse = {
+  code: number;
+  msg: string;
+  data: null;
+  errorCode?: string;
+  details?: unknown;
+};
+
 export function getToken() {
   return window.localStorage.getItem(TOKEN_KEY);
 }
@@ -300,6 +316,61 @@ function handleAuthExpired() {
   notifyAuthExpired();
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export class ApiRequestError extends Error {
+  readonly statusCode: number;
+  readonly errorCode?: string;
+  readonly details?: unknown;
+
+  constructor(message: string, statusCode: number, errorCode?: string, details?: unknown) {
+    super(message);
+    this.name = "ApiRequestError";
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.details = details;
+  }
+}
+
+export class ApiProtocolError extends Error {
+  constructor(message = "接口响应格式不正确") {
+    super(message);
+    this.name = "ApiProtocolError";
+  }
+}
+
+export function parseApiResponse<T>(payload: unknown, statusCode: number): T {
+  if (!isRecord(payload)) {
+    throw new ApiProtocolError();
+  }
+
+  const hasData = Object.prototype.hasOwnProperty.call(payload, "data");
+  if (statusCode >= 200 && statusCode < 300) {
+    if (typeof payload.code !== "number" || payload.code !== statusCode || payload.msg !== "success" || !hasData) {
+      throw new ApiProtocolError();
+    }
+    return payload.data as T;
+  }
+
+  if (typeof payload.code !== "number" || payload.code !== statusCode || typeof payload.msg !== "string" || !hasData || payload.data !== null) {
+    throw new ApiProtocolError();
+  }
+
+  const body = payload as ApiErrorResponse;
+  throw new ApiRequestError(
+    body.msg,
+    statusCode,
+    body.errorCode,
+    body.details,
+  );
+}
+
+async function readApiResponse(response: Response): Promise<unknown> {
+  return response.json().catch(() => null);
+}
+
 async function request<T>(path: string, options: RequestInit = {}): Promise<T> {
   const headers = new Headers(options.headers);
   headers.set("Content-Type", "application/json");
@@ -315,11 +386,11 @@ async function request<T>(path: string, options: RequestInit = {}): Promise<T> {
     if (path !== "/api/admin/auth/login" && shouldExpireAdminSession(response.status, Boolean(token))) {
       handleAuthExpired();
     }
-    const body = await response.json().catch(() => ({}));
-    throw new Error(body.message ?? `请求失败：${response.status}`);
+    const body = await readApiResponse(response);
+    return parseApiResponse<T>(body, response.status);
   }
 
-  return response.json() as Promise<T>;
+  return parseApiResponse<T>(await readApiResponse(response), response.status);
 }
 
 export async function login(email: string, password: string) {
@@ -347,11 +418,11 @@ export async function uploadMediaAsset(file: File, group = "site-config") {
     if (shouldExpireAdminSession(response.status, Boolean(token))) {
       handleAuthExpired();
     }
-    const body = await response.json().catch(() => ({}));
-    throw new Error(body.message ?? `请求失败：${response.status}`);
+    const body = await readApiResponse(response);
+    return parseApiResponse<MediaAsset>(body, response.status);
   }
 
-  return response.json() as Promise<MediaAsset>;
+  return parseApiResponse<MediaAsset>(await readApiResponse(response), response.status);
 }
 
 export async function getSiteConfig() {