# 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`），不打破现有命名
