WonderQ-Project/docs/admin-api-requirements.md

# WonderQ Admin API 接口需求

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

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

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

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

首页和用车站点模块的字段、单例、排序与删除约束见 [module-config-api.md](./module-config-api.md)。

所有 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`。
- 所有持久化资源的 `id` 由后端生成稳定 UUID 字符串。Admin UI 必须保存并复用接口返回的 ID，不能根据标题、文案或数组下标自行拼接，也不能假设 ID 是可读 slug。

## 接口清单

| 方法     | 路径                                      | 用途                 |
| -------- | ----------------------------------------- | -------------------- |
| `POST`   | `/api/admin/auth/login`                   | 后台登录             |
| `POST`   | `/api/admin/auth/refresh`                 | 使用 HttpOnly Cookie 刷新后台访问令牌 |
| `POST`   | `/api/admin/auth/logout`                  | 撤销当前后台会话     |
| `GET`    | `/api/admin/me`                           | 当前后台用户         |
| `GET`    | `/api/admin/system/profile`              | 当前用户、角色、权限码和动态菜单 |
| `GET`    | `/api/admin/system/routers`              | 按当前管理员权限返回 RuoYi 风格动态路由树 |
| `GET`    | `/api/admin/system/users`               | 查询后台用户         |
| `POST`   | `/api/admin/system/users`               | 新增后台用户         |
| `PATCH`  | `/api/admin/system/users/{userId}`     | 更新后台用户         |
| `GET`    | `/api/admin/system/roles`               | 查询管理角色和数据范围 |
| `POST`   | `/api/admin/system/roles`               | 新增管理角色         |
| `PATCH`  | `/api/admin/system/roles/{roleId}`     | 更新管理角色         |
| `GET`    | `/api/admin/system/menus`               | 查询目录、页面和按钮 |
| `POST`   | `/api/admin/system/menus`               | 新增目录、页面或按钮 |
| `PATCH`  | `/api/admin/system/menus/{menuId}`     | 更新目录、页面或按钮 |
| `GET`    | `/api/admin/system/depts`               | 查询部门             |
| `POST`   | `/api/admin/system/depts`               | 新增部门             |
| `PATCH`  | `/api/admin/system/depts/{deptId}`     | 更新部门             |
| `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/home/play-recommendations`    | 查询首页玩法推荐     |
| `POST`   | `/api/admin/home/play-recommendations`    | 新增首页玩法推荐     |
| `PATCH`  | `/api/admin/home/play-recommendations/{id}` | 更新首页玩法推荐   |
| `DELETE` | `/api/admin/home/play-recommendations/{id}` | 删除首页玩法推荐   |
| `PATCH`  | `/api/admin/home/play-recommendations/reorder` | 排序首页玩法推荐 |
| `GET`    | `/api/admin/home/team-buildings`          | 查询首页团队共创     |
| `POST`   | `/api/admin/home/team-buildings`          | 新增首页团队共创     |
| `PATCH`  | `/api/admin/home/team-buildings/{id}`     | 更新首页团队共创     |
| `DELETE` | `/api/admin/home/team-buildings/{id}`     | 删除首页团队共创     |
| `PATCH`  | `/api/admin/home/team-buildings/reorder`  | 排序首页团队共创     |
| `GET`    | `/api/admin/home/wild-archives`           | 查询首页极境视界     |
| `POST`   | `/api/admin/home/wild-archives`           | 新增首页极境视界     |
| `PATCH`  | `/api/admin/home/wild-archives/{id}`      | 更新首页极境视界     |
| `DELETE` | `/api/admin/home/wild-archives/{id}`      | 删除首页极境视界     |
| `PATCH`  | `/api/admin/home/wild-archives/reorder`   | 排序首页极境视界     |
| `GET`    | `/api/admin/leads`                        | 线索列表             |
| `PATCH`  | `/api/admin/leads/{id}/status`            | 更新线索状态         |
| `GET`    | `/api/admin/media-assets`                 | 素材列表             |
| `POST`   | `/api/admin/media-assets/upload`          | 上传图片             |

## 站点模块

`SiteModule` 只允许以下值：

```ts
type SiteModule =
  | "heroSlides"
  | "vehicleOptions";
