# 【修改接口·管理后台】核团核算状态改用 `review_status`（#5066）

> **PR**: [#5067](https://git.1814.love:8443/wx/HL/pulls/5067) | **服务**: `hl-order-service-v3` | **更新时间**: 2026-07-19 10:22

## 1. 关键变化

> ⚠️ 两个接口的字段名 `settlementStatus` / `settlementStatusName` 均保持不变，但字段的数据来源、可选枚举和业务语义已经变化。前端不得继续复用财务结算状态字典。

- 核团核算状态的数据来源由 `order_main.settlement_status` 改为 `order_main.review_status`。
- 页面状态统一为：
  - `PENDING`：待核算
  - `IN_PROGRESS`：核算中
  - `COMPLETED`：已完成
- 列表查询参数名仍为 `settlementStatus`，但合法值改为 `PENDING / IN_PROGRESS / COMPLETED`。
- 旧值 `NONE` 不再是合法查询参数；历史 `review_status = NONE / NULL` 的订单统一投影为 `PENDING / 待核算`。
- 本次仅调整核团页面的查询和返回投影，不修改财务复核及结算完成所使用的 `settlement_status`。

## 2. 变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 核团核算任务列表 | GET | `/v3/admin/order-settlement/tasks` | 修改接口 | 筛选和返回状态改用 `review_status`；参数名 `settlementStatus` 保持不变 |
| 2 | 查询核团详情 | GET | `/v3/admin/order/{orderId}/settlement/return-detail` | 修改接口 | `orderInfo` 中的核算状态改用 `review_status` 投影 |

## 3. 接口详情

### 3.1 核团核算任务列表

`GET /v3/admin/order-settlement/tasks`

- **认证**：需要管理后台 JWT。
- **幂等性**：是，只读查询。
- **请求体**：无。
- **响应结构**：`Result<PageResult<SettlementTaskRespVO>>`。
- 分页、关键词、出发日期筛选和列表范围均保持不变。

#### Query 入参

| 字段 | 类型 | 必填 | 合法值 | 说明 |
|---|---|---|---|---|
| `settlementStatus` | string | 否 | `PENDING` / `IN_PROGRESS` / `COMPLETED` | 核团页面核算状态；字段名保留，实际筛选 `order_main.review_status` |

其他 Query 参数保持不变：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `page` | number | 否 | 当前页码，默认 `1` |
| `pageSize` | number | 否 | 每页条数，默认 `20`，范围 `1` 到 `100` |
| `keyword` | string | 否 | 按订单号、团号、产品名模糊查询 |
| `departureDateFrom` | string | 否 | 出发日期开始，格式 `yyyy-MM-dd` |
| `departureDateTo` | string | 否 | 出发日期结束，格式 `yyyy-MM-dd` |

#### 受影响的响应字段

| 字段 | JSON 类型 | 修改后说明 |
|---|---|---|
| `data.records[].settlementStatus` | string | 核团核算状态：`PENDING / IN_PROGRESS / COMPLETED` |
| `data.records[].settlementStatusName` | string | 页面文案：`待核算 / 核算中 / 已完成` |

列表中的其他字段、分页结构和排序规则均保持不变。

#### 请求与响应示例

**请求**

```http
GET /v3/admin/order-settlement/tasks?page=1&pageSize=10&settlementStatus=IN_PROGRESS
Authorization: Bearer <JWT>
```

**响应片段**

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "orderId": "2077233886248534018",
        "orderNo": "HL202607180001",
        "teamNo": "T20260718001",
        "productName": "呼伦贝尔草原 5 日游",
        "departureDate": "2026-07-20",
        "returnDate": "2026-07-24",
        "peopleCount": 3,
        "peopleSummary": "2成人1婴儿",
        "systemBalanceAmount": 0.00,
        "settlementStatus": "IN_PROGRESS",
        "settlementStatusName": "核算中"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  },
  "traceId": null,
  "success": true
}
```

### 3.2 查询核团详情

`GET /v3/admin/order/{orderId}/settlement/return-detail`

- **认证**：需要管理后台 JWT。
- **幂等性**：是，只读查询。
- **请求体**：无。
- **路径参数和响应整体结构保持不变。**

#### 受影响的响应字段

| 字段 | JSON 类型 | 修改后说明 |
|---|---|---|
| `data.orderInfo.settlementStatus` | string | 核团核算状态：`PENDING / IN_PROGRESS / COMPLETED`，来源为 `review_status` |
| `data.orderInfo.settlementStatusName` | string | 页面文案：`待核算 / 核算中 / 已完成` |

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "orderInfo": {
      "orderId": "2077233886248534018",
      "orderNo": "HL202607180001",
      "settlementStatus": "COMPLETED",
      "settlementStatusName": "已完成"
    },
    "travelers": [],
    "driverVehicles": [],
    "receivableItems": [],
    "collectionRecords": []
  },
  "traceId": null,
  "success": true
}
```

> 示例仅展示本次相关字段；详情接口原有的订单信息、出行人、司机车辆、应收和收款字段均保持不变。

## 4. 枚举与状态映射

| `settlementStatus` | `settlementStatusName` | 核团页面语义 |
|---|---|---|
| `PENDING` | 待核算 | 尚未开始核算 |
| `IN_PROGRESS` | 核算中 | 已开始录入或处理核算数据 |
| `COMPLETED` | 已完成 | 核单已经提交完成 |

### 历史数据兼容

| `order_main.review_status` 实际值 | 接口返回 `settlementStatus` | 接口返回 `settlementStatusName` |
|---|---|---|
| `NULL`、空值或 `NONE` | `PENDING` | 待核算 |
| `PENDING` | `PENDING` | 待核算 |
| `IN_PROGRESS` | `IN_PROGRESS` | 核算中 |
| `COMPLETED` | `COMPLETED` | 已完成 |

