WonderQ-Project/docs/module-config-api.md

页面模块配置 Admin API 契约

本文档定义 WonderQ-Admin 后端需要为 WonderQ-Admin-UI 实现的页面模块配置 CRUD 接口。接口用于维护小程序/H5 前台页面模块中的配置数据，例如首页轮播、目的地宫格、贵州地图、主题卡片、特价优惠、精选线路分组、特色酒店、万趣用车和更多服务。

适用模块

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

module	名称	用途
heroSlides	顶部轮播	首页首屏轮播图、标题短文案、展示排序和启用状态
destinations	目的地	首页/目的地页展示、搜索入口和热门标记
destinationHero	目的地页顶部主视觉	目的地页顶部大图、标题、小标题、启用状态和排序
destinationRegions	目的地页热门区域	目的地页“热门区域”快捷入口、搜索关键词和景点摘要
demandHero	需求页顶部定制说明	需求页顶部标题、副标题、说明文案和步骤
demandFeatureCards	需求页服务说明卡	需求页服务说明卡标题、描述、启用状态和排序
demandForm	需求页表单配置	固定表单字段标签、占位符、提交按钮和快捷选项
demandRecommendations	需求页热门推荐线路	需求页推荐标题、副文案和商品 ID 关联顺序
map	贵州地图	首页「探索贵州」区域内的地图图片素材
themes	主题甄选	首页主题卡片和跳转
campaigns	特价优惠	首页特价优惠活动元信息
routeSections	精选线路子分组	首页“精选线路”按运营任务新增分组，维护标题、副文案、启用状态和关联商品
hotelGroups	特色酒店	首页“特色酒店”卡片，维护标题、描述、价格、标签、封面图、启用状态和排序
vehicleOptions	万趣用车	首页“万趣用车”卡片，维护标题、描述、封面图、启用状态和排序
ctaBanners	更多服务	权益、管家、目的地和需求入口等更多服务卡片

商品本体、活动商品池和线索跟进继续走独立业务接口，不混入本契约。routeSections 只维护精选线路子分组和商品 ID 关联，不重复编辑商品详情；hotelGroups 和 vehicleOptions 只维护首页卡片内容，不绑定商品本体。

通用约定

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

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

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

后端实现重点

WonderQ-Admin 后端实现页面模块配置接口时，需要把 map 和 campaigns 作为正式模块接入，而不是只在前端展示：

• 模块白名单必须包含 heroSlides、destinations、destinationHero、destinationRegions、demandHero、demandFeatureCards、demandForm、demandRecommendations、map、themes、campaigns、routeSections、hotelGroups、vehicleOptions、ctaBanners。
• 权限校验、模块路由、服务层分发和数据模型映射都必须识别 map 和 campaigns，否则前端会收到 MODULE_CONFIG_FORBIDDEN 并以 toast 展示失败原因。
• GET /api/admin/site-config 即使没有地图数据，也必须返回 map: []，不要省略 map 字段。
• GET /api/admin/site-config 即使没有特价优惠数据，也必须返回 campaigns: []，不要省略 campaigns 字段。
• GET /api/admin/site-config 必须返回 destinationHero、destinationRegions、demandHero、demandFeatureCards、demandForm、demandRecommendations、routeSections，包含未启用配置。hotelGroups、vehicleOptions 也必须稳定返回数组，无数据时返回 []。
• map 只维护一张图片，只需要支持查询、创建、更新、删除，不需要排序接口。
• campaigns 维护活动元信息，只需要支持查询、创建、更新、删除，不需要排序接口。
• destinationHero、destinationRegions、demandHero、demandFeatureCards、demandRecommendations、routeSections 允许按运营任务新增多项；已创建配置支持更新字段、删除和分组顺序。demandForm 是单例配置，只支持一条表单配置，不提供排序。hotelGroups、vehicleOptions 支持新增、更新、删除和排序。
• 同一商品不能同时出现在多个 routeSections 子分组；更新 productIds 时后端需要校验互斥。
• 图片上传仍走 POST /api/admin/media-assets/upload，模块保存接口只接收上传结果里的 OSS url 字段并写入 image。

