# 常用货物需求卡

## 目录

- [REQ-CYHW-001 列表与分页](#req-cyhw-001-列表与分页)
- [REQ-CYHW-002 条件查询与重置](#req-cyhw-002-条件查询与重置)
- [REQ-CYHW-003 查看常用货物](#req-cyhw-003-查看常用货物)
- [REQ-CYHW-004 新增常用货物](#req-cyhw-004-新增常用货物)
- [REQ-CYHW-005 编辑常用货物](#req-cyhw-005-编辑常用货物)
- [REQ-CYHW-006 编号与级联规则](#req-cyhw-006-编号与级联规则)
- [REQ-CYHW-007 下载导入模板](#req-cyhw-007-下载导入模板)
- [REQ-CYHW-008 批量导入](#req-cyhw-008-批量导入)
- [REQ-CYHW-009 批量导出](#req-cyhw-009-批量导出)
- [REQ-CYHW-010 单条删除](#req-cyhw-010-单条删除)
- [REQ-CYHW-011 批量删除](#req-cyhw-011-批量删除)
- [REQ-CYHW-012 组织权限与审计](#req-cyhw-012-组织权限与审计)
- [通用规则](#通用规则)

---

### REQ-CYHW-001 列表与分页

- 功能点：

  - 默认展示当前组织全部常用货物数据，列表按更新时间降序排列。
  - 展示组织、一级货物类型、二级货物类型、货物名称、货物编号、品牌、包装、货值、规格、计价单位、型号、说明、备注、创建人、更新时间、创建时间、操作等字段。
  - 支持勾选多行数据用于批量导出、批量删除。
  - 操作列固定展示查看、编辑、删除，具体显示受权限控制。
  - 普通用户默认仅看当前组织数据，列表顶部不提供“当前组织/全部组织”切换。
  - 分页默认 10 条/页，支持 20/50/100 条/页。

- 异常与边界：

  - 查询无数据时展示空状态。
  - 当前页删除后无数据时自动回退页码并刷新列表。
  - 列表、分页、导入、导出均按当前组织权限范围生效。
  - 列表加载失败时保留当前筛选与分页条件。

- 反例：
  - 不允许默认按更新时间以外的字段覆盖排序规则。
  - 不允许通过列表顶部组织范围切换查看全部组织数据。
  - 不允许分页后丢失当前查询条件。

---

### REQ-CYHW-002 条件查询与重置

- 功能点：

  - 筛选条件仅保留货物名称、货物编号、一级货物类型、二级货物类型、组织，按该顺序展示。
  - 点击查询后按条件展示数据。
  - 点击重置后清空所有条件并恢复默认列表。

- 异常与边界：

  - 查询条件为空时点击查询，按默认规则展示当前组织全部数据。
  - 查询结果为空时展示空状态，不清空用户已输入条件。
  - 重置后页码恢复第一页，并按更新时间降序重新加载。

- 反例：
  - 不允许重置后仍保留隐藏条件。
  - 不允许只按单一条件查询而忽略组合条件。
  - 不允许展示品牌、包装、货值、规格、计价单位、型号、说明、数据来源等额外筛选条件。

---

### REQ-CYHW-003 查看常用货物

- 功能点：

  - 支持通过行操作查看常用货物详情。
  - 详情展示所有业务字段，字段全部置灰不可编辑。
  - 查看弹窗底部仅显示关闭按钮。

- 异常与边界：

  - 数据已删除或不存在时提示数据不存在，并刷新列表。
  - 详情加载失败时提示失败原因，不影响列表现状。

- 反例：
  - 不允许在查看状态下保存修改。
  - 不允许查看时切换组织范围并修改数据。
  - 不允许查看弹窗出现提交按钮。

---

### REQ-CYHW-004 新增常用货物

- 功能点：

  - 支持新增常用货物档案，货物所属类别通过一级货物类型与二级货物类型级联选择定义。
  - 一级货物类型使用下拉搜索选择。
  - 二级货物类型使用下拉搜索选择，未选一级货物类型时置灰不可操作；切换一级货物类型时二级选项自动清空并重新加载。
  - 一级货物类型、二级货物类型、货物名称、货物编号为必填字段，字段名称需展示“\*”标识。
  - 新增、编辑表单不展示一级货物类型编码、二级货物类型编码，只保留货物编号字段。
  - 选择二级货物类型后，货物编号自动拼接一级货物类型编号在前面，用户仅需继续补充后续编号。
  - 货物名称使用文本输入框，必填，长度不超过 100 字符。
  - 货物编号使用文本输入框，必填，长度不超过 20 字符。
  - 品牌使用文本输入框，选填，长度不超过 50 字符。
  - 货值使用普通输入框，选填，仅允许输入数字，最多保留 2 位小数；计价单位下拉选择放在货值输入框后面同一行展示。
  - 规格使用文本输入框，选填，长度不超过 50 字符。
  - 型号使用文本输入框，选填，长度不超过 50 字符。
  - 说明使用文本输入框，选填，长度不超过 100 字符。
  - 备注使用文本域，选填，长度不超过 200 字符。
  - 包装为下拉选择，选项包含袋装、散装、桶装、箱装、托盘等。
  - 计价单位为下拉选择，选项包含元/吨、元/立方米、元/件、元/车。
  - 保存成功后刷新列表。

- 异常与边界：

  - 一级货物类型为空时阻止提交并提示“请选择一级货物类型”。
  - 二级货物类型为空时阻止提交并提示“请选择二级货物类型”。
  - 货物名称为空、超长或格式不合法时阻止提交并提示“请输入货物名称”。
  - 货物编号为空、超长或未拼接一级货物类型编号前缀时阻止提交。
  - 选择二级货物类型后未带出一级货物类型编号前缀时阻止提交。
  - 二级货物类型不属于当前一级货物类型时阻止提交。
  - 货物编号重复时阻止提交并提示“该货物编号已存在”。
  - 货值包含非数字字符或小数位超过 2 位时阻止提交。
  - 包装或计价单位不在允许选项内时阻止提交。
  - 品牌、规格、型号超过 50 字符时阻止提交。
  - 说明超过 100 字符时阻止提交。
  - 备注超过 200 字符时阻止提交并提示。
  - 提交失败时保留用户已填写内容。

- 反例：
  - 不允许在未选择一级货物类型时选择二级货物类型。
  - 不允许手工删除或修改货物编号中的一级货物类型编号前缀。
  - 不允许保存重复货物编号。
  - 不允许新增启用/停用状态字段。

---

### REQ-CYHW-005 编辑常用货物

- 功能点：

  - 支持编辑已存在的常用货物档案。
  - 一级货物类型、二级货物类型在编辑状态下置灰不可编辑。
  - 货物编号在编辑状态下置灰不可编辑。
  - 编辑表单不展示一级货物类型编码、二级货物类型编码，只保留货物编号字段。
  - 货物名称、品牌、包装、货值、规格、计价单位、型号、说明、备注等字段可编辑。
  - 货值使用普通输入框且只能输入数字，计价单位下拉选择紧跟在货值后面同一行展示。
  - 可编辑字段的控件类型、长度限制和校验规则与新增一致。
  - 保存成功后刷新列表。

- 异常与边界：

  - 货物名称、货值、包装、计价单位、备注等字段的校验规则与新增保持一致。
  - 编辑的数据已不存在时提示数据不存在，并刷新列表。
  - 提交失败时保留用户修改内容。

- 反例：
  - 不允许编辑时修改一级货物类型、二级货物类型和货物编号。
  - 不允许编辑后产生重复货物编号。
  - 不允许编辑状态下绕过新增校验规则。

---

### REQ-CYHW-006 编号与级联规则

- 功能点：

  - 常用货物所属类别由一级货物类型和二级货物类型级联定义。
  - 一级货物类型变更时，二级货物类型选项同步刷新。
  - 二级货物类型必须归属于当前选择的一级货物类型。
  - 选择二级货物类型后，货物编号必须自动拼接一级货物类型编号在前面。
  - 货物编号全局唯一。

- 异常与边界：

  - 一级货物类型未选择时二级货物类型下拉置灰不可操作。
  - 切换一级货物类型后已选二级货物类型自动清空。
  - 一级货物类型编号前缀不存在时不允许继续保存。
  - 二级货物类型与一级货物类型不匹配时不允许继续保存。
  - 货物编号重复时阻止提交并提示“该货物编号已存在”。

- 反例：
  - 不允许货物编号脱离二级货物类型单独维护。
  - 不允许一级、二级货物类型选错后仍沿用旧编号前缀。
  - 不允许出现同一货物编号多条记录。

---

### REQ-CYHW-007 下载导入模板

- 功能点：

  - 支持下载 Excel 导入模板。
  - 模板字段包含一级货物类型、二级货物类型编码、货物名称、货物编号后缀、品牌、包装、单价、规格、计价单位、型号、说明、备注。
  - 模板中一级货物类型、二级货物类型编码、货物名称、货物编号后缀为必填字段，字段名称需增加“\*”标识。
  - 模板中的字段顺序与导入校验顺序保持一致。
  - 模板字段说明需标明：货物名称不超过 100 字符；品牌、规格、型号不超过 50 字符；说明不超过 100 字符；备注不超过 200 字符。
  - 模板用于批量导入常用货物档案。

- 异常与边界：

  - 模板下载失败时提示失败，允许重新下载。
  - 模板字段缺失或顺序错误时视为模板异常，应修正后再发布。
  - 模板应附带字段说明，明确货物编号后缀为 2 位数字，单价为数值且保留 2 位小数。

- 反例：
  - 不允许模板缺少一级货物类型、二级货物类型编码、货物名称、货物编号后缀等关键字段。
  - 不允许模板包含与导入无关的状态字段。
  - 不允许模板字段与导入校验字段不一致。

---

### REQ-CYHW-008 批量导入

- 功能点：

  - 支持上传 Excel 文件批量导入常用货物。
  - 导入时逐条校验必填项、长度、数字格式、货物编号唯一性、二级货物类型编码是否存在等规则。
  - 导入时根据二级货物类型编码自动取得 4 位货物编号前缀，并与货物编号后缀组成完整货物编号。
  - 导入成功的数据标记为“批量导入”。
  - 存在失败行时自动生成错误报告 Excel 并自动下载，失败文件字段顺序与原模板一致，并在最后一列追加“导入失败原因”。
  - 导入失败明细文件名包含“常用货物导入失败明细”和时间戳。
  - 导入完成后刷新列表，并在页面上方提示“导入数据成功”。

- 异常与边界：

  - 文件格式错误时阻止导入并提示失败原因。
  - 一级货物类型为空时对应行导入失败并写入错误原因。
  - 二级货物类型编码不存在时对应行导入失败并写入错误原因。
  - 二级货物类型编码不属于填写的一级货物类型时对应行导入失败。
  - 货物名称为空或超过 100 字符时对应行导入失败。
  - 货物编号后缀为空或不是 2 位数字时对应行导入失败。
  - 货物编号重复时对应行导入失败并写入错误原因“该货物编号已存在”。
  - 品牌、规格、型号超过 50 字符时对应行导入失败。
  - 说明超过 100 字符时对应行导入失败。
  - 单价小于 0 或小数位超过 2 位时对应行导入失败。
  - 包装或计价单位不在允许选项内时对应行导入失败。
  - 备注超过 200 字符时对应行导入失败。
  - 单行错误不影响其他正确数据入库。
  - 全部失败时不入库，但仍生成错误报告。
  - 存在部分失败时下载失败明细，并提示“部分数据导入失败，已下载失败明细”。

- 反例：
  - 不允许错误数据静默跳过。
  - 不允许错误数据入库。
  - 不允许只提示失败数量而不提供失败明细。

---

### REQ-CYHW-009 批量导出

- 功能点：

  - 支持勾选多行数据后批量导出 Excel 文件。
  - 未勾选数据时点击批量导出，默认导出当前查询条件下的全部数据。
  - 导出字段与列表显示字段一致。

- 异常与边界：

  - 当前条件下无数据时允许导出空文件或提示无可导出数据。
  - 导出失败时提示失败原因，不改变当前勾选状态。

- 反例：
  - 不允许只导出当前页数据。
  - 不允许未筛选时导出非当前查询条件数据。

---

### REQ-CYHW-010 单条删除

- 功能点：

  - 支持通过行操作删除单条常用货物。
  - 点击删除弹出二次确认弹窗，提示删除后不可恢复。
  - 删除成功后刷新列表，并提示“删除成功”。

- 异常与边界：

  - 删除前必须校验是否已被运单、合同、报价单、库存记录等业务数据引用。
  - 已被引用时不允许删除，并 toast 提示“已被业务引用，不允许删除”。
  - 数据不存在时提示数据不存在，并刷新列表。

- 反例：
  - 不允许跳过二次确认直接删除。
  - 不允许删除已被业务引用的常用货物。
  - 不允许用停用状态替代删除。

---

### REQ-CYHW-011 批量删除

- 功能点：

  - 支持勾选多行常用货物后批量删除。
  - 点击批量删除弹出二次确认弹窗。
  - 删除前逐一校验所选数据是否被业务引用。
  - 已引用记录从删除队列剔除并单独提示。
  - 删除成功后刷新列表，并提示“删除成功 XX 条，因引用跳过 XX 条”。

- 异常与边界：

  - 未勾选数据时点击批量删除，应提示先选择需要删除的数据。
  - 所选数据全部被引用时不执行删除，并提示全部跳过原因。
  - 部分删除失败时应提示成功数量和跳过数量。

- 反例：
  - 不允许批量删除已被业务引用的记录。
  - 不允许因为部分记录被引用而影响可删除记录的正常删除。
  - 不允许删除后不刷新列表。

---

### REQ-CYHW-012 组织权限与审计

- 功能点：

  - 组织列作为数据权限字段，普通用户默认仅可查看当前组织数据。
  - 列表顶部不提供“当前组织/全部组织”切换。
  - 根据权限配置控制查看、编辑、删除、导入、导出等操作入口。
  - 创建人、创建时间、更新时间由系统自动记录。

- 异常与边界：

  - 无权限用户访问时提示权限不足。
  - 不允许通过前端组织范围切换越权查看或操作全部组织数据。
  - 列表、详情、导出等用户可见场景优先展示创建人姓名，不直接展示用户 ID。

- 反例：
  - 不允许普通用户通过手动构造组织条件越权修改数据。
  - 不允许手动维护创建人、创建时间、更新时间。
  - 不允许删除或篡改审计信息。

---

## 通用规则

- 常用货物是实际业务中高频使用的具体货物档案。
- 货物所属类别必须通过一级货物类型与二级货物类型级联确定。
- 新增、编辑表单不展示一级货物类型编码、二级货物类型编码，只保留货物编号。
- 选择二级货物类型后，货物编号必须自动拼接一级货物类型编号在前面。
- 货物编号在系统中全局唯一，新增、编辑、导入时均需校验重复；重复时提示“该货物编号已存在”。
- 一级货物类型与二级货物类型为级联关系，一级变更时二级选项必须清空并重新加载。
- 货物名称必填且长度不超过 100 字符。
- 货值使用普通输入框，仅允许输入数字，最多保留 2 位小数；计价单位下拉放在货值后面同一行展示。
- 品牌、规格、型号最多 50 字符。
- 说明最多 100 字符。
- 备注最多 200 字符。
- 包装选项包含袋装、散装、桶装、箱装、托盘等；计价单位选项包含元/吨、元/立方米、元/件、元/车。
- 新增、编辑、导入成功后均需刷新列表。
- 删除前必须校验业务引用，已引用记录不允许删除。
