wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-08/04_5455_看板列表非法枚举参数显式报错-修改接口-管理后台.md
Mimingguang ce61e09027
所有检测均成功
changelog-filename-gate / validate (push) Successful in 2s
详情
chore(changelog): 回写 #5455 前端核账终态 
修改原因：看板非法枚举错误已由后端显式返回，需确认管理后台无需额外兼容。

修改内容：引用受控枚举与请求错误透传提交，回写 verified。

实际验证：reviewer no findings；当前 HEAD checkpoint 已通过；source npm test 46 项通过。

路径：changelogs-v2/2026-08/04_5455_看板列表非法枚举参数显式报错-修改接口-管理后台.md。
2026-08-04 15:45:53 +08:00

5.8 KiB
原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, author, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
schema ticket title consumer change_type author backend_status gateway_status frontend_status frontend_owner frontend_ref target_release verified_at status_note updated_at base
hl-changelog/v2 5455 看板列表非法枚举参数显式报错（vehicleTypeKeys/statuses 同为拒绝） admin 修改接口 wx(GIT) deployed verified verified Pi hl-admin@09808c07c18719e30ee7a8e2c8005852ea673e26 v2.1 2026-08-04 后端完成：PR #5466 已合并 dev-v3 并部署 TEST，网关验证非法枚举返 100001、合法枚举筛选回归不变；前端需对 100001 错误码做提示处理。 2026-08-04 dev-v3

车务: 看板列表非法枚举参数显式报错（vehicleTypeKeys/statuses 同为拒绝）

服务: hl-fleet-service PR: #5466 Issue: #5455 日期: 2026-08-04 影响范围: 管理后台车务端看板列表/汇总的车型与状态筛选参数

⚠️ 关键变化

GET /admin/fleet/board/orders 的枚举筛选参数传入非法值时，不再静默失效，统一返回 100001 参数非法（与 variant 非法值口径一致）。

参数 以前的行为 现在的行为
vehicleTypeKeys / typeKeys 非法值静默忽略 → 返回全量数据（筛选静默失效，如 BAD_TYPE → total=66） 返回 100001，message 指明非法值与合法枚举
statuses / status 非法值静默忽略 → 返回 0 条（如 BAD_STATUS → total=0） 返回 100001，message 指明非法值与合法枚举

合法值不变：

  • 车型：suv（越野）/ mpv（商务车）/ bus（大巴）/ sedan（轿车），支持多选、逗号分隔，兼容历史大写与中文别名（如 越野、商务）。
  • 状态：unassigned（待派）/ unassigned_urgent（待派·临近出团）/ holding（排车锁定）/ holding_urgent（排车超时）/ assigned（已派）/ change_requested（请求换车，M1 恒空）/ canceled（已取消）/ completed（已完成），支持中英文别名、大小写与逗号分隔。

变更接口清单

# 接口 方法 路径 变更类型 说明
1 看板列表 GET /admin/fleet/board/orders 校验新增 非法枚举返 100001

说明：/admin/fleet/board/summary 按设计忽略 statuses/status（不参与汇总过滤），非法状态值不报错，行为不变；vehicleTypeKeys 在汇总中参与过滤，非法值同样返 100001。

接口详情

1. 看板列表 GET /admin/fleet/board/orders

枚举入参（全部可选）：

参数 类型 合法值 说明
vehicleTypeKeys String[] suv/mpv/bus/sedan 车型大类多选，任一命中即返；未派按需求车型、已派按实际车辆大类过滤
typeKeys String[] 同上 车型多选别名（未传 vehicleTypeKeys 时生效）
statuses String[] unassigned/unassigned_urgent/holding/holding_urgent/assigned/change_requested/canceled/completed 多状态筛选，任一命中即返；空=不过滤
status String 同上 状态筛选别名（单值或逗号分隔；与 statuses 合并）

异常示例（非法车型枚举）：

GET /admin/fleet/board/orders?page=1&pageSize=20&vehicleTypeKeys=BAD_TYPE
Authorization: Bearer <token>
（无请求体）

  {
    "code": 100001,
    "message": "参数非法: vehicleTypeKeys 仅支持 suv/mpv/bus/sedan，传入非法值：BAD_TYPE",
    "data": null,
    "traceId": null,
    "success": false
  }

异常示例（非法状态枚举，与车型同为拒绝口径）：

GET /admin/fleet/board/orders?page=1&pageSize=20&statuses=BAD_STATUS

  {
    "code": 100001,
    "message": "参数非法: statuses 含非法状态值：BAD_STATUS（合法值：unassigned/unassigned_urgent/holding/holding_urgent/assigned/change_requested/canceled/completed）",
    "data": null,
    "traceId": null,
    "success": false
  }

典型成功示例（合法多选）：

GET /admin/fleet/board/orders?page=1&pageSize=20&vehicleTypeKeys=suv,mpv&statuses=unassigned_urgent
Authorization: Bearer <token>

{"code": 200, "message": "成功", "data":   {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  }, "success": true}

错误码

code 含义 说明
100001 参数非法 枚举筛选参数含非法值；message 列出非法值与合法枚举

前端需要做什么

  • 请求参数生成逻辑不变（合法值、多选、逗号分隔均兼容）。
  • 新增处理：收到 code=100001 时展示 message（如「参数非法: vehicleTypeKeys 仅支持 suv/mpv/bus/sedan，传入非法值：xxx」），不再静默展示全量/空结果。典型场景：下拉数据版本与后端枚举不一致、拼写错误。
  • 建议核对：筛选组件本地若有非法值兜底逻辑（如清空筛选重查全量），可保留但应以 100001 提示为准。

验证证据

  • 单元测试：非法 vehicleTypeKeys/typeKeys（含合法值混传非法值）/statuses/status 均抛 100001 且不查库；合法多选（suv + 中文别名）筛选行为回归不变；汇总接口非法 statuses 按设计忽略不报错。
  • mvn -pl hl-fleet-service -am verify 通过（本次改动相关用例全绿）。
  • 测试环境网关验证：vehicleTypeKeys=BAD_TYPE → 100001；statuses=BAD_STATUS → 100001；合法枚举（suv、suv,mpv）筛选正常。

关联 / 联系人

链接

联系人

  • 后端负责人: @wx