类型定义

type SiteModule = "heroSlides" | "destinations" | "destinationHero" | "destinationRegions" | "demandHero" | "demandFeatureCards" | "demandForm" | "demandRecommendations" | "map" | "themes" | "campaigns" | "routeSections" | "hotelGroups" | "vehicleOptions" | "ctaBanners";

type SiteItemPatch = {
  title?: string;
  subtitle?: string | null;
  kicker?: string | null;
  name?: string;
  slug?: string;
  region?: string | null;
  label?: string;
  keyword?: string | null;
  spots?: string | null;
  alt?: string;
  image?: string | null;
  description?: string | null;
  coverImage?: string | null;
  steps?: string[];
  destinationLabel?: string;
  destinationPlaceholder?: string | null;
  phoneLabel?: string;
  phonePlaceholder?: string | null;
  noteLabel?: string;
  notePlaceholder?: string | null;
  submitLabel?: string;
  chips?: string[];
  targetType?: string | null;
  targetValue?: string | null;
  isHot?: boolean;
  isActive?: boolean;
  sortOrder?: number;
  productIds?: string[];
  status?: "draft" | "published";
  startsAt?: string | null;
  endsAt?: string | null;
};

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>;

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

type DestinationRegion = {
  id: string;
  label: string;
  keyword: string | null;
  spots: string | null;
  isActive: boolean;
  sortOrder: number;
  createdAt?: string;
  updatedAt?: string;
};

type MapImage = {
  id: string;
  image: string | null;
  isActive: boolean;
  createdAt?: string;
  updatedAt?: string;
};

type MapImageCreateInput = {
  image: string;
  isActive?: boolean;
};

type MapImageUpdateInput = Partial<MapImageCreateInput>;

type Campaign = {
  id: string;
  slug: string;
  title: string;
  description: string | null;
  coverImage: string | null;
  priceAmount: number | null;
  priceUnit: string | null;
  tags: string[];
  status: "draft" | "published";
  startsAt: string | null;
  endsAt: string | null;
  createdAt?: string;
  updatedAt?: string;
};

type CampaignCreateInput = {
  title: string;
  slug: string;
  description?: string | null;
  coverImage?: string | null;
  priceAmount?: number | null;
  priceUnit?: string | null;
  tags?: string[];
  status?: "draft" | "published";
  startsAt?: string | null;
  endsAt?: string | null;
};

type CampaignUpdateInput = Partial<CampaignCreateInput>;

type RouteSection = {
  id: string;
  title: string;
  subtitle: string | null;
  productIds: string[];
  isActive: boolean;
  sortOrder: number;
  createdAt?: string;
  updatedAt?: string;
};

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

type HotelGroupItem = SiteCardItem & {
  coverImage?: string | null;
  priceAmount?: number | null;
  priceUnit?: string | null;
  tags?: string[];
  status?: "draft" | "published";
};

type CtaBanner = {
  id: string;
  alt: string;
  image: string;
  targetType: string | null;
  targetValue: string | null;
  isActive: boolean;
  sortOrder: number;
  createdAt?: string;
  updatedAt?: string;
};

各模块字段要求：

module	创建必填	可选字段
heroSlides	title	kicker、image、isActive、sortOrder
destinations	name	slug、region、image、isHot、isActive、sortOrder
destinationHero	title	kicker、image、isActive、sortOrder
destinationRegions	label	keyword、spots、isActive、sortOrder
demandHero	title	kicker、description、steps、isActive、sortOrder
demandFeatureCards	title	description、isActive、sortOrder
demandForm	submitLabel	destinationLabel、destinationPlaceholder、phoneLabel、phonePlaceholder、noteLabel、notePlaceholder、chips、isActive
demandRecommendations	title	subtitle、productIds、isActive、sortOrder
map	image	isActive
themes	label	image、targetType、targetValue、isActive、sortOrder
campaigns	title、slug	description、coverImage、priceAmount、priceUnit、tags、status、startsAt、endsAt
routeSections	title	subtitle、productIds、isActive、sortOrder
hotelGroups	title	description、image、coverImage、priceAmount、priceUnit、tags、status、isActive、sortOrder
vehicleOptions	title	description、image、isActive、sortOrder
ctaBanners	alt（服务标题）	image、targetType、targetValue、isActive、sortOrder

