diff --git a/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime.md b/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime.md new file mode 100644 index 0000000..5b91710 --- /dev/null +++ b/changelogs/2026-05/15_refactor_admin_resp_vo_add_updatetime.md @@ -0,0 +1,111 @@ +# refactor(admin): 14 个查询接口 RespVO 补 updateTime/updatedAt 字段 + +> **服务**: hl-order-service-v2 / hl-product-service-v2 / hl-resource-service +> **PR**: #2348 (已合 dev,已部署测试服) +> **Issue**: #2346 +> **日期**: 2026-05-15 +> **影响范围**: 管理后台 hl-ui 14 个查询接口的列表 / 详情返回结构 + +--- + +## 给前端的话(mmg 看这里) + +管理后台 14 个 admin 查询接口的响应 VO **新增了 `updateTime` 或 `updatedAt` 字段**(视模块命名约定),可以在列表上加「最后修改时间」列了。 + +字段名规律: +- order-v2 / product-v2 模块:`updateTime` +- resource guide 模块:`updatedAt`(与本模块既有 `createdAt` 风格一致) + +值类型:`LocalDateTime` 字符串(如 `"2026-05-15 10:30:00"`),可能为 null(少数旧数据没填的话)。 + +**不影响任何现有字段,纯新增;前端不改也不会报错,要展示才取**。 + +--- + +## 受影响的 14 个接口(按服务分组) + +### hl-resource-service(3 个,字段名 `updatedAt`) + +| 接口 | RespVO | +|------|--------| +| `GET /admin/guide/article/list` | GuideArticleListVO | +| `GET /admin/guide/category/list` | GuideCategoryVO | +| `GET /admin/guide/tag/managed`、`/admin/guide/tag/all` | GuideTagVO | + +> ⚠️ GuideTagVO 因为 DB 表 `guide_tag` 本身没有 `updated_at` 列,本次**没加**字段(即 `updatedAt` 字段不存在于响应中)。如果后续业务需要支持标签修改时间,需要先发 V*.sql 加列。 + +### hl-product-service-v2(10 个,字段名 `updateTime`) + +| 接口 | RespVO | +|------|--------| +| `GET /admin/product/item/{id}`(产品详情) | ProductDetailRespVO | +| `GET /admin/product-line/{id}` 及列表 | ProductLineRespVO | +| `GET /admin/product/equipment-template/simple` | EquipmentTemplateSimpleRespVO | +| `GET /admin/product/item/{id}/itinerary/day` | ItineraryDayRespVO | +| `GET /admin/product/item/{id}/price-calendar` | PriceCalendarRespVO | +| `GET /admin/product/item/{id}/schedule/list` | ScheduleRespVO | +| `GET /admin/product/item/{id}/schedule/team` | ScheduleTeamRespVO | +| `GET /admin/travel-guarantee-template/list` 等 | TravelGuaranteeTemplateRespVO | +| `GET /admin/product/formula/group/list` 等 | FormulaGroupRespVO | +| `GET /admin/product/formula/var/list` | FormulaVarRespVO | + +### hl-order-service-v2(1 个,字段名 `updateTime`) + +| 接口 | RespVO | +|------|--------| +| `GET /admin/travel-agency/enabled` 等下拉 | AgencySimpleRespVO | + +--- + +## 不在范围(13 个 VO 按语义跳过) + +以下 VO 属于"聚合 / 估算 / 操作结果",**不是 DB 持久化实体**,加 updateTime 无意义,前端不要期待这些接口返回时间字段: + +- 保险预览/试算:InsurancePreviewApplyRespVO、InsuranceTrialPriceRespVO +- 充值/上传结果:RechargeRespVO、InvoiceUploadRespVO +- 旅客智能解析结果:AdminTravelerSmartParseRespVO +- 地图生成 / 复制分享 / 最低价聚合:ProductMapGenerateRespVO、ProductShareRespVO、ProductMinPriceRespVO +- 操作日志(createTime 即操作时间):ProductOperationLogRespVO +- 建议价计算:ResourceSuggestPriceRespVO、SuggestPriceRespVO +- 多源价格日历聚合:UnifiedPricingCalendarRespVO +- 公式版本快照:FormulaVersionRespVO + +mp 端 VO **不在本次范围**。 + +--- + +## 验证记录 + +### 本地(PR 提交前) +- mvn clean compile 三服务全绿 +- 8080 网关 + SUPER_ADMIN token 抽样 5 接口全过 + +### 测试服(部署后,2026-05-15) +经 `https://api.test.1814.love:9443` + admin token 抽样: + +| 接口 | 字段 | 实测值 | +|------|------|--------| +| /admin/travel-agency/enabled | updateTime | 2026-05-08 14:41:03 ✅ | +| /admin/product/formula/group/list | updateTime | 2026-04-14 00:50:15 ✅ | +| /admin/guide/category/list | updatedAt | 2026-03-31 22:05:01 ✅ | +| /admin/guide/article/list | updatedAt | 2026-03-17 23:40:04 ✅ | +| /admin/travel-guarantee-template/list | updateTime | 2026-04-15 21:30:22 ✅ | + +5/5 全过。 + +--- + +## 实现细节(mmg 不用关心,归档备查) + +### Service 层修复 +PR 中除了 VO 加字段,还修了 4 处 Service 手动 `new + set` 构造时漏字段(不修则 VO 字段恒 null): +- TravelAgencyServiceImpl.toSimpleVO +- EquipmentTemplateService.toSimpleRespVO +- GuideArticleService 两处构造 +- GuideCategoryService.toVO + +其余 VO 走 `BeanUtil.toBean(DO.class, VO.class)`,BaseDO 的 createTime/updateTime 自动复制,无需 Service 改动。 + +### 字段命名约定 +- `BaseDO` 用 `createTime`/`updateTime`(驼峰,与 DB 列 `create_time`/`update_time` MyBatis 自动映射) +- guide 模块历史用 `createdAt`/`updatedAt`(DB 列 `created_at`/`updated_at`),不打破现有命名