hl-api-changelog/changelogs-v2/2026-08/07_5633_订单详情补核单状态字段-修改接口-管理后台.md

schema, ticket, title, consumer, change_type, author, 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	author	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	5633	订单详情补核单状态字段	admin	修改接口	yst(GIT)	deployed	verified	implemented	mmg	hl-admin@18f8e23b9b2c77a81fed3de87fe9a7b94ff3b201	v2.1		PR #5635 已合并 dev-v3；2026-08-10 复核确认测试服已部署、reviewStatus/reviewStatusName 经网关实测在出参中（见文末验证证据章节）。管理后台待接入。	2026-08-10	dev-v3

🔧【修改接口·管理后台】订单详情补核单状态字段 (#5633)

PR：#5635 ｜ 服务：hl-order-service-v3 ｜ 更新时间：2026-08-07 ｜ 消费端：管理后台

1. 接口背景

订单详情页原有的「核单中」徽标取自 flowStatus=REVIEWING（订单流程状态），而核单列表页按 review_status（核单任务状态）分 tab，两者是两个不同字段：详情文案「核单中」与列表 tab 文案「核算中」字序不一致，导致用户在详情看到「核单中」后到核单列表找不到对应 tab，产生「单丢了」的误判。

本次在订单详情出参 main 段补齐 reviewStatus / reviewStatusName 两个字段，与核单列表 tab 使用同一枚举、同一文案，消除详情与列表的口径歧义。

2. 变更清单

#	接口名	方法	路径	变更类型	说明
1	订单详情	GET	/v3/admin/order/{id}	修改	出参 data.main 段新增 reviewStatus、reviewStatusName 两个字段；其余字段与行为不变

3. 接口详情

3.1 订单详情

• 接口说明：查询单个订单的详情聚合数据（主单 + 各 Tab 数据段），本次变更只涉及 data.main 段。
• 使用场景：管理后台打开订单详情页。
• 认证：需要管理后台登录态和订单查看权限。
• 幂等性：是，只读查询。
• 限流：未声明接口级独立限流规则。

4. 接口入参

4.1 路径参数 / Query 参数

字段	位置	类型	必填	说明与校验
id	Path	String(Long)	是	订单 ID，必须为正整数；按字符串传递，避免大整数精度损失

无 Query 参数。

4.2 请求体字段

GET 请求无请求体。

5. 出参字段

响应类型：Result<OrderDetailRespVO>。本次变更集中在 data.main（OrderMainVO）段，下表只列出与本次变更相关的主单状态字段簇；main 段其余字段及 tags / overview 等其他数据段均不变。

5.1 统一响应外层

字段	类型	可空	说明
code	Integer	否	成功为 200；失败见 §7
message	String	否	结果说明
data	Object/null	失败时为空	成功时为订单详情聚合数据
traceId	String	是	链路追踪 ID
success	Boolean	否	code=200 时为 true

5.2 data.main 状态字段簇

字段	类型	可空	说明
id	String(Long)	否	订单 ID，按字符串返回
orderNo	String	否	订单号
orderStatus	String	否	订单主状态枚举值（6 主状态）
orderStatusName	String	否	订单主状态中文名
flowStatus	String	是	订单流程细状态枚举值；REVIEWING 表示流程处于核单环节，不等于核单任务状态
flowStatusName	String	是	订单流程细状态中文名（如「核单中」）
reviewStatus	String/null	是	本次新增。核单任务状态枚举值，对应 order_main.review_status，与核单列表 tab 同枚举；取值见 §6
reviewStatusName	String/null	是	本次新增。核单任务状态中文名，与核单列表 tab 文案一字不差；取值见 §6
flowStep	Integer/null	是	线性 6 步当前步序号（1-6=进行中各步；null=已取消终态）
flowStepTotal	Integer	否	线性步骤总数，固定 6
flowStepName	String/null	是	当前步中文名
flowStepCode	String/null	是	当前步编码
flowStepStatus	String/null	是	当前步状态

main 段其余字段（金额、日期、来源、合同/保险/退款状态徽标等）本次无变化，沿用既有契约。

6. 枚举 / 数据字典

6.1 main.reviewStatus / main.reviewStatusName

所属字段：data.main.reviewStatus、data.main.reviewStatusName ｜ 类型：String/null ｜ 可空：是

reviewStatus 值	reviewStatusName 值	说明
NONE	待核算	尚未生成核单任务；对齐核单列表归一逻辑，与 PENDING 同显「待核算」，不单独显示「未核单」
PENDING	待核算	核单任务待处理
IN_PROGRESS	核算中	核单任务进行中
COMPLETED	已完成	核单任务已完成
null	null	订单尚无 review_status 值（如未进入核单流程的订单）；此时两字段均为 JSON 空值，不是字符串 "null"

容错规则：

• reviewStatus 为 null 时，reviewStatusName 也为 null，不报错。
• reviewStatus 为无法识别的值时，reviewStatusName 原样返回该值，接口不抛错。

与 flowStatus 的关系：flowStatus=REVIEWING 表示订单流程走到核单环节（中文名「核单中」），是流程维度；reviewStatus 是核单任务自身的状态机维度，与核单列表 tab 同源。两者并存、语义不同，前端展示核单任务状态时以 reviewStatus / reviewStatusName 为准。

7. 错误码

code	含义	触发场景
200	查询成功	正常返回订单详情
400	请求参数错误	id 不是正整数
401	未登录或登录态失效	缺少或携带无效的管理后台访问令牌
403	无访问权限	登录态、角色或权限不允许访问
581007	订单不存在	id 对应订单不存在（含已软删除）

8. 示例

8.1 典型成功：核单任务进行中

请求：

GET /v3/admin/order/9223372036854775000
Authorization: Bearer <管理后台访问令牌>

无请求体。

响应（只截取 data.main 状态字段簇，其余字段省略）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "main": {
      "id": "9223372036854775000",
      "orderNo": "HL20260801000001",
      "orderStatus": "CONFIRMED",
      "orderStatusName": "已确认",
      "flowStatus": "REVIEWING",
      "flowStatusName": "核单中",
      "reviewStatus": "IN_PROGRESS",
      "reviewStatusName": "核算中",
      "flowStep": 5,
      "flowStepTotal": 6,
      "flowStepName": "核单结算",
      "flowStepCode": "SETTLEMENT",
      "flowStepStatus": "IN_PROGRESS"
    }
  },
  "traceId": null,
  "success": true
}

