API Changelog Bot和Claude Opus 5
14d84237e7
changelog-filename-gate / validate (push) Failing after 2s
- #8561 派单矩阵三入口补年份区间校验，越界返新错误码 605076 - #8571 未派订单清单月份越界改由 Service 判定，与 matrix 另两个入口同构返 605010 - #8556 派单看板订单详情识别团期配车，排车步与实派车数不再只认逐户派车行 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
237 行
10 KiB
Markdown
237 行
10 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8571"
|
||
title: "矩阵未派订单清单月份越界改由 Service 判，与另两个入口同构"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "pending"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "PR #8582 合并 dev-v3（6634d0588d）；hl-fleet-service dev-v3 分支部署测试网关 @ 9c7ac9382 并实测：unassigned-orders 月份越界（如 13、0）统一返回 605010，月份缺失仍返 100001，grid 入口的既有 605010 行为未回归。"
|
||
updated_at: "2026-09-30"
|
||
base: "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 | 人数展示文案 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /admin/fleet/matrix/unassigned-orders?year=2026&month=13&season=active
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
区间边界内实测（`month=1`）：
|
||
|
||
```json
|
||
{"code":200,"message":"成功","data":[],"traceId":null,"success":true}
|
||
```
|
||
|
||
区间边界内实测（`month=12`）：
|
||
|
||
```json
|
||
{"code":200,"message":"成功","data":[],"traceId":null,"success":true}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
`month` 合法时若当月无未派订单，`data` 为空数组，属正常业务结果，与越界返回的错误响应（`success:false`）可明确区分。
|
||
|
||
#### 错误响应
|
||
|
||
`month=13`（越界）实测：
|
||
|
||
```json
|
||
{"code":605010,"message":"月份超出范围","data":null,"traceId":null,"success":false}
|
||
```
|
||
|
||
`month=0`（越界）实测：
|
||
|
||
```json
|
||
{"code":605010,"message":"月份超出范围","data":null,"traceId":null,"success":false}
|
||
```
|
||
|
||
`month` 缺失（未传该参数）实测，**未受本次改动影响**：
|
||
|
||
```json
|
||
{"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](https://git.1814.love/wx/HL/issues/8571)
|
||
- 关联 PR: [wx/HL#8582](https://git.1814.love/wx/HL/pulls/8582)
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#8571](https://git.1814.love/wx/HL/issues/8571)
|
||
- **PR**: [#8582](https://git.1814.love/wx/HL/pulls/8582)
|
||
- **Merge commit**: [6634d0588d](https://git.1814.love/wx/HL/commit/6634d0588d)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|