后端可以在创建时补全 id、默认 isActive=true、默认 sortOrder=当前模块最后一位。 campaigns 创建时默认 status="draft"，不会进入 Public site-config.campaigns；只有 status="published" 的活动会进入 H5 Public API。 Admin UI 面向运营只展示活动标题、活动描述、封面图和前台启用状态；slug 是接口必填技术标识，前端可在新建时自动生成，编辑时复用原值。

顶部轮播 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
    }
  ]
}

目的地页主视觉 destinationHero 专用契约

destinationHero 对应 MiniAPP 目的地页顶部大图和标题文案。后台允许维护多条主视觉配置；Public API 只输出启用项，MiniAPP 按 sortOrder 升序取第一条渲染顶部主视觉，无有效配置时回退本地静态主视觉。

字段语义：

字段	类型	创建	更新	说明
id	string	后端生成	不允许修改	主视觉配置项唯一 ID
title	string	必填	可选	主视觉标题，不能为空
kicker	string | null	可选	可选	标题上方小文案
image	string | null	可选	可选	主视觉图片 URL；为空时客户端使用兜底图
sortOrder	number	可选	可选	展示顺序，未传时追加到末尾
isActive	boolean	可选	可选	是否前台启用，创建默认 true
createdAt	string	后端生成	后端维护	ISO 时间字符串，可选返回
updatedAt	string	后端生成	后端维护	ISO 时间字符串，可选返回

接口：

POST /api/admin/site-config/destinationHero
PATCH /api/admin/site-config/destinationHero/:id
DELETE /api/admin/site-config/destinationHero/:id
PATCH /api/admin/site-config/destinationHero/reorder

创建请求示例：

{
  "title": "山水、苗寨、古城与野咖同程安排",
  "kicker": "贵州小包团目的地",
  "image": "/assets/guizhou/huangguoshu-waterfall.jpg",
  "isActive": true,
  "sortOrder": 0
}

目的地页热门区域 destinationRegions 专用契约

destinationRegions 对应 MiniAPP 目的地页“热门区域”快捷入口。该模块只维护区域卡片文本和搜索关键词，不绑定商品本体；点击后的商品命中仍由 /api/public/products?keyword=<keyword> 及商品目的地、标题、标签、别名匹配完成。

字段语义：

字段	类型	创建	更新	说明
id	string	后端生成	不允许修改	热门区域配置项唯一 ID
label	string	必填	可选	区域卡片名称，不能为空
keyword	string | null	可选	可选	点击搜索关键词；为空时 MiniAPP 使用 label
spots	string | null	可选	可选	卡片下方景点摘要
sortOrder	number	可选	可选	展示顺序，未传时追加到末尾
isActive	boolean	可选	可选	是否前台启用，创建默认 true
createdAt	string	后端生成	后端维护	ISO 时间字符串，可选返回
updatedAt	string	后端生成	后端维护	ISO 时间字符串，可选返回

接口：

POST /api/admin/site-config/destinationRegions
PATCH /api/admin/site-config/destinationRegions/:id
DELETE /api/admin/site-config/destinationRegions/:id
PATCH /api/admin/site-config/destinationRegions/reorder

创建请求示例：

{
  "label": "黔南",
  "keyword": "黔南荔波",
  "spots": "荔波小七孔、茂兰",
  "isActive": true,
  "sortOrder": 2
}

目的地 destinations 专用契约

目的地模块对应 MiniAPP 首页和目的地页的目的地卡片，也为商品维护页提供目的地下拉。目的地只维护字典数据和前台入口，不直接维护商品详情；商品是否进入目的地搜索结果由商品本体的 destinationId 和 status 决定。

字段语义：

