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

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。

通用约定

• API 前缀：/api/admin。
• 除登录接口外均需 Authorization: Bearer <admin-jwt>。
• JSON 请求统一使用 camelCase 字段。
• 变更接口写入审计日志后再提交事务。
• 失败响应统一包含 message、code 和可选 details。

接口清单

方法	路径	用途
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 只允许以下值：

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

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

成功响应包含 token 和 { id, email, name, role }。

兼容边界

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