fbf2c772a8
- 移除所有废弃的旧首页配置模块，包括destinationHero、demand相关、HomeExperience、vehicleService等表结构与代码，新增数据库迁移删除遗留表 - 重构管理端后台布局为标准RuoYi风格，新增Sidebar、Navbar、SettingsDrawer等组件，替换旧的过渡菜单实现 - 调整移动端响应断点为768px，更新布局相关测试用例，新增布局组件测试 - 删除OperationsTools发布/重置页面，移除/tools菜单入口，清理对应的API调用与测试代码 - 重构玩法模块编辑器：替换旧的图片手动输入框为图片上传组件，移除冗余的取消按钮 - 新增线索查询offset参数支持，完善查询参数处理逻辑 - 优化rbac菜单构建逻辑，新增可见性控制参数 - 修正管家编辑器提示文案，优化系统资源编辑器表单初始化逻辑 - 清理小程序端废弃的体验推荐组件与相关测试代码 - 更新文档与种子脚本，匹配新的API契约与使用说明
8.5 KiB
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: Bearer <admin-jwt>。 - JSON 请求统一使用 camelCase 字段。
- 变更接口写入审计日志后再提交事务。
- 成功业务结果统一放在
data；创建成功为 HTTP/code201。 - 失败统一返回数字
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/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 只允许以下值：
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>" }
成功响应包裹为 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。
角色数据范围使用以下五个编码：all（全部）、dept（当前部门）、dept_and_children（当前部门及子部门）、custom_dept（自定义部门）、self（本人）。运营资源通过 deptId 和 createdById 归属字段执行查询过滤。
登录按 IP 与账号组合执行 Redis 限流，默认 60 秒最多 5 次；权限菜单缓存默认 300 秒。Redis 故障不能放行权限检查，缓存不可用时只能重新读取数据库，认证会话和限流不可用时返回 503。
兼容边界
- 当前 Admin UI 不应调用未列出的领域接口。
- 站点配置字段必须与
src/api.ts保持一致。 - 任何字段、模块或路径变化必须同步更新本文档和前端类型。