---
schema: "hl-changelog/v2"
ticket: "8571"
title: "矩阵未派订单清单月份越界改由 Service 判，与另两个入口同构"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
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