8.2 边界情况：尚无核单任务状态（reviewStatus 为 null）

场景说明：订单尚未进入核单流程，order_main.review_status 为 NULL，两字段均返回 JSON 空值；前端按「无核单任务状态」处理，不要按字符串 "null" 判断。

请求：

GET /v3/admin/order/900000000002
Authorization: Bearer <管理后台访问令牌>

无请求体。

响应（只截取 data.main 状态字段簇）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "main": {
      "id": "900000000002",
      "orderNo": "HL20260802000002",
      "orderStatus": "PENDING",
      "orderStatusName": "待确认",
      "flowStatus": "AWAITING_CONFIRM",
      "flowStatusName": "待确认",
      "reviewStatus": null,
      "reviewStatusName": null,
      "flowStep": 2,
      "flowStepTotal": 6,
      "flowStepName": "待确认",
      "flowStepCode": "CONFIRM",
      "flowStepStatus": "IN_PROGRESS"
    }
  },
  "traceId": null,
  "success": true
}

另：reviewStatus=NONE 时 reviewStatusName 返回「待核算」（与 PENDING 同文案，对齐核单列表归一逻辑），见 §6。

8.3 业务失败：订单不存在

请求：

GET /v3/admin/order/999999999999
Authorization: Bearer <管理后台访问令牌>

无请求体。

响应：

{
  "code": 581007,
  "message": "订单不存在",
  "data": null,
  "traceId": null,
  "success": false
}

9. 业务边界

• 适用：所有 v3 订单的详情查询；需要展示「核单任务状态」（与核单列表 tab 口径一致）的场景。
• 不适用：判断订单流程进度仍用 flowStatus / flowStep 等流程字段，reviewStatus 只表达核单任务自身状态，不能替代流程状态。
• 特殊边界：
  • 未进入核单流程的订单 reviewStatus 为 null，属正常数据，不是异常。
  • NONE 与 PENDING 展示文案同为「待核算」，与核单列表 tab 完全一致；需要区分「未生成任务」与「任务待处理」时用 reviewStatus 枚举值判断，不要用中文名判断。

10. 修改前后对比

10.1 字段级对比（data.main 段）

字段	修改前	修改后
reviewStatus	不存在	新增，String/null，核单任务状态枚举值
reviewStatusName	不存在	新增，String/null，核单任务状态中文名（与核单列表 tab 同文案）
其余字段	不变	不变

10.2 行为级对比

维度	修改前	修改后
详情页核单状态来源	只有 flowStatus=REVIEWING（文案「核单中」），与核单列表 tab 口径不一致	新增 reviewStatus / reviewStatusName，与核单列表 tab 同枚举、同文案
接口签名	Result<OrderDetailRespVO>	不变，仅出参多 2 个字段
入参 / 错误码	不变	不变

11. 影响评估 / 回滚

• 兼容性：纯新增出参字段，向后兼容；未接入新字段的前端版本不受影响，可继续按原字段渲染。
• 破坏兼容：无。
• 前端同步上线：不要求同步上线；详情页核单徽标切换到 reviewStatusName 可在后端发布后任意时间进行。
• 回滚方案：还原 PR #5635 对应提交即可，main 段不再返回这两个字段；前端读取不到时按字段缺失处理（undefined），不会解析报错。

12. 注意事项

• reviewStatusName 文案与核单列表 tab 一字不差：「待核算 / 核算中 / 已完成」；不要在前端自行映射文案，直接使用该字段，避免再次出现字序不一致。
• NONE 与 PENDING 同显「待核算」是有意对齐核单列表的归一逻辑，不是 bug。
• reviewStatus 为 null 时 reviewStatusName 必为 null；reviewStatus 为非法值时 reviewStatusName 原样返回该值，接口不抛错。
• main.id 等 Long 型 ID 按字符串序列化，前端按字符串处理，避免大整数精度丢失。

13. 关联 / 联系人

• Issue：#5633
• PR：#5635
• Commit：c378061b08
• 后端负责人：腰苏图

验证证据（2026-08-10 复核回填，wx）

本条 changelog 2026-08-07 推送时 backend_status=implemented（非法枚举且未部署），违反「测试服部署+实测后才通知前端」流程。2026-08-10 复核补齐部署与验证证据如下：

• 测试服 hl-order-service-v3 运行版本为 2026-08-10 15:10 构建（dev-v3），晚于 PR #5635 合并点（2026-08-07 14:25），本变更代码已在运行实例中。
• GET /v3/admin/order/{orderId} 经网关 9443 + 真 admin token 实测：data.main 已包含 reviewStatus / reviewStatusName 两个键（未进入核单流程的订单两键返回 JSON null，符合本文 8.2 边界示例）。