# WonderQ Admin API 接口需求

本文档描述 `WonderQ-Admin-UI` 当前使用的 Admin API。接口负责站点内容维护、素材、发布和需求线索管理。

玩法分类和路线管理的字段、嵌套路由、排序与删除约束见 [wanfa-api.md](./wanfa-api.md)。该文档是本主契约的玩法领域补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。

管家顾问资料管理的字段、图片、排序与删除约束见 [concierge-api.md](./concierge-api.md)。该文档是本主契约的管家领域补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。

详情展示内容的字段、图片、排序与商品领域隔离约束见 [detail-api.md](./detail-api.md)。该文档是本主契约的详情领域补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。

首页体验、团队共创和极境视界内容的字段、图片、排序与商品领域隔离约束见 [home-api.md](./home-api.md)。该文档是本主契约的首页内容补充，适用端为 `WonderQ-Admin` 和 `WonderQ-Admin-UI`。

所有 Admin JSON 接口遵循 [三端统一 API 响应契约](./api-response-contract.md)。

## 通用约定

- API 前缀：`/api/admin`。
- 除登录接口外均需 `Authorization: Bearer <admin-jwt>`。
- JSON 请求统一使用 camelCase 字段。
- 变更接口写入审计日志后再提交事务。
- 成功业务结果统一放在 `data`；创建成功为 HTTP/code `201`。
- 失败统一返回数字 `code`、用户可读 `msg`、`data: null`，业务错误码放在可选的 `errorCode`。

## 接口清单

| 方法     | 路径                                      | 用途                 |
| -------- | ----------------------------------------- | -------------------- |
| `POST`   | `/api/admin/auth/login`                   | 后台登录             |
| `GET`    | `/api/admin/me`                           | 当前后台用户         |
| `GET`    | `/api/admin/dashboard`                    | 工作台统计和最近线索 |
| `GET`    | `/api/admin/site-config`                  | 获取全部站点配置     |
| `POST`   | `/api/admin/site-config/{module}`         | 新增模块项           |
| `PATCH`  | `/api/admin/site-config/{module}/{id}`    | 更新模块项           |
| `DELETE` | `/api/admin/site-config/{module}/{id}`    | 删除模块项           |
| `PATCH`  | `/api/admin/site-config/{module}/reorder` | 调整排序             |
| `GET`    | `/api/admin/leads`                        | 线索列表             |
| `PATCH`  | `/api/admin/leads/{id}/status`            | 更新线索状态         |
| `GET`    | `/api/admin/media-assets`                 | 素材列表             |
| `POST`   | `/api/admin/media-assets/upload`          | 上传图片             |
| `POST`   | `/api/admin/reset-guizhou-content`        | 重置站点内容         |
| `POST`   | `/api/admin/publish`                      | 发布站点快照         |

## 站点模块

`SiteModule` 只允许以下值：

```ts
type SiteModule =
  | "heroSlides"
  | "destinationHero"
  | "demandHero"
  | "demandFeatureCards"
  | "demandForm"
  | "vehicleOptions";
```

模块职责：

| 模块                 | 主要字段                                                           | 约束                     |
| -------------------- | ------------------------------------------------------------------ | ------------------------ |
| `heroSlides`         | `title`、`kicker`、`image`、`isActive`、`sortOrder`                | 可新增、编辑、删除、排序 |
| `destinationHero`    | `title`、`kicker`、`image`、`isActive`、`sortOrder`                | 可新增、编辑、删除、排序 |
| `demandHero`         | `title`、`kicker`、`description`、`steps`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
| `demandFeatureCards` | `title`、`description`、`isActive`、`sortOrder`                    | 可新增、编辑、删除、排序 |
| `demandForm`         | 表单标签、占位文案、`chips`、`isActive`                            | 单例，不支持排序         |
| `vehicleOptions`     | `title`、`description`、`image`、`isActive`、`sortOrder`           | 可新增、编辑、删除、排序 |

`GET /api/admin/site-config` 返回以上全部模块，包含停用内容，空模块返回 `[]`。

## 登录与工作台

### 登录

`POST /api/admin/auth/login` 请求：

```json
{ "email": "admin@example.test", "password": "<password>" }
```

成功响应包裹为 `data: { token, user: { id, email, name, role } }`；具体字段结构保持现有登录接口约定。

## 兼容边界

- 当前 Admin UI 不应调用未列出的领域接口。
- 站点配置字段必须与 `src/api.ts` 保持一致。
- 任何字段、模块或路径变化必须同步更新本文档和前端类型。