字段	类型	创建	更新	说明
id	string	后端生成	不允许修改	目的地配置项唯一 id
name	string	必填	可选	目的地名称，保存时去掉首尾空格，不能为空；Public API 仍返回 name，MiniAPP 会归一化为页面内部 label
slug	string	可选	可选	目的地技术标识；创建时为空由后端按 name 自动生成，更新时传入空字符串应返回 422
region	string | null	可选	可选	所属区域，可为空
image	string | null	可选	可选	目的地卡片背景图 URL
isHot	boolean	可选	可选	是否热门；首页和目的地页可据此展示热门优先内容
isActive	boolean	可选	可选	前台启用状态；Public API 只返回启用目的地
sortOrder	number	可选	可选	前台展示顺序；Public API 按该字段升序输出
aliases	Array<{ id: string; alias: string }>	后端返回	当前接口不维护	搜索别名；当前 Admin UI 只展示，别名维护不在本次目的地页 CRUD 范围
_count.products	{ products: number }	后端返回	不允许修改	Admin GET /api/admin/destinations 可返回，用于判断目的地是否仍被商品引用

目的地 CRUD

新增目的地：

POST /api/admin/site-config/destinations

请求体：

{
  "name": "新目的地",
  "slug": "",
  "region": "黔南",
  "image": "/assets/guizhou/libo-xiaoqikong.jpg",
  "isHot": true,
  "isActive": true,
  "sortOrder": 0
}

响应状态码 201，响应体返回创建后的完整 Destination。创建时 slug 可以为空字符串，后端会按 name 自动生成；isHot 未传默认 false，isActive 未传默认 true，sortOrder 未传时追加到当前模块末尾。

更新目的地：

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

请求体为目的地字段的部分对象，只修改请求体中出现的字段。name 和 slug 如果出现在请求体中，保存后不能为空。

删除目的地：

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

响应状态码 200：

{
  "id": "dest_001"
}

删除只删除省内目的地配置项，不删除商品本体、图片素材或线索记录。若仍有商品引用该目的地，后端返回 409 MODULE_CONFIG_CONFLICT；运营应先在商品维护页将相关商品归档或解除 destinationId 关联。

调整目的地顺序：

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

请求体：

{
  "itemIds": ["dest_002", "dest_001", "dest_003"]
}

约束：

• itemIds 必须刚好包含当前全部目的地 id。
• 不允许重复 id，不允许混入其他模块 id。
• 后端按数组顺序写入 sortOrder，从 0 开始。
• Public GET /api/public/site-config 只输出启用目的地，并继续按 sortOrder 升序返回。

贵州地图 map 专用契约

贵州地图模块对应当前管理端抽屉中的 2 个区域：

• 地图图片：image
• 显示状态：isActive

字段语义：

字段	类型	创建	更新	说明
id	string	后端生成	不允许修改	地图图片配置项唯一 id
image	string | null	必填	可选	单张地图图片地址或素材 URL，创建时不能为空
isActive	boolean	可选	可选	前台是否展示；未传时默认 true
createdAt	string	后端生成	后端维护	ISO 时间字符串，可选返回
updatedAt	string	后端生成	后端维护	ISO 时间字符串，可选返回

贵州地图只维护一张图片，不提供排序能力。map 的查询响应返回数组是为了复用现有站点配置结构，但最多返回 1 项。创建第二张地图图片时，后端应返回 409 或改为更新当前唯一图片，具体以后端实现保持一致。贵州地图不定义标题、文案和跳转能力。map 的创建、更新、查询响应中不要返回 title、name、label、alt、targetType、targetValue、sortOrder。

后端推荐策略：POST /api/admin/site-config/map 在不存在地图图片时创建；已存在时返回 409 MAP_IMAGE_ALREADY_EXISTS，或直接更新当前唯一图片。无论选择哪种策略，都要保证 PATCH /api/admin/site-config/map/:id 可以按 id 更新当前图片。

贵州地图 CRUD

新增贵州地图图片：

POST /api/admin/site-config/map

请求体：

{
  "image": "https://bucket.oss-cn-example.aliyuncs.com/admin/map/2026/07/01/guizhou-map.webp",
  "isActive": false
}

响应状态码 201：

