# 基础资料与车船务模块测试用例

## 范围说明

- 后台前端路径：`/base/region`、`/base/port-terminal`、`/base/railway-station`、`/base/airport-master`、`/vehicle/maintenance-record`、`/vehicle/maintenance-plan`、`/base/fee-item`、`/base/currency`、`/base/customer-type`
- 后端服务：基础资料走 `blade-system`，维修/保养走 `blade-transport`
- 依据：前端页面、前端 API、后端 Controller、Service、Entity 的真实字段、权限码、接口路径和校验逻辑

## 通用用例

### REQ-COMMON-01 列表与分页

- 功能点：进入页面后自动请求列表或树接口，支持分页、刷新、搜索、重置搜索。
- 异常与边界：① `current/size` 缺失时使用默认分页；② 搜索条件为空时返回全部可见数据；③ 搜索无结果时显示空表格；④ 后端返回异常时页面 loading 应结束并提示错误。
- 反例：① 无 Token 调接口返回 401；② 无菜单权限访问页面或接口返回 403；③ 篡改分页参数为负数或超大值不应导致服务异常。

### REQ-COMMON-02 新增与编辑

- 功能点：有新增或编辑权限时可打开表单，必填项校验通过后提交，成功后刷新列表。
- 异常与边界：① 必填字段为空前端应阻断；② 直接调接口绕过前端校验时，后端有业务校验的模块应返回失败；③ 编辑不存在或已删除数据应失败或不产生脏数据。
- 反例：① 无新增权限不显示新增按钮，直接调新增接口返回 403；② 无编辑权限不显示编辑按钮，直接调编辑接口返回 403。

### REQ-COMMON-03 删除、批量删除与逻辑删除

- 功能点：单条删除、批量删除确认后调用 `remove` 接口，成功后列表移除数据。
- 异常与边界：① 未勾选数据点击批量删除提示“请选择至少一条数据”；② `ids` 为空、非数字、包含不存在 ID 不应误删其他数据；③ 删除后列表不再展示逻辑删除数据。
- 反例：① 无删除权限不显示删除按钮，直接调删除接口返回 403；② 重复删除同一数据不应导致服务异常。

### REQ-COMMON-04 启用/停用

- 功能点：支持启用/停用的模块可切换状态，状态值为 `1=启用`、`2=停用`。
- 异常与边界：① `id` 为空返回“主键不能为空”；② 状态不是 1 或 2 返回“启停状态不正确”；③ 数据不存在返回对应“不存在”提示。
- 反例：① 无状态权限不显示启停按钮；② 直接传 `status=0/3/null` 不应更新状态。

### REQ-COMMON-05 导入、导出与模板

- 功能点：支持导入导出的模块可下载模板、上传 `.xls/.xlsx`、按筛选条件或选中 ID 导出。
- 异常与边界：① 上传非 Excel 文件应失败；② 空模板导入应提示失败或无数据；③ 导入部分行错误时应返回具体行号；④ 导出选中数据时只导出选中 ID。
- 反例：① 无导入/导出/模板权限不显示对应按钮；② 直接调接口无权限返回 403。

## 行政区划 `/base/region`

### REQ-REGION-01 懒加载区划树

- 功能点：左侧树默认以 `parentCode=00` 加载省级节点，点击节点加载下级，右侧回显详情。
- 异常与边界：① 顶级、叶子节点、无子节点均应正确展示；② 节点无子节点时 `leaf=true`；③ `parentCode` 不存在时返回空列表；④ 节点切换时右侧表单数据同步更新。
- 反例：① 直接传异常 `parentCode` 不应报 500；② 无 `region` 菜单权限访问 `/blade-system/region/lazy-tree` 返回 403。

### REQ-REGION-02 新增/编辑下级区划

- 功能点：点击“新增下级”后自动带出父区划编号、父区划名称，填写区划子编号、名称、等级、排序后提交 `/blade-system/region/submit`。
- 异常与边界：① 父区划编号、区划编号、名称、等级、排序必填；② 子编号拼接后不能与已有区划冲突；③ 已存在区划编号时后端执行更新；④ 区划等级为省/市/区/镇/村时写入对应编码与名称字段。
- 反例：① 缺少区划名称前端应阻断；② 直接调接口传空 `code/name/regionLevel` 不应产生不可用节点；③ 非法等级不应生成错误层级数据。

### REQ-REGION-03 删除区划

