# 三端统一 API 响应契约

本文档是 `WonderQ-Admin`、`WonderQ-Admin-UI-Vue`、`WonderQ-MiniAPP` 的统一 JSON 响应规范。适用于 `/health`、`/api/public/**` 和 `/api/admin/**`，新接口必须直接遵守本契约。

## 基本结构

所有 JSON 响应都必须包含 `code`、`msg` 和 `data`：

```json
{
  "code": 200,
  "msg": "success",
  "data": {}
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | `number` | 与 HTTP 状态码一致；成功通常为 `200`，创建成功为 `201`。 |
| `msg` | `string` | 成功固定为 `success`；失败为用户可读的错误信息。 |
| `data` | `object \| array \| string \| number \| boolean \| null` | 成功时承载原接口业务结果；失败时必须为 `null`。 |
| `errorCode` | `string`，可选 | 稳定的业务错误码，使用大写蛇形命名。 |
| `details` | `unknown`，可选 | 面向客户端的结构化错误详情，不得包含 SQL、堆栈、Token 或环境变量。 |

`data` 内的业务字段保持各领域文档原有结构不变。也就是说，列表的 `items`、首页的 `experiences`、玩法的 `categories` 等字段都位于响应的 `data` 内，而不是与 `code` 同级。

## ID 规范

- 所有持久化资源的 `id` 都是服务端生成的稳定不透明字符串，当前实现统一使用 UUID v4 格式。
- ID 只在记录创建时生成，后续列表、详情、排序、编辑和删除响应必须保持不变；禁止在序列化或每次请求时重新随机生成。
- 玩法路线详情的 `DetailRecord.key` 等于对应的 `WanfaRoute.id`，详情、列表、排序和跳转必须复用同一个路线 ID。
- 本地 fallback/mock 数据可以继续使用便于阅读的语义 ID，但这些 ID 不代表服务端正式 ID；接口成功后应以 API 返回的 UUID 为准。

## 成功响应

### 查询、更新、排序

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "items": []
  }
}
```

### 创建

创建接口返回 HTTP `201`，响应中的 `code` 也必须为 `201`：

```json
{
  "code": 201,
  "msg": "success",
  "data": {
    "id": "example-id"
  }
}
```

### 删除

删除接口仍保留原有业务结果，只放入 `data`：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "example-id"
  }
}
```

## 失败响应

失败响应的 HTTP 状态码和 `code` 必须相同，`data` 必须为 `null`：

```json
{
  "code": 404,
  "msg": "未找到对应内容",
  "data": null,
  "errorCode": "RESOURCE_NOT_FOUND",
  "details": {
    "resource": "example"
  }
}
```

`errorCode` 和 `details` 没有值时可以省略，但不能用空对象替代 `data: null`。常见错误码包括：

| HTTP/code | 场景 | 推荐 `errorCode` |
| --- | --- | --- |
| `400` | 请求参数、排序列表或字段格式错误 | `VALIDATION_ERROR` 或领域错误码 |
| `401` | 未登录或 Token 无效 | `AUTH_REQUIRED` 或 `AUTH_INVALID` |
| `404` | 资源不存在、停用或未配置 | 领域 `*_NOT_FOUND` |
| `409` | 重复键、删除冲突或并发冲突 | 领域 `*_CONFLICT` |
| `422` | 仍由业务层使用的不可处理实体 | 领域错误码 |
| `500` | 未知服务端异常 | `INTERNAL_SERVER_ERROR` |

参数校验错误由后端统一转换为 `400 + VALIDATION_ERROR`；如果某个既有业务场景仍返回 `422`，也必须按本契约包装，且 `code` 必须为数字 `422`。

## 客户端处理

- `WonderQ-Admin` 负责所有路由和全局异常处理，不能把内部异常、SQL、堆栈、Token 或环境配置写入 `msg`、`details` 或响应日志。
- `WonderQ-Admin-UI-Vue` 的公共 `request<T>` 校验包裹结构，成功只返回 `data`；失败使用 `msg` 提示，并保留 `errorCode`、`details`。
- `WonderQ-MiniAPP` 的公共请求层执行同样校验，页面、Store 和归一化函数继续只接收业务类型，不重复读取 `data`。
- HTTP 错误是服务端返回了合法错误包；网络错误是请求未获得 HTTP 响应；协议错误是响应缺少必填字段或字段类型不正确，三者应分别进入现有错误、重试和 fallback 流程。
- 未包裹的旧响应不再兼容，客户端必须将其识别为协议错误。

## 联调检查

每次新增或修改接口时，至少检查：

1. 成功查询返回 `200`，创建返回 `201`。
2. `code` 为数字且等于 HTTP 状态码。
3. 成功 `msg` 为 `success`，失败 `data` 为 `null`。
4. 列表、详情、删除和排序的原业务字段只出现在 `data` 内。
5. `400`、`401`、`404`、`409`、`422`、`500`（适用时）都保持相同包裹结构。

相关领域字段和路径以 [public-api.md](./public-api.md)、[admin-api-requirements.md](./admin-api-requirements.md)、[module-config-api.md](./module-config-api.md)、[wanfa-api.md](./wanfa-api.md)、[detail-api.md](./detail-api.md) 和 [concierge-api.md](./concierge-api.md) 为准。