{
  "id": "map_001",
  "image": "https://bucket.oss-cn-example.aliyuncs.com/admin/map/2026/07/01/guizhou-map.webp",
  "isActive": false,
  "createdAt": "2026-07-01T08:00:00.000Z",
  "updatedAt": "2026-07-01T08:00:00.000Z"
}

更新贵州地图图片：

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

请求体为 MapImageUpdateInput，只提交需要修改的字段。

删除贵州地图图片：

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

特价优惠 campaigns 专用契约

特价优惠模块对应 H5 Public API 的 site-config.campaigns，只维护活动元信息，不维护活动商品关联列表。

字段语义：

字段	类型	创建	更新	说明
id	string	后端生成	不允许修改	活动唯一 id
slug	string	必填	可选	活动标识，需要全局唯一
title	string	必填	可选	活动标题，后台列表主标题
description	string | null	可选	可选	活动描述，后台列表副文案
coverImage	string | null	可选	可选	活动封面图 OSS URL
priceAmount	number | null	可选	可选	参考起价，单位按 priceUnit 展示
priceUnit	string | null	可选	可选	价格单位文案，默认 起/人
tags	string[]	可选	可选	活动卡片标签，最多 3 个
status	"draft" | "published"	可选	可选	新建默认 draft；Public API 只返回 published
startsAt	string | null	可选	可选	活动开始时间
endsAt	string | null	可选	可选	活动结束时间
createdAt	string	后端生成	后端维护	ISO 时间字符串，可选返回
updatedAt	string	后端生成	后端维护	ISO 时间字符串，可选返回

特价优惠 CRUD

新增特价优惠：

POST /api/admin/site-config/campaigns

请求体：

{
  "slug": "classic-deal",
  "title": "经典打卡特惠",
  "description": "经典首游活动",
  "coverImage": "https://bucket.oss-cn-example.aliyuncs.com/admin/campaigns/2026/07/02/classic.webp",
  "priceAmount": 162500,
  "priceUnit": "起/人",
  "tags": ["臻藏旅位", "赛事庆典"],
  "status": "draft",
  "startsAt": null,
  "endsAt": null
}

更新特价优惠：

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

删除特价优惠：

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

特价优惠不定义 sortOrder、isActive、targetType 和 targetValue；兼容期如果请求体携带这些字段，后端可以忽略，但不要写入 Campaign 业务数据。 tags 保存前需要 trim 并过滤空字符串；有效标签超过 3 个时返回 422 MODULE_CONFIG_VALIDATION_ERROR，details 为 { "field": "tags", "max": 3 }。

精选线路子分组 routeSections 专用契约

routeSections 对应首页“精选线路”的运营分组。运营可按任务新增分组，并维护分组标题、副文案、启用状态、分组顺序、关联线路商品和商品顺序。

字段语义：

字段	类型	更新	说明
id	string	不允许修改	系统生成分组 ID
title	string	可选	分组标题，不能为空
subtitle	string | null	可选	分组副文案
productIds	string[]	可选	关联商品 ID，按数组顺序展示
isActive	boolean	可选	用户侧是否展示该分组
sortOrder	number	可选	分组展示顺序

更新分组：

POST /api/admin/site-config/routeSections

请求体示例：

{
  "title": "经典人文打卡线路",
  "subtitle": "黄果树、荔波小七孔、千户苗寨、镇远古城、梵净山一次串联"
}

响应状态码 201，返回创建后的子分组。id 由后端生成；精选线路分组按运营任务动态新增，不再限制为固定三组，也不再使用 routes / routes-outdoor / routes-mix 作为固定槽位。

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

请求体示例：

{
  "title": "经典人文打卡线路",
  "subtitle": "黄果树、荔波小七孔、千户苗寨、镇远古城、梵净山一次串联",
  "isActive": true,
  "productIds": ["product-uuid-1", "product-uuid-2"]
}

调整分组顺序：

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

约束：

• productIds 中的商品必须存在。
• 同一商品不能出现在其他精选线路子分组；冲突时返回 409 ROUTE_SECTION_PRODUCT_CONFLICT。
• DELETE /api/admin/site-config/routeSections/:id 删除分组配置并返回被删除 ID；只移除首页分组，不删除关联商品本体。

