feat: add support for map module in site configuration and update related APIs
This commit is contained in:
duanshuwen
@@ -1,6 +1,6 @@
|
||||
# 页面模块配置 Admin API 契约
|
||||
|
||||
本文档定义 WonderQ-Admin 后端需要为 WonderQ-Admin-UI 实现的页面模块配置 CRUD 接口。接口用于维护小程序/H5 前台页面模块中的配置数据，例如首页轮播、目的地宫格、主题卡片和底部运营入口。
|
||||
本文档定义 WonderQ-Admin 后端需要为 WonderQ-Admin-UI 实现的页面模块配置 CRUD 接口。接口用于维护小程序/H5 前台页面模块中的配置数据，例如首页轮播、目的地宫格、贵州地图、主题卡片和底部运营入口。
|
||||
|
||||
## 适用模块
|
||||
|
||||
@@ -10,6 +10,7 @@
|
||||
| -------------- | ------------ | ---------------------------------------------- |
|
||||
| `heroSlides` | 顶部轮播 | 首页首屏轮播图、标题短文案、展示排序和启用状态 |
|
||||
| `destinations` | 目的地 | 首页/目的地页展示、搜索入口和热门标记 |
|
||||
| `map` | 贵州地图 | 首页「探索贵州」区域内的地图图片素材 |
|
||||
| `themes` | 主题甄选 | 首页主题卡片和跳转 |
|
||||
| `ctaBanners` | 底部运营入口 | 权益卡、管家入口、需求入口等 CTA |
|
||||
|
||||
@@ -34,10 +35,20 @@
|
||||
}
|
||||
```
|
||||
|
||||
## 后端实现重点
|
||||
|
||||
WonderQ-Admin 后端实现页面模块配置接口时，需要把 `map` 作为正式模块接入，而不是只在前端展示：
|
||||
|
||||
- 模块白名单必须包含 `heroSlides`、`destinations`、`map`、`themes`、`ctaBanners`。
|
||||
- 权限校验、模块路由、服务层分发和数据模型映射都必须识别 `map`，否则前端会收到 `MODULE_CONFIG_FORBIDDEN` 并以 toast 展示失败原因。
|
||||
- `GET /api/admin/site-config` 即使没有地图数据，也必须返回 `map: []`，不要省略 `map` 字段。
|
||||
- `map` 只维护一张图片，只需要支持查询、创建、更新、删除，不需要排序接口。
|
||||
- 图片上传仍走 `POST /api/admin/media-assets/upload`，模块保存接口只接收上传结果里的 OSS `url` 字段并写入 `image`。
|
||||
|
||||
## 类型定义
|
||||
|
||||
```ts
|
||||
type SiteModule = "heroSlides" | "destinations" | "themes" | "ctaBanners";
|
||||
type SiteModule = "heroSlides" | "destinations" | "map" | "themes" | "ctaBanners";
|
||||
|
||||
type SiteItemPatch = {
|
||||
title?: string;
|
||||
@@ -75,6 +86,21 @@ type HeroSlideCreateInput = {
|
||||
};
|
||||
|
||||
type HeroSlideUpdateInput = Partial<HeroSlideCreateInput>;
|
||||
|
||||
type MapImage = {
|
||||
id: string;
|
||||
image: string | null;
|
||||
isActive: boolean;
|
||||
createdAt?: string;
|
||||
updatedAt?: string;
|
||||
};
|
||||
|
||||
type MapImageCreateInput = {
|
||||
image: string;
|
||||
isActive?: boolean;
|
||||
};
|
||||
|
||||
type MapImageUpdateInput = Partial<MapImageCreateInput>;
|
||||
```
|
||||
|
||||
各模块字段要求：
|
||||
@@ -83,6 +109,7 @@ type HeroSlideUpdateInput = Partial<HeroSlideCreateInput>;
|
||||
| -------------- | -------- | ------------------------------------------------------------- |
|
||||
| `heroSlides` | `title` | `kicker`、`image`、`isActive`、`sortOrder` |
|
||||
| `destinations` | `name` | `slug`、`region`、`image`、`isHot`、`isActive`、`sortOrder` |
|
||||
| `map` | `image` | `isActive` |
|
||||
| `themes` | `label` | `image`、`targetType`、`targetValue`、`isActive`、`sortOrder` |
|
||||
| `ctaBanners` | `alt` | `image`、`targetType`、`targetValue`、`isActive`、`sortOrder` |
|
||||
|
||||
@@ -219,9 +246,73 @@ PATCH /api/admin/site-config/heroSlides/reorder
|
||||
}
|
||||
```
|
||||
|
||||
## 贵州地图 `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
|
||||
|
||||
新增贵州地图图片：
|
||||
|
||||
```http
|
||||
POST /api/admin/site-config/map
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"image": "https://bucket.oss-cn-example.aliyuncs.com/admin/map/2026/07/01/guizhou-map.webp",
|
||||
"isActive": false
|
||||
}
|
||||
```
|
||||
|
||||
响应状态码 `201`：
|
||||
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
```
|
||||
|
||||
更新贵州地图图片：
|
||||
|
||||
```http
|
||||
PATCH /api/admin/site-config/map/:id
|
||||
```
|
||||
|
||||
请求体为 `MapImageUpdateInput`，只提交需要修改的字段。
|
||||
|
||||
删除贵州地图图片：
|
||||
|
||||
```http
|
||||
DELETE /api/admin/site-config/map/:id
|
||||
```
|
||||
|
||||
## 接口列表
|
||||
|
||||
以下路径由四类页面模块复用；`heroSlides` 的请求体和响应体以“顶部轮播专用契约”为准。
|
||||
以下路径由五类页面模块复用；`heroSlides`、`map` 的请求体和响应体以各自专用契约为准。
|
||||
|
||||
### 获取完整站点配置
|
||||
|
||||
@@ -235,11 +326,14 @@ GET /api/admin/site-config
|
||||
type SiteConfig = {
|
||||
heroSlides: HeroSlide[];
|
||||
destinations: Destination[];
|
||||
map: MapImage[];
|
||||
themes: ThemeCard[];
|
||||
ctaBanners: CtaBanner[];
|
||||
};
|
||||
```
|
||||
|
||||
`map` 字段必须稳定返回数组；无数据时返回空数组 `[]`。
|
||||
|
||||
### 新增模块配置项
|
||||
|
||||
```http
|
||||
@@ -304,6 +398,8 @@ PATCH /api/admin/site-config/:module/reorder
|
||||
- 不允许混入其他模块 id。
|
||||
- 后端按数组顺序写入 `sortOrder`，从 0 开始。
|
||||
|
||||
`map` 模块不提供排序能力。若收到 `PATCH /api/admin/site-config/map/reorder`，后端应返回 `400` 或 `405`，不要创建任何排序数据。
|
||||
|
||||
响应状态码 `200`：
|
||||
|
||||
```json
|
||||
|
||||
Reference in New Issue
Block a user