- 功能点：选中无子节点的区划后可删除，调用 `/blade-system/region/remove?id=code`。
- 异常与边界：① 存在子节点时返回“请先删除子节点!”；② 删除叶子节点后树刷新不再展示；③ 删除根节点或顶级关键节点需被权限/业务规则保护。
- 反例：① 传不存在 code 不应删除其他节点；② 无删除权限不显示“删除”按钮。

### REQ-REGION-04 导入与覆盖

- 功能点：下载行政区划模板，上传 Excel，可选择“数据覆盖”。
- 异常与边界：① `isCovered=0` 时重复主键应失败；② `isCovered=1` 时重复主键应更新；③ Excel 必填列缺失或父子关系错误应提示；④ 大批量导入后树加载正常。
- 反例：① 非 Excel 文件上传失败；② 无导入权限不显示导入入口。

### REQ-REGION-05 导出与调试

- 功能点：导出当前筛选行政区划数据，调试弹窗可验证区划查询结果。
- 异常与边界：① 空筛选导出全量可见数据；② 按编码/名称筛选导出匹配数据；③ 数据量大时导出文件能正常生成。
- 反例：① 无导出权限不显示导出按钮；② 无调试权限不显示调试按钮。

## 港口码头主数据 `/base/port-terminal`

### REQ-PORT-01 列表、搜索与上级港口下拉

- 功能点：列表支持按编码、名称、类型、所属省份、所属城市、数据来源、状态搜索；新增码头时通过 `/port-select` 加载启用港口。
- 异常与边界：① 港口行的上级港口显示 `-`；② 码头行展示父港口名称和编码；③ 仅启用且类型为“港口”的数据进入上级港口下拉。
- 反例：① 停用港口不应出现在上级港口下拉；② 无查询权限直接调列表返回 403。

### REQ-PORT-02 新增港口

- 功能点：类型选择“港口”，填写 5 位大写字母编码、名称、所属城市、经纬度、数据来源后保存。
- 异常与边界：① 编码自动转大写；② 港口编码必须匹配 `^[A-Z]{5}$`；③ 港口保存时清空上级港口字段；④ 编码唯一。
- 反例：① 编码为空返回“编码不能为空”；② 编码为 `AB12C` 或长度不是 5 返回“港口编码为5位大写字母”；③ 重复编码返回“该编码已存在”。

### REQ-PORT-03 新增码头

- 功能点：类型选择“码头”，选择上级港口，编码格式为 `港口编码-码头标识`，保存后自动写入父港口信息。
- 异常与边界：① 未选上级港口返回“码头必须选择上级港口”；② 上级类型必须为港口；③ 码头编码必须以上级港口编码加 `-` 开头；④ 保存后继承父港口所属省份/城市。
- 反例：① 编码 `ABCDE01` 返回“码头编码格式为港口编码-码头标识”；② 编码 `ZZZZZ-01` 但父港口为 `ABCDE` 返回“码头编码必须以所属港口编码开头”。

### REQ-PORT-04 编辑、启停、删除

- 功能点：可编辑港口/码头基础信息，可启用/停用，可逻辑删除。
- 异常与边界：① 停用港口前若存在已启用码头，返回“该港口下存在已启用码头，请先停用码头”；② 状态非法返回“启停状态不正确”；③ 删除后列表不展示。
- 反例：① 直接停用不存在 ID 返回“港口码头不存在”；② 无编辑/状态/删除权限时按钮不可见且接口返回 403。

### REQ-PORT-05 导入、导出、模板

- 功能点：下载“港口码头主数据模板”，批量导入港口/码头，按查询条件或选中 ID 导出。
- 异常与边界：① 导入错误返回具体 Excel 行号；② 重复编码导入失败；③ 码头行必须能匹配父港口；④ 导出状态显示“启用/停用”。
- 反例：① 非 Excel 文件上传失败；② 无导入/导出/模板权限不显示按钮。

## 铁路车站主数据 `/base/railway-station`

### REQ-RAIL-01 列表与搜索

- 功能点：列表展示编码、TMIS 国标编码、电报码、车站名称、线路、省市、经纬度、数据来源、状态，支持名称、数据来源、状态等搜索。
- 异常与边界：① 空列表显示正常；② 创建/更新时间格式正确；③ 搜索重置后恢复全量列表。
- 反例：① 无菜单权限访问列表接口返回 403；② 非法分页参数不应导致 500。

### REQ-RAIL-02 新增/编辑车站

