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

WonderQ Admin API 接口需求

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

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

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

详情展示内容及路线参考价格字段、图片、排序与商品领域隔离约束见 detail-api.md。该文档是本主契约的详情领域补充，适用端为 WonderQ-Admin 和 WonderQ-Admin-UI-Vue。

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

所有 Admin JSON 接口遵循 三端统一 API 响应契约。

通用约定

• API 前缀：/api/admin。
• 验证码和登录接口不要求 Authorization；其余受保护 Admin API 使用 Authorization: Bearer <admin-jwt> 或认证 Cookie 约定。
• JSON 请求统一使用 camelCase 字段。
• 变更接口写入审计日志后再提交事务。
• 成功业务结果统一放在 data；创建成功为 HTTP/code 201。
• 失败统一返回数字 code、用户可读 msg、data: null，业务错误码放在可选的 errorCode。
• 所有持久化资源的 id 由后端生成稳定 UUID 字符串。Admin UI 必须保存并复用接口返回的 ID，不能根据标题、文案或数组下标自行拼接，也不能假设 ID 是可读 slug。

管理端图标约定

• WonderQ-Admin-UI-Vue 的界面图标统一使用 @element-plus/icons-vue，不新增手写 SVG、Emoji 或其他图标库。
• src/components/layout/LayoutIcon.vue 是后端菜单图标名与 Element Plus 图标组件之间的受控白名单适配器；未知图标必须回退为默认菜单图标，不能动态执行组件路径。
• 为兼容既有菜单数据，Route、Chevron 等 WonderQ 图标名继续保留为前端语义别名，分别映射到 Element Plus 的 Guide、ArrowDown。
• ConciergeDetail.icon 等业务字段属于内容数据，不是管理端界面图标；其值和接口契约不因本规范改变。

接口清单

方法	路径	用途
GET	/api/admin/auth/captcha	获取后台登录图形验证码
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	上传图片

GET /api/admin/media-assets?pageNum=1&pageSize=20 按创建时间倒序分页返回素材，pageSize 最大为 200，响应为 data: { items, total, pageNum, pageSize }。管理端翻页时必须重新请求接口，不在前端截取固定数量的素材。

媒体上传成功响应中的 data.url 是可直接用于图片回显的 HTTP(S) URL。OSS 私有读场景下，该 URL 会包含短时 GET 签名；管理端应直接使用返回值，后续 Admin/Public API 响应会重新生成签名。该接口只写入素材库，不会自动绑定首页配置；绑定首页轮播或用车卡片后，仍需提交对应的站点配置保存接口。

站点模块

SiteModule 只允许以下值：

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 请求：

{
  "email": "admin@example.test",
  "password": "<password>",
  "captchaId": "<captcha-id>",
  "captchaCode": "ABCD",
  "rememberMe": false
}

登录前先调用 GET /api/admin/auth/captcha，接口返回：

{
  "code": 200,
  "msg": "success",
  "data": {
    "captchaEnabled": true,
    "captchaId": "<captcha-id>",
    "image": "data:image/svg+xml;base64,<image-data>",
    "expiresIn": 120
  }
}

验证码只允许消费一次，默认 120 秒过期。验证码答案只以哈希形式保存在 Redis 中；验证码错误、过期或重复使用时登录返回 401，管理端应重新获取验证码。验证码接口和登录接口都依赖 Redis，Redis 不可用时返回 503，不得绕过验证码或会话校验。

rememberMe 默认为 false。勾选后，Refresh Token Cookie 按现有 7 天有效期持久化，刷新令牌轮换时继续保持持久化；未勾选时使用会话级 HttpOnly Cookie，刷新时不延长为持久化 Cookie。该字段只控制登录会话生命周期，不表示服务端或前端保存密码。

成功响应包裹为 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，否则普通运营角色会因无法读取菜单管理页面而无法加载自己的导航。响应为：

{
  "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 映射到预注册组件白名单，未知组件不得执行或加载。

菜单管理新增/编辑

GET /api/admin/system/menus 返回平铺 items 和按 parentId 组装的 tree。每个节点包含 parentId、name、type、path、component、permission、icon、sortOrder、isVisible、isActive 和 children，用于菜单工作台、角色授权树和新增/编辑菜单的父级选择。

POST /api/admin/system/menus 与 PATCH /api/admin/system/menus/{id} 使用以下菜单类型规则：

• directory（目录）：必须有路由地址；不使用组件路径和权限标识。
• page（页面）：必须有路由地址和预注册组件路径；可填写权限标识。
• button（按钮）：必须填写权限标识；路由地址、组件路径和菜单图标必须为空，按钮不能作为其他菜单的父级。

顶级菜单的 parentId 为 null。父级必须存在且为目录或页面；更新菜单时不能选择自身或其子孙节点，服务端也会重复校验该规则。名称和文本字段会去除首尾空格；权限标识重复返回 409，类型字段缺失或不符合规则返回 422。菜单新增、编辑、删除和排序继续写入审计日志并清理权限菜单缓存。

Vue 管理端的父级树只展示目录/页面，编辑当前菜单时排除当前分支；图标选择器使用 @element-plus/icons-vue 的受控白名单，支持名称搜索、清空和未知值回退默认图标，不执行服务端返回的组件或图标路径。

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

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

兼容边界

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