wx/hl-api-changelog

派生 0

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

2026-07-19 10:42:52 +08:00

10 KiB

原始文件 Blame 文件历史

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

PR: #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	页面文案：`待核算 / 核算中 / 已完成`

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

请求与响应示例

请求

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

响应片段

{
  "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	页面文案：`待核算 / 核算中 / 已完成`

响应示例

{
  "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
PR: #5067
Merge commit: f60241f3d

10 KiB 原始文件 Blame 文件历史 Unescape Escape

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

1. 关键变化

2. 变更接口清单

3. 接口详情

3.1 核团核算任务列表

Query 入参

受影响的响应字段

请求与响应示例

3.2 查询核团详情

受影响的响应字段

响应示例

4. 枚举与状态映射

历史数据兼容

列表筛选规则

5. 修改前后对比

6. 前端适配清单

7. 错误与边界行为

8. 不影响范围

9. 影响评估与回滚

10. 后端验证与发布状态

11. 历史契约说明

12. 关联链接

10 KiB

原始文件 Blame 文件历史

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