### 列表筛选规则

| Query 参数 | 后端筛选行为 |
|---|---|
| 不传 `settlementStatus` | 不追加核算状态过滤，返回符合其他条件的任务 |
| `PENDING` | 匹配 `review_status = PENDING / NONE / NULL`，兼容历史订单 |
| `IN_PROGRESS` | 精确匹配 `review_status = IN_PROGRESS` |
| `COMPLETED` | 精确匹配 `review_status = COMPLETED` |
| `NONE` 或其他值 | 参数校验失败，HTTP 200、业务码 `400` |

## 5. 修改前后对比

| 项目 | 修改前 | 修改后 |
|---|---|---|
| 接口字段名 | `settlementStatus` / `settlementStatusName` | 保持不变 |
| 状态数据源 | 财务结算态 `settlement_status` | 核团核算流程态 `review_status` |
| 查询参数枚举 | `NONE / PENDING / COMPLETED` | `PENDING / IN_PROGRESS / COMPLETED` |
| `PENDING` 文案/语义 | 待财务复核 | 待核算 |
| `COMPLETED` 文案/语义 | 已结算 | 已完成 |
| 处理中状态 | 无独立值 | 新增 `IN_PROGRESS / 核算中` |
| 历史 `NONE / NULL` 返回值 | `NONE / 未结算` | 归一为 `PENDING / 待核算` |

## 6. 前端适配清单

- [ ] 核团状态下拉改为 `PENDING / IN_PROGRESS / COMPLETED`。
- [ ] 下拉文案依次使用“待核算 / 核算中 / 已完成”。
- [ ] 删除核团页面向接口传递 `NONE` 的逻辑。
- [ ] 不修改 Query 参数名，继续传 `settlementStatus`。
- [ ] 不修改响应字段名，继续读取 `settlementStatus` 和 `settlementStatusName`。
- [ ] 不再复用财务结算状态字典解释这两个核团接口。
- [ ] 若前端自行维护状态文案，必须同步更新；优先使用后端返回的 `settlementStatusName`。
- [ ] 对历史未开始核算的订单统一按 `PENDING / 待核算` 展示。

## 7. 错误与边界行为

| 场景 | 行为 |
|---|---|
| 未传 `settlementStatus` | 正常查询，不按核算状态过滤 |
| 传 `settlementStatus=NONE` | 参数校验失败，HTTP 200、业务码 `400` |
| 传其他非法状态 | 参数校验失败，HTTP 200、业务码 `400` |
| 历史 `review_status=NONE/NULL` | 列表和详情均返回 `PENDING / 待核算` |
| 房务角色访问 | 保持原权限规则，不因本次变更放开 |
| 订单不存在 | 详情接口保持原订单不存在错误 |
| 空列表 | 返回成功响应，`records=[]` |

## 8. 不影响范围

- 财务复核和财务结算完成仍使用 `order_main.settlement_status`。
- 核单提交后写入 `settlement_status=PENDING`、财务确认后写入 `settlement_status=COMPLETED` 的流程不变。
- 两个接口的 URL、HTTP 方法、认证方式、分页结构和其他字段均不变。
- 不涉及数据库表结构或数据迁移。
- 不影响核团详情中的出行人、司机车辆、应收明细和收款明细契约。
- 不影响其他财务页面对 `settlementStatus` 的既有使用；本次语义仅适用于本文列出的两个核团接口。

## 9. 影响评估与回滚

- **字段结构是否破坏兼容**：否，字段名和 JSON 类型不变。
- **业务语义是否变化**：是，同名字段的数据来源、枚举和中文含义均发生变化。
- **前端是否需要同步适配**：是，核团状态下拉和本地状态字典必须同步。
- **是否影响已有数据**：不改写已有数据；读取时兼容历史 `NONE / NULL`。
- 回滚 PR #5067 后，两个接口会重新使用旧的财务结算状态语义。
- 因 `PENDING`、`COMPLETED` 是同名但不同含义的值，前后端版本回滚必须同步，不能仅根据字段是否存在判断版本。
- 无数据库迁移，无需清理或恢复数据。

## 10. 后端验证与发布状态

- PR #5067 原定向测试：48 tests，0 failures，0 errors。
- 与审计分支融合后的核团状态/快照/Feign 定向测试：121 tests，0 failures，0 errors。
- 融合后的 `hl-order-service-v3` 全量测试：5,797 tests，0 failures，0 errors，15 条件跳过。
- PR #5067 已于 2026-07-19 10:22 合并到 `dev-v3`。
- 本文未取得测试环境部署或网关真实接口调用证据；合并完成不等同于测试环境已经生效。

## 11. 历史契约说明

| 文档/PR | 说明 | 当前有效性 |
|---|---|---|
| Changelog `18_5055_核团核算列表详情-修改接口-管理后台.md` / PR #5058 | 首次交付核团列表与详情聚合接口 | 接口结构及非状态字段仍有效 |
| 上述文档中的 `settlementStatus` 枚举和示例 | 使用 `NONE / PENDING / COMPLETED` 及“未结算 / 待财务复核 / 已结算” | 已被本文纠正，不再作为核团页面契约 |
| PR #5067 / Issue #5066 | 核团核算状态改用 `review_status` | 当前最新契约 |

## 12. 关联链接

- **Issue**: [#5066](https://git.1814.love:8443/wx/HL/issues/5066)
- **PR**: [#5067](https://git.1814.love:8443/wx/HL/pulls/5067)
- **Merge commit**: [f60241f3d](https://git.1814.love:8443/wx/HL/commit/f60241f3d6fdb2f36c091dc93d0232f2dcfe4775)