wx/hl-api-changelog

派生 0

文件

T

API Changelog Bot 090b25a484

changelog-filename-gate / validate (push) Failing after 2s

详情

docs(changelog): 2026-08 批量补齐 author/关联联系人章节（yst格式），5558 从 v1 目录迁至 v2

2026-08-05 22:01:46 +08:00

22 KiB

原始文件 Blame 文件历史

author, schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

author	schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
yst(GIT)	hl-changelog/v2	5380	核单人员页签收口与车辆空态契约	admin	删除接口	deployed	not_required	implemented	Pi	v2.1@21dccf38d1413b098cfd5a456d3fb76611581ebb		2026-08-02	管理后台已仅保留导游、摄影师人员页签，删除领队/司机/其他人员 API 链路，并按 settlementReady/blockReasonCode 区分车辆两类空态；finalize 前重读权威 Step3。checkpoint 全量通过，业务提交 21dccf38d1413b098cfd5a456d3fb76611581ebb 已推送 origin/v2.1。网关有效登录态正向 curl 仍未完成，不标记 verified。	2026-08-02	dev-v3

⚠️【删除接口·管理后台】核单人员页签收口与车辆空态契约 (#5380)

PR: #5393 | 服务: order-v3 | 更新时间: 2026-08-01

1. 接口背景

核单页面的人员费用仅保留导游、摄影师两类。领队、司机、其他人员不再作为核单人员费用页签，原有三组查询与保存接口同步删除。

车辆费用查询同时补齐两种空结果语义：订单没有当前用车需求时，空结果可以继续核单；订单有当前用车需求但车辆费用尚未就绪时，也返回成功空结果，并通过机器可读字段明确阻断原因。

变更接口清单

#	接口名	方法	路径	变更类型	说明
1	查询领队人员费用	GET	`/v3/admin/order/:orderId/settlement/staff-fees/leaders`	删除	不再提供领队核单 Tab 查询
2	全量替换领队人员费用	PUT	`/v3/admin/order/:orderId/settlement/staff-fees/leaders`	删除	不再提供领队核单 Tab 保存
3	查询司机人员费用	GET	`/v3/admin/order/:orderId/settlement/staff-fees/drivers`	删除	不再提供司机核单 Tab 查询
4	全量替换司机人员费用	PUT	`/v3/admin/order/:orderId/settlement/staff-fees/drivers`	删除	不再提供司机核单 Tab 保存
5	查询其他人员费用	GET	`/v3/admin/order/:orderId/settlement/staff-fees/others`	删除	不再提供其他人员核单 Tab 查询
6	全量替换其他人员费用	PUT	`/v3/admin/order/:orderId/settlement/staff-fees/others`	删除	不再提供其他人员核单 Tab 保存
7	查询车辆核单草稿	GET	`/v3/admin/order/:orderId/settlement/step3/vehicles`	修改	出参新增 `settlementReady`、`blockReasonCode`，并区分两种成功空结果

人员费用继续保留以下两组接口，路径和方法不变：

Tab	查询	保存
导游	`GET /v3/admin/order/:orderId/settlement/staff-fees/guides`	`PUT /v3/admin/order/:orderId/settlement/staff-fees/guides`
摄影师	`GET /v3/admin/order/:orderId/settlement/staff-fees/photographers`	`PUT /v3/admin/order/:orderId/settlement/staff-fees/photographers`

3. 接口详情

3.1 删除：领队人员费用查询与保存

原接口名：查询领队人员费用 / 全量替换领队人员费用
原方法与路径：
- GET /v3/admin/order/:orderId/settlement/staff-fees/leaders
- PUT /v3/admin/order/:orderId/settlement/staff-fees/leaders
使用场景：已删除，不再用于核单页面。
认证：原接口要求管理后台登录态；接口删除后，即使登录态有效也返回 HTTP 404。
幂等性：不适用。
限流：无接口级特殊限流。

路径参数

字段	类型	必填	说明	校验
`orderId`	String(Long)	是	订单 ID	原校验为正整数；接口删除后不再进入参数校验

请求体

GET 无请求体。PUT 原有请求体不再接受；不得继续提交领队费用 items。

出参与错误码

两个接口均无业务成功响应。任意订单调用均返回 HTTP 404，不能用其他人员费用路径替代领队路径。

code	含义	触发场景
`404`	请求地址不存在	调用任一已删除的领队接口

业务边界

有效订单、历史订单和不存在的订单调用结果一致：路由不存在。
原有领队费用数据不构成前端可继续调用该接口的兼容理由。

示例：GET 已删除

请求：

GET /v3/admin/order/2080000000000000001/settlement/staff-fees/leaders
Authorization: Bearer JWT_TOKEN

无请求体。

响应：

{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}

示例：PUT 已删除

请求：

PUT /v3/admin/order/2080000000000000001/settlement/staff-fees/leaders
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

{
  "items": []
}

响应：

{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}

3.2 删除：司机人员费用查询与保存

原接口名：查询司机人员费用 / 全量替换司机人员费用
原方法与路径：
- GET /v3/admin/order/:orderId/settlement/staff-fees/drivers
- PUT /v3/admin/order/:orderId/settlement/staff-fees/drivers
使用场景：已删除，不再用于核单页面；车辆费用继续使用 §3.4 的车辆核单草稿查询。
认证：原接口要求管理后台登录态；接口删除后，即使登录态有效也返回 HTTP 404。
幂等性：不适用。
限流：无接口级特殊限流。

路径参数

字段	类型	必填	说明	校验
`orderId`	String(Long)	是	订单 ID	原校验为正整数；接口删除后不再进入参数校验

请求体

GET 无请求体。PUT 原有请求体不再接受；不得继续提交司机费用 items。

出参与错误码

两个接口均无业务成功响应。任意订单调用均返回 HTTP 404。司机人员费用接口与车辆核单草稿接口不是同一路由，不得改路径尾段后继续提交原司机费用请求体。

code	含义	触发场景
`404`	请求地址不存在	调用任一已删除的司机接口

业务边界

有效订单、历史订单和不存在的订单调用结果一致：路由不存在。
车辆费用只读取 /settlement/step3/vehicles 的契约；已删除司机接口不再提供车辆费用补充入口。

示例：GET 已删除

请求：

GET /v3/admin/order/2080000000000000001/settlement/staff-fees/drivers
Authorization: Bearer JWT_TOKEN

无请求体。

响应：

{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}

示例：PUT 已删除

请求：

PUT /v3/admin/order/2080000000000000001/settlement/staff-fees/drivers
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

{
  "items": []
}

响应：

{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}

3.3 删除：其他人员费用查询与保存

原接口名：查询其他人员费用 / 全量替换其他人员费用
原方法与路径：
- GET /v3/admin/order/:orderId/settlement/staff-fees/others
- PUT /v3/admin/order/:orderId/settlement/staff-fees/others
使用场景：已删除，不再用于核单页面。
认证：原接口要求管理后台登录态；接口删除后，即使登录态有效也返回 HTTP 404。
幂等性：不适用。
限流：无接口级特殊限流。

路径参数

字段	类型	必填	说明	校验
`orderId`	String(Long)	是	订单 ID	原校验为正整数；接口删除后不再进入参数校验

请求体

GET 无请求体。PUT 原有请求体不再接受；不得继续提交其他人员费用 items。

出参与错误码

两个接口均无业务成功响应。任意订单调用均返回 HTTP 404，不能用导游或摄影师路径承载其他人员费用。

code	含义	触发场景
`404`	请求地址不存在	调用任一已删除的其他人员接口

业务边界

有效订单、历史订单和不存在的订单调用结果一致：路由不存在。
“其他人员”和“其他支出”是不同契约；本次删除不改变其他支出接口。

示例：GET 已删除

请求：

GET /v3/admin/order/2080000000000000001/settlement/staff-fees/others
Authorization: Bearer JWT_TOKEN

无请求体。

响应：

{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}

示例：PUT 已删除

请求：

PUT /v3/admin/order/2080000000000000001/settlement/staff-fees/others
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

{
  "items": []
}

响应：

{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}

3.4 修改：查询车辆核单草稿

接口名：查询车辆核单草稿
方法与路径：GET /v3/admin/order/:orderId/settlement/step3/vehicles
使用场景：查询订单当前车辆核单明细及车辆费用是否已具备核单条件。
认证：需要管理后台登录态并满足订单查看权限；房务角色不可访问。
幂等性：是，只读查询。
限流：无接口级特殊限流。

路径参数

字段	类型	必填	说明	校验
`orderId`	String(Long)	是	订单 ID	正整数

无 Query 参数、无请求体。

统一响应外层

字段	类型	说明
`code`	Integer	业务码；成功为 `200`
`message`	String	结果说明
`data`	Object/null	成功时为车辆核单草稿；失败时为 `null`
`traceId`	String/null	链路追踪 ID，未返回时可为空
`success`	Boolean	`code=200` 时为 `true`

成功响应 data

字段	类型	可空	说明
`orderId`	String(Long)	否	订单 ID，按字符串返回
`version`	Long	否	车辆核单草稿版本；空结果为 `0`
`totalAmount`	Decimal	否	当前全部车辆明细金额合计；空结果为 `0.00`
`allConfirmed`	Boolean	否	当前明细是否全部已确认；有需求但费用未就绪的空结果为 `false`
`settlementReady`	Boolean	否	车辆费用是否已具备核单条件；本次新增公开字段
`blockReasonCode`	String	是	不具备核单条件时的机器可读原因；可核单时为 `null`
`items`	Array	否	当前车辆费用全量明细；无明细时为 `[]`

data.items[]

字段	类型	可空	说明
`id`	String(Long)	否	车辆核单明细 ID
`sourceType`	String	否	来源编码，见 §6.1
`sourceTypeName`	String	否	来源名称
`serviceDate`	String(date)	否	服务日期，格式 `YYYY-MM-DD`
`vehicleId`	String(Long)	是	车辆 ID
`vehiclePlate`	String	是	车牌号
`vehicleModelId`	String(Long)	是	车型 ID
`vehicleModelName`	String	是	车型名称
`driverId`	String(Long)	是	司机 ID
`driverName`	String	是	司机姓名
`amount`	Decimal	否	核单金额
`paymentMethod`	String	否	付款方式编码，见 §6.2
`paymentMethodName`	String	否	付款方式名称
`settlementConfirmStatus`	String	否	核单确认状态编码，见 §6.3
`settlementConfirmStatusName`	String	否	核单确认状态名称
`remark`	String	是	备注
`voucherUrls`	String[]	否	凭证 URL；无凭证时为 `[]`

错误码

code	含义	触发场景
`400`	请求参数错误	`orderId` 不是正整数
`403`	无访问权限	登录态或角色无权访问该接口
`581007`	订单不存在	`orderId` 对应订单不存在
`584071`	无权访问该订单	当前账号不在订单可访问范围内
`584100`	车辆费用暂时不可用	车辆费用来源调用失败、响应身份不匹配或必要字段无效
`584101`	车辆费用尚未满足核单条件	已返回非空车辆明细，但存在未完结或未满足费用条件的明细

584102 不再用于本 GET 的“当前需求存在但车辆费用尚未生成”场景；该场景改为 code=200 的空结果，见下方示例。

业务边界与判定表

场景	`items`	`totalAmount`	`settlementReady`	`blockReasonCode`	`allConfirmed`	结果
无当前用车需求	`[]`	`0.00`	`true`	`null`	`true`	成功，可继续完成核单
有当前用车需求，但车辆费用尚未生成	`[]`	`0.00`	`false`	`VEHICLE_FEE_NOT_READY`	`false`	成功，但不能完成核单
有明细且来源已就绪，仍有行未确认	非空	合计金额	`true`	`null`	`false`	成功，需先完成明细确认
有明细且来源已就绪，所有行已确认	非空	合计金额	`true`	`null`	`true`	成功，可继续完成核单

items=[] 不是失败判据，必须结合 settlementReady 判断。
allConfirmed=true 只表示没有未确认行；是否具备核单条件仍以 settlementReady 为准。
车辆费用来源调用失败或明细必要字段无效仍返回业务错误，不转换为空结果。

示例 1：典型成功，有已确认车辆明细

请求：

GET /v3/admin/order/900000000001/settlement/step3/vehicles
Authorization: Bearer JWT_TOKEN

无请求体。

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": "900000000001",
    "version": 4,
    "totalAmount": 1200.00,
    "allConfirmed": true,
    "settlementReady": true,
    "blockReasonCode": null,
    "items": [
      {
        "id": "930000000001",
        "sourceType": "FLEET",
        "sourceTypeName": "车务",
        "serviceDate": "2026-08-01",
        "vehicleId": "880000000001",
        "vehiclePlate": "藏A12345",
        "vehicleModelId": "870000000001",
        "vehicleModelName": "七座商务车",
        "driverId": "860000000001",
        "driverName": "张师傅",
        "amount": 1200.00,
        "paymentMethod": "COMPANY_PAID",
        "paymentMethodName": "公司付款",
        "settlementConfirmStatus": "CONFIRMED",
        "settlementConfirmStatusName": "已确认",
        "remark": "金额已核对",
        "voucherUrls": []
      }
    ]
  },
  "traceId": null,
  "success": true
}

