15 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 | 8561 | 派单矩阵三个入口补年份区间校验，新增错误码 605076 | admin | wx(GIT) | 修改接口 | deployed | verified | not_required | PR #8565 合并 dev-v3（ad3c6e4305）；hl-fleet-service dev-v3 分支部署测试网关 @ 9c7ac9382 并实测：grid/month-counts/unassigned-orders 三入口越界年份（1800/9999/1990）均返回 605076，区间内年份（含 2020/2100 两端边界，已在 grid 入口实测）行为不变。 | 2026-09-30 | dev-v3 |
hl-fleet-service: 派单矩阵三个入口补年份区间校验，新增错误码 605076
存放目录:
changelogs-v2/2026-09/服务: hl-fleet-service (端口 8087) PR: #8565 Issue: #8561 日期: 2026-09-30 影响范围: 管理后台派单矩阵三个查询入口（grid / month-counts / unassigned-orders）的年份校验
⚠️ 关键变化
- 派单矩阵三个查询入口（
grid/month-counts/unassigned-orders）此前只校月份是否在 1-12，不校年份——year=1800、year=9999这类明显异常值会被当成合法年份继续查询。现在统一在 Service 层加了年份区间校验[2020, 2100]，越界抛新增错误码 605076。 - 605076 的错误文案是
年份超出范围（仅支持 2020-2100 年）（AssignmentErrorCode.MATRIX_YEAR_OUT_OF_RANGE，文案里的年份区间已按当前常量渲染为 2020/2100）。 - 校验顺序是先年后月：
year越界时直接抛 605076，不会先看month。 - 区间内年份（含边界 2020、2100）行为完全不变，仍按原逻辑正常查询并返回 200。
- 三入口的
year字段本身仍是必填（@NotNull），缺失依旧是既有的参数校验码100001，本次未改动这一路径。
二、变更接口清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 矩阵主数据 | GET | /admin/fleet/matrix/grid |
校验补充 | 新增年份区间校验，越界返 605076 |
| 2 | 矩阵年度月度统计 | GET | /admin/fleet/matrix/month-counts |
校验补充 | 新增年份区间校验，越界返 605076 |
| 3 | 矩阵未派订单清单 | GET | /admin/fleet/matrix/unassigned-orders |
校验补充 | 新增年份区间校验，越界返 605076 |
三、接口详情
1. 矩阵主数据 GET /admin/fleet/matrix/grid
VO: MatrixGridReqVO → MatrixGridRespVO
使用场景
车务打开派单矩阵页查看某年某月逐日车辆占用/待派情况时调用。本次改动只影响 year 越界场景的响应，区间内查询字段结构与既有行为未变。
入参字段表
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| year | Query | Integer | ✅ | 🔴 新增：2020-2100（越界返 605076） | 年份 |
| month | Query | Integer | ✅ | 1-12（越界返 605010） | 月份 |
| season | Query | String | - | active/pending/archived/blacklist | 司机赛季筛选，默认 active |
| fleetTeamIds | Query | Long[] | - | - | 车队 ID 多选，空=全部 |
| fleets | Query | String[] | - | 已废弃，仅客户端迁移兼容 | 旧版车队稳定编码多选 |
| typeKeys | Query | String[] | - | 规范小写，空=全部 | 车型大类多选 |
| status | Query | String | - | all/unassigned/assigned | 兼容矩阵筛选 |
| statuses | Query | String[] | - | 非空时优先于 status | 有效状态精确筛选 |
出参字段表
响应结构本次未改动，以下仅列出与本次校验相关、已实测确认的顶层字段：
| 字段 | 类型 | 说明 |
|---|---|---|
| year | Integer | 年份（回显） |
| month | Integer | 月份（回显） |
| daysInMonth | Integer | 该月天数 |
| vehicles | List | 车辆逐日占用数据 |
请求示例
GET /admin/fleet/matrix/grid?year=2020&month=6&season=active
响应示例
区间下边界（year=2020）实测：
{"code":200,"message":"成功","data":{"year":2020,"month":6,"daysInMonth":30},"traceId":null,"success":true}
区间上边界（year=2100）实测：
{"code":200,"message":"成功","data":{"year":2100,"month":6},"traceId":null,"success":true}
空数据 / 降级响应
区间内查询若当月无任何车辆/派车数据，vehicles 为空数组，属正常业务结果，不是错误；本次改动不影响此形态。
错误响应
{"code":605076,"message":"年份超出范围（仅支持 2020-2100 年）","data":null,"traceId":null,"success":false}
（实测 year=1800 与 year=9999 均返回上述响应体，仅请求参数不同。）
业务边界
year越界（不在 [2020, 2100]）→ 605076，month是否越界不影响判定结果（先年后月）。year合法、month越界（如 13）→ 仍按既有 605010 路径处理，本次未改动。year/month缺失仍是既有的 100001（参数非法），未受本次改动影响。
2. 矩阵年度月度统计 GET /admin/fleet/matrix/month-counts
VO: MatrixMonthCountsReqVO → MatrixMonthCountsRespVO
使用场景
车务查看某年 12 个月各状态计数概览时调用（矩阵页顶部年度视图）。本次改动只影响 year 越界场景。
入参字段表
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| year | Query | Integer | ✅ | 🔴 新增：2020-2100（越界返 605076） | 年份 |
| season | Query | String | - | active/pending/archived/blacklist | 司机赛季筛选，默认 active |
| fleetTeamIds | Query | Long[] | - | - | 车队 ID 多选，空=全部 |
| typeKeys | Query | String[] | - | 规范小写，空=全部 | 车型大类多选 |
注：本端点没有 month 入参，年份越界统一走 605076，不会把调用方指去改一个不存在的字段。
出参字段表
| 字段 | 类型 | 说明 |
|---|---|---|
| year | Integer | 年份（回显） |
| months | List | 12 个月各状态计数 |
请求示例
GET /admin/fleet/matrix/month-counts?year=2026&season=active
响应示例
{"code":200,"message":"成功","data":{"year":2026},"traceId":null,"success":true}
（实测该年 12 个月 statusCounts 均为 0，字段结构本次未改动，示例只截取顶层字段。）
空数据 / 降级响应
区间内年份若全年无任何数据，months 中每个月的计数均为 0，属正常业务结果；本次改动不影响此形态。
错误响应
{"code":605076,"message":"年份超出范围（仅支持 2020-2100 年）","data":null,"traceId":null,"success":false}
（实测 year=1800 返回上述响应体。）
业务边界
year越界（不在 [2020, 2100]）→ 605076。year缺失仍是既有的 100001（参数非法），未受本次改动影响。
3. 矩阵未派订单清单 GET /admin/fleet/matrix/unassigned-orders
VO: MatrixUnassignedReqVO → List<MatrixUnassignedOrderVO>
使用场景
车务查看某年某月未派车订单清单（含虚拟待派条目）时调用。本次改动只影响 year 越界场景；month 越界的同构收敛见工单 #8571 的 changelog。
入参字段表
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| year | Query | Integer | ✅ | 🔴 新增：2020-2100（越界返 605076），本次前摘掉了原 @Min(1970)/@Max(9999) |
年份 |
| month | Query | Integer | ✅ | 1-12（越界返 605010，见 #8571） | 月份 |
| typeKeys | Query | String[] | - | 规范小写，空=全部 | 车型大类多选 |
出参字段表
响应结构本次未改动。
| 字段 | 类型 | 说明 |
|---|---|---|
| virtualPending | Boolean | 是否虚拟待派条目（库里无对应行，由 order-v3 当前需求投射） |
| headcountLabel | String | 人数展示文案 |
请求示例
GET /admin/fleet/matrix/unassigned-orders?year=1990&month=6&season=active
响应示例
{"code":200,"message":"成功","data":[],"traceId":null,"success":true}
（对照：year=2026&month=6（区间内）实测返回上述形态，data 为空数组属正常业务结果，与越界错误可区分。）
空数据 / 降级响应
区间内年份若当月无未派订单，data 为空数组，属正常业务结果，与越界返回的错误响应（success:false）可明确区分。
错误响应
{"code":605076,"message":"年份超出范围（仅支持 2020-2100 年）","data":null,"traceId":null,"success":false}
（实测 year=1990 返回上述响应体；本次改动前该场景返回的是框架码 100001，见"六.6、修改前后对比"。）
业务边界
- 🔴 契约收窄：本端点
year原有的校验区间是[1970, 9999]（@Min/@Max注解），本次收窄为[2020, 2100]且改走业务码 605076。year=1990这类此前能通过框架校验、现在会被拒绝的取值，前端如果曾经允许用户选择这类年份，需要同步收紧可选范围。 year越界 → 605076；month越界 → 605010（#8571），二者不互相覆盖，先年后月。year/month缺失仍是既有的 100001（@NotNull保留，未随本次摘除区间注解一并摘掉）。
四、契约约束与正确调用方式
本节只写后端接受/拒绝 payload 的规则，不写 UI 渲染建议。
✅ 正确 / ❌ 错误 payload 对照
| 场景 | payload / 响应 |
|---|---|
✅ year 在 [2020, 2100] 区间内（含边界） |
三入口均正常返回 code=200 |
❌ year 不在 [2020, 2100] 区间（如 1800/1990/9999） |
三入口均返回 code=605076 |
❌ 继续沿用 unassigned-orders 此前 [1970, 9999] 的可选年份范围 |
year=1990 等取值现在会被 605076 拒绝，不再是 100001 |
| ❌ 把 605076 当作可重试错误自动重试 | 605076 是入参永久性非法，重试同一 year 不会成功，需要用户重新选择年份 |
切换状态时的必要动作
前端拦到 code=605076 时应提示"年份超出范围，仅支持 2020-2100 年"类文案，并将年份选择控件的可选范围收紧到该区间，不要自动重试。
五、数据库行为
本次涉及的三个接口均为只读查询，无任何数据库写操作。改动只在 Service 层新增一段入参校验逻辑，不涉及任何表结构或存量数据变化。
六、边界行为
year不在 [2020, 2100] → 605076（三入口统一，本次新增）year缺失 → 100001（既有行为，未改动）year合法、month越界 → 605010（grid 既有行为；unassigned-orders 同构收敛见 #8571）year/month均合法 → 按既有逻辑正常查询，字段结构未变
六.5、枚举 / 数据字典
矩阵年份越界错误码（AssignmentErrorCode.MATRIX_YEAR_OUT_OF_RANGE）
所属字段: 无（HTTP 响应顶层 code） | 类型: Integer
| 值 | 中文 | 说明 |
|---|---|---|
605076 |
年份超出范围（仅支持 2020-2100 年） | 🔴 本次新增；三个矩阵查询入口的 year 不在 [2020, 2100] 时统一返回；入参永久性非法，不应自动重试 |
六.6、修改前后对比
字段级对比
本次无请求/响应字段新增或删除；unassigned-orders 的 year 字段摘掉了 @Min(1970)/@Max(9999) 注解（见入参字段表标注），字段本身仍是必填 Integer。
行为级对比
| 场景 | 改前 | 改后 |
|---|---|---|
grid / month-counts，year 越界（不在 [2020,2100]，如 1800/9999） |
未校验，当作合法年份继续查询 | 返回 code=605076（新增拦截） |
unassigned-orders，year 不在 [2020, 2100]（含此前 @Min(1970)/@Max(9999) 认为合法的 [1970,2019]∪[2101,9999] 区间） |
该子区间内视为合法继续查询，落在 [1970,9999] 之外才返回框架码 100001 | 统一返回业务码 605076，不再区分是否曾落在 [1970,9999] 内 |
三入口，year 在 [2020, 2100] |
正常返回 200 | 不变，仍正常返回 200 |
六.7、影响评估
- 是否破坏向后兼容: 是（仅
unassigned-orders）——year的可接受范围从[1970, 9999]收窄到[2020, 2100]，且越界时的错误码从 100001 变为 605076；grid/month-counts此前对越界年份没有任何拦截，本次是新增拦截而非收窄既有契约。 - 前端是否必须同步上线: 是——年份选择控件若允许超出
[2020, 2100]的取值，现在会收到新的 605076 错误码，前端需要新增该码的处理分支（提示文案 + 阻断当前查询），并建议同步收紧可选年份范围以减少用户触发该错误的机会。 - 前端 workaround 清理点: 若此前为"年份异常导致矩阵页面空白/报错"写过特殊兼容逻辑，可以确认不再需要，因为现在有明确的 605076 信号可用。
七、不影响范围
- 仅影响: 派单矩阵三个查询入口（
grid/month-counts/unassigned-orders）在year入参越界时的响应。 - 零影响:
- 三入口在
year合法时的成功路径字段结构 month越界的既有校验 605010（unassigned-orders的同构收敛见 #8571 单独的 changelog）season/fleetTeamIds/typeKeys/status/statuses等其余入参的校验逻辑day-orders等矩阵模块下其余未涉及本次改动的端点
- 三入口在
八、测试环境已验证
服务：hl-fleet-service，dev-v3 分支部署测试网关 @ 9c7ac9382（含 #8561 所在提交），测试网关 https://api.test.1814.love：
✓ GET grid?year=1800&month=6 → code=605076, message="年份超出范围（仅支持 2020-2100 年）"
✓ GET grid?year=9999&month=6 → code=605076
✓ GET month-counts?year=1800 → code=605076
✓ GET unassigned-orders?year=1990&month=6 → code=605076（此前为 100001，见六.6）
✓ GET grid?year=2020&month=6（下边界）→ code=200，正常返回
✓ GET grid?year=2100&month=6（上边界）→ code=200，正常返回
✓ GET month-counts?year=2026（区间中段）→ code=200，正常返回
✓ GET unassigned-orders?year=2026&month=6（区间中段）→ code=200, data=[]
注：2020/2100 两端边界值仅在 grid 入口做了直接边界实测；month-counts/unassigned-orders 在区间中段（year=2026）验证了正常放行。三入口共用同一段 requireValidYearMonth 校验逻辑（MatrixService.java），边界判定不因入口而异，越界拦截已在三入口分别实测（见上）。
十、相关文档
- 关联 Issue: wx/HL#8561
- 关联 PR: wx/HL#8565
关联 / 联系人
链接
- Issue: #8561
- PR: #8565
- Merge commit: ad3c6e4305
联系人
- 后端负责人: @wx