docs(changelog-v2): Round 3 收尾 13 项 (PR #2853 Closes #2851)

changelogs-v2/2026-05/22_2851_round3-followup_PR2853.md

@@ -0,0 +1,96 @@
+# Round 3 收尾 13 项:TokenService 灰度删 + swap 状态机假阳性修复 + PiiMaskUtil 三套合一 + youngChild 术语统一 + 杂项
+
+> **服务**: hl-user-service + hl-product-service-v2 + hl-fleet-service + hl-order-service-v3 + hl-common-core + hl-starter-protection
+> **PR**: #2853
+> **Issue**: #2851
+> **日期**: 2026-05-22
+> **影响**: 内部 / 注释 / 工具类合一 — **司机/出行人 PII 脱敏掩码格式微调,前端需注意**
+
+---
+
+## ⚠️ 关键变化(前端需关注)
+
+### 1. 🟡 司机/出行人 PII 脱敏掩码格式微调(`fleet maskIdCard`)
+**前**:`150102******1234`(6 位星固定长度)
+**后**:`150***********1234`(SensitiveDataUtil 变长星)
+
+**影响**:司机 / 出行人列表 `idCardNoMasked` 字段长度从 18 字符变 17 字符(具体看身份证长度差),前端如果有断言式校验需放宽。**业务语义不变,仍是 PII 脱敏**。
+
+### 2. 🟡 "幼儿数 / 幼童" → 统一改"小童"(术语)
+跨 7 个 VO/Service:`OrderCreateReqVO` / `OrderMainVO` / `ProductFeignClient` / `GroupOrderStrategy` 等 `@ApiModelProperty` 和 javadoc 中"幼儿数"、"幼童"全统一为"小童"。**字段名 `youngChildCount` 不变**,只是中文标签统一。前端如展示了原"幼儿数"或"幼童"字样,改为"小童数"即可。
+
+### 3. 🟢 @Lock4j 抢锁失败错误码扩展(后端)
+之前 R2 加的 `LockFailureExceptionHandler` 只拦 `LockFailureException`,现在改拦父类 `LockException`,覆盖 lock4j Redis lua 异常 / 释放锁失败等所有 lock4j 异常,统一返 `100503 RESOURCE_LOCKED`。
+
+---
+
+## 一、必修 13 项(6 P0 + 7 P1)
+
+### P0
+1. **TokenService 灰度 fallback 删**(2026-05-22 到期):删 8 行旧 key 兼容 + 对应单测
+2. **HouseHotelSwapServiceImpl.isInExceptionState 假阳性修复**:`findOpenByOrderAndTypes` 仅查 `SWAP_HOTEL`,REFUND 剔除(REFUND OPEN 待办与 swap 无关,避免误 fire `EXCEPTION→CLAIMING`)
+3. **RefundReconcileJob.java:67 Wrapper 下沉**:Job 内 `new LambdaQueryWrapperX` 改 `RefundRecordMapper.selectPendingForReconcile` default
+4. **youngChildCount 中文名统一「小童」**(7 文件)
+5. **PiiMaskUtil 三套合一 → SensitiveDataUtil**:
+   - 删 `hl-order-service-v3/.../shared/util/PiiMaskUtil.java`
+   - 删 `hl-fleet-service/.../shared/util/PiiMaskUtil.java`
+   - `SensitiveDataUtil` 新增 `maskRawLine` 方法收编 v3 正则
+   - v3 + fleet 共 11 处调用方迁移
+   - **v2 PiiMaskUtil 保留(legacy 模块,非本工单范围)**
+6. **过时 TODO + 占位日志清理**:MaterialDashboardService TODO 删 / ProductDayHotelService + GroupTourBatchService log.warn("[TODO]") → log.debug
+
+### P1
+7. `LockFailureExceptionHandler` 拦父类 `LockException`
+8. `HotelRequirementMapper.@Select` 删 → `HouseAssignmentService.countConfirmedByRequirement` 暴露
+9. `@Autowired` → 构造器注入(AgencyProperties + RefundReviewService)
+10. `TravelerErrorCode.TRANSPORT_PLAN_NOT_BELONG_TO_ORDER (581121)` 0 调用 @Deprecated 删(9 行)
+11. `HouseStateMachineConfig:154` 重复叙事精简
+12. `RouteMapCacheService:27` 主观词"性能优化" → "缓存减少对高德 API 重复请求"
+13. `HouseAssignmentService` 两处 TODO 格式统一为 `#2729-followup`
+
+---
+
+## 二、测试服验证
+
+| 服务 | 部署 commit | uptime | 验证 |
+|------|------------|--------|------|
+| hl-user-service | dev-v3 含 #2853 | 22:30 | ✅ TokenService 灰度 fallback 已删 |
+| hl-product-service-v2 | dev-v3 含 #2853 | 22:31 | ✅ |
+| hl-fleet-service | dev-v3 含 #2853 | 22:32 | ✅ |
+| hl-order-service-v3 | dev-v3 含 #2853 | 22:33(SSH restart) | ✅ |
+
+单测:5 模块全绿(common 463/463 / user 2433/2433 / product-v2 1300/1300 / fleet 178/178 / order-v3 1911/1928 — 17 失败全 baseline 预存)。
+
+---
+
+## 三、Round 1 + 2 + 3 累计成果
+
+| 维度 | Round 1 | Round 2 | Round 3 | 累计 |
+|------|---------|---------|---------|------|
+| 工单 | #2841-#2844 | #2849 | #2851 | 6 张 |
+| PR | #2845-#2848 | #2850 | #2853 | 6 张 |
+| 净行数 | -1359 | +311 | -130 | **-1178** |
+| HOUSE 评分 | C+ → A- | A- | A | C+ → **A** |
+| 整体评分 | C+ → A- | A- → A | A → **A+** | A+ |
+
+---
+
+## 四、留尾(独立工单 backlog,**本轮明确不做**)
+
+- **#2852 HTML 标签全模块清零 3010 处**(大工程独立)
+- MpInternalRefundController 444 行 BFF Facade 抽离
+- 9 个 Service+Impl 单实现合并(refund/house/agency)
+- 巨型 private 方法独立 Builder/Assembler
+- 720000/798000 段位上移 CommonErrorCode
+- Long ID @JsonSerialize Mixin 全局
+- AdminUserService 红线 5 二期(跨聚合 Mapper)
+- 手工金额格式化抽 MoneyUtil
+- v2 PiiMaskUtil legacy 清理
+
+---
+
+## 五、关联
+
+- 工单: #2851(closed)
+- PR: #2853(merged)
+- Round 3 review 来源: Claude /@cr 4 agent 并发(A 注释严谨/B 逻辑准确/C 残留过度设计/D 跨模块一致性)2026-05-22