hl-api-changelog/changelogs-v2/2026-07/31_5368_非订单页面统一补齐真实团号与团号搜索-修改接口-管理后台.md

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5368	非订单页面统一补齐真实团号与团号搜索	admin	修改接口	deployed	verified	verified	Pi	hl-admin@4c8bdb97c89fa399e5fbb13240ea082f64fefc59	v2.1	2026-08-03	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/）。管理后台已由 Pi 领取并开始逐页核对真实团号消费。	2026-08-04	dev-v3

管理端：非订单页面统一补齐真实团号与团号搜索

服务: hl-user-service、hl-order-service-v2、hl-order-service-v3、hl-fleet-service Issue: wx/HL#5368 前端交接 Issue: wx/hl-api-changelog#64 日期: 2026-07-31 影响范围: 管理后台工作台、订单列表、合同、评价、车务、房务、会话等订单关联页面 候选基线: dev-v3@07834e4c5（PR #5386 已合并） 合并 PR: #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 替代

前端统一展示示例：

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。

⚠️ v1/v3 切换口径（2026-08-04 决策）

合同页全量使用 v3 端点，不再使用 v1：

• 创建合同：POST /v3/admin/contract/create、POST /v3/admin/contract/create-by-scheme
• 刷新合同状态：GET /v3/admin/contract/{id}/status（实测成功）
• 列表、详情、作废、下载、重发短信：均走 /v3/admin/contract/*

v1（/admin/contract/*）不再用于合同页：

• v1 存量历史合同（约 20 条，SIGNING/VOIDED）自然消亡，不迁移、不做兼容转换；
• v1/v3 合同数据隔离不互通：v3 创建的合同 contractId 不能调 v1 接口（返回错误码 510001）；v1 创建的旧合同不会出现在 v3 列表/详情中。

前端合同页应统一按上述 v3 端点实现，移除 v1 合同调用，不得混用两套接口。

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 独立完成。

---

验证证据（已完成项与剩余门禁）

• PR #5386 已合并至 dev-v3@07834e4c5；合并前独立只读复审 P0/P1=0、唯一 P2（profile/orders 镜像缺 displayStatus/displayStatusLabel/updateTime 透传）已修复并回归。
• 全量验证通过：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。
• 4 服务已部署 TEST：order-v2 task 03b0fecb、order-v3 2b54e87b、user 258865cf、fleet d290d667（均 success）。
• 网关实测（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
• 后端 Draft PR: wx/HL#5386
• 前端交接 Issue: wx/hl-api-changelog#64
• 历史车务契约: changelogs-v2/2026-07/85_5156_车务看板与矩阵主标识显示团号-前端待处理-管理后台.md（其中团号空值回退订单号的建议被本次口径取代）