- 功能点：填写 TMIS 国标编码、电报码、车站名称、所属城市、经纬度后保存；后端自动生成编码 `TL + TMIS`。
- 异常与边界：① TMIS 必须 5 位数字；② 电报码必须 3 位大写字母；③ 省份、城市必选且城市必须隶属于省份；④ 备注最多 200 字。
- 反例：① TMIS 为 `1234A` 返回“TMIS国标编码为5位数字”；② 电报码为 `ab1` 返回“电报码为3位大写字母”；③ 省市不匹配返回“所属城市与所属省份不匹配”。

### REQ-RAIL-03 唯一性与坐标

- 功能点：TMIS、电报码、编码均唯一；经度范围 -180 到 180，纬度范围 -90 到 90。
- 异常与边界：① 编辑自身不触发重复；② 经度/纬度为空允许保存；③ 边界值 -180、180、-90、90 可保存。
- 反例：① 重复 TMIS 返回“该TMIS编码已存在”；② 重复电报码返回“该电报码已存在”；③ 经度 181 或纬度 91 返回范围错误。

### REQ-RAIL-04 启停、删除、导入导出

- 功能点：支持启停、批量删除、下载模板、批量导入、批量导出。
- 异常与边界：① 状态仅允许 1/2；② 导入错误返回具体行号；③ 导出选中 ID 时只导出选中数据。
- 反例：① 不存在 ID 启停返回“铁路车站不存在”；② 无对应权限时按钮不可见且接口返回 403。

## 空港机场主数据 `/base/airport-master`

### REQ-AIRPORT-01 列表与搜索

- 功能点：列表展示编码、IATA、ICAO、机场标准名称、简称、省市、经纬度、数据来源、状态，支持名称、编码、数据来源、状态搜索。
- 异常与边界：① 空数据时表格正常；② 搜索无结果展示空列表；③ 时间字段格式正确。
- 反例：① 无菜单权限访问 `/blade-system/airport-master/list` 返回 403。

### REQ-AIRPORT-02 新增/编辑机场

- 功能点：填写 IATA、ICAO、机场标准名称、所属省市、经纬度后保存；后端自动生成编码 `JC- + IATA`。
- 异常与边界：① IATA 必须 3 位大写字母；② ICAO 必须 4 位大写字母；③ 省市必选且隶属关系正确；④ 简称可为空；⑤ 备注最多 200 字。
- 反例：① IATA 为 `PV1` 返回“IATA编码为3位大写字母”；② ICAO 为 `ZSS` 返回“ICAO代码为4位大写字母”；③ 省市不匹配返回“所属城市与所属省份不匹配”。

### REQ-AIRPORT-03 唯一性与坐标

- 功能点：IATA、ICAO、编码唯一；经纬度范围与铁路车站一致。
- 异常与边界：① 编辑自身不触发重复；② 经纬度为空允许保存；③ 边界坐标可保存。
- 反例：① 重复 IATA 返回“该IATA编码已存在”；② 重复 ICAO 返回“该ICAO代码已存在”；③ 经度 181 或纬度 -91 返回范围错误。

### REQ-AIRPORT-04 启停、删除、导入导出

- 功能点：支持启停、批量删除、下载模板、导入、导出。
- 异常与边界：① 状态仅允许 1/2；② 导入错误返回 Excel 行号；③ 导出状态显示“启用/停用”。
- 反例：① 不存在 ID 启停返回“空港机场不存在”；② 无权限时按钮不可见且接口返回 403。

## 车辆维修记录 `/vehicle/maintenance-record`

### REQ-MAINT-RECORD-01 列表、查看与搜索

- 功能点：列表展示车船类型、车牌号/船号、维修人、维修时间、位置、费用、里程/航程、附件数量等；支持车船类型、车牌号/船号、创建时间范围搜索。
- 异常与边界：① 附件为 JSON 数组时显示数量；② 附件为逗号字符串时按逗号计数；③ 里程单位为空时默认按车船类型展示。
- 反例：① 无查看权限不显示查看按钮；② 无菜单权限调列表接口返回 403。

### REQ-MAINT-RECORD-02 新增/编辑维修记录

