# refactor(admin): 47 个 admin 查询接口 RespVO 续补 update 时间字段（PR #2348 漏扫续修）

> **服务**: hl-resource-service / hl-user-service / hl-order-service-v2
> **PR**: #2353 (已合 dev，已部署测试服)
> **Issue**: #2351（续 #2346）
> **日期**: 2026-05-15
> **影响范围**: 管理后台 hl-ui 47 个查询接口

---

## 给前端的话（mmg 看这里）

⚠️ **重要**：上一份 changelog `15_refactor_admin_resp_vo_add_updatetime.md` 只覆盖了 14 个 VO，**远远不够**。本批续补 **47 个 VO**，涵盖 mmg 反馈的 `/admin/scenic/spots` 等接口。

### 字段名规律
- 大多数 `updateTime`（与 BaseDO 一致）
- guide / banner / topic / explore / file / task / wechat / album / arrival / review / material / scenic / hotel / restaurant / vehicle / activity / cost / staff / supplies / service 等模块 `updatedAt`（与各模块既有 `createdAt` 风格一致）

### 验证
经测试服 9443 网关 + admin token，**抽样 18/18 全过**（含 `/admin/scenic/spots`）：

| 接口 | 字段 | 实测值 |
|------|------|--------|
| /admin/scenic/spots | updatedAt | 2026-03-31 22:58:10 |
| /admin/vehicle/models | updatedAt | 2026-04-13 17:18:06 |
| /admin/service/items | updatedAt | 2026-03-07 11:36:35 |
| /admin/cost/items | updatedAt | 2026-02-17 22:45:59 |
| /admin/material/list | updatedAt | 2026-05-15 17:53:42 |
| /admin/banner | updatedAt | 2026-03-17 16:23:49 |
| /admin/explore/category | updatedAt | 2026-04-01 16:25:51 |
| /admin/task/boards | updatedAt | 2026-02-13 16:28:53 |
| /admin/file/list | updatedAt | 2026-05-12 10:36:02 |
| /admin/order/list | updateTime | 2026-05-09 11:48:00 |
| /admin/order/early-bird/list | updateTime | 2026-04-20 12:15:05 |
| /admin/payment/list | updateTime | 2026-05-09 11:47:44 |
| /admin/review/list | updatedAt | 2026-05-07 14:48:56 |
| /admin/contract/list | updateTime | 2026-05-07 14:43:45 |
| /admin/contract/templates | updateTime | 2026-02-25 13:01:07 |
| /admin/contract/scheme/list | updateTime | 2026-04-24 16:20:00 |
| /admin/contract/clause-template/list | updateTime | 2026-05-13 14:15:25 |
| /admin/insurance/products | updateTime | 2026-02-24 20:55:11 |

---

## 受影响的 47 个 VO

### hl-resource-service（10 个，全 updatedAt）

| 模块 | VO |
|------|-----|
| material | MaterialVO |
| activity | ActivityListVO |
| cost | CostItemListVO |
| hotel | HotelListVO |
| restaurant | RestaurantListVO |
| **scenic** | **ScenicSpotListVO** ← mmg 反馈的就是这个 |
| service | ServiceItemListVO |
| staff | StaffListVO |
| supplies | SuppliesListVO |
| vehicle | VehicleModelListVO |

### hl-user-service（9 个）

- updatedAt 风格：WechatGroupVO, BannerVO, ExploreCategoryVO, ExploreCategoryDetailVO, TopicVO, FileVO, BoardVO, SubtaskVO
- updateTime 风格：MessageCategoryVO, NameItemRespVO

### hl-order-service-v2（28 个）

contract: ClauseTemplateVO, ContractSchemeAttachmentRespVO, ContractSchemeVO, ContractTemplateVO, ContractTourGuideRespVO, ContractVO
insurance: InsuranceOrderVO, InsuranceProductVO
order/album: AlbumFileVO, AlbumFolderVO
order/arrival: ArrivalPlanRespVO
order/assignment: VehicleAssignmentVO
order/core: OrderListVO, OrderVO
order/customize: CustomizeRequestVO
order/earlybird: EarlyBirdPlanVO
order/finance: AdminOrderDiscountVO, AdminOrderSurchargeVO, InvoiceVO
order/itinerary: ItineraryEditVO
order/review: AdminReportQueueItemRespVO, ReviewListVO, ReviewVO (3 个 updatedAt)
order/todo: OrderTodoVO
order/workorder: WorkOrderVO
payment: PaymentTransactionVO, RefundRecordVO

---

## 不在范围（14 个 VO 撤回，前端不要期待这些有 update 字段）

DO/DB 表本身**没有 update_at 列**，是设计上的"一次写入即不变"实体：

- 资源服务 10 个 Tag/Ref 表：MaterialRefVO / MaterialTagVO / ActivityTagVO / HotelTagVO / RestaurantTagVO / ScenicTagVO / ServiceTagVO / StaffTagVO / SuppliesTagVO / VehicleTagVO（标签计数表无 update 需求）
- 用户服务 3 个：FileRefVO（关联表）/ TimelineItemVO（audit log）/ SendLogVO（事件日志）
- 订单服务 1 个：ReviewImageVO（评价图片表无 update 设计）

---

## 实现细节（mmg 不用关心，归档备查）

### Service 层手动 set 修复 41 处（核心修复！）

本批 47 个 VO 中 41 个走"手动 `new + set`"路径（占 87%）。**如果只补 VO 不补 Service，字段恒 null**，看似改了实际没用。

CR 过程发现这个 bug 模式（PR #2348 也犯过 14/4 占比），本次彻底排查所有 setter，每处都补：
- 各 `XxxService.toListVO()` / `toVO()` 转换方法
- builder 风格的 service：`.updatedAt(...)` 在 build() 前

特殊 3 处跨名桥接（DO `updateTime` → VO `updatedAt`）：
- TopicService → `.updatedAt(topic.getUpdateTime())`
- ReviewDetailAssembler / ReviewCommandService / ReviewQueryService → `vo.setUpdatedAt(review.getUpdateTime())`

### 已知遗漏（OrderTodoVO 部分路径）

`OrderTodoQueryService.mapActiveTodoToVOList:86` 和 `mapInsuranceToVOList:121` 走 mapper 自定义 SQL 返回的 `ActiveTodoDTO`/`InsuranceCompletedDTO`，DTO 本身无 update 字段，需先改 mapper SQL。

**影响**：OrderTodoVO 在 list 页/详情页能看到 updateTime（已补），仅"待办活跃"特定查询路径会 null。后续 mapper 改造专项处理。

### 前一批未补已修

PR #2348 本身的 14 个 VO 已都正常工作（本批未动那 14 个，请前端继续使用）。

---

## 总账

- PR #2348 (14 个) + PR #2353 (47 个) = **总共 61 个 admin VO 已补 update 字段**
- 总共 15 个 VO 因 DO/DB 设计无 update_at 撤回（PR #2348: 1 个 GuideTagVO + PR #2353: 14 个）
- 总共 45 处 Service 手动 set 修复（PR #2348: 4 处 + PR #2353: 41 处）
