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-MiniAPP/src/lib/api.ts

@@ -1,6 +1,7 @@
 import type {
   AuthCustomer,
   AuthSession,
+  ApiErrorResponse,
   PhoneLoginPayload,
   PublicConciergeResponse,
   PublicDetail,
@@ -29,15 +30,66 @@ type RequestOptions = {
   headers?: Record<string, string>;
 };
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
 function responseMessage(data: unknown, fallback: string) {
   if (typeof data === "string") return data || fallback;
-  if (data && typeof data === "object" && "message" in data) {
-    const message = (data as { message?: unknown }).message;
+  if (isRecord(data)) {
+    const message = data.msg ?? data.message;
     if (typeof message === "string" && message.trim()) return message;
   }
   return fallback;
 }
 
+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(
+    responseMessage(body, `Request failed: ${statusCode}`),
+    statusCode,
+    typeof body.errorCode === "string" ? body.errorCode : undefined,
+    body.details,
+  );
+}
+
 export function request<T>(path: string, options: RequestOptions = {}) {
   return new Promise<T>((resolve, reject) => {
     uni.request({
@@ -50,15 +102,11 @@ export function request<T>(path: string, options: RequestOptions = {}) {
       },
       success(result) {
         const statusCode = result.statusCode ?? 0;
-        if (statusCode >= 200 && statusCode < 300) {
-          resolve(result.data as T);
-          return;
+        try {
+          resolve(parseApiResponse<T>(result.data, statusCode));
+        } catch (error) {
+          reject(error);
         }
-        reject(
-          new Error(
-            responseMessage(result.data, `Request failed: ${statusCode}`),
-          ),
-        );
       },
       fail(error) {
         reject(new Error(error.errMsg || "Request failed"));

WonderQ-MiniAPP/src/lib/types.ts

@@ -4,6 +4,22 @@ export const BRAND_FULL_NAME = `${BRAND_NAME}，${BRAND_TAGLINE}`;
 export const SUPPORT_PHONE = "18786174929";
 export const AUTH_SESSION_KEY = "miniapp:auth-session";
 
+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 type AuthCustomer = { id: string; phoneMasked: string };
 export type AuthSession = { token: string; customer: AuthCustomer };
 export type PhoneLoginPayload = { code: string };