WonderQ Admin API 接口需求

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

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

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

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

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

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

通用约定

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/POST/PATCH`	`/api/admin/system/users`	管理后台用户
`GET/POST/PATCH`	`/api/admin/system/roles`	管理角色和数据范围
`GET/POST/PATCH`	`/api/admin/system/menus`	管理目录、页面和按钮
`GET/POST/PATCH`	`/api/admin/system/depts`	管理部门
`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 只允许以下值：

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

模块职责：

模块	主要字段	约束
`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`	可新增、编辑、删除、排序
`vehicleService`	`introTitle`、`intro`、`serviceSections`、`advantages`、`processSteps`、`isActive`	单例，维护用车需求页说明

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

vehicleService 为单例配置，serviceSections 和 processSteps 的每项为 { title, description }，advantages 为字符串数组。Admin UI 以每行一项编辑并在保存前去除空行。

用车需求线索

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

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

登录与工作台

角色数据范围使用以下五个编码：all（全部）、dept（当前部门）、dept_and_children（当前部门及子部门）、custom_dept（自定义部门）、self（本人）。运营资源通过 deptId 和 createdById 归属字段执行查询过滤；资源归属迁移完成前不得在生产环境切换非管理员角色。

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

兼容边界

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

7.6 KiB Raw Blame History Unescape Escape