# Round 2 review 收尾 7 项:Wrapper 漏修 + LockFailure 500 + JavaDoc 旧编号 + 孤儿枚举 + Publisher rename + 脱敏收敛 + Mapper default 单测

> **存放目录**: 二期 → `changelogs-v2/2026-05/`
> **服务**: hl-user-service + hl-common-core + hl-starter-protection + hl-order-service-v3
> **PR**: #2850
> **Issue**: #2849
> **日期**: 2026-05-22
> **影响范围**: 全部内部代码简化 / 无破坏性变更 — 但 **HouseEventPublisher → HouseNotificationPublisher rename + LockFailureException 全局新错误码**

---

## ⚠️ 关键变化(前端可感知)

### 1. 🟡 @Lock4j 抢锁失败错误码 100503 RESOURCE_LOCKED
之前 `@Lock4j(acquireTimeout=5s)` 抢锁失败抛 `LockFailureException` 上抛 GlobalExceptionHandler 兜底返 500,前端体验差。

**现**:全局 `LockFailureExceptionHandler` 拦截返:
```json
{ "code": 100503, "message": "资源被占用,请稍后重试", "success": false }
```

**生效范围**:全部 @Lock4j 注解(目前主要 ProductSnapshotService.restoreSnapshot,后续扩展)。前端如有错误码映射需识别 100503 显示"操作冲突,请稍后重试"提示。

### 2. 🟢 Bug 修复:漏修的 listCustomers Wrapper(后端内部)
`hl-user-service` listCustomers Service 内 Wrapper 残留下沉到 `UserMapper.selectCustomerPage` default。前端无感知。

---

## 一、变更接口清单

| # | 接口 | 变更类型 | 说明 |
|---|------|----------|------|
| 1 | 所有 @Lock4j 注解接口(目前 `/admin/product/snapshot/restore`) | **错误码新增** | 抢锁失败返 `100503 RESOURCE_LOCKED` 而非 500 |
| 2 | `/admin/customer/page` 等 | **内部重构** | listCustomers Wrapper 下沉到 Mapper default(前端响应不变) |

---

## 二、关键改动(内部)

1. **`hl-common-core.CommonErrorCode`** 新增 `RESOURCE_LOCKED(100503, "资源被占用,请稍后重试")`
2. **`hl-starter-protection.LockFailureExceptionHandler`** 新增全局 `@RestControllerAdvice` 拦截 `LockFailureException` 返 100503
3. **`HouseEventEnum.CUSTOMER_CHANGE`** 孤儿常量删除(PR #2846 删了对应状态机规则,枚举常量是孤儿)
4. **`HouseEventPublisher` → `HouseNotificationPublisher`** rename(单职责后类名误导)— 9 处引用 + 3 IT @MockBean 同步
5. **`ComplaintConverter`** 手工 substring 脱敏 → `PiiMaskUtil.maskPhone()`(删 13 行)
6. **PR #2846 8 处 JavaDoc 旧编号/类名更新**(808990→808900 / 808994→808901 / 808993→808941 / `RESOURCE_SERVICE_UNAVAILABLE`→`RESOURCE_UNAVAILABLE` / `INVENTORY_DEDUCT_FAILED`→`ROOM_STOCK_INSUFFICIENT`)
7. **5 个新 Mapper default 单测**:LoginLogMapperTest / UserMapperTest / AdminUserMapperTest(8 测试)

---

## 三、测试服验证

| 服务 | 部署 commit | uptime | 验证 |
|------|------------|--------|------|
| hl-user-service | dev-v3 含 #2850 | 21:34 | ✅ Wrapper 下沉 + 新 Mapper default 单测全绿 |
| hl-order-service-v3 | dev-v3 含 #2850 | 21:36(SSH restart) | ✅ Publisher rename 后启动正常 |

---

## 四、累计 Round 1 + Round 2 收益

| 维度 | 数值 |
|------|------|
| PR 数 | 5 张(#2845 / #2846 / #2847 / #2848 / #2850) |
| 工单数 | 5 张(#2841 / #2842 / #2843 / #2844 / #2849) |
| 净行数 | **-1359(R1) + +311(R2 含 5 新测试文件)= 净 -1048 行** |
| HOUSE 模块评分 | C+ → **A-** |
| 整体评分 | Round 1 A- → Round 2 后整体 **A** |
| 单测数 | 2579 + Round 1 各服务 全绿 |

---

## 五、留尾(独立工单 backlog)

- **product-v2 全模块 294 文件 HTML 标签清零**(P0 铁规 15h 全局)→ 大工程独立工单
- **MpTripDetailVO Object → List<Map> 真实数据回归** → /@qa 工单
- **AdminUserService 9 处跨聚合 Mapper(红线 5 二期)** → 独立工单
- **HOUSE FLEET vehicle_plan Feign 接通后补 DRIVER 通知三件套** → 独立工单
- **MaterialCategory ↔ Permission 双 @Lazy 抽 PermissionGate** → backlog
- **EquipmentTemplateService ↔ ProductLineService 双 @Lazy 抽 ProductEquipmentBindingService** → backlog

---

## 六、关联

- 工单: #2849(closed)
- PR: #2850(merged)
- Round 2 review 来源: Claude /@cr 3 agent 并发(A/B/C)2026-05-22
- **memory P0 铁规 7 升级**:agent 严禁 git stash(同周 3 次违规累计 4+ 次)