```

模块职责：

| 模块                 | 主要字段                                             | 约束                     |
| -------------------- | ---------------------------------------------------- | ------------------------ |
| `heroSlides`         | `title`、`kicker`、`image`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |
| `vehicleOptions`     | `title`、`description`、`image`、`isActive`、`sortOrder` | 可新增、编辑、删除、排序 |

`GET /api/admin/site-config` 只返回以上两个模块，包含停用内容，空模块返回 `[]`。首页工作台的玩法推荐、万趣用车、团队共创和极境视界由对应领域接口维护；旧需求页主视觉、特色卡片、需求表单、独立体验推荐和旧用车服务配置不再提供接口。

## 用车需求线索

`GET /api/admin/leads?leadType=vehicle` 只返回用车线索，可叠加 `status`、`keyword`、`offset` 和 `take` 筛选。返回 `data: { items, total, offset, take }`，其中 `take` 最大为 `200`。用车线索的 `vehicleDemand` 保留服务类型、日期、地点、人数、行李和车型快照，运营端只负责查看和跟进，不提供车辆库存、排班、计价或订单操作。

`PATCH /api/admin/leads/{id}/status` 使用现有状态：`new`、`assigned`、`contacted`、`planning`、`won`、`invalid`。状态变更写入审计日志并返回更新后的线索对象。

## 登录与工作台

### 登录

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

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

成功响应包裹为 `data: { token, accessToken, expiresIn, user: { id, email, name, role } }`。`accessToken` 是短时访问令牌，`token` 是当前响应中的同值兼容字段；Refresh Token 只通过同域 HttpOnly Cookie 返回，不进入 JSON。

管理员登录、刷新和退出依赖 Redis 会话存储。Refresh Token 轮换后旧令牌立即失效；Redis 不可用时认证接口返回 `503`，不降级为无会话校验。

`/api/admin/system/profile` 返回 `roles`、`permissions`、`menus`、`dataScopes` 和 `deptIds`。菜单只返回启用且可见的目录/页面，按钮菜单保留在页面节点的 `children` 中；前端组件只能从预注册组件白名单加载 `component`。

`GET /api/admin/system/routers` 是管理端对应 RuoYi `getRouters` 的独立接口。接口只要求当前管理员会话，不要求调用者拥有 `system:menu:read`，否则普通运营角色会因无法读取菜单管理页面而无法加载自己的导航。响应为：

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "menu-id",
      "name": "系统管理",
      "type": "directory",
      "path": "/system",
      "component": null,
      "permission": null,
      "icon": "Setting",
      "sortOrder": 60,
      "children": [
        {
          "id": "page-id",
          "name": "用户管理",
          "type": "page",
          "path": "/system/users",
          "component": "SystemUsers",
          "permission": "system:user:read",
          "children": []
        }
      ]
    }
  ]
}
```

后端先按当前管理员角色计算可见菜单，再过滤停用菜单与不可见目录/页面；按钮菜单作为页面节点的 `children` 返回，但不会被前端注册为页面路由。`profile.menus` 继续保留以兼容旧管理端，`routers` 才是 `WonderQ-Admin-UI-Vue` 动态导航和动态路由注册的权威来源。前端只能将 `component` 映射到预注册组件白名单，未知组件不得执行或加载。

角色数据范围使用以下五个编码：`all`（全部）、`dept`（当前部门）、`dept_and_children`（当前部门及子部门）、`custom_dept`（自定义部门）、`self`（本人）。运营资源通过 `deptId` 和 `createdById` 归属字段执行查询过滤。

登录按 IP 与账号组合执行 Redis 限流，默认 60 秒最多 5 次；权限菜单缓存默认 300 秒。Redis 故障不能放行权限检查，缓存不可用时只能重新读取数据库，认证会话和限流不可用时返回 `503`。

## 兼容边界

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