# QA-D 文档驱动 + QA-E 字段反查发现 4 个 P0/P1 真实 bug 修复

> **服务**: hl-gateway + hl-order-service-v3
> **PR**: #2864 / #2866
> **Issue**: #2863 / #2865
> **日期**: 2026-05-22
> **影响**: **5 个原本经网关 404 的 v3 接口现在通了** + **list/detail 字段静默不一致 2 bug 修复**

---

## ⚠️ 关键变化(前端必读)

### 1. 🔴 订单列表 `tags` 字段类型变更(breaking change,**前端必须同步改 hl-ui**)

**之前**:`tags` = `string[]` 如 `['VIP', '高净值']`
**之后**:`tags` = `Array<{name, type, color}>` 富对象数组(与 detail 端 `main.tags` 完全一致)

**影响**:`/v3/admin/order` 列表 list[].tags 类型变更。**前端用 `tags.join(',')` 字符串操作会 NPE**,必须改为 `tags.map(t => t.name).join(',')`。

**示例**:
```js
// 之前
order.tags  // ['VIP', '高净值']
order.tags[0]  // 'VIP'

// 之后
order.tags  // [{name: 'VIP', type: 'level', color: '#FF0000'}, ...]
order.tags[0].name  // 'VIP'
order.tags[0].color  // 用于显示标签底色
```

### 2. 🟡 订单详情 `main.orderNo` + `main.teamNo` 字段新增

**之前**:`/v3/admin/order/{id}` detail.main 只有 `displayOrderNo`,无 `orderNo` 和 `teamNo`
**之后**:detail.main 同时返 `orderNo` + `teamNo` + `displayOrderNo` 三个字段

**影响**:前端可从详情页直接拿原始 `orderNo` 用于搜索/精确比对/退款关联/合同关联,不需要反解 `displayOrderNo`。

**何时出现差异**:成团后 `displayOrderNo = "{orderNo}-T{teamNo}"`,之前前端从详情页拿不到原始 orderNo;改后两个字段都有。

### 3. 🟢 5 个原本经网关 404 的 v3 接口现在通了

**之前**:这 5 个 admin/internal 接口经网关访问 100% 404(gateway 缺路由),前端从未能调过
**之后**:网关补路由后,接口可正常调用(401 / 200 等正常响应)

| 接口前缀 | Controller |
|----------|-----------|
| `/v3/admin/complaint/**` | AdminComplaintController |
| `/v3/admin/review/**` | AdminReviewController |
| `/v3/internal/review/**` | InternalReviewController |
| `/v3/internal/mp/review/**` | InternalMpReviewController |
| `/v3/internal/house/**` | HouseInternalAssignmentController |

### 4. 🟡 `/admin/order/{id}/status-log` 改为 `/v3/admin/order/{id}/status-log`

**之前**:`AdminOrderStatusLogController` `@RequestMapping("/admin/order")` 没 v3 前缀,被 v2 路由抢截 100% 404
**之后**:改为 `/v3/admin/order`,与 v3 命名规范一致

**影响**:前端如果调过 `/admin/order/{id}/status-log` 会 404(原本也 404,没人调过),改后用 `/v3/admin/order/{id}/status-log`。

---

## 一、改动概览

### PR #2864 — 修 gateway 6 路由(Closes #2863)
- gateway `application.yml` line 205 `order-service-v3` 路由 Path 末尾追加 5 个 path
- `AdminOrderStatusLogController` `@RequestMapping("/admin/order")` → `/v3/admin/order`
- `AdminOrderStatusLogControllerTest` 3 处 mockMvc 路径同步改 `/v3` 前缀
- 3 文件 +6 -6 lines
- 测试:GatewayRouteAuditTest 1/1 + AdminOrderStatusLogControllerTest 3/3 全绿

### PR #2866 — 修 2 个静默字段 bug(Closes #2865)
- BUG-1: `OrderMainVO` 补 `orderNo` + `teamNo` 字段,Converter 同步映射
- BUG-2: list `tags` 类型 `List<String>` → `List<TagVO>` 富对象(复用 detail 端 TagVO)
- `OrderInfoConverter.toTagVO` 提升 public static,list/detail 共用映射器
- `OrderService.listOrders` 批量聚合 `Map<orderId, List<TagVO>>` 去 N+1
- 6 文件 +179 -9 lines
- 新增 5 单测(OrderInfoConverterTest 3 + OrderServiceTest 2)
- 测试:113 直接相关 0 failures(89 service + 24 converter)

---

## 二、QA 测试覆盖说明