- 功能点：新增或编辑时填写车船类型、车牌号/船号、维修时间、费用等，保存到 `/blade-transport/maintenance-record/submit`。
- 异常与边界：① 前端要求车船类型、车牌号/船号、维修时间、费用必填；② 车牌号/船号最多 30 字符；③ 维修人最多 20 字符；④ 位置/地址最多 100 字符；⑤ 更换零件最多 200 字符；⑥ 备注最多 500 字符。
- 反例：① 前端传空车牌号应阻断；② 直接调接口绕过前端传空必填字段，当前后端未做完整业务校验，应作为接口层风险重点确认；③ 超长字段前端应阻断。

### REQ-MAINT-RECORD-03 里程单位默认值

- 功能点：`mileageUnit` 为空时，车辆默认“公里”，船舶默认“海里”。
- 异常与边界：① 车船类型从车辆切换船舶后默认单位应同步；② 已手动选择单位时不应被错误覆盖；③ 详情回显单位正确。
- 反例：① `vehicleType=船舶` 且 `mileageUnit` 为空保存后不应显示“公里”；② `vehicleType=车辆` 为空不应显示“海里”。

### REQ-MAINT-RECORD-04 删除与权限

- 功能点：支持单条和批量逻辑删除，删除后列表不展示。
- 异常与边界：① 未勾选批量删除提示；② 删除多个 ID 时只删除选中数据；③ 租户数据不应跨租户可见。
- 反例：① 无删除权限不显示按钮且接口返回 403；② 非本租户数据不应被查询或删除。

## 车辆保养计划 `/vehicle/maintenance-plan`

### REQ-MAINT-PLAN-01 列表、查看与搜索

- 功能点：列表展示车船类型、车牌号/船号、保养人、保养时间、保养项目、费用、里程/航程、下次保养时间、下次保养里程、附件数量等。
- 异常与边界：① 创建时间范围搜索生效；② 里程和下次保养里程展示单位；③ 附件数量展示规则与维修记录一致。
- 反例：① 无查看权限不显示查看按钮；② 无菜单权限调列表接口返回 403。

### REQ-MAINT-PLAN-02 新增/编辑保养计划

- 功能点：新增或编辑时填写车船类型、车牌号/船号、保养时间、费用、保养项目、下次保养信息等。
- 异常与边界：① 前端要求车船类型、车牌号/船号、保养时间、费用必填；② 车牌号/船号最多 30 字符；③ 保养人最多 20 字符；④ 保养项目/地址最多 100 字符；⑤ 店名最多 50 字符；⑥ 联系电话最多 20 字符；⑦ 备注最多 500 字符。
- 反例：① 费用为空前端应阻断；② 直接调接口绕过前端传空必填字段，当前后端未做完整业务校验，应作为接口层风险重点确认。

### REQ-MAINT-PLAN-03 里程单位与下次保养

- 功能点：车辆默认“公里”，船舶默认“海里”；下次保养时间、下次保养里程可为空。
- 异常与边界：① 下次保养时间早于保养时间时需确认业务是否允许；② 下次保养里程小于当前里程时需确认业务是否允许；③ 单位切换后两个里程字段展示一致。
- 反例：① 船舶默认单位不应为“公里”；② 前端或后端不应因下次保养字段为空报错。

### REQ-MAINT-PLAN-04 删除与权限

- 功能点：支持单条和批量逻辑删除。
- 异常与边界：① 未勾选批量删除提示；② 删除后列表刷新；③ 租户隔离生效。
- 反例：① 无删除权限不显示按钮且接口返回 403；② 非本租户数据不应被查询或删除。

## 费用项 `/base/fee-item`

### REQ-FEE-01 列表与搜索

- 功能点：列表展示中文名称、英文名称、状态、更新时间、创建时间，支持中文名称、英文名称、状态搜索。
- 异常与边界：① 空搜索返回全部未删除数据；② 搜索不存在名称返回空列表；③ 状态标签正确显示“启用/停用”。
- 反例：① 无菜单权限调 `/blade-system/fee-item/list` 返回 403。

### REQ-FEE-02 新增/编辑费用项

- 功能点：中文名称必填，英文名称非必填；提交前去除前后空格；默认状态为启用。
- 异常与边界：① 中文名称最多 50 字；② 英文名称最多 100 字；③ 中文名称唯一；④ 编辑自身不触发重复。
- 反例：① 中文名称为空返回“中文名称不能为空”；② 重复中文名称返回“该中文名称已存在”；③ 英文名称超过 100 字返回“英文名称不能超过100字”。

### REQ-FEE-03 启停、删除与权限