示例 2：边界成功，无当前用车需求

请求：

GET /v3/admin/order/900000000002/settlement/step3/vehicles
Authorization: Bearer JWT_TOKEN

无请求体。

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": "900000000002",
    "version": 0,
    "totalAmount": 0.00,
    "allConfirmed": true,
    "settlementReady": true,
    "blockReasonCode": null,
    "items": []
  },
  "traceId": null,
  "success": true
}

示例 3：边界成功，有当前需求但车辆费用尚未就绪

请求：

GET /v3/admin/order/900000000003/settlement/step3/vehicles
Authorization: Bearer JWT_TOKEN

无请求体。

响应：

{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": "900000000003",
    "version": 0,
    "totalAmount": 0.00,
    "allConfirmed": false,
    "settlementReady": false,
    "blockReasonCode": "VEHICLE_FEE_NOT_READY",
    "items": []
  },
  "traceId": null,
  "success": true
}

示例 4：业务失败，车辆费用来源暂时不可用

请求：

GET /v3/admin/order/900000000004/settlement/step3/vehicles
Authorization: Bearer JWT_TOKEN

无请求体。

响应：

{
  "code": 584100,
  "message": "车务车辆总车费暂时不可用，请稍后重试",
  "data": null,
  "traceId": null,
  "success": false
}

