接入 2026-05-18 推送的 v3 订单服务 25 个新接口(changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md + 18_§2_traveler模块-新增接口-管理后台.md)时,前端梳理出以下 5 处契约不明或互相冲突的地方,需后端确认后才能继续视图层接入。
changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md
18_§2_traveler模块-新增接口-管理后台.md
progressStepper.nodes[].subItems.subStatus
文档示例只见到 subStatus: "DONE",但字段表格里没列完整枚举。
subStatus: "DONE"
问题:
ASSIGN_PARALLEL
subItems[].subStatus
DONE / ACTIVE / PENDING / NOT_APPLICABLE
transportPlanIds
问题 2a:§2.1 表格 header 写"每条 17 字段",但实际列出 16 个字段。漏的是哪个?
问题 2b:transportPlanIds 类型冲突:
List<Long>
["80012345"]
前端立场:无论后端选 Long 还是 String,JSON 序列化后雪花 ID 超 Number.MAX_SAFE_INTEGER 会精度丢失,前端一律按 String 透传。强烈建议两处统一 serialize 成 String,避免 long 直接出 JSON 触发精度问题。
Number.MAX_SAFE_INTEGER
POST /v3/admin/order/{id}/traveler/add
POST /v3/admin/order/.../travelers
/add
问题:哪个是真路径?前端目前按表格实现走 /traveler/add,需后端确认或统一文档。
/traveler/add
581120
问题:同一错误码不同接口下含义不同。前端 toast 文案需要根据接口路径区分,建议后端拆开重新分配两个 code,避免后续日志/监控告警混淆。
transition
eventCode
POST /v3/admin/order/{id}/transition 入参 eventCode 引用 §6.17 / §6.18 / §6.19,但这些章节在汇总文档里只列了使用场景,没列具体的字符串枚举值清单。
POST /v3/admin/order/{id}/transition
问题:前端"确认锁单 / 关闭订单 / 触发尾款支付 / 出团 / 完结订单 / 取消..."等所有按钮在调 transition 时,具体要传哪个 eventCode 字符串?能否补一份完整枚举表(eventCode → 触发场景 → 前置状态 → 目标状态)?
5 个问题不全部确认,前端 Layer 2 视图层接入(list / detail 主聚合 + 6 Tab + 12 Modal)无法收尾。#5(transition eventCode)优先级最高,影响订单详情底部所有操作按钮的接线。
API 文件 src/api/orderV2.js 已实现 25 个函数(已 merge 到本地分支),按文档表格为准走,#2(transportPlanIds) 一律按 String 透传,#3 路径走 /traveler/add。视图层接入暂停等回复。
src/api/orderV2.js
已按代码事实修订两份 changelog 并推送到 main，commit 89a1938。请拉取最新版后继续视图层接入。
main
89a1938
changelogs-v2/2026-05/18_§2_traveler模块-新增接口-管理后台.md
NOT_APPLICABLE
2^53-1
/travelers
/traveler/list
PENDING_PAY / PENDING_COMPLETE / CUSTOMIZING / PENDING_DEPARTURE / PENDING_BALANCE / TRAVELLING / REVIEWING / SETTLED / REFUNDING / CANCELLED
AWAITING_DEPOSIT / ... / CANCELLED_BEFORE_PAY
orderStatus
flowStatus
"PENDING_DEPARTURE"
customerPhone
customerPhoneMasked
contractStatus / insuranceStatus / refundStatus / hasRefund / hasServiceStandard / hasFinanceDetail
consultantSource 不是强枚举类（无 Java enum），是字符串。值域可能为 MANUAL / SHARED / DEFAULT_ASSIGNED / ROUND_ROBIN / LINK_BOUND，且 user-service 后续可能扩展。已在 §6.4 加完整 5 值表 + ⚠️「未知值兜底为 MANUAL 标签」的规则。前端做穷举 switch 时务必有 default 分支。
consultantSource
MANUAL / SHARED / DEFAULT_ASSIGNED / ROUND_ROBIN / LINK_BOUND
如还有其他文档与实测不符的，继续提 issue。
a47588b
你提的契约问题让我反查代码，结果发现一个更底层的问题：当时代码实现的 OrderStatus / OrderFlowStatus 本身就偏离了 SRS v5.48 §0.4 的设计。我第一轮直接按代码现状写进 changelog，等于把"代码偏离设计"固化成对外契约，前端按那个接入也是错的。
OrderStatus
OrderFlowStatus
1. 代码侧（HL PR #2589）：把 OrderStatus / OrderFlowStatus 改回 SRS 设计：
REFUNDING
order_status='CANCELLED'
refund_status
AWAITING_DEPOSIT/DEPOSIT_PAID_PENDING_CONFIRM/CONFIRMED_PENDING_HOTEL...
AWAITING_PROFILE/AWAITING_HOTEL_SUBMIT/HOTEL_IN_PROGRESS/PENDING_CONFIRM/...
INITIATE_REFUND → REFUNDING
→ CANCELLED
mvn verify
2. changelog 侧（本仓 commit a47588b）：
CONFIRMED_PENDING_DEPARTURE
PENDING_DEPARTURE
AWAITING_DEPOSIT
AWAITING_PROFILE
AWAITING_DEPOSIT/DEPOSIT_PAID_PENDING_CONFIRM/...
AWAITING_PROFILE/PENDING_CONFIRM/...
REFUNDING 这个值在 refund 模块自己还有（RefundApplication.status 用，记退款申请的状态），那是另一个域的字段。本次删的只是 OrderStatus.REFUNDING（订单粗态）。前端调退款相关接口时，refund_application.status 字段里仍可能见到 "REFUNDING"，那是合法的，与本次改动无关。
RefundApplication.status
OrderStatus.REFUNDING
refund_application.status
"REFUNDING"
抱歉来回折腾一次。第一次回复时没去对设计文档，是我的责任。如果还有不符的地方继续提 issue，谢谢！
前端已消化两轮回复（subStatus / transportPlanIds / /traveler/add 路径 / 581120 / eventCode 5 处 + §6.2/§6.3 9+15 项重写）。代码 commit 见 v2.1 分支 258796fe / 7baa99af。关闭。
没有设置依赖项。
该备注对被屏蔽的用户不可见。
删除分支是永久的。虽然已删除的分支在实际被删除前有可能会短时间存在，但这在大多数情况下无法撤销。是否继续？
背景
接入 2026-05-18 推送的 v3 订单服务 25 个新接口(
changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md+18_§2_traveler模块-新增接口-管理后台.md)时,前端梳理出以下 5 处契约不明或互相冲突的地方,需后端确认后才能继续视图层接入。1. §1.3.1 主聚合
progressStepper.nodes[].subItems.subStatus枚举集不完整文档示例只见到
subStatus: "DONE",但字段表格里没列完整枚举。问题:
ASSIGN_PARALLEL节点的subItems[].subStatus完整枚举是哪些?(我们目前推测有DONE / ACTIVE / PENDING / NOT_APPLICABLE,但未确认)2. §2.1 出行人列表字段表与示例不一致 +
transportPlanIds类型在两处不同问题 2a:§2.1 表格 header 写"每条 17 字段",但实际列出 16 个字段。漏的是哪个?
问题 2b:
transportPlanIds类型冲突:List<Long>transportPlanIds是["80012345"](字符串数组)前端立场:无论后端选 Long 还是 String,JSON 序列化后雪花 ID 超
Number.MAX_SAFE_INTEGER会精度丢失,前端一律按 String 透传。强烈建议两处统一 serialize 成 String,避免 long 直接出 JSON 触发精度问题。3. §2.3 「单个出行人新增」路径文档表格与示例不一致
POST /v3/admin/order/{id}/traveler/addPOST /v3/admin/order/.../travelers(复数,无/add)问题:哪个是真路径?前端目前按表格实现走
/traveler/add,需后端确认或统一文档。4. 错误码
581120在 §2.4 和 §2.8 重复581120= 最后一个成人禁止删除581120= 原文超长问题:同一错误码不同接口下含义不同。前端 toast 文案需要根据接口路径区分,建议后端拆开重新分配两个 code,避免后续日志/监控告警混淆。
5. §1.7
transition接口的eventCode枚举集未完整展开POST /v3/admin/order/{id}/transition入参eventCode引用 §6.17 / §6.18 / §6.19,但这些章节在汇总文档里只列了使用场景,没列具体的字符串枚举值清单。问题:前端"确认锁单 / 关闭订单 / 触发尾款支付 / 出团 / 完结订单 / 取消..."等所有按钮在调 transition 时,具体要传哪个
eventCode字符串?能否补一份完整枚举表(eventCode → 触发场景 → 前置状态 → 目标状态)?影响范围
5 个问题不全部确认,前端 Layer 2 视图层接入(list / detail 主聚合 + 6 Tab + 12 Modal)无法收尾。#5(transition eventCode)优先级最高,影响订单详情底部所有操作按钮的接线。
前端临时处理
API 文件
src/api/orderV2.js已实现 25 个函数(已 merge 到本地分支),按文档表格为准走,#2(transportPlanIds) 一律按 String 透传,#3 路径走/traveler/add。视图层接入暂停等回复。已按代码事实修订两份 changelog 并推送到
main，commit89a1938。请拉取最新版后继续视图层接入。推送后文件位置
changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.mdchangelogs-v2/2026-05/18_§2_traveler模块-新增接口-管理后台.md修改内容
你提的 5 项
NOT_APPLICABLE+ 明示 subStatus 枚举同 statusList<Long>保留（正确），补全局 Jackson 规则脚注：超2^53-1自动转 String，雪花 ID 一定出 String，示例值换 19 位真实雪花/traveler/addvs/travelers/traveler/add；§2.1 list curl 也对齐 →/traveler/list顺手补的 4 项（代码实际与文档严重错位，前端验证时一定会再撞到）
PENDING_PAY / PENDING_COMPLETE / CUSTOMIZING / PENDING_DEPARTURE / PENDING_BALANCE / TRAVELLING / REVIEWING / SETTLED / REFUNDING / CANCELLED）+ 中文标签列AWAITING_DEPOSIT / ... / CANCELLED_BEFORE_PAY）+ 中文标签列orderStatusflowStatus写中文"PENDING_DEPARTURE"等）—— API 实际传/返的都是英文，中文标签前端自己映射customerPhone文档说 "admin 明文" 实际是customerPhoneMasked脱敏contractStatus / insuranceStatus / refundStatus / hasRefund / hasServiceStandard / hasFinanceDetail6 个字段 + 改字段名额外提醒
consultantSource不是强枚举类（无 Java enum），是字符串。值域可能为MANUAL / SHARED / DEFAULT_ASSIGNED / ROUND_ROBIN / LINK_BOUND，且 user-service 后续可能扩展。已在 §6.4 加完整 5 值表 + ⚠️「未知值兜底为 MANUAL 标签」的规则。前端做穷举 switch 时务必有 default 分支。如还有其他文档与实测不符的，继续提 issue。
⚠️ 第一轮回复（
89a1938）的 §6.2 / §6.3 部分作废，请改用a47588b。缘起
你提的契约问题让我反查代码，结果发现一个更底层的问题：当时代码实现的
OrderStatus/OrderFlowStatus本身就偏离了 SRS v5.48 §0.4 的设计。我第一轮直接按代码现状写进 changelog，等于把"代码偏离设计"固化成对外契约，前端按那个接入也是错的。已做修正
1. 代码侧（HL PR #2589）：把
OrderStatus/OrderFlowStatus改回 SRS 设计：OrderStatus10 项 → 9 项：删REFUNDING（SRS 决议：退款发起瞬间订单order_status='CANCELLED'，退款进度由refund_status子字段表达）OrderFlowStatus13 项 → 15 项：从支付节奏视角（AWAITING_DEPOSIT/DEPOSIT_PAID_PENDING_CONFIRM/CONFIRMED_PENDING_HOTEL...）全量重写为业务环节视角（AWAITING_PROFILE/AWAITING_HOTEL_SUBMIT/HOTEL_IN_PROGRESS/PENDING_CONFIRM/...），与 SRS 中文 1:1 对齐INITIATE_REFUND → REFUNDING改为→ CANCELLED（事件保留，目标态变）mvn verify1068 tests 0 failures 全绿2. changelog 侧（本仓 commit
a47588b）：flowStatus不再是CONFIRMED_PENDING_DEPARTURE，而是PENDING_DEPARTUREAWAITING_DEPOSIT→AWAITING_PROFILE（"待支付订金" → "待补全信息"）你需要做的
a47588b），看 §6.2 / §6.3 表 + 示例的新值AWAITING_DEPOSIT/DEPOSIT_PAID_PENDING_CONFIRM/...写的前端枚举映射全部要换名，改为AWAITING_PROFILE/PENDING_CONFIRM/...顺手提醒
REFUNDING这个值在 refund 模块自己还有（RefundApplication.status用，记退款申请的状态），那是另一个域的字段。本次删的只是OrderStatus.REFUNDING（订单粗态）。前端调退款相关接口时，refund_application.status字段里仍可能见到"REFUNDING"，那是合法的，与本次改动无关。抱歉来回折腾一次。第一次回复时没去对设计文档，是我的责任。如果还有不符的地方继续提 issue，谢谢！
前端已消化两轮回复（subStatus / transportPlanIds / /traveler/add 路径 / 581120 / eventCode 5 处 + §6.2/§6.3 9+15 项重写）。代码 commit 见 v2.1 分支 258796fe / 7baa99af。关闭。