需求页配置专用契约

需求页在 Admin UI “需求线索”结构页下维护，模块名称必须与前台区块一一对应：

module	前台区块	CRUD 说明
demandHero	顶部定制说明	支持新增、编辑、删除、排序、启停；MiniAPP 取启用列表第一项
demandFeatureCards	服务说明卡	支持新增、编辑、删除、排序、启停
demandForm	需求表单配置	单例数组；支持新增第一条、编辑、删除、启停；不支持排序
demandRecommendations	热门推荐线路	支持新增、编辑、删除、排序、启停；productIds 只维护商品关联顺序

字段语义：

module	字段	说明
demandHero	title、kicker、description、steps	顶部主标题、上方短文案、说明文字和步骤文案；steps/chips 保存前 trim 并过滤空字符串
demandFeatureCards	title、description	服务说明卡标题和说明
demandForm	destinationLabel、destinationPlaceholder、phoneLabel、phonePlaceholder、noteLabel、notePlaceholder、submitLabel、chips	固定表单文案配置，不改变 Public lead 必填字段
demandRecommendations	title、subtitle、productIds	推荐分组标题、副文案和商品 ID 顺序

约束：

• demandForm 重复创建时返回 409 MODULE_CONFIG_SINGLETON_EXISTS。
• demandRecommendations.productIds 中的商品必须存在，重复商品返回 422 DEMAND_RECOMMENDATION_PRODUCT_DUPLICATE。
• demandRecommendations 不限制商品是否已属于首页 routeSections，也不删除商品本体。
• Public GET /api/public/site-config 只返回启用的需求页配置；demandRecommendations.productIds 只包含 status="published" 的商品 ID。
• MiniAPP 表单提交仍调用 POST /api/public/leads，sourcePage="demand_page"，不新增必填字段。

特色酒店 hotelGroups 专用契约

hotelGroups 对应首页“特色酒店”卡片。它复用“特价优惠”的数据配置体验，支持新增、编辑、删除、排序，并维护标题、描述、价格、标签、封面图、启用状态；不维护商品详情和商品关联。

字段语义：

字段	类型	创建	更新	说明
id	string	后端生成	不允许修改	酒店卡片配置项 ID
title	string	必填	可选	酒店卡片标题，保存时去掉首尾空格，不能为空
description	string | null	可选	可选	酒店卡片描述，空字符串可归一为 null
image	string | null	可选	可选	兼容旧字段；后端应与 coverImage 保持一致
coverImage	string | null	可选	可选	酒店封面图主字段，管理端上传组件写入该字段
priceAmount	number | null	可选	可选	价格数值
priceUnit	string | null	可选	可选	价格单位文案，默认建议 起/晚
tags	string[]	可选	可选	标签数组，最多 3 个，保存时去掉空标签
status	"draft" | "published"	可选	可选	发布状态；管理端“前台启用”开关同步维护该字段
isActive	boolean	可选	可选	前台启用状态；Public API 只返回 status="published" 且 isActive=true 的项
sortOrder	number	可选	可选	首页展示顺序

POST /api/admin/site-config/hotelGroups
PATCH /api/admin/site-config/hotelGroups/:id
DELETE /api/admin/site-config/hotelGroups/:id
PATCH /api/admin/site-config/hotelGroups/reorder

删除只删除首页酒店卡片配置，不删除任何商品、目的地或素材库资源。Public API 只返回 published 且启用项，并按 sortOrder 升序输出；无启用项时 MiniAPP 使用本地 src/content.ts 兜底内容。

万趣用车 vehicleOptions 专用契约

vehicleOptions 对应首页“万趣用车”卡片，仍是普通首页内容卡片，不维护商品详情和商品关联。

字段语义：

字段	类型	创建	更新	说明
id	string	后端生成	不允许修改	用车卡片配置项 ID
title	string	必填	可选	卡片标题，保存时去掉首尾空格，不能为空
description	string | null	可选	可选	卡片描述，空字符串可归一为 null
image	string | null	可选	可选	卡片封面图 URL
isActive	boolean	可选	可选	前台启用状态
sortOrder	number	可选	可选	首页展示顺序
createdAt	string	后端生成	后端维护	ISO 时间字符串，可选返回
updatedAt	string	后端生成	后端维护	ISO 时间字符串，可选返回

