349 行
14 KiB
Markdown
349 行
14 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8226"
|
||
title: "车型大类中文名空白校验收紧（全角空格等 Unicode 空白改为拒绝）+ 空名大类不再被挤出车型字典白名单"
|
||
consumer: "admin"
|
||
author: "jw(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "9e0897c2934a6720fb9cbab05b1e14394c74c8f6"
|
||
target_release: ""
|
||
verified_at: "2026-09-23"
|
||
status_note: "PR #8232 已合并 dev-v3（9231b8d8c），2026-09-23 14:30 滚动部署 TEST 双实例（检出 7a876ec57）。真实网关实测：新增/编辑车型大类 typeName 传全角空格、半角空格、空串、null 均返回 400「大类中文名不能为空」，库内零写入；读侧临时把 mpv 名称置空后，order-v3 车型白名单仍含 mpv（展示名回落为 mpv），验毕已原样还原。前端待办：车型大类表单的 typeName 必填校验需同样把全角空格视为空。前端已交付(2026-09-23):CategoryEditModal typeName 必填规则改 trim() 判空 validator,纯全角/半角空白提交前拦下(与后端 400 同口径),首尾带空格正常名放行且提交不 trim 原样发;新建组件 spec 4 例全绿。"
|
||
updated_at: "2026-09-23"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 车队车型管理: 车型大类中文名空白校验收紧 + 空名大类不再被挤出字典白名单
|
||
|
||
> **存放目录**: 二期(v3) → `changelogs-v2/2026-09/`
|
||
>
|
||
> **服务**: hl-fleet-service
|
||
> **PR**: #8232
|
||
> **Issue**: #8226
|
||
> **日期**: 2026-09-23
|
||
> **影响范围**: 管理后台「车型管理」新增/编辑车型大类表单的 typeName 校验；order-v3 用车需求车型字典白名单（582032）的数据源
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）
|
||
|
||
- 本次变化：新增/编辑车型大类时，`typeName` 如果全部由**全角空格（U+3000）等 Unicode 空白**组成，现在返回 `400「大类中文名不能为空」`。
|
||
- 前端以前以为的：`typeName` 只要不是空串、不全是半角空格，后端就会接受。
|
||
- 实际新行为：以前后端用 `@NotBlank` 校验，它按 `String.trim()` 判空，只去掉半角空白，所以全角空格能写进库。可车队给 order-v3 的车型白名单按 `isBlank()` 判空名，会把这种名字当成空的、把整个大类从白名单里丢掉，结果这个大类下的用车需求被 `582032「不存在或已下线」` 误拒。现在两处同时收口：写侧拒绝这种名字；读侧即使库里出现空名，也不再把该大类挤出白名单。
|
||
|
||
---
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 新增车型大类 | POST | `/admin/fleet/vehicle-types` | 入参校验收紧 | `typeName` 全为 Unicode 空白（含全角空格）改为 400 |
|
||
| 2 | 编辑车型大类 | PUT | `/admin/fleet/vehicle-types/{typeId}` | 入参校验收紧 | 同上 |
|
||
|
||
---
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 新增车型大类 `POST /admin/fleet/vehicle-types`
|
||
|
||
**VO**: `VehicleTypeSaveReqVO → VehicleTypeRespVO`
|
||
|
||
#### 使用场景
|
||
|
||
管理后台「车队 → 车型管理」新增一个车型大类（如 SUV系列 / 商务车）时调用。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
|
||
| typeKey | Body | String | ✅ | 非空白，≤16，全局唯一（600101） | 大类标识 key，如 `suv` |
|
||
| typeName | Body | String | ✅ | **至少含一个非空白字符（空白按 Unicode 判定，全角空格也算空白，本次收紧）**，≤64 | 大类中文名 |
|
||
| icon | Body | String | ❌ | ≤64 | 图标组件名或 emoji |
|
||
| description | Body | String | ❌ | ≤256 | 大类描述 |
|
||
| sortOrder | Body | Integer | ✅ | 非 null | 排序权重，升序 |
|
||
|
||
#### 出参 `Result<VehicleTypeRespVO>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | Long | 大类 ID |
|
||
| typeKey | String | 大类 key |
|
||
| typeName | String | 大类中文名 |
|
||
| icon | String | 图标 |
|
||
| description | String | 描述 |
|
||
| sortOrder | Integer | 排序权重 |
|
||
| seatOptions | Array\<Integer\> | 座位数选项，新建恒为 `[]` |
|
||
| modelCount | Integer | 型号数，新建恒为 0 |
|
||
| inUseCount | Integer | 在役车辆数，新建恒为 0 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"typeKey": "mpv",
|
||
"typeName": "商务车",
|
||
"icon": "",
|
||
"description": "",
|
||
"sortOrder": 2
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"id": "2064609312168083458",
|
||
"typeKey": "mpv",
|
||
"typeName": "商务车",
|
||
"icon": "",
|
||
"description": "",
|
||
"sortOrder": 2,
|
||
"seatOptions": [],
|
||
"modelCount": 0,
|
||
"inUseCount": 0
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
写接口没有空数据场景，也没有降级分支；校验不通过时零写入。
|
||
|
||
```json
|
||
{ "code": 400, "message": "大类中文名不能为空", "data": null, "success": false }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
`typeName` 为 null、空串、纯半角空格、纯全角空格，一律返回同一条错误，且只报一条：
|
||
|
||
```json
|
||
{ "code": 400, "message": "大类中文名不能为空", "data": null, "traceId": null, "success": false }
|
||
```
|
||
|
||
```json
|
||
{ "code": 600101, "message": "车型大类标识已存在", "data": null, "success": false }
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 鉴权：未登录 → 业务码 `401`（「缺少有效的 Authorization 头」）。
|
||
- 只拒绝**全部**由空白组成的名字；首尾带空格的正常名（如 `" 商务车 "`）照常放行，后端不做 trim。
|
||
- 以前只有全角空格这一类会被放行，现在也拒绝；null、空串、半角空格在改前就被拒，行为不变。
|
||
|
||
---
|
||
|
||
### 2. 编辑车型大类 `PUT /admin/fleet/vehicle-types/{typeId}`
|
||
|
||
**VO**: `VehicleTypeSaveReqVO → VehicleTypeRespVO`
|
||
|
||
#### 使用场景
|
||
|
||
管理后台「车型管理」编辑已有大类的名称、图标、描述或排序。`typeKey` 不可改，后端忽略入参中的 `typeKey`。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| Authorization | Header | String | ✅ | - | 管理端登录令牌 |
|
||
| typeId | Path | Long | ✅ | 大类须存在（600102） | 大类 ID |
|
||
| typeName | Body | String | ✅ | **至少含一个非空白字符（空白按 Unicode 判定，全角空格也算空白，本次收紧）**，≤64 | 大类中文名 |
|
||
| icon | Body | String | ❌ | ≤64；不传则不改 | 图标 |
|
||
| description | Body | String | ❌ | ≤256；不传则不改 | 描述 |
|
||
| sortOrder | Body | Integer | ✅ | 非 null | 排序权重 |
|
||
|
||
#### 出参 `Result<VehicleTypeRespVO>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | Long | 大类 ID |
|
||
| typeKey | String | 大类 key（不可改） |
|
||
| typeName | String | 大类中文名 |
|
||
| icon | String | 图标 |
|
||
| description | String | 描述 |
|
||
| sortOrder | Integer | 排序权重 |
|
||
| seatOptions | Array\<Integer\> | 该大类下型号座位数选项，去重升序 |
|
||
| modelCount | Integer | 型号数 |
|
||
| inUseCount | Integer | 在役车辆数 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"typeName": "商务车",
|
||
"icon": "",
|
||
"description": "",
|
||
"sortOrder": 2
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"id": "2064609312168083458",
|
||
"typeKey": "mpv",
|
||
"typeName": "商务车",
|
||
"sortOrder": 2,
|
||
"seatOptions": [7],
|
||
"modelCount": 1,
|
||
"inUseCount": 0
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
写接口没有空数据场景，也没有降级分支；校验不通过时零写入，`update_time` 也不变。
|
||
|
||
```json
|
||
{ "code": 400, "message": "大类中文名不能为空", "data": null, "success": false }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{ "code": 400, "message": "大类中文名不能为空", "data": null, "traceId": null, "success": false }
|
||
```
|
||
|
||
```json
|
||
{ "code": 600102, "message": "车型大类不存在", "data": null, "success": false }
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 鉴权：未登录 → 业务码 `401`。
|
||
- 参数校验先于「大类是否存在」：`typeName` 为空白时，即使 `typeId` 不存在也返回 400，而不是 600102。
|
||
- 编辑时把名字清空是被拒绝的操作，不会把一个在营大类变成空名大类。
|
||
|
||
---
|
||
|
||
## 四、契约约束与正确调用方式（接口类必写）
|
||
|
||
> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。
|
||
|
||
### ✅ 正确 / ❌ 错误 payload 对照
|
||
|
||
| 场景 | payload | 结果 |
|
||
|------|---------|------|
|
||
| ✅ 正常中文名 | `typeName: "商务车"` | 通过 |
|
||
| ✅ 首尾带空格 | `typeName: " 商务车 "` | 通过，原样落库 |
|
||
| ❌ 纯全角空格 | `typeName: " "` | 400（**本次新增拒绝**） |
|
||
| ❌ 纯半角空格 / 空串 / null | `typeName: " "` / `""` / 不传 | 400（改前已拒） |
|
||
|
||
- 前端表单的必填校验应与后端一致，按「去掉**全部 Unicode 空白**后是否为空」判定。JS 的 `String.prototype.trim()` 会去掉全角空格（U+3000），可以直接用 `value.trim() === ''` 判空。
|
||
|
||
---
|
||
|
||
## 五、数据库行为（涉及写操作时必写）
|
||
|
||
- 无 Flyway migration、无 DDL、无表结构变更。`fleet_vehicle_type.type_name` 原本就是 `VARCHAR(64) NOT NULL`。
|
||
- 校验失败的请求零写入：TEST 实测 4 次 POST、2 次 PUT 被拒后，`fleet_vehicle_type` 全表逐字段（含 `update_time`）与请求前一致，也没有生成测试 key 的行。
|
||
- 存量处理成本为 0：TEST 上在架大类 4 行，`type_name` 都非空白。
|
||
|
||
---
|
||
|
||
## 六、边界行为
|
||
|
||
- 未登录 → 业务码 `401`。
|
||
- `typeName` 只要含一个非空白字符就放行；是否是「像中文的名字」后端不判断。
|
||
- 读侧兜底（内部接口，前端不直接调用，写在这里方便排查 582032）：如果库里仍出现空名大类（例如被直接改库），车队给 order-v3 的车型白名单（`GET /internal/fleet/vehicle-types/category-names`）**照样包含这个大类**，只是展示名回落为规范 key（如 `mpv`），同时车队服务打一条 WARN「车型大类名称为空，展示名回落到规范 key」。改前这个大类会从白名单里整个消失，导致用车需求报 `582032「车型 mpv 不在车型字典内（不存在或已下线）」`，而座位数校验照常通过。
|
||
- 同一规范 key 下有多行时，展示名取排序最前、且名称非空白的那一行。
|
||
|
||
---
|
||
|
||
## 六.6、修改前后对比（修改/删除类接口必写，新增跳过）
|
||
|
||
### 字段级对比
|
||
|
||
| 字段 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| `typeName` 校验 | `@NotBlank`：按 `trim()` 判空，全角空格放行 | `@NotNull` + Unicode 空白判定：全角空格等一律拒 |
|
||
|
||
### 行为级对比
|
||
|
||
| 行为 | 改前 | 改后 |
|
||
|------|------|------|
|
||
| 新增/编辑时 `typeName` 传全角空格 | 200，落库 | 400「大类中文名不能为空」，零写入 |
|
||
| `typeName` 传 null / 空串 / 半角空格 | 400 | 400（同一条文案，只报一条） |
|
||
| 库里存在空名在营大类时，order-v3 提交该大类的用车需求 | 582032 误拒（座位校验却通过） | 正常通过字典校验 |
|
||
|
||
---
|
||
|
||
## 六.7、影响评估（修改/删除类必写）
|
||
|
||
- **是否破坏向后兼容**：只收紧了一种此前被接受的取值（`typeName` 全为全角空格等 Unicode 空白），这种名字本来就没有业务意义；请求/响应结构不变。
|
||
- **前端是否必须同步上线**：否。前端不改的话，用户输入全角空格会在提交后收到后端 400 文案，不会写坏数据。建议前端表单必填校验同步用 `trim()` 判空，在提交前就提示。
|
||
- **前端 workaround 清理点**：无。
|
||
|
||
---
|
||
|
||
## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面）
|
||
|
||
- **仅影响**：新增/编辑车型大类的 `typeName` 校验；内部接口 `category-names` 对空名大类的取舍。
|
||
- **零影响**：
|
||
- `typeKey`、`icon`、`description`、`sortOrder` 的校验规则。
|
||
- `GET /admin/fleet/vehicle-types`（树）、`/page`、`/list` 的响应结构与内容。
|
||
- 车型型号（`/admin/fleet/vehicle-types/{typeId}/models` 等）相关接口。
|
||
- order-v3 的 582032 / 582033 错误码与文案本身；名称正常的大类在白名单里的名称与顺序不变（TEST 实测 4 个在架大类改前改后一致）。
|
||
- 座位数选项接口 `seat-options` 的行为（本来就不看名称）。
|
||
|
||
---
|
||
|
||
## 八、测试环境已验证
|
||
|
||
部署：PR #8232 合并 `dev-v3`（`9231b8d8c`），2026-09-23 14:30 滚动部署 TEST 双实例（检出 `7a876ec57`，含本单）。
|
||
|
||
构建身份（零写入判据）：直连 8087 / 8187 两个实例，`PUT /admin/fleet/vehicle-types/999999999`（不存在的 id）：`typeName` 传全角空格返回 400（旧代码会放行到 600102）；同一 id 传正常名返回 600102（阴性对照）。
|
||
|
||
真实网关（`https://api.test.1814.love`，管理端 token）：
|
||
|
||
```
|
||
POST /admin/fleet/vehicle-types 无 token → 401 缺少有效的 Authorization 头 ✓
|
||
POST /admin/fleet/vehicle-types typeName=" " → 400 大类中文名不能为空 ✓
|
||
POST /admin/fleet/vehicle-types typeName=" " → 400 大类中文名不能为空 ✓
|
||
POST /admin/fleet/vehicle-types typeName="" → 400 大类中文名不能为空 ✓
|
||
POST /admin/fleet/vehicle-types typeName=null → 400 大类中文名不能为空 ✓
|
||
PUT /admin/fleet/vehicle-types/{suv2 的 id} typeName=" " → 400 ✓
|
||
PUT /admin/fleet/vehicle-types/{suv2 的 id} typeName="" → 400 ✓
|
||
fleet_vehicle_type 全表前后逐字段一致（含 update_time）✓
|
||
```
|
||
|
||
读侧（内部接口，两个实例）：把 `mpv` 的 `type_name` 临时依次改为空串、半角空格、全角空格，`category-names` 均返回 `mpv → "mpv"`，其余 3 个大类名称与顺序不变，`seat-options?vehicleType=mpv` 仍返回 `[7]`；验毕 `type_name` 与 `update_time` 均恢复原值（逐字段一致）。
|
||
|
||
单元测试：`VehicleTypeServiceTest` 28、`VehicleTypeSaveReqVOValidationTest` 5、`VehicleTypeControllerTest` 17、`VehicleTypeControllerIdempotentTest` 6、`FleetRedLineArchTest` 18，共 74 例 0 失败。
|
||
|
||
---
|
||
|
||
## 十、相关文档
|
||
|
||
- 关联 Issue: [wx/HL#8226](https://git.1814.love/wx/HL/issues/8226)
|
||
- 关联 PR: [wx/HL#8232](https://git.1814.love/wx/HL/pulls/8232)
|
||
- 上游来源：#8202（子订单行程用车车型大类接入车队字典校验，582032）
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#8226](https://git.1814.love/wx/HL/issues/8226)
|
||
- **PR**: [#8232](https://git.1814.love/wx/HL/pulls/8232)
|
||
- **Merge commit**: [9231b8d8c](https://git.1814.love/wx/HL/commit/9231b8d8c)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @jw
|
||
- **前端负责人**: @mmg
|