6. 枚举 / 数据字典

6.1 `sourceType`

所属字段：data.items[].sourceType ｜类型：String

值	中文	说明
`FLEET`	车务	车辆费用来源于当前车辆安排
`MANUAL`	手工	手工维护的车辆核单明细

6.2 `paymentMethod`

所属字段：data.items[].paymentMethod ｜类型：String

值	中文	说明
`CASH_PAID`	现金已付	现金支付
`SIGNED`	签单	按签单方式结算
`COMPANY_PAID`	公司付款	由公司支付

6.3 `settlementConfirmStatus`

所属字段：data.items[].settlementConfirmStatus ｜类型：String

值	中文	说明
`UNCONFIRMED`	未确认	当前车辆费用行尚未完成核单确认
`CONFIRMED`	已确认	当前车辆费用行已完成核单确认

6.4 `blockReasonCode`

所属字段：data.blockReasonCode ｜类型：String/null

值	中文	说明
`VEHICLE_FEE_NOT_READY`	车辆费用尚未就绪	有当前用车需求，但尚无可返回的车辆费用明细；此时 `settlementReady=false`
`null`	无阻断原因	此时 `settlementReady=true`；`null` 是空值，不是字符串 `"null"`

验证证据

PR #5393 已合并至 dev-v3，合并提交为 e4c1720871f33db38936d709caa7696db199ad1f。
部署任务 e6720666 构建成功，按 8186→8086 完成滚动，两个实例均为 UP。
测试服管理后台真实页面成功读取 9 条 FLEET 车辆费用，未再出现旧的车辆空数据错误。
测试服 8086 OpenAPI 已确认仅保留 guides、photographers 两组人员费用接口；leaders、drivers、others 六个路由不存在，车辆响应包含 settlementReady、blockReasonCode。
网关 curl 已确认路由可达，但旧 JWT 返回业务 401；逐接口正向网关 curl 因有效登录态缺失而阻断。
验收结论：TARGETED_FALLBACK / PARTIAL。已确认部署、双实例、页面车辆数据和服务 OpenAPI 契约；未完成带有效登录态的逐接口网关正向验证，不能描述为 Full E2E 或网关全量 verified。
PR 自动化记录：受影响测试 513 项通过，新增规格测试 116 项通过；模块全量 7198 项中 7166 项通过、31 项跳过、1 项失败，唯一失败为既有迁移版本重复问题。

