9.9 KiB
子卷包装关系批量新增设计
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。
批量请求包含非空记录列表；每条记录包含：
clientKeypackageBoxSnboxTypeboxLengthboxWidthboxHighqualityGuaranPerioddateOfFgInboundcontainerNamestatus
后端对 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。 - 超限分组全部失败，合法分组正常保存。
- 前端准确显示每条失败记录及错误原因，并允许修改后重试。
- 现有单条新增、修改及列表功能不受影响。