- 功能点：支持启用/停用和批量逻辑删除。
- 异常与边界：① 状态仅允许 1/2；② 删除后不出现在列表；③ 无选择批量删除提示。
- 反例：① 不存在 ID 启停返回“费用项不存在”；② 无新增/编辑/删除/状态权限时对应按钮不可见且接口返回 403。

## 币种主数据 `/base/currency`

### REQ-CURRENCY-01 列表与搜索

- 功能点：列表展示币种代码、中文名、英文名、符号、小数位数、汇率、本位币、数据来源、状态，支持代码、中文名、英文名、本位币、数据来源、状态搜索。
- 异常与边界：① 本位币以“是/否”标签展示；② 状态以“启用/停用”展示；③ 搜索重置后恢复全量。
- 反例：① 无菜单权限调列表接口返回 403。

### REQ-CURRENCY-02 新增/编辑币种

- 功能点：币种代码 3 位大写字母，中文名称必填，小数位数 0 到 8，汇率大于 0，本位币默认否，数据来源默认手工导入。
- 异常与边界：① 代码自动转大写并过滤非字母；② 本位币选择“是”时汇率自动设为 1；③ 备注最多 200 字；④ 编辑自身不触发代码重复。
- 反例：① 代码为空返回“币种代码不能为空”；② 代码 `US1` 返回“币种代码为3位大写字母”；③ 小数位数 -1 或 9 返回“小数位数范围为0到8”；④ 汇率 0 返回“汇率必须大于0”。

### REQ-CURRENCY-03 本位币唯一性

- 功能点：系统只允许一个本位币，且本位币汇率必须为 1。
- 异常与边界：① 第一条本位币可保存；② 第二条设置本位币返回失败；③ 修改已有本位币的其他字段仍应成功；④ 将非本位币改为本位币前需确保无其他本位币。
- 反例：① 本位币汇率为 6.8 返回“本位币汇率必须为1”；② 已存在本位币时新增另一个本位币返回“本位币只能设置一个”。

### REQ-CURRENCY-04 启停、删除、导入导出

- 功能点：支持启停、批量删除、模板下载、批量导入、导出。
- 异常与边界：① 导入“是否本位币”仅支持 是/否/1/0；② 导入重复代码返回具体行号；③ 导出本位币和状态显示中文。
- 反例：① 导入本位币填写“Y”返回“是否本位币只能填写是或否”；② 不存在 ID 启停返回“币种不存在”；③ 无权限时按钮不可见且接口返回 403。

## 客商类型 `/base/customer-type`

### REQ-CUSTOMER-TYPE-01 列表与搜索

- 功能点：列表展示中文名称、英文名称、状态、更新时间、创建时间，支持中文名称、英文名称、状态搜索。
- 异常与边界：① 空搜索返回全部未删除数据；② 搜索无结果展示空表格；③ 状态标签正确。
- 反例：① 无菜单权限调 `/blade-system/customer-type/list` 返回 403。

### REQ-CUSTOMER-TYPE-02 新增/编辑客商类型

- 功能点：中文名称必填，英文名称非必填；提交前去除前后空格；默认状态为启用。
- 异常与边界：① 中文名称最多 50 字；② 英文名称最多 100 字；③ 中文名称唯一；④ 编辑自身不触发重复。
- 反例：① 中文名称为空返回“中文名称不能为空”；② 重复中文名称返回“该中文名称已存在”；③ 英文名称超过 100 字返回“英文名称不能超过100字”。

### REQ-CUSTOMER-TYPE-03 启停、删除与权限

- 功能点：支持启用/停用和批量逻辑删除。
- 异常与边界：① 状态仅允许 1/2；② 删除后不出现在列表；③ 未选择数据批量删除提示。
- 反例：① 不存在 ID 启停返回“客商类型不存在”；② 无新增/编辑/删除/状态权限时对应按钮不可见且接口返回 403。

## 依赖与风险

- 行政区划是机场、铁路车站、港口/码头所属地区选择的数据基础，测试机场/铁路/港口前需准备省市区划数据。
- 港口/码头存在父子关系，停用港口前需先停用其下启用码头。
- 维修记录、保养计划目前主要依赖前端校验，后端直接 `saveOrUpdate`，接口直调空必填字段、负费用、超长字段等场景应作为风险用例重点验证。
- 所有模块均依赖 `@PreAuth(menu=...)` 和按钮权限，测试时需准备有权限、无按钮权限、无菜单权限三类账号。
