From 6a8e845bdee05f233dd86ae08092509788f11555 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Wed, 22 Apr 2026 19:29:45 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=B5=84=E6=BA=90=E7=AE=A1=E7=90=86?=
 =?UTF-8?q?=E7=AB=AF=20Map=E2=86=92VO=20=E7=B1=BB=E5=9E=8B=E5=8C=96=20(PR?=
 =?UTF-8?q?=20#1201)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...6-04-22_resource-admin-map-to-vo-batch1.md | 68 +++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 changelogs/2026-04/2026-04-22_resource-admin-map-to-vo-batch1.md

diff --git a/changelogs/2026-04/2026-04-22_resource-admin-map-to-vo-batch1.md b/changelogs/2026-04/2026-04-22_resource-admin-map-to-vo-batch1.md
new file mode 100644
index 0000000..e6a3290
--- /dev/null
+++ b/changelogs/2026-04/2026-04-22_resource-admin-map-to-vo-batch1.md
@@ -0,0 +1,68 @@
+# 资源管理端 Map→VO 类型化（批次 1）
+
+**PR**: [#1201](https://git.1814.love:8443/wx/HL/pulls/1201) | **合并时间**: 2026-04-22 19:27
+
+## 背景
+
+`hl-resource-service` 代码规范批次 1 整改，把管理端 Controller 返 `Map<String,Object>` 全部改成强类型 RespVO。**字段名与原 Map key 完全一致**，前端 `.data.xxxId`/`.data.name` 读法不变，但 TypeScript 类型定义可以升级到具体 VO。
+
+## 影响的管理端接口
+
+| 端点 | 旧返回 | 新返回 | 字段对齐 |
+|------|-------|-------|---------|
+| `GET /admin/hotel/list-all-simple` | `Result<List<Map>>` | `Result<List<HotelSimpleRespVO>>` | `hotelId: Long, hotelName: string` |
+| `POST /admin/hotel/{id}/submit-approval` | `Result<Map<String,String>>` | `Result<ApprovalSubmitRespVO>` | `approvalId: string, status: string` |
+| `POST /admin/hotel/room-type/{id}/submit-approval` | 同上 | 同上 | 同上 |
+| `POST /admin/scenic/{id}/submit-approval` | 同上 | 同上 | 同上 |
+| `POST /admin/restaurant/{id}/submit-approval` | 同上 | 同上 | 同上 |
+| `POST /admin/activity/{id}/submit-approval` | 同上 | 同上 | 同上 |
+| `POST /admin/service/{id}/submit-approval` | 同上 | 同上 | 同上 |
+| `POST /admin/vehicle/{id}/submit-approval` | 同上 | 同上 | 同上 |
+| `POST /admin/staff/{id}/submit-approval` | 同上 | 同上 | 同上 |
+| `POST /admin/supplies/{id}/submit-approval` | 同上 | 同上 | 同上 |
+| `GET /admin/material/export` | `Result<List<Map<String,String>>>` | `Result<List<MaterialExportRespVO>>` | 字段名完全保留 |
+
+## 前端改动建议
+
+**TypeScript 类型升级**（可选，字段名无变化）：
+
+```typescript
+// Before
+interface HotelSimpleItem {
+  hotelId: string;  // 或 number
+  hotelName: string;
+}
+
+// After (对齐后端 HotelSimpleRespVO)
+interface HotelSimpleRespVO {
+  hotelId: number;  // Long
+  hotelName: string;
+}
+
+// submitApproval 响应
+interface ApprovalSubmitRespVO {
+  approvalId: string;
+  status: string;
+}
+```
+
+**渲染代码无需改动**：`response.data.hotelId` / `response.data.approvalId` 依然可用。
+
+## 校验增强（@Valid）
+
+20 处 `/admin/**` 和 `/internal/**` 的 `@RequestBody` 接口补了 `@Valid`。以下 internal 端点如果前端曾绕过网关直连调用（不推荐），会因为校验失败返回 400：
+
+- `POST /internal/{resource}/approval-result`（需 `ApprovalResultDTO.spNo/spStatus` 非空）
+- `POST /internal/resource/price/{resource}`（需 `PriceQuery` 必填字段）
+- `POST /admin/material/category/permissions`（需 `materialIds` 非空）
+
+**前端实际调用都走网关 + 全字段传参，不受影响**。
+
+## 无需前端改动的范围
+
+- Mapper / Service 层重构（48 Mapper 升级 BaseMapperX、Wrapper 下沉到 default 方法）
+- 4 个新增聚合 Service（ResourcePriceQueryService 等，仅改内部实现）
+
+## 相关后端 changelog
+
+详细后端契约变更见 [`hl-backend-changelog/2026-04/2026-04-22_resource-service-rules-refactor-batch1.md`](../../../hl-backend-changelog/changelogs/2026-04/2026-04-22_resource-service-rules-refactor-batch1.md)。