233 lines
9.9 KiB
Markdown
233 lines
9.9 KiB
Markdown
# 子卷包装关系批量新增设计
|
||
|
||
## 1. 背景与目标
|
||
|
||
子卷包装关系列表目前仅支持单条新增。新增“批量新增”功能，用户可在同一个弹窗中录入多条 `lms_sub_package_relation` 数据，并在卡片视图与表格视图之间自由切换。两种视图共享同一份数据，切换时不丢失输入。
|
||
|
||
实现以 `docs/prototype_design/design/2026-08-17-sub-package-relation-card-batch-design.html` 中的“自由切换批量新增”为交互参考，不追求额外视觉扩展，重点是稳定录入、分组校验、部分成功保存和逐行错误反馈。
|
||
|
||
## 2. 范围
|
||
|
||
### 2.1 本次包含
|
||
|
||
- 在子卷包装关系列表工具栏增加“批量新增”按钮。
|
||
- 在 `src/views/lms/subpackagerelation/modules` 中封装独立批量新增弹窗组件。
|
||
- 支持卡片和表格两种批量录入视图，并可自由切换。
|
||
- 复用现有木箱类型选择弹窗选择木箱类型并回填尺寸。
|
||
- 复用字典管理中的 `sub_package_status` 状态字典，默认状态为 `0`。
|
||
- 新增独立批量创建 API、请求 VO、响应 VO 和服务方法。
|
||
- 按“木箱码 + 木箱类型”分组校验 `lms_box_type.max_num`。
|
||
- 合法分组保存；失败分组返回到前端逐行展示，不影响其他合法分组。
|
||
|
||
### 2.2 本次不包含
|
||
|
||
- 不修改现有单条新增、修改接口及其请求实体。
|
||
- 不调整列表查询、删除、导出功能。
|
||
- 不新增权限标识，批量新增沿用 `lms:sub-package-relation:create`。
|
||
- 不修改数据库表结构。
|
||
- 不增加原型之外的批量导入、Excel 粘贴、拖拽排序等功能。
|
||
|
||
## 3. 前端设计
|
||
|
||
### 3.1 页面接入
|
||
|
||
在子卷包装关系列表页接入批量新增弹窗，并在工具栏增加“批量新增”按钮。按钮使用 `lms:sub-package-relation:create` 权限。
|
||
|
||
批量新增全部成功时关闭弹窗并刷新列表；部分成功时保持弹窗打开，同时刷新列表以显示已保存的数据。
|
||
|
||
### 3.2 组件职责
|
||
|
||
在 `apps/web-antdv-next/src/views/lms/subpackagerelation/modules` 下新增独立批量新增弹窗组件。该组件负责：
|
||
|
||
- 维护统一的批量记录数组 `rows`。
|
||
- 渲染卡片视图或表格视图。
|
||
- 新增、复制、删除和清空记录。
|
||
- 打开木箱类型选择弹窗并回填当前行。
|
||
- 执行前端必填校验。
|
||
- 提交批量请求并将失败结果映射回具体记录。
|
||
|
||
每条前端记录包含稳定且不重复的 `clientKey`。切换视图、增删记录和提交失败后均保留该标识。后端原样返回失败记录的 `clientKey`，前端以此定位错误行，不使用可能变化的数组下标作为唯一标识。
|
||
|
||
### 3.3 录入字段
|
||
|
||
批量新增只录入以下字段：
|
||
|
||
| 字段 | 必填 | 交互 |
|
||
| --- | --- | --- |
|
||
| `packageBoxSn` | 是 | 输入木箱唯一码 |
|
||
| `boxType` | 是 | 点击只读输入区域，打开木箱类型选择弹窗 |
|
||
| `boxLength` | 否 | 选择木箱类型后自动回填，只读 |
|
||
| `boxWidth` | 否 | 选择木箱类型后自动回填，只读 |
|
||
| `boxHigh` | 否 | 选择木箱类型后自动回填，只读 |
|
||
| `qualityGuaranPeriod` | 是 | 输入保质期 |
|
||
| `dateOfFgInbound` | 是 | 选择入库日期 |
|
||
| `containerName` | 是 | 输入子卷号 |
|
||
| `status` | 是 | 使用 `sub_package_status` 字典，默认 `0` |
|
||
|
||
木箱类型选择复用：
|
||
|
||
`apps/web-antdv-next/src/views/lms/boxtype/components/BoxTypeSelectModal.vue`
|
||
|
||
组件记录当前正在选择木箱类型的 `clientKey`。选择完成后，将 `boxType`、`boxLength`、`boxWidth` 和 `boxHigh` 回填到该记录。
|
||
|
||
### 3.4 卡片与表格切换
|
||
|
||
- 弹窗初始存在一条空记录，默认显示表格视图。
|
||
- 卡片和表格只负责展示与编辑，数据源始终是同一个 `rows` 数组。
|
||
- 视图切换不创建数据副本，不触发提交，也不清理校验错误。
|
||
- 卡片视图按记录展示字段和错误信息。
|
||
- 表格视图按行展示字段，宽度不足时使用横向滚动。
|
||
|
||
### 3.5 行操作
|
||
|
||
- 新增：在末尾添加一条空记录，状态默认 `0`。
|
||
- 复制：复制木箱类型、尺寸、保质期、入库日期和状态；清空木箱唯一码、子卷号，并生成新的 `clientKey`。
|
||
- 删除：删除目标记录；组件至少保留一条空记录。
|
||
- 清空：清除全部输入和错误，并恢复为一条状态为 `0` 的空记录。
|
||
|
||
### 3.6 前端校验和结果处理
|
||
|
||
提交前检查所有必填字段。有缺失时不发送请求，在卡片或表格对应行显示错误。
|
||
|
||
后端响应后：
|
||
|
||
- 全部成功：关闭弹窗，提示成功，触发列表刷新。
|
||
- 部分成功：刷新列表；删除已保存记录，只保留失败记录；根据 `clientKey` 写入错误信息；弹窗保持打开。
|
||
- 全部失败：保留全部记录，根据 `clientKey` 展示错误信息。
|
||
|
||
## 4. 后端接口设计
|
||
|
||
### 4.1 接口
|
||
|
||
新增独立接口：
|
||
|
||
`POST /lms/sub-package-relation/batch-create`
|
||
|
||
权限：`lms:sub-package-relation:create`
|
||
|
||
现有 `POST /create` 和 `PUT /update` 不变。
|
||
|
||
### 4.2 请求实体
|
||
|
||
新增批量请求 VO 和批量行 VO，避免复用现有包含大量必填校验的 `SubPackageRelationSaveReqVO`。
|
||
|
||
批量请求包含非空记录列表；每条记录包含：
|
||
|
||
- `clientKey`
|
||
- `packageBoxSn`
|
||
- `boxType`
|
||
- `boxLength`
|
||
- `boxWidth`
|
||
- `boxHigh`
|
||
- `qualityGuaranPeriod`
|
||
- `dateOfFgInbound`
|
||
- `containerName`
|
||
- `status`
|
||
|
||
后端对 `clientKey` 和业务必填字段再次校验。批量行 VO 不包含 `id`，该接口只执行新增。
|
||
|
||
### 4.3 响应实体
|
||
|
||
响应包含：
|
||
|
||
- `successCount`：成功保存条数。
|
||
- `failureCount`：失败条数。
|
||
- `failures`：失败记录列表。
|
||
|
||
每条失败记录包含：
|
||
|
||
- `clientKey`：前端记录标识。
|
||
- `rowIndex`：请求中的一基行号，用于辅助展示和日志定位。
|
||
- `errorCode`：稳定的错误类型。
|
||
- `message`：面向用户的中文错误信息。
|
||
|
||
预期错误类型至少包括必填校验失败、木箱类型不存在、木箱容量超限和分组保存失败。
|
||
|
||
## 5. 业务校验与保存流程
|
||
|
||
### 5.1 分组规则
|
||
|
||
请求记录按 `packageBoxSn + boxType` 分组。每个分组是容量校验和保存事务的最小业务单元。
|
||
|
||
### 5.2 木箱类型校验
|
||
|
||
根据请求中去重后的 `boxType` 批量查询 `lms_box_type`。不存在的木箱类型对应分组全部失败，每条记录均返回错误。
|
||
|
||
后端容量判断使用数据库中 `lms_box_type` 的 `max_num`，不信任前端回填数据。请求携带的长、宽、高作为本次关系记录的保存值；木箱类型不存在时不保存。
|
||
|
||
### 5.3 容量校验
|
||
|
||
对每个“木箱码 + 木箱类型”分组，统计数据库中相同木箱码和木箱类型的现有有效关系数量，并计算：
|
||
|
||
`数据库已有数量 + 本次分组数量 <= lms_box_type.max_num`
|
||
|
||
满足条件时分组可保存；超过上限时整个分组失败，本次分组内一条都不保存。错误信息包含木箱码、类型、最大容量、已有数量和本次提交数量，例如：
|
||
|
||
`木箱 BX001（类型 A）最多容纳 3 个子卷，已有 2 个，本次提交 2 个`
|
||
|
||
逻辑删除数据不计入已有数量，沿用 MyBatis-Plus 的逻辑删除过滤规则。
|
||
|
||
### 5.4 分组隔离保存
|
||
|
||
通过独立事务执行器或等价的可生效事务边界逐组保存，禁止依赖同类方法自调用触发事务。
|
||
|
||
- 合法分组在独立事务中写入。
|
||
- 分组内任意一条写入失败，该组事务全部回滚。
|
||
- 一个分组失败不影响其他分组继续保存。
|
||
- 保存失败时，该组每条记录均返回同一分组写入错误。
|
||
|
||
接口本身正常返回结构化结果；仅在无法继续处理整个请求的系统级异常时返回通用接口错误。
|
||
|
||
### 5.5 并发边界
|
||
|
||
本次仅在服务层执行“查询已有数量后判断”的容量校验，不新增数据库锁、唯一约束或表结构。并发请求同时操作相同木箱码和类型时，仍可能产生竞态；该问题不在本次“不修改数据库结构、不过度设计”的实现范围内。
|
||
|
||
## 6. 错误展示
|
||
|
||
前端在记录级别保存后端错误：
|
||
|
||
- 卡片视图：显示在卡片头部或卡片内容上方。
|
||
- 表格视图：显示在对应行的错误区域，并保留该行所有输入。
|
||
- 顶部汇总提示成功条数和失败条数。
|
||
|
||
错误记录在用户修改对应行后可清除；再次提交时只提交弹窗中保留的失败记录。
|
||
|
||
## 7. 验证方案
|
||
|
||
### 7.1 后端测试
|
||
|
||
- 未超 `max_num` 时正常保存。
|
||
- 数据库已有数量加本次数量刚好等于 `max_num` 时正常保存。
|
||
- 超过 `max_num` 时该组全部失败。
|
||
- 多个分组中一组超限，其他组正常保存。
|
||
- 木箱类型不存在时该组失败。
|
||
- 某组写入异常时该组回滚，其他组不受影响。
|
||
- `clientKey`、一基行号、成功数和失败数返回正确。
|
||
|
||
### 7.2 前端验证
|
||
|
||
- 卡片和表格切换后输入、行标识和错误不丢失。
|
||
- 新增、复制、删除和清空行为正确。
|
||
- 木箱类型弹窗回填到当前记录，并带出长、宽、高。
|
||
- `sub_package_status` 字典加载正确，新增行默认状态为 `0`。
|
||
- 前端必填校验能定位具体记录。
|
||
- 部分成功后只保留失败记录并展示原因。
|
||
|
||
### 7.3 完成前命令验证
|
||
|
||
- 运行 LMS 后端受影响模块的定向测试或编译。
|
||
- 运行前端目标应用的类型检查。
|
||
- 对新增和修改的前端文件执行可用的静态检查。
|
||
- 若项目工具链自身异常，保留失败输出并在交付说明中区分代码问题和环境问题。
|
||
|
||
## 8. 成功标准
|
||
|
||
- 用户可从列表页打开批量新增弹窗。
|
||
- 用户可在卡片和表格视图间自由切换，输入不丢失。
|
||
- 木箱类型通过现有选择弹窗选择，尺寸正确回填。
|
||
- 状态来自 `sub_package_status` 字典，默认值为 `0`。
|
||
- 后端按“木箱码 + 木箱类型”结合数据库已有数量校验 `max_num`。
|
||
- 超限分组全部失败，合法分组正常保存。
|
||
- 前端准确显示每条失败记录及错误原因，并允许修改后重试。
|
||
- 现有单条新增、修改及列表功能不受影响。
|