本次 4 个 QA agent 并行覆盖 dev-v3 近 5 天 wx 提交全量:

| Agent | 范围 | 结果 |
|-------|------|------|
| **QA-A** HOUSE 模块全量 | 46 测试点 | 42 PASS / 4 WARN(数据稀疏)/ 0 FAIL / 0 BLOCKER |
| **QA-B** 订单/traveler/agency/合同/tag-library | 53 项 | 51 PASS / 2 WARN(doc-vs-code 错误码)/ 0 BLOCKER |
| **QA-C** 通知/字典/mp/fleet | 40 URL | 全 PASS / 0 BLOCKER |
| **QA-D** 文档驱动业务流端到端 | 8 业务链 + 4 反例 + 6 规则 | 找出 **2 个 P0 BLOCKER**(gateway 路由 5 缺 + 1 冲突) |
| **QA-E** 字段语义反查(API cross-check + DB SELECT) | 10 对接口比对 | 找出 **2 个真实静默 bug**(tags shape / orderNo 丢失) |

---

## 三、测试服验证

| 服务 | 部署 commit | uptime | 验证 |
|------|------------|--------|------|
| hl-gateway | dev-v3 含 #2864 | 部署完毕 | 6 路径 HTTP 200 通(无 404) |
| hl-order-service-v3 | dev-v3 含 #2864+#2866 | 部署完毕 | detail.main.orderNo + list[0].tags 富对象待 mmg 复测 |

---

## 四、5 天 wx 提交累计成果(全部 PR 总览)

| Round | 工单 | PR | 主题 | 净行数 |
|-------|------|-----|------|--------|
| R1 review | #2841-#2844 | #2845-#2848 | 反过度设计 + 简洁可读 | -1359 |
| R2 收尾 | #2849 | #2850 | 7 项可现做项 + Lock4j 100503 | +311 |
| R3 收尾 | #2851 | #2853 | TokenService 灰度 + PiiMaskUtil 三合一 + 小童 | -130 |
| R4 Backlog | #2852/#2854/#2855/#2856/#2857 | #2858-#2862 | HTML 清零 1589 文件 + BFF Facade + 红线 5 + MoneyUtil + Service+Impl | 净 -340 |
| **QA 真测发现** | **#2863/#2865** | **#2864/#2866** | **gateway 6 路由 + list/detail 2 静默 bug** | **+185 -15** |
| **合计** | **13 工单** | **13 PR** | | **净 -1348 行** |

整体评分:**A+ 维持**(QA 真测 4+1 agent 全覆盖,5 个静默 bug 已修)。

---

## 五、hotfix #2881(回滚 PR #2864 引入的回归)

QA 真测验证 PR #2864 时发现 `/v3/admin/order/{id}/status-log` 返 500 Ambiguous handler。PR #2864 误把 wx 故意写的 `AdminOrderStatusLogController @RequestMapping("/admin/order")`(被 v2 抢截 404,设计上的"隐藏入口",PRP § 9 R13)改成 `/v3/admin/order`,反而与 OrderController 早就存在的同 URL 端点撞冲突。

**hotfix PR #2881 (#2880)**:
- AdminOrderStatusLogController 路径回滚 `/v3/admin/order` → `/admin/order`(故意 404 设计)
- AdminOrderStatusLogControllerTest 3 处 mockMvc 同步回滚
- javadoc 加大量警告注释 + 历史教训("严禁改 v3 前缀,会与 OrderController 撞 URL")

**保留 PR #2864 其他改动**:gateway 5 路由追加(complaint/review/internal-review/internal-mp-review/internal-house)是真 bug 修复,保留。

**最终验证**(部署后):
- `/v3/admin/order/{id}/status-log` code=200,真返 `List<LogTimelineVO>` 1 条(occurredAt/operator/action/fromStatus/toStatus/amount 6 字段)
- `/admin/order/{id}/status-log` code=404 维持设计

## 六、关联

- 工单: #2863 / #2865 / #2880(全部 closed)
- PR: #2864 / #2866 / #2881(全部 squash merged)
- QA 报告:
  - `.tmp/qa-house-report.txt`(QA-A 46 项)
  - `.tmp/qa-ord-report.txt`(QA-B 53 项)
  - `.tmp/qa-msg-report.txt`(QA-C 40 项)
  - `.tmp/qa-doc-chain-report.txt`(QA-D 8 业务链)
  - `.tmp/qa-cross-check-report.txt`(QA-E 10 字段对比 + DB 反查)
- memory 升级:P0 #16(新 admin Controller 必同步改 gateway 路由)第 5 次复发,强化 reminder