docs(changelog): #5368 非订单页面统一补齐真实团号与团号搜索交接前端

2026-08-03 20:11:50 +08:00 · 2026-08-03 20:11:50 +08:00 · 118877e367
--- a/changelogs-v2/2026-07/31_5368_非订单页面统一补齐真实团号与团号搜索-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/31_5368_非订单页面统一补齐真实团号与团号搜索-修改接口-管理后台.md
@ -0,0 +1,271 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5368"
+title: "非订单页面统一补齐真实团号与团号搜索"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-08-03"
+status_note: "PR #5386 已合并（dev-v3@07834e4c5）；order-v2/order-v3/user/fleet 已部署 TEST（tasks 03b0fecb/2b54e87b/258865cf/d290d667）并经网关验证：profile/orders teamNo=groupCode+keyword 搜索、contract teamNo 过滤分页正确、fleet insurance/board teamNo 返回与查询（orderNo 片段不命中）、chat 会话 teamNo、月度对账 teamNo、雪花 ID JSON String。OpenAPI/oasdiff 与 Spring Cloud Contract 仍 not_configured（人工回退证据见 D:/tmp/hl5368-gateway-evidence/）。frontend_status 保持 pending，待前端按自身流程消费。"
+updated_at: "2026-08-03"
+base: "dev-v3"
+---
+
+# 管理端：非订单页面统一补齐真实团号与团号搜索
+
+> **服务**: `hl-user-service`、`hl-order-service-v2`、`hl-order-service-v3`、`hl-fleet-service`
+> **Issue**: [wx/HL#5368](https://git.1814.love:8443/wx/HL/issues/5368)
+> **前端交接 Issue**: `wx/hl-api-changelog#64`
+> **日期**: 2026-07-31
+> **影响范围**: 管理后台工作台、订单列表、合同、评价、车务、房务、会话等订单关联页面
+> **候选基线**: `dev-v3@07834e4c5`（PR #5386 已合并）
+> **合并 PR**: [#5386](https://git.1814.love:8443/wx/HL/pulls/5386) head `b65cff23a`，merge commit `07834e4c5`
+> **后端/网关状态**: backend=deployed，gateway=verified（2026-08-03）
+
+> **契约裁决（yst 2026-08-03T16:24，承接 #5372）**: `/internal/order/designer-list` 仅扩展 keyword 对真实 `groupCode` 的模糊搜索，保留原响应字段，**不新增 `teamNo`**；对外 `/admin/order/list` 与 `/admin/profile/orders` 返回 `teamNo: String|null`，user-service 在公开边界执行 `teamNo=groupCode`。后端已按此实现并合并。
+
+---
+
+## ⚠️ 关键变化
+
+1. 非订单管理页面统一新增 canonical 字段 `teamNo: string | null`。它只表示真实团号：
+   - order-v3 来源为 `order_main.team_no`；
+   - order-v2 来源为既有 `groupCode`；
+   - 车务司机险来源为派单时真实团号快照；历史无值保持 `null`。
+2. **禁止 `teamNo || orderNo` 回退**。`teamNo` 无值时前端统一显示 `-`（或既定空值占位），不得把 `orderNo`、`groupNo` 或其他编号伪装成团号。
+3. `orderNo` 不删除：仍用于订单管理、内部关联、兼容展示和原有订单号搜索，但它不是团号。
+4. 所有雪花 ID（例如 `orderId`、`contractId`、`schemeId`、`taskId`、`assignmentId`、`driverId`、`requirementId`、`bizId`）按 JSON String 处理。前端不得转为 JavaScript `Number`，路由、行键和动作请求继续使用这些稳定 ID，不得使用 `teamNo` 替代。
+5. 本文覆盖并纠正历史 `#5156` changelog 中“团号空值回退订单号”的建议：本次统一口径为**无真实团号即空值，不回退订单号**。
+
+---
+
+## 一、通用字段契约
+
+| 字段 | JSON 类型 | 空值 | 用途 | 兼容规则 |
+|------|-----------|------|------|----------|
+| `teamNo` | `string \| null` | 未生成、历史无快照或下游降级时为 `null` | 页面团号展示、约定接口的团号搜索 | canonical 新字段；禁止从其他编号推导 |
+| `orderNo` | `string \| null` | 依原接口 | 订单号展示、订单管理、内部关联及原有搜索 | 保留，不删除；不得作为团号回退 |
+| `groupCode` | `string \| null` | 依原接口 | order-v2 兼容 | 保留；`teamNo` 的真实值取自该字段，但前端新代码读 `teamNo` |
+| `groupNo` | `string \| null` | 依原接口 | 司机相关历史兼容 | 保留；司机详情新代码读 `teamNo` |
+| 各类雪花 ID | `string` 或 `string \| null` | 依业务字段 | 路由、行键、详情和动作接口参数 | 禁止 `Number(id)`、数学运算或以 `teamNo` 替代 |
+
+前端统一展示示例：
+
+```ts
+const visibleTeamNo = teamNo?.trim() || '-'
+// 禁止：teamNo?.trim() || orderNo?.trim() || '-'
+```
+
+---
+
+## 变更接口
+
+| # | 页面/接口 | 方法与路径 | 请求变化 | 响应变化 |
+|---|-----------|------------|----------|----------|
+| 1 | 管理后台工作台 | `GET /admin/profile/dashboard` | 无 | 各角色订单项补 `teamNo` |
+| 2 | 定制师“我的订单” | `GET /admin/profile/orders` | `keyword` 增加团号模糊匹配 | `data.records[].teamNo` |
+| 3 | 订单管理列表 | `GET /admin/order/list` | `keyword` 增加团号模糊匹配 | `data.records[].teamNo`；保留 `groupCode` |
+| 4 | 合同列表 | `GET /v3/admin/contract/list` | 新增可选 query `teamNo`，模糊匹配 | `data.records[].teamNo`；合同/订单/方案 ID 为字符串 |
+| 5 | 合同详情 | `GET /v3/admin/contract/<id>` | 无 | `data.teamNo`；相关雪花 ID 为字符串 |
+| 6 | 评价列表 | `GET /v3/admin/review/list` | `keyword` 的 OR 搜索新增团号 | `data.records[].teamNo` |
+| 7 | 评价详情 | `GET /v3/admin/review/<reviewId>` | 无 | `data.teamNo` |
+| 8 | 司机险任务 | `GET /admin/fleet/insurance/tasks` | 新增可选 query `teamNo`，仅模糊匹配真实 `team_no` | `data.records[].teamNo`；历史空值为 `null` |
+| 9 | 司机详情 | `GET /admin/fleet/drivers/<driverId>` | 无 | `data.relatedOrders[].teamNo`；保留 `groupNo` |
+| 10 | 车务派单看板 | `GET /admin/fleet/board/orders` | 既有 `teamNo` 搜索只匹配真实团号，不再匹配订单号 | 既有 `teamNo` 保持；空值不回退 `orderNo` |
+| 11 | 车务看板详情 | `GET /admin/fleet/board/orders/<orderId>` | 无 | 既有 `teamNo` 保持；空值不回退 `orderNo` |
+| 12 | 车务矩阵 | `GET /admin/fleet/matrix/grid` | 团号搜索/展示遵循真实 `teamNo` | `assignments[].teamNo` 不回退 |
+| 13 | 车务矩阵未派单 | `GET /admin/fleet/matrix/unassigned-orders` | 团号搜索/展示遵循真实 `teamNo` | `data[].teamNo` 不回退 |
+| 14 | 车务矩阵单日清单 | `GET /admin/fleet/matrix/day-orders` | 团号搜索/展示遵循真实 `teamNo` | `data[].teamNo` 不回退 |
+| 15 | 会话列表 | `GET /admin/message/chat/conversations` | 无 | `data.records[].teamNo`；`bizId`、`peerAdminId`、`requirementId` 为字符串 |
+| 16 | 打开会话 | `POST /admin/message/chat/open`、`/open-house`、`/open-house-lead`、`/open-fleet` | 无 | `data.order.teamNo`；订单卡需求 ID 为字符串 |
+| 17 | 房务选单池 | `GET /v3/admin/order/grab-pool/hotel-requirements` | `keyword` OR 搜索新增真实团号 | `data.records[].teamNo` |
+| 18 | 房务我的/全部接单 | `GET /v3/admin/order/grab-pool/my-claims/hotel`、`/all-claims/hotel` | `keyword` OR 搜索新增真实团号 | `data.list[].teamNo` |
+| 19 | 房务待办 | `GET /v3/admin/order/todos` | `keyword` 保留 title/reason OR 语义并增加真实团号 | `data.list[].teamNo` |
+| 20 | 房务月度对账明细 | `GET /v3/admin/house/reconciliation/monthly/hotel-orders` | 无 | `data[].teamNo` |
+
+内部 Feign 链路同步透传 `teamNo`，供 `/admin/profile/dashboard` 和管理端会话使用；前端不得直接调用 internal API。
+
+> **契约裁决（yst 2026-08-03，承接 #5372）**：`GET /internal/order/designer-list` 仅扩展既有 `keyword` 对真实 `groupCode` 的模糊搜索，**保留原响应字段，不新增 `teamNo`**；对外 `/admin/order/list` 与 `/admin/profile/orders` 返回 `teamNo: String|null`，user-service 在公开边界执行 `teamNo = groupCode`。
+
+---
+
+## 三、接口详情与搜索口径
+
+### 1. 工作台与我的订单
+
+#### `GET /admin/profile/dashboard`
+
+新增响应字段路径：
+
+| 角色/区域 | 字段路径 | 类型 |
+|-----------|----------|------|
+| 管理员、定制师即将出行 | `data.upcomingTrips[].teamNo` | `string \| null` |
+| 房务即将入住 | `data.upcomingTrips[].teamNo` | `string \| null` |
+| 房务待办卡片 | `data.todoCards[].teamNo` | `string \| null` |
+
+#### `GET /admin/profile/orders`
+
+- `data.records[].teamNo: string | null`，真实值来自 order-v2 `groupCode`。
+- `keyword` 的 OR 搜索范围扩展为：订单号、团号、联系人姓名、产品名。
+- 原响应 `groupCode` 保留兼容。
+
+### 2. 订单管理列表 `GET /admin/order/list`
+
+- 新增 `data.records[].teamNo: string | null`，值来自真实 `groupCode`。
+- 保留 `data.records[].groupCode`。
+- `keyword` 搜索规则：
+  - 订单号、团号、联系人姓名、产品名：模糊匹配；
+  - 完整手机号：精确匹配；
+  - 各条件保持 OR 语义。
+
+示例字段值：
+
+| 字段 | 示例 |
+|------|------|
+| `orderId` | `"2045390643479412737"` |
+| `orderNo` | `"HL20260731123456"` |
+| `groupCode` | `"26-0801"` |
+| `teamNo` | `"26-0801"` |
+
+### 3. 合同
+
+#### `GET /v3/admin/contract/list`
+
+新增 query：
+
+| 字段 | 类型 | 必填 | 规则 |
+|------|------|------|------|
+| `teamNo` | `string` | 否 | 模糊匹配 `order_main.team_no`；空白按未传处理 |
+
+新增响应字段 `data.records[].teamNo: string | null`。
+
+#### `GET /v3/admin/contract/<id>`
+
+新增响应字段 `data.teamNo: string | null`。
+
+下列 ID 以 JSON String 返回：`contractId`、`orderId`、`schemeId`；详情中的 `travelers[].travelerId` 及状态日志中的 `logId`、`contractId` 同样按字符串处理。`schemeId`、`travelerId` 等可空字段保持 `null`。
+
+### 4. 评价
+
+#### `GET /v3/admin/review/list`
+
+- 新增 `data.records[].teamNo: string | null`。
+- `keyword` 保留原 `content`、`userNickname`、`orderNo`、`targetName` 的 OR 语义，并新增真实 `teamNo` 模糊匹配。
+
+#### `GET /v3/admin/review/<reviewId>`
+
+新增 `data.teamNo: string | null`。评价与订单等雪花 ID 继续按字符串消费。
+
+### 5. 司机险任务 `GET /admin/fleet/insurance/tasks`
+
+新增 query：
+
+| 字段 | 类型 | 必填 | 规则 |
+|------|------|------|------|
+| `teamNo` | `string` | 否 | 最长 64；trim 后模糊匹配任务真实 `team_no`，**不匹配 `order_no`** |
+
+新增 `data.records[].teamNo: string | null`：
+
+- 新任务保存派单时的真实团号快照；
+- 历史任务没有快照时返回 `null`，不伪造、不回填 `orderNo`；
+- `taskId`、`driverId`、`assignmentId`、`orderId`、`insuranceOrderId`、`handledBy` 均作为 JSON String（可空字段允许 `null`）。
+
+### 6. 司机详情 `GET /admin/fleet/drivers/<driverId>`
+
+- `data.relatedOrders[].teamNo: string | null` 为 canonical 团号。
+- `data.relatedOrders[].groupNo` 保留兼容。
+- `teamNo` 无真实来源时返回 `null`，不从 `orderNo` 或 `groupNo` 推导。
+
+### 7. 车务看板与矩阵
+
+已有 `teamNo` 字段继续使用，但统一收紧：
+
+- 看板 `teamNo` 查询仅匹配真实团号，不再把 `orderNo` 当团号命中；
+- 页面可见团号只显示 `teamNo`；空值显示 `-`，不得回退 `orderNo`；
+- 看板、详情、矩阵的路由、行键、拖拽、派单、改派、取消等动作继续使用 `orderId`、`assignmentId`、`assignmentGroupId` 等字符串 ID；
+- `orderNo` 可继续在明确标注“订单号”的区域展示，不得标成团号。
+
+### 8. 管理端会话
+
+- `GET /admin/message/chat/conversations`：`data.records[].teamNo: string | null`。
+- 四个打开会话接口：`data.order.teamNo: string | null`。
+- order-v3 不可达、订单无团号或历史摘要无值时，`teamNo` 返回 `null`，绝不回退 `orderNo`。
+- `bizId`、`peerAdminId`、`requirementId` 等雪花 ID 作为字符串处理。
+
+### 9. 房务选单池、我的订单、待办与对账
+
+- 选单池、我的接单、全部接单的 `keyword` 在原订单号/客人姓名/电话/产品名 OR 搜索基础上增加真实团号模糊匹配。
+- 待办 `keyword` 保持 `title`/`reason` OR 搜索，并增加按真实团号预解析订单 ID；筛选在分页前生效。
+- 相关列表项和月度对账酒店订单明细新增 `teamNo: string | null`。
+- 房务工作台通过 order-v3 → user-service Feign 链路透传同一字段；下游降级时字段保持 `null`。
+
+---
+
+## 四、前端正确调用与展示
+
+1. 页面展示团号只读 `teamNo`，空值显示 `-`；不要使用 `orderNo`、`groupCode` 或 `groupNo` 做运行时回退。
+2. 订单管理已有代码可继续使用 `groupCode`，但新改页面统一迁移到 canonical `teamNo`。
+3. 明确标注“订单号”的区域可以继续显示 `orderNo`；“团号”区域不得混入订单号。
+4. 搜索框按各接口契约传参：
+   - 合同、司机险使用独立 query `teamNo`；
+   - profile orders、订单列表、评价、房务列表使用原 `keyword`；
+   - 车务看板使用既有 `teamNo` 参数，但其语义已收紧为只查真实团号。
+5. 所有雪花 ID 从响应到 store、路由参数、表格 row key 和动作 payload 全程保持字符串。禁止 `parseInt`、一元 `+`、`Number()` 或数值排序。
+6. `frontend_status` 必须保持 `pending`；只有前端按自身流程完成、验证并回填合法引用后才能迁移状态，后端不得代填。
+
+---
+
+## 五、边界行为
+
+- 真实团号未生成：`teamNo: null`，页面显示 `-`。
+- 历史司机险任务没有团号快照：`teamNo: null`，不做订单号回退。
+- order-v3/Feign 降级：工作台或会话中 `teamNo` 可为 `null`，页面不得报错。
+- 独立 `teamNo` 参数为空白：按未传处理。
+- 团号关键词搜索在数据库分页前生效；不得仅过滤当前页。
+- 原有 `orderNo`、`groupCode`、`groupNo` 及其他响应字段保持兼容。
+- 本次为只读字段扩展和查询语义扩展，不改变订单状态机、合同状态机、评价审核、房务接单、车务派单和聊天权限。
+
+---
+
+## 六、展示与分页守恒
+
+- 同一字符串 `orderId` 在工作台、合同、评价、车务、房务与聊天响应中的非空 `teamNo` 必须一致。
+- 新字段与搜索扩展不增删业务状态，不改变状态标签、颜色、权限、排序主键或动作参数。
+- 合同、评价、司机险、房务等分页列表必须在数据库分页前应用团号条件；`total` 与切页结果守恒，禁止仅过滤当前页。
+- 房务 `todoCards` 与 `upcomingTrips` 中同一订单的 `teamNo` 必须一致；OPEN 聚合与历史分页均遵循相同真实团号来源。
+
+---
+
+## 七、不影响范围
+
+- 不删除 `orderNo`、`groupCode`、`groupNo`。
+- 不改变任何写接口的稳定 ID 入参。
+- 不授权前端直连 order-v3 internal API。
+- 不代表后端已合并、网关已放行、测试服已部署或前端已适配。
+- `D:/work2/hl-ui` 未修改；前端变更由前端 owner 独立完成。
+
+---
+
+## 验证证据（已完成项与剩余门禁）
+
+- [x] PR #5386 已合并至 `dev-v3@07834e4c5`；合并前独立只读复审 P0/P1=0、唯一 P2（profile/orders 镜像缺 displayStatus/displayStatusLabel/updateTime 透传）已修复并回归。
+- [x] 全量验证通过：order-v2 3496 tests、order-v3 7272 tests、user 3512 tests、fleet 2887 tests，全 0 failures；fleet spotless:check 通过；`FleetInsuranceTaskTeamNoMysqlTest` 以外部 MySQL 8 实跑 3/3。证据：`D:/tmp/hl5368-fleet-verify-final2.log`、`D:/tmp/hl5368-user-test4.log`。
+- [x] 4 服务已部署 TEST：order-v2 task `03b0fecb`、order-v3 `2b54e87b`、user `258865cf`、fleet `d290d667`（均 success）。
+- [x] 网关实测（`api.test.1814.love:9443`）：profile/orders 返回 `teamNo=groupCode` 且 keyword 团号搜索 total 正确；`/admin/order/list` 同；contract list 团号过滤分页前生效（精确 total=1/模糊 total=2）且 detail 返回 teamNo；fleet insurance tasks 返回并可按 teamNo 查询（命中 4/不存在 0）；fleet board teamNo 搜索仅匹配真实团号（orderNo 片段不命中）；chat 订单会话返回 teamNo、非订单会话 null；house 月度对账返回 teamNo；所有雪花 ID 均 JSON String；同一订单 2079576729147338754 在 contract 与月度对账均返回 `26-4165`。证据：`D:/tmp/hl5368-gateway-evidence/gateway-evidence.md`。
+- [ ] OpenAPI/oasdiff 与 Spring Cloud Contract 仍未配置（`not_configured`）；已用上述生产者/消费者 JUnit 与真实网关 HTTP 作为人工回退证据。
+- [ ] 测试环境 review 列表与 grab-pool 无业务数据（total=0），团号 OR 搜索由 Mapper 单测覆盖，未做真数据命中验证。
+- [ ] 前端完成展示、搜索、路由与动作回归后，由前端 owner 更新 `frontend_status`；当前保持 `pending`。
+
+---
+
+## 八、相关文档
+
+- 后端 Issue: [wx/HL#5368](https://git.1814.love:8443/wx/HL/issues/5368)
+- 后端 Draft PR: [wx/HL#5386](https://git.1814.love:8443/wx/HL/pulls/5386)
+- 前端交接 Issue: `wx/hl-api-changelog#64`
+- 历史车务契约: `changelogs-v2/2026-07/85_5156_车务看板与矩阵主标识显示团号-前端待处理-管理后台.md`（其中团号空值回退订单号的建议被本次口径取代）