10 KiB
10 KiB
schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
| schema | ticket | title | consumer | author | change_type | backend_status | gateway_status | frontend_status | frontend_owner | frontend_ref | target_release | verified_at | status_note | updated_at | base |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| hl-changelog/v2 | 8571 | 矩阵未派订单清单月份越界改由 Service 判，与另两个入口同构 | admin | wx(GIT) | 修改接口 | deployed | verified | not_required | PR #8582 合并 dev-v3（6634d0588d）；hl-fleet-service dev-v3 分支部署测试网关 @ 9c7ac9382 并实测：unassigned-orders 月份越界（如 13、0）统一返回 605010，月份缺失仍返 100001，grid 入口的既有 605010 行为未回归。 | 2026-09-30 | dev-v3 |
hl-fleet-service: 矩阵未派订单清单月份越界改由 Service 判，与另两个入口同构
存放目录:
changelogs-v2/2026-09/服务: hl-fleet-service (端口 8087) PR: #8582 Issue: #8571 日期: 2026-09-30 影响范围: 管理后台派单矩阵未派订单清单端点unassigned-orders的月份越界校验
⚠️ 关键变化
unassigned-orders的month越界校验此前是框架层@Min(1)/@Max(12)注解，越界返回框架码 100001；grid端点的month越界则一直是 Service 层requireValidYearMonth判定，返回业务码 605010。同一类"月份填错了"，两个端点走两套码、两套错误文案，前端得按端点分别写处理分支。- 本次摘掉
unassigned-orders的@Min/@Max注解，越界统一改由 Service 层requireValidYearMonth判定，现在与grid完全同构：越界一律返回 605010（月份超出范围）。 - 🔴
@NotNull被保留：month字段缺失（不传该参数）仍然返回既有的 100001（参数非法: 月份不能为空），这条路径没有变化——只有"传了值但越界"这一种场景的错误码变了。 year字段的年份越界校验（605076）是另一张工单 #8561 引入的独立改动，与本次month校验改动在同一个requireValidYearMonth方法里但各自独立生效，请分别查阅两份 changelog。
二、变更接口清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 矩阵未派订单清单 | GET | /admin/fleet/matrix/unassigned-orders |
校验口径收敛 | month 越界改由 Service 判，与 grid 统一返回 605010 |
三、接口详情
1. 矩阵未派订单清单 GET /admin/fleet/matrix/unassigned-orders
VO: MatrixUnassignedReqVO → List<MatrixUnassignedOrderVO>
使用场景
车务查看某年某月未派车订单清单（含虚拟待派条目）时调用。本次改动只影响 month 越界场景的错误码；year 越界的新增校验（605076）见工单 #8561 的 changelog。
入参字段表
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| year | Query | Integer | ✅ | 2020-2100（越界返 605076，见 #8561） | 年份 |
| month | Query | Integer | ✅ | 🔴 1-12，越界改为返 605010（此前是框架码 100001），本次摘掉了原 @Min(1)/@Max(12) |
月份 |
| typeKeys | Query | String[] | - | 规范小写，空=全部 | 车型大类多选 |
出参字段表
响应结构本次未改动。
| 字段 | 类型 | 说明 |
|---|---|---|
| virtualPending | Boolean | 是否虚拟待派条目 |
| headcountLabel | String | 人数展示文案 |
请求示例
GET /admin/fleet/matrix/unassigned-orders?year=2026&month=13&season=active
响应示例
区间边界内实测（month=1）：
{"code":200,"message":"成功","data":[],"traceId":null,"success":true}
区间边界内实测（month=12）：
{"code":200,"message":"成功","data":[],"traceId":null,"success":true}
空数据 / 降级响应
month 合法时若当月无未派订单，data 为空数组，属正常业务结果，与越界返回的错误响应（success:false）可明确区分。
错误响应
month=13（越界）实测：
{"code":605010,"message":"月份超出范围","data":null,"traceId":null,"success":false}
month=0（越界）实测：
{"code":605010,"message":"月份超出范围","data":null,"traceId":null,"success":false}
month 缺失（未传该参数）实测，未受本次改动影响：
{"code":100001,"message":"参数非法: 月份不能为空","data":null,"traceId":null,"success":false}
业务边界
- 🔴
month越界（不在 1-12，如 0、13）从此前的框架码 100001 改为业务码 605010，与grid端点完全同构；前端若曾经按 100001 识别"月份越界"这一具体场景，需要改成识别 605010。 month缺失（不传参数）仍是 100001，@NotNull判定发生在requireValidYearMonth之前，未被本次改动波及，无需新增分支。year越界返回 605076（#8561 引入），与本次month越界的 605010 是两个独立判定，requireValidYearMonth先判年后判月。
四、契约约束与正确调用方式
本节只写后端接受/拒绝 payload 的规则，不写 UI 渲染建议。
✅ 正确 / ❌ 错误 payload 对照
| 场景 | payload / 响应 |
|---|---|
✅ month 在 1-12 区间内（含边界 1、12） |
正常返回 code=200 |
❌ month 不在 1-12 区间（如 0、13） |
返回 code=605010 |
❌ 不传 month 参数 |
返回 code=100001（未受本次改动影响） |
❌ 继续按 code=100001 识别"月份越界"这一具体场景 |
本端点越界场景已改为 605010，100001 现在只对应"缺参" |
切换状态时的必要动作
前端若此前对本端点单独写过"code=100001 → 月份超出范围"的文案分支，需要改成识别 605010（文案为"月份超出范围"），并与 grid 端点共用同一套 605010 处理逻辑；100001 的处理分支需要改为对应"参数缺失"。
五、数据库行为
本次涉及的接口为只读查询，无任何数据库写操作。改动只是把一段入参校验从框架注解移到 Service 层方法内，不涉及任何表结构或存量数据变化。
六、边界行为
month不在 1-12 → 605010（本次改动后的新行为，此前是 100001）month缺失（未传参数）→ 100001（既有行为，未改动）year越界 → 605076（#8561 引入的独立判定，先于month判定执行）month在 1-12 且year合法 → 正常返回，字段结构未变
六.5、枚举 / 数据字典
月份越界错误码（AssignmentErrorCode.MATRIX_MONTH_OUT_OF_RANGE）
所属字段: 无（HTTP 响应顶层 code） | 类型: Integer
| 值 | 中文 | 本次是否新增 | 说明 |
|---|---|---|---|
605010 |
月份超出范围 | 端点内是新用法（既有码，grid 端点此前已在用） |
unassigned-orders 本次起对 month 越界统一返回该码，与 grid 同构 |
100001 |
参数非法 | 未变 | month 缺失（未传参数）时仍返回，文案为"参数非法: 月份不能为空" |
六.6、修改前后对比
字段级对比
本次无请求/响应字段新增或删除；month 字段摘掉了 @Min(1)/@Max(12) 注解，@NotNull 保留，字段本身仍是必填 Integer。
行为级对比
| 场景 | 改前 | 改后 |
|---|---|---|
unassigned-orders，month 越界（如 0、13） |
返回框架码 100001（@Min/@Max 拦截） |
返回业务码 605010 |
unassigned-orders，month 缺失 |
返回 100001 |
不变，仍返回 100001 |
grid，month 越界 |
返回 605010 |
不变，仍返回 605010（本次未改动 grid，仅用于对照验证未回归） |
unassigned-orders，month 在 1-12 |
正常返回 200 | 不变，仍正常返回 200 |
六.7、影响评估
- 是否破坏向后兼容: 是——
month越界时的错误码从100001变为605010，前端若按具体码值做过分支判断，命中该场景的分支需要更新。 - 前端是否必须同步上线: 是（仅针对本端点单独维护过 100001 越界分支的场景）——若前端此前对
unassigned-orders单独写过"code=100001即月份越界"的判断，现在需要改为识别605010；若前端此前是把 100001 统一当作"参数错误"泛化处理且未细分场景，则不受影响。 - 前端 workaround 清理点: 若此前为"同一类月份错误在 grid 和 unassigned-orders 上分别处理"写过两套逻辑，现在两端点已统一为 605010，可以合并成一套。
七、不影响范围
- 仅影响:
unassigned-orders端点在month入参越界（不在 1-12）时的错误码。 - 零影响:
month缺失时的错误码（仍是 100001）year校验逻辑（605076，属 #8561 独立改动）grid/month-counts两个端点的既有行为unassigned-orders在month合法时的成功路径字段结构
八、测试环境已验证
服务：hl-fleet-service，dev-v3 分支部署测试网关 @ 9c7ac9382（含 #8571 所在提交），测试网关 https://api.test.1814.love：
✓ GET unassigned-orders?year=2026&month=13 → code=605010, message="月份超出范围"（此前应为 100001）
✓ GET unassigned-orders?year=2026&month=0 → code=605010
✓ GET unassigned-orders?year=2026&month=1（下边界）→ code=200, data=[]
✓ GET unassigned-orders?year=2026&month=12（上边界）→ code=200, data=[]
✓ GET unassigned-orders?year=2026（不传 month）→ code=100001, message="参数非法: 月份不能为空"（@NotNull 未被误摘）
✓ GET grid?year=2026&month=13 → code=605010（grid 既有行为，未回归）
十、相关文档
- 关联 Issue: wx/HL#8571
- 关联 PR: wx/HL#8582
关联 / 联系人
链接
- Issue: #8571
- PR: #8582
- Merge commit: 6634d0588d
联系人
- 后端负责人: @wx