10. 修改前后对比

10.1 字段级对比

字段	改前	改后
车辆响应 `data.settlementReady`	不对管理后台输出	新增 `Boolean`，明确车辆费用是否具备核单条件
车辆响应 `data.blockReasonCode`	不存在	新增 `String/null`，不可核单时返回机器可读原因

10.2 行为级对比

行为	改前	改后
核单人员 Tab	领队、司机、导游、摄影师、其他人员共 5 个	仅保留导游、摄影师 2 个
领队人员费用 GET/PUT	可查询、保存	路由删除，调用返回 HTTP 404
司机人员费用 GET/PUT	可查询、保存	路由删除，调用返回 HTTP 404
其他人员费用 GET/PUT	可查询、保存	路由删除，调用返回 HTTP 404
无当前用车需求	返回空明细，但响应未公开就绪原因字段	成功返回空明细，`settlementReady=true`、`blockReasonCode=null`
有当前需求但车辆费用尚未生成	GET 返回 `584102`，页面无法取得可判定空态	成功返回空明细，`settlementReady=false`、`blockReasonCode=VEHICLE_FEE_NOT_READY`
车辆来源失败或明细无效	返回业务错误	仍返回业务错误，不伪装成空结果

11. 影响评估 / 回滚

11.1 影响评估

