0e911a98f3
- #5599/#5567/#5633(yst 8-06~8-07 推送时未部署测试服): 2026-08-10 复核确认代码已随 order-v3 8-10 部署上测试服,补验证证据章节(部署点位+DB 列+网关实测),backend_status 回填 deployed/gateway verified - #5444、#5730-5732: backend_status released→deployed(枚举合法化,状态语义不变) - #5784 补验证证据章节、#5788 章节结构规范化、#5797 清理 not_required 残留前端字段 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
285 行
12 KiB
Markdown
285 行
12 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "5633"
|
||
title: "订单详情补核单状态字段"
|
||
consumer: "admin"
|
||
change_type: "修改接口"
|
||
author: "yst(GIT)"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "implemented"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "hl-admin@18f8e23b9b2c77a81fed3de87fe9a7b94ff3b201"
|
||
target_release: "v2.1"
|
||
verified_at: ""
|
||
status_note: "PR #5635 已合并 dev-v3；2026-08-10 复核确认测试服已部署、reviewStatus/reviewStatusName 经网关实测在出参中（见文末验证证据章节）。管理后台待接入。"
|
||
updated_at: "2026-08-10"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 🔧【修改接口·管理后台】订单详情补核单状态字段 (#5633)
|
||
|
||
> **PR**：[#5635](https://git.1814.love:8443/wx/HL/pulls/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 典型成功：核单任务进行中
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
GET /v3/admin/order/9223372036854775000
|
||
Authorization: Bearer <管理后台访问令牌>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
**响应**（只截取 `data.main` 状态字段簇，其余字段省略）：
|
||
|
||
```json
|
||
{
|
||
"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"` 判断。
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
GET /v3/admin/order/900000000002
|
||
Authorization: Bearer <管理后台访问令牌>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
**响应**（只截取 `data.main` 状态字段簇）：
|
||
|
||
```json
|
||
{
|
||
"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 业务失败：订单不存在
|
||
|
||
**请求**：
|
||
|
||
```http
|
||
GET /v3/admin/order/999999999999
|
||
Authorization: Bearer <管理后台访问令牌>
|
||
```
|
||
|
||
无请求体。
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"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](https://git.1814.love:8443/wx/HL/issues/5633)
|
||
- **PR**：[#5635](https://git.1814.love:8443/wx/HL/pulls/5635)
|
||
- **Commit**：[c378061b08](https://git.1814.love:8443/wx/HL/commit/c378061b08e85cc7794b23c2a49691ad4f8eb01e)
|
||
- **后端负责人**：腰苏图
|
||
|
||
## 验证证据（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 边界示例）。
|