diff --git a/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime_batch2.md b/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime_batch2.md new file mode 100644 index 0000000..f7e22ec --- /dev/null +++ b/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime_batch2.md @@ -0,0 +1,126 @@ +# 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 处)