docs: 资源管理端 Map→VO 类型化 (PR #1201)

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)。