WonderQ-Admin-UI/docs/admin-module-config-api.md

页面模块配置 Admin API 契约

本文档定义 WonderQ-Admin 后端需要为 WonderQ-Admin-UI 实现的页面模块配置 CRUD 接口。接口用于维护小程序/H5 前台页面模块中的配置数据，例如首页轮播、目的地宫格、主题卡片和底部运营入口。

适用模块

当前一期只纳入结构化页面配置模块：

module	名称	用途
heroSlides	顶部轮播	首页首屏轮播图、标题短文案、展示排序和启用状态
destinations	目的地	首页/目的地页展示、搜索入口和热门标记
themes	主题甄选	首页主题卡片和跳转
ctaBanners	底部运营入口	权益卡、管家入口、需求入口等 CTA

商品池、活动商品池和线索跟进继续走独立业务接口，不混入本契约。

通用约定

• 所有接口前缀为 /api/admin。
• 所有接口需要校验 Authorization: Bearer <token>。
• 请求和响应均为 application/json。
• 字段使用 camelCase。
• PATCH 为部分更新，只修改请求体中出现的字段。
• 删除接口返回 JSON，不能返回空 body，因为当前前端请求封装会读取 JSON。

错误响应保持当前前端兼容格式：

{
  "message": "模块不存在或无权限操作",
  "code": "MODULE_CONFIG_FORBIDDEN",
  "details": {}
}

类型定义

type SiteModule = "heroSlides" | "destinations" | "themes" | "ctaBanners";

type SiteItemPatch = {
  title?: string;
  kicker?: string;
  name?: string;
  slug?: string;
  region?: string | null;
  label?: string;
  alt?: string;
  image?: string | null;
  targetType?: string | null;
  targetValue?: string | null;
  isHot?: boolean;
  isActive?: boolean;
  sortOrder?: number;
};

type HeroSlide = {
  id: string;
  title: string;
  kicker: string | null;
  image: string | null;
  isActive: boolean;
  sortOrder: number;
  createdAt?: string;
  updatedAt?: string;
};

type HeroSlideCreateInput = {
  title: string;
  kicker?: string | null;
  image?: string | null;
  isActive?: boolean;
  sortOrder?: number;
};

type HeroSlideUpdateInput = Partial<HeroSlideCreateInput>;

各模块字段要求：

module	创建必填	可选字段
heroSlides	title	kicker、image、isActive、sortOrder
destinations	name	slug、region、image、isHot、isActive、sortOrder
themes	label	image、targetType、targetValue、isActive、sortOrder
ctaBanners	alt	image、targetType、targetValue、isActive、sortOrder

后端可以在创建时补全 id、默认 isActive=true、默认 sortOrder=当前模块最后一位。

顶部轮播 heroSlides 专用契约

顶部轮播对应当前管理端抽屉中的 3 个区域：

• 展示内容：title、kicker
• 资源图片：image
• 排序与状态：sortOrder、isActive

字段语义：

字段	类型	创建	更新	说明
id	string	后端生成	不允许修改	顶部轮播配置项唯一 id
title	string	必填	可选	前台轮播主标题，提交时需要去除首尾空格，不能为空
kicker	string | null	可选	可选	副标题/短文案，空字符串可归一化为 null 或 ""，前后端需保持响应一致
image	string | null	可选	可选	单张轮播图地址或素材 URL；未上传时为 null
sortOrder	number	可选	可选	展示顺序，整数；未传时追加到当前模块末尾
isActive	boolean	可选	可选	前台是否展示；未传时默认 true
createdAt	string	后端生成	后端维护	ISO 时间字符串，可选返回
updatedAt	string	后端生成	后端维护	ISO 时间字符串，可选返回

顶部轮播不定义跳转能力。heroSlides 的创建、更新、查询响应中不要返回 targetType、targetValue；兼容期如果请求体携带这两个字段，后端可以忽略，但不要写入顶部轮播业务数据。

顶部轮播 CRUD

新增顶部轮播：

POST /api/admin/site-config/heroSlides

请求体：

{
  "title": "新轮播",
  "kicker": "贵州小包团首选",
  "image": "/assets/source/hero.jpg",
  "isActive": true,
  "sortOrder": 0
}

响应状态码 201：

{
  "id": "slide_001",
  "title": "新轮播",
  "kicker": "贵州小包团首选",
  "image": "/assets/source/hero.jpg",
  "isActive": true,
  "sortOrder": 0,
  "createdAt": "2026-07-01T08:00:00.000Z",
  "updatedAt": "2026-07-01T08:00:00.000Z"
}

更新顶部轮播：

PATCH /api/admin/site-config/heroSlides/:id

请求体为 HeroSlideUpdateInput，只提交需要修改的字段：

{
  "title": "夏日贵州小包团",
  "image": null,
  "isActive": false
}

响应状态码 200，响应体返回更新后的完整 HeroSlide。

删除顶部轮播：

DELETE /api/admin/site-config/heroSlides/:id

响应状态码 200：

{
  "id": "slide_001"
}

删除后后端需要重新整理 heroSlides 内剩余项的 sortOrder。

