docs: 补充核团核算状态契约 (#5066)

2026-07-19 10:42:52 +08:00 · 2026-07-19 10:42:52 +08:00 · e94e8d7e6e
--- a/changelogs-v2/2026-07/64_5066_核团核算状态改用review_status-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/64_5066_核团核算状态改用review_status-修改接口-管理后台.md
@ -0,0 +1,244 @@
+# 【修改接口·管理后台】核团核算状态改用 `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)