是否破坏向后兼容：是。领队、司机、其他人员共 6 个接口已删除。
前端是否必须同步上线：是。管理后台必须移除这 3 个 Tab 及其查询、保存调用，仅保留导游、摄影师 Tab。
车辆字段兼容性：新增字段本身为向后兼容；若仍沿用 items=[] 或捕获 584102 判断空态，将无法区分“无需求”和“费用未就绪”。

11.2 回滚边界

前端版本不得回滚到仍调用 leaders、drivers、others 六个路由的版本，否则对应页面请求固定失败。
若前端暂时不使用车辆新增字段，JSON 仍可解析，但不能可靠判断空结果是否允许完成核单。

12. 注意事项

删除领队、司机、其他人员 3 个核单 Tab 及其 GET/PUT 请求封装、请求状态和保存动作。
保留导游 guides、摄影师 photographers 两个 Tab，原路径不变。
车辆查询返回 code=200 且 items=[] 时，不得直接当作异常或无条件放行；必须读取 settlementReady。
完成核单前同时检查 settlementReady 与 allConfirmed，不能只判断明细数组是否为空。
清理 GET 车辆费用遇到 584102 时的空态兼容逻辑；新的“有需求但费用未就绪”结果由 blockReasonCode=VEHICLE_FEE_NOT_READY 表达。
orderId、车辆明细 ID、车辆 ID、车型 ID、司机 ID 均按字符串处理；金额按 Decimal 处理。

22 KiB

原始文件 Blame 文件历史

⚠️【删除接口·管理后台】核单人员页签收口与车辆空态契约 (#5380)

1. 接口背景

变更接口清单

3. 接口详情

3.1 删除：领队人员费用查询与保存

3.2 删除：司机人员费用查询与保存

3.3 删除：其他人员费用查询与保存

3.4 修改：查询车辆核单草稿

6. 枚举 / 数据字典

6.1 `sourceType`

6.2 `paymentMethod`

6.3 `settlementConfirmStatus`

6.4 `blockReasonCode`

验证证据

10. 修改前后对比

10.1 字段级对比

10.2 行为级对比

11. 影响评估 / 回滚

11.1 影响评估

11.2 回滚边界

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

关联/联系人

链接

联系人

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

⚠️【删除接口·管理后台】核单人员页签收口与车辆空态契约 (#5380)

1. 接口背景

变更接口清单

3. 接口详情

3.1 删除：领队人员费用查询与保存

3.2 删除：司机人员费用查询与保存

3.3 删除：其他人员费用查询与保存

3.4 修改：查询车辆核单草稿

6. 枚举 / 数据字典

6.1 sourceType

6.2 paymentMethod

6.3 settlementConfirmStatus

6.4 blockReasonCode

验证证据

10. 修改前后对比

10.1 字段级对比

10.2 行为级对比

11. 影响评估 / 回滚

11.1 影响评估

11.2 回滚边界

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

关联/联系人

链接

联系人

22 KiB

原始文件 Blame 文件历史

6.1 `sourceType`

6.2 `paymentMethod`

6.3 `settlementConfirmStatus`

6.4 `blockReasonCode`