fix bug

需求卡/货物类型管理需求卡.md

@@ -0,0 +1,348 @@
+# 货物类型管理需求卡
+
+## 目录
+
+- [REQ-CARGO-001 列表与分页](#req-cargo-001-列表与分页)
+- [REQ-CARGO-002 条件查询与重置](#req-cargo-002-条件查询与重置)
+- [REQ-CARGO-003 查看货物类型](#req-cargo-003-查看货物类型)
+- [REQ-CARGO-004 新增货物类型](#req-cargo-004-新增货物类型)
+- [REQ-CARGO-005 编辑货物类型](#req-cargo-005-编辑货物类型)
+- [REQ-CARGO-006 编码与层级校验](#req-cargo-006-编码与层级校验)
+- [REQ-CARGO-007 下载导入模板](#req-cargo-007-下载导入模板)
+- [REQ-CARGO-008 批量导入](#req-cargo-008-批量导入)
+- [REQ-CARGO-009 批量导出](#req-cargo-009-批量导出)
+- [REQ-CARGO-010 单条删除](#req-cargo-010-单条删除)
+- [REQ-CARGO-011 批量删除](#req-cargo-011-批量删除)
+- [REQ-CARGO-012 权限与日志](#req-cargo-012-权限与日志)
+- [通用规则](#通用规则)
+
+---
+
+### REQ-CARGO-001 列表与分页
+
+- 功能点：
+  - 默认展示全部货物类型数据。
+  - 展示序号、货物类型、货物类型编码、上级货物类型、上级货物类型编码、创建人、备注、更新时间、创建时间、操作等字段。
+  - 一级货物类型的上级货物类型、上级货物类型编码显示为“/”。
+  - 默认按创建时间降序展示。
+  - 支持分页展示，默认10条/页，支持20/50/100条/页。
+  - 支持勾选多行数据，用于批量导出、批量删除。
+  - 操作列固定展示查看、编辑、删除。
+
+- 异常与边界：
+  - 查询无数据时展示空状态。
+  - 当前页数据删除后为空时自动调整页码并刷新列表。
+  - 列表加载失败时保留当前查询条件和分页条件，提示用户重新查询。
+
+- 反例：
+  - 不允许默认按货物类型编码、名称或更新时间覆盖创建时间降序规则。
+  - 不允许分页后丢失当前查询条件。
+  - 不允许在操作列展示启用、停用操作。
+
+
+---
+
+### REQ-CARGO-002 条件查询与重置
+
+- 功能点：
+  - 支持按货物类型、货物类型编码条件查询。
+  - 选择或输入查询条件后，点击查询按钮展示符合条件的数据。
+  - 点击重置按钮清空所有查询条件，并恢复默认列表。
+  - 支持多个查询条件组合筛选。
+
+- 异常与边界：
+  - 查询条件为空时点击查询，按默认规则展示全部数据。
+  - 查询结果为空时展示空状态，不清空用户已输入的查询条件。
+  - 重置后页码恢复到第一页，并按创建时间降序重新加载数据。
+
+- 反例：
+  - 不允许点击重置后仍保留隐藏查询条件。
+  - 不允许只按单个条件查询而忽略其他已选择条件。
+  - 不允许查询后改变列表字段或操作按钮范围。
+
+
+---
+
+### REQ-CARGO-003 查看货物类型
+
+- 功能点：
+  - 支持通过行操作查看货物类型详情。
+  - 详情展示类型、上级货物类型、上级货物类型编码、货物类型、货物类型编码、备注、创建人、创建时间、更新时间等信息。
+  - 查看状态下字段只读。
+
+- 异常与边界：
+  - 数据已被删除或不存在时提示数据不存在，并刷新列表。
+  - 一级货物类型详情中的上级货物类型、上级货物类型编码显示为“/”或空值。
+  - 详情加载失败时提示失败原因，不改变列表数据。
+
+- 反例：
+  - 不允许在查看状态下保存修改。
+  - 不允许将创建人展示为用户ID。
+  - 不允许查看详情时自动切换为编辑状态。
+
+
+---
+
+### REQ-CARGO-004 新增货物类型
+
+- 功能点：
+  - 支持新增一级货物类型和二级货物类型。
+  - 新增字段包含类型、上级货物类型、上级货物类型编码、货物类型、货物类型编码、备注。
+  - 类型使用radio单选控件，选项为一级货物类型、二级货物类型，默认选中一级货物类型。
+  - 上级货物类型使用搜索下拉选择控件，仅在选择二级货物类型时显示，支持按上级货物类型名称或编码搜索。
+  - 上级货物类型编码使用文本输入框展示，选择上级货物类型后自动带出，不可编辑。
+  - 货物类型使用文本输入框，必填，长度为1~50字符。
+  - 货物类型编码使用文本输入框，必填，长度为4以内；一级货物类型编码为2位数字，二级货物类型编码为4位数字且前2位继承父级编码。
+  - 备注使用文本输入框，非必填，最多200字符。
+  - 类型字段必填，并在字段名称前展示“*”标识。
+  - 货物类型字段必填，并在字段名称前展示“*”标识。
+  - 选择一级货物类型时，录入货物类型、货物类型编码、备注；货物类型编码必填并在字段名称前展示“*”标识，上级货物类型和上级货物类型编码不展示。
+  - 选择二级货物类型时，展示上级货物类型、上级货物类型编码、货物类型编码等字段；上级货物类型、上级货物类型编码、货物类型、货物类型编码均必填并在字段名称前展示“*”标识。
+  - 选择二级货物类型时，上级货物类型通过搜索下拉选择；上级货物类型编码、货物类型编码在选择上级货物类型后自动带出。
+  - 保存成功后刷新列表。
+
+- 异常与边界：
+  - 类型为空时阻止提交并提示“请选择货物类型级别”。
+  - 选择二级货物类型且上级货物类型为空时阻止提交并提示“请选择上级货物类型”。
+  - 货物类型为空时阻止提交并提示“请输入货物类型名称”。
+  - 货物类型超过50字符时阻止提交并提示。
+  - 同一上级下存在同名货物类型时阻止提交并提示“该上级下已存在同名货物类型”。
+  - 一级货物类型的货物类型编码为空或不是2位数字时阻止提交并提示“货物类型编码格式不正确”。
+  - 二级货物类型的货物类型编码为空或不是4位数字时阻止提交并提示“货物类型编码格式不正确”。
+  - 二级货物类型编码前2位与上级货物类型编码不一致时阻止提交并提示“二级编码前2位必须与上级货物类型编码一致”。
+  - 货物类型编码重复时阻止提交并提示“该货物类型编码已存在”。
+  - 备注超过200字符时阻止提交并提示“备注不能超过200字”。
+  - 提交失败时保留用户已填写内容，方便修正后重新提交。
+
+- 反例：
+  - 不允许新增无编码的货物类型。
+  - 不允许新增无上级货物类型的二级货物类型。
+  - 不允许新增时设置启用或停用状态。
+
+
+---
+
+### REQ-CARGO-005 编辑货物类型
+
+- 功能点：
+  - 支持编辑已存在的货物类型信息。
+  - 编辑字段包含类型、上级货物类型、上级货物类型编码、货物类型、货物类型编码、备注。
+  - 类型使用radio单选控件，选项为一级货物类型、二级货物类型。
+  - 上级货物类型使用搜索下拉选择控件，仅在选择二级货物类型时显示，支持按上级货物类型名称或编码搜索。
+  - 上级货物类型编码使用文本输入框展示，选择上级货物类型后自动带出，不可编辑。
+  - 货物类型使用文本输入框，必填，长度为1~50字符。
+  - 货物类型编码使用文本输入框，必填，长度为4以内；一级货物类型编码为2位数字，二级货物类型编码为4位数字且前2位继承父级编码。
+  - 备注使用文本输入框，非必填，最多200字符。
+  - 二级货物类型选择上级货物类型后，自动带出上级货物类型编码和货物类型编码。
+  - 保存成功后刷新列表。
+
+- 异常与边界：
+  - 类型为空时阻止提交并提示“请选择货物类型级别”。
+  - 选择二级货物类型且上级货物类型为空时阻止提交并提示“请选择上级货物类型”。
+  - 货物类型为空时阻止提交并提示“请输入货物类型名称”。
+  - 货物类型超过50字符时阻止提交并提示。
+  - 同一上级下存在同名货物类型时阻止提交并提示“该上级下已存在同名货物类型”。
+  - 修改货物类型编码时重新校验编码格式和全局唯一性。
+  - 修改二级货物类型的上级货物类型时，重新校验层级关系合法性。
+  - 一级货物类型的货物类型编码为空或不是2位数字时阻止提交并提示“货物类型编码格式不正确”。
+  - 二级货物类型的货物类型编码为空或不是4位数字时阻止提交并提示“货物类型编码格式不正确”。
+  - 二级货物类型编码前2位与上级货物类型编码不一致时阻止提交并提示“二级编码前2位必须与上级货物类型编码一致”。
+  - 货物类型编码重复时阻止提交并提示“该货物类型编码已存在”。
+  - 备注超过200字符时阻止提交并提示“备注不能超过200字”。
+  - 编辑的数据已不存在时提示数据不存在，并刷新列表。
+  - 提交失败时保留用户修改内容，方便修正后重新提交。
+
+- 反例：
+  - 不允许编辑后产生重复货物类型编码。
+  - 不允许将二级货物类型修改为无上级货物类型的数据。
+  - 不允许通过编辑操作设置启用或停用状态。
+
+
+---
+
+### REQ-CARGO-006 编码与层级校验
+
+- 功能点：
+  - 货物类型采用两级层级结构，一级货物类型为大类，二级货物类型为小类。
+  - 每条二级货物类型通过上级货物类型编码关联到一级货物类型。
+  - 一级货物类型编码为2位数字。
+  - 二级货物类型编码为4位数字，前2位继承父级编码，后2位为自增序号。
+  - 货物类型编码在系统中全局唯一。
+
+- 异常与边界：
+  - 一级货物类型编码不是2位数字时阻止提交。
+  - 二级货物类型编码不是4位数字时阻止提交。
+  - 二级货物类型编码前2位与上级货物类型编码不一致时阻止提交。
+  - 编码重复时阻止提交并提示“该货物类型编码已存在”。
+
+- 反例：
+  - 不允许一级货物类型编码为1、001、A1。
+  - 不允许二级货物类型编码为120、00120、01A0。
+  - 不允许上级货物类型编码为01时录入0201作为二级货物类型编码。
+
+
+---
+
+### REQ-CARGO-007 下载导入模板
+
+- 功能点：
+  - 支持下载Excel导入模板。
+  - 模板字段包含类型、上级货物类型、上级货物类型编码、货物类型、货物类型编码、备注。
+  - 模板中类型、货物类型、货物类型编码为必填字段，字段名称需增加“*”标识。
+  - 模板中上级货物类型、上级货物类型编码仅在类型为二级货物类型时必填，字段名称需增加“*”标识并注明适用条件。
+  - 模板必填字段标题需展示为“*类型”“*上级货物类型”“*上级货物类型编码”“*货物类型”“*货物类型编码”，其中上级货物类型和上级货物类型编码仅适用于二级货物类型。
+  - 模板字段说明需标明：类型为单选值，仅允许填写一级货物类型或二级货物类型；上级货物类型支持按名称或编码匹配；货物类型长度1~50字符；备注最多200字符。
+  - 模板中一级货物类型的货物类型编码由用户手动填写，二级货物类型的货物类型编码根据选择的上级货物类型自动带出。
+  - 模板用于批量导入一级货物类型和二级货物类型。
+
+- 异常与边界：
+  - 模板下载失败时提示下载失败，用户可重新下载。
+  - 模板字段顺序应保持稳定，避免用户导入时映射错误。
+  - 模板中的编码填写说明应与层级编码规则保持一致。
+  - 模板中必填字段未带“*”标识时视为模板不符合要求，应修正后发布。
+
+- 反例：
+  - 不允许模板缺少类型、货物类型编码等关键字段。
+  - 不允许模板包含启用、停用状态字段。
+  - 不允许模板字段与导入校验字段不一致。
+  - 不允许二级货物类型导入模板隐藏上级货物类型或上级货物类型编码。
+
+
+---
+
+### REQ-CARGO-008 批量导入
+
+- 功能点：
+  - 支持上传Excel文件批量导入货物类型。
+  - 导入时逐条校验必填项、字段长度、数据格式、同级名称唯一性、编码唯一性、层级关系合法性。
+  - 导入类型仅允许一级货物类型、二级货物类型。
+  - 导入二级货物类型时，上级货物类型为条件必填，需能按上级货物类型名称或编码匹配到唯一一级货物类型，并自动关联上级货物类型编码。
+  - 导入一级货物类型时，上级货物类型和上级货物类型编码不参与校验和入库。
+  - 校验通过的数据入库成功，并标记为“批量导入”。
+  - 若存在失败行，生成错误报告Excel并自动下载。
+  - 导入完成后刷新列表，并在页面上方提示“导入数据成功”。
+
+- 异常与边界：
+  - 文件格式错误时阻止导入并提示失败原因。
+  - 类型为空或不属于允许选项时对应行导入失败，并写入错误原因“请选择货物类型级别”。
+  - 二级货物类型的上级货物类型为空或无法匹配到唯一一级货物类型时对应行导入失败，并写入错误原因“请选择上级货物类型”。
+  - 货物类型为空时对应行导入失败，并写入错误原因“请输入货物类型名称”。
+  - 货物类型超过50字符时对应行导入失败并写入错误原因。
+  - 同一上级下存在同名货物类型时对应行导入失败，并写入错误原因“该上级下已存在同名货物类型”。
+  - 一级货物类型的货物类型编码为空或不是2位数字时对应行导入失败，并写入错误原因“货物类型编码格式不正确”。
+  - 二级货物类型的货物类型编码为空或不是4位数字时对应行导入失败，并写入错误原因“货物类型编码格式不正确”。
+  - 二级货物类型编码前2位与上级货物类型编码不一致时对应行导入失败，并写入错误原因“二级编码前2位必须与上级货物类型编码一致”。
+  - 备注超过200字符时对应行导入失败，并写入错误原因“备注不能超过200字”。
+  - 单行数据错误不影响其他校验通过的数据入库。
+  - 全部数据失败时不入库，但仍生成错误报告Excel。
+  - 导入文件内存在重复编码或与系统已有编码重复时，对应行导入失败并写入错误原因。
+  - 二级货物类型引用的上级货物类型不存在时，对应行导入失败并写入错误原因。
+
+- 反例：
+  - 不允许异常数据静默跳过。
+  - 不允许错误数据入库。
+  - 不允许只提示失败数量而不提供错误报告。
+  - 不允许导入启用或停用状态。
+
+
+---
+
+### REQ-CARGO-009 批量导出
+
+- 功能点：
+  - 支持勾选多行数据后批量导出Excel文件。
+  - 未勾选数据时点击批量导出，默认导出当前查询条件下的全部数据。
+  - 导出字段与列表显示字段一致。
+
+- 异常与边界：
+  - 当前查询条件下无数据时允许导出空文件或提示无可导出数据。
+  - 导出数据量较大时提示用户等待或按系统策略异步处理。
+  - 导出失败时提示失败原因，不改变列表勾选状态。
+
+- 反例：
+  - 不允许未勾选数据时导出全系统未筛选数据。
+  - 不允许只导出当前页数据。
+  - 不允许导出列表未展示的启用、停用状态字段。
+
+
+---
+
+### REQ-CARGO-010 单条删除
+
+- 功能点：
+  - 支持通过行操作删除单条货物类型。
+  - 点击删除时弹出二次确认弹窗，提示“确定要删除该货物类型吗？删除后不可恢复。”。
+  - 删除成功后刷新列表，并提示“删除成功”。
+
+- 异常与边界：
+  - 删除前校验该货物类型是否已被运单、合同等业务数据引用。
+  - 已被业务数据引用时不允许删除，并提示“该货物类型已被业务数据引用，不可删除”。
+  - 数据已不存在时提示数据不存在，并刷新列表。
+  - 用户取消二次确认时不执行删除。
+
+- 反例：
+  - 不允许跳过二次确认直接删除。
+  - 不允许删除已被业务数据引用的货物类型。
+  - 不允许用停用状态替代删除操作。
+
+
+---
+
+### REQ-CARGO-011 批量删除
+
+- 功能点：
+  - 支持勾选多行货物类型后批量删除。
+  - 点击批量删除时弹出二次确认弹窗。
+  - 确认删除前逐一校验所选数据是否被业务引用。
+  - 已引用的记录从删除队列剔除并单独提示。
+  - 删除完成后刷新列表，并提示“删除成功XX条，因业务引用跳过XX条”。
+
+- 异常与边界：
+  - 未勾选数据时点击批量删除，应提示先选择需要删除的数据。
+  - 所选数据全部被引用时不执行删除，并提示全部跳过原因。
+  - 部分删除失败时应提示成功数量、失败数量和失败原因。
+  - 用户取消二次确认时不执行删除。
+
+- 反例：
+  - 不允许批量删除已被业务数据引用的货物类型。
+  - 不允许因为部分数据被引用而取消全部可删除数据的删除。
+  - 不允许删除后不刷新列表。
+
+
+---
+
+### REQ-CARGO-012 权限与日志
+
+- 功能点：
+  - 根据用户权限控制查看、新增、编辑、删除、导入、导出等操作入口。
+  - 记录新增、编辑、删除、批量导入、批量导出等关键操作日志。
+  - 创建人、创建时间、更新时间由系统自动记录。
+
+- 异常与边界：
+  - 无权限访问或操作时提示权限不足。
+  - 操作失败时不记录为成功日志。
+  - 列表、详情、导出等用户可见场景优先展示创建人姓名，不直接展示用户ID。
+
+- 反例：
+  - 不允许无权限用户执行新增、编辑、删除、导入、导出操作。
+  - 不允许用户手动维护创建人、创建时间、更新时间。
+  - 不允许删除或篡改操作日志。
+
+
+---
+
+## 通用规则
+
+- 货物类型数据采用两级层级结构：一级货物类型为大类，二级货物类型为小类。
+- 每条二级货物类型必须通过上级货物类型编码关联到一级货物类型。
+- 货物类型编码遵循层级编码规则：一级货物类型为2位数字编码，二级货物类型为4位数字编码，前2位继承父级编码，后2位为自增序号。
+- 货物类型编码在系统中全局唯一，新增、编辑、导入提交时均需校验重复；重复时提示“该货物类型编码已存在”。
+- 新增页面和导入模板中，类型、货物类型、货物类型编码必须做必填校验并展示“*”标识；选择二级货物类型时，上级货物类型、上级货物类型编码必须显示、必填并展示“*”标识。
+- 新增、编辑页面中，类型使用radio单选控件，上级货物类型使用下拉选择控件，其他字段使用输入框。
+- 一级货物类型编码由用户手动输入；二级货物类型的上级货物类型编码、货物类型编码在选择上级货物类型后自动带出。
+- 本模块不设置启用/停用状态，货物类型一旦创建后长期有效；业务上不需要的货物类型通过删除操作处理。
+- 删除货物类型前必须校验是否已被运单、合同等业务数据引用；已被引用的数据不允许删除。
+- 备注最多200个字，超过限制时应阻止提交并提示。
+- 列表默认按创建时间降序展示，分页默认10条/页，支持20/50/100条/页。
+- 新增、编辑、导入、删除成功后均需刷新列表。
+- 列表、详情、导出等用户可见场景应展示用户姓名，避免直接展示用户ID。