调整顶部轮播顺序：

PATCH /api/admin/site-config/heroSlides/reorder

请求体：

{
  "itemIds": ["slide_002", "slide_001", "slide_003"]
}

响应状态码 200：

{
  "items": [
    {
      "id": "slide_002",
      "title": "第二张",
      "kicker": null,
      "image": null,
      "sortOrder": 0,
      "isActive": true
    },
    {
      "id": "slide_001",
      "title": "第一张",
      "kicker": null,
      "image": null,
      "sortOrder": 1,
      "isActive": true
    }
  ]
}

接口列表

以下路径由四类页面模块复用；heroSlides 的请求体和响应体以“顶部轮播专用契约”为准。

获取完整站点配置

GET /api/admin/site-config

响应：

type SiteConfig = {
  heroSlides: HeroSlide[];
  destinations: Destination[];
  themes: ThemeCard[];
  ctaBanners: CtaBanner[];
};

新增模块配置项

POST /api/admin/site-config/:module

请求体为 SiteItemPatch。响应状态码 201，响应体返回创建后的完整配置项：

{
  "id": "slide_001",
  "title": "新轮播",
  "kicker": "",
  "image": null,
  "isActive": true,
  "sortOrder": 5
}

更新模块配置项

PATCH /api/admin/site-config/:module/:id

请求体为 SiteItemPatch。响应状态码 200，响应体返回更新后的完整配置项。

删除模块配置项

DELETE /api/admin/site-config/:module/:id

响应状态码 200，响应体：

{
  "id": "slide_001"
}

删除后后端需要重新整理同模块内剩余项的 sortOrder。

调整模块配置顺序

PATCH /api/admin/site-config/:module/reorder

请求体：

{
  "itemIds": ["slide_002", "slide_001", "slide_003"]
}

约束：

• itemIds 必须包含该模块当前全部配置项 id。
• 不允许重复 id。
• 不允许混入其他模块 id。
• 后端按数组顺序写入 sortOrder，从 0 开始。

响应状态码 200：

{
  "items": [
    { "id": "slide_002", "title": "第二张", "sortOrder": 0, "isActive": true },
    { "id": "slide_001", "title": "第一张", "sortOrder": 1, "isActive": true }
  ]
}

如果后端使用 Express/Fastify 等路由，/:module/reorder 需要注册在 /:module/:id 之前，避免 reorder 被当成 id。

状态码

状态码	场景
200	查询、更新、删除、排序成功
201	创建成功
400	module 非法、请求体格式错误、排序 id 不完整
401	未登录或 token 无效
403	无权限维护页面配置
404	配置项不存在
409	删除被发布版本、商品或活动引用的配置项时发生冲突
422	字段校验失败，例如必填标题为空
500	服务端异常

前端联调入口

WonderQ-Admin-UI 当前调用函数位于 src/api.ts：

• getSiteConfig()
• createSiteConfigItem(module, input)
• updateSiteConfigItem(module, id, input)
• deleteSiteConfigItem(module, id)
• reorderSiteConfigItems(module, itemIds)

维护地图 UI 位于 src/pages/structure/StructurePage.tsx。

图片素材上传

用于 WonderQ-Admin-UI 在维护页面模块图片时上传本地图片，并把返回的 OSS URL 写入 image 字段。

POST /api/admin/media-assets/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>

表单字段：

字段	类型	必填	说明
file	File	是	图片文件，仅支持 JPG、PNG、WebP、GIF
group	string	否	素材分组，只能包含字母、数字、下划线和中划线；默认 general

限制：

• 单个文件最大 5MB。
• 后端会校验 Content-Type 和文件头魔数，拒绝 SVG、非图片文件和伪装类型。
• 后端将文件上传到 OSS，返回可用于前台展示的 URL，并写入 MediaAsset 素材记录。

响应状态码 201：

{
  "id": "asset_001",
  "url": "https://bucket.oss-cn-example.aliyuncs.com/admin/heroSlides/2026/07/01/example.png",
  "name": "hero.png",
  "mimeType": "image/png",
  "sizeBytes": 102400,
  "group": "heroSlides",
  "createdAt": "2026-07-01T08:00:00",
  "updatedAt": "2026-07-01T08:00:00"
}

常见错误：

状态码	code	场景
400	MEDIA_UPLOAD_INVALID_TYPE	文件不是允许的图片类型
400	MEDIA_UPLOAD_TYPE_MISMATCH	Content-Type 与文件头不一致
400	MEDIA_UPLOAD_INVALID_GROUP	group 格式非法
413	MEDIA_UPLOAD_TOO_LARGE	文件超过 5MB
503	MEDIA_STORAGE_NOT_CONFIGURED	OSS 环境配置不完整
502	MEDIA_STORAGE_UPLOAD_FAILED	OSS 上传失败

前端封装位于 src/api.ts：

uploadMediaAsset(file: File, group?: string): Promise<MediaAsset>

src/components/admin/SingleImageUploader.tsx 已使用该封装；结构维护页会把当前模块 id 作为 group 上传。