feat: add support for map module in site configuration and update related APIs

2026-07-01 21:29:38 +08:00
parent 462498660e
commit 710d020504
8 changed files with 293 additions and 103 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,6 +3,6 @@
 本目录存放后台管理前端相关文档。

 - `admin-backend-plan.md`：从原 MiniAPP 迁出的后台管理规划，保留管理模块、页面能力和与后端 API 的协作边界。
- `admin-module-config-api.md`：页面模块配置 CRUD 接口契约，供 WonderQ-Admin 后端实现首页轮播、目的地、主题卡和 CTA 等模块配置接口。
+- `admin-module-config-api.md`：页面模块配置 CRUD 接口契约，供 WonderQ-Admin 后端实现首页轮播、目的地、贵州地图、主题卡和 CTA 等模块配置接口。

 后端 API 文档位于 `D:\www\znkj\WonderQ-Admin\docs`。
--- a/docs/admin-backend-plan.md
+++ b/docs/admin-backend-plan.md
@@ -162,6 +162,7 @@ flowchart LR
 | `home_sections` | 首页模块配置 |
 | `hero_slides` | 首页轮播 |
 | `destinations` | 目的地 |
+| `map_images` | 贵州地图单图配置 |
 | `destination_aliases` | 搜索别名 |
 | `themes` | 主题甄选 |
 | `products` | 线路产品 |
@@ -237,7 +238,7 @@ leads (
 - `CRUD /api/admin/products`
 - `CRUD /api/admin/destinations`
 - `CRUD /api/admin/campaigns`
- `CRUD /api/admin/home-config`
+- `CRUD /api/admin/site-config/:module`：页面模块配置，覆盖 `heroSlides`、`destinations`、`map`、`themes`、`ctaBanners`
 - `CRUD /api/admin/media-assets`
 - `GET /api/admin/leads`
 - `PATCH /api/admin/leads/:id/status`
@@ -256,7 +257,7 @@ leads (
 - 新建 `src/api/client.ts` 和 `src/api/types.ts`。
 - 新建 `src/adapters/siteConfig.ts`，把接口数据转成当前组件需要的结构。
 - 保留本地 JSON fallback，便于本地开发和接口故障降级。
- 把 `heroSlides`、`destinations`、`themeCards`、`sectionHeaders`、`bottomCtas` 从静态 import 改成接口加载。
+- 把 `heroSlides`、`destinations`、`map`、`themeCards`、`sectionHeaders`、`bottomCtas` 从静态 import 改成接口加载。

 ### 第二步：产品和目的地接口化

--- a/docs/admin-module-config-api.md
+++ b/docs/admin-module-config-api.md
@@ -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