POST /api/admin/site-config/vehicleOptions
PATCH /api/admin/site-config/vehicleOptions/:id
DELETE /api/admin/site-config/vehicleOptions/:id
PATCH /api/admin/site-config/vehicleOptions/reorder

删除只删除首页用车卡片配置，不删除任何商品、目的地或素材库资源。Public API 只返回启用项，并按 sortOrder 升序输出；无启用项时 MiniAPP 使用本地 src/content.ts 兜底内容。

更多服务 ctaBanners 专用契约

ctaBanners 对应首页“更多服务”模块，用于维护权益、管家、目的地和需求入口等服务卡片。管理端复用顶部轮播的列表式操作：新增卡片、编辑标题和背景图、删除卡片、上移/下移排序，以及控制前台启用状态。

字段语义：

字段	类型	创建	更新	说明
id	string	后端生成	不允许修改	服务卡片唯一 id
alt	string	必填	可选	服务标题，展示在“更多服务”卡片上，提交时 trim 后不能为空
image	string | null	可选	可选	服务卡片背景图 OSS URL；上传仍走媒体接口
targetType	string | null	可选	可选	点击目标类型，例如权益、管家、目的地或需求入口
targetValue	string | null	可选	可选	点击目标值；无额外参数时可为空
isActive	boolean	可选	可选	用户侧是否展示；未传默认 true
sortOrder	number	可选	可选	展示顺序；未传时追加到模块末尾

复用通用接口：

POST /api/admin/site-config/ctaBanners
PATCH /api/admin/site-config/ctaBanners/:id
DELETE /api/admin/site-config/ctaBanners/:id
PATCH /api/admin/site-config/ctaBanners/reorder

删除只删除首页“更多服务”卡片配置，不删除任何素材库资源。Public API 只返回启用项，并按 sortOrder 升序输出；无启用项时 MiniAPP 使用本地 src/content.ts 兜底内容。

接口列表

以下路径由页面模块复用；heroSlides、destinationHero、destinationRegions、demandHero、demandFeatureCards、demandForm、demandRecommendations、map、campaigns、routeSections、hotelGroups、vehicleOptions、ctaBanners 的请求体和响应体以各自专用契约为准。

获取完整站点配置

GET /api/admin/site-config

响应：

type SiteConfig = {
  heroSlides: HeroSlide[];
  destinations: Destination[];
  destinationHero: DestinationHero[];
  destinationRegions: DestinationRegion[];
  demandHero: DemandHero[];
  demandFeatureCards: DemandFeatureCard[];
  demandForm: DemandForm[];
  demandRecommendations: DemandRecommendation[];
  map: MapImage[];
  themes: ThemeCard[];
  campaigns: Campaign[];
  routeSections: RouteSection[];
  hotelGroups: HotelGroupItem[];
  vehicleOptions: SiteCardItem[];
  ctaBanners: CtaBanner[];
};

destinationHero、destinationRegions、demandHero、demandFeatureCards、demandForm、demandRecommendations、map 字段必须稳定返回数组；无数据时返回空数组 []。 campaigns 字段必须稳定返回数组；无数据时返回空数组 []。 routeSections 字段必须稳定返回数组；无数据时返回 []，由管理端通过“新增”逐个创建子分组。hotelGroups、vehicleOptions 字段也必须稳定返回数组；无数据时返回 []。

新增模块配置项

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 开始。

map、campaigns 和 demandForm 模块不提供排序能力。若收到对应 reorder 请求，后端应返回 400 或 405，不要创建任何排序数据。destinations、destinationHero、destinationRegions、demandHero、demandFeatureCards、demandRecommendations、routeSections、hotelGroups、vehicleOptions 支持排序，但 itemIds 必须刚好包含当前已保存的同模块配置项 ID。

响应状态码 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 或 coverImage。

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 上传。