docs: 设计木箱类型最大子卷数字段

docs/superpowers/specs/2026-08-17-box-type-max-num-design.md

@@ -0,0 +1,63 @@
+# 木箱类型最大子卷数设计
+
+## 背景
+
+木箱类型数据库表已追加 `max_num` 字段，用于记录一个木箱允许容纳的最大子卷数量。现需补齐后端数据链路及前端展示、创建、编辑能力。
+
+## 目标与约束
+
+- Java 和 TypeScript 字段统一命名为 `maxNum`，由 MyBatis 的驼峰转下划线规则映射到 `max_num`。
+- 最大子卷数在新增和编辑时均为必填项。
+- 只允许输入大于等于 1 的整数。
+- 新增木箱类型时默认值为 `1`；编辑时使用接口返回的原值。
+- 木箱类型管理列表和复用型木箱类型选择弹窗均展示“最大子卷数”。
+- 数据库字段已由用户添加，本次不新增或修改数据库脚本。
+
+## 方案
+
+采用前后端双重约束：前端数字输入框提供即时限制和默认值，后端参数校验保证通过 API 直接提交的数据同样合法。相比只依赖单端校验，此方案能够兼顾操作体验和数据完整性。
+
+## 后端设计
+
+在木箱类型数据对象、保存请求和响应对象中增加 `Integer maxNum`：
+
+- `BoxTypeDO`：持久化 `max_num`。
+- `BoxTypeSaveReqVO`：使用 `@NotNull` 和 `@Min(1)`，确保新增、编辑请求必须提供大于等于 1 的值。
+- `BoxTypeRespVO`：返回最大子卷数，并使用 Excel 注解支持现有导出链路。
+
+现有 Bean 转换和 MyBatis 通用 Mapper 会自动传递该字段，无需修改 Service 或 Mapper XML。
+
+## 前端设计
+
+在木箱类型 API 类型中增加 `maxNum`，并在表单中增加“最大子卷数”字段：
+
+- 组件使用 `InputNumber`。
+- `defaultValue` 设置为 `1`。
+- `min` 设置为 `1`。
+- `precision` 设置为 `0`，限制为整数。
+- `step` 设置为 `1`。
+- 表单规则设置为必填。
+
+木箱类型管理表格和 `BoxTypeSelectModal` 选择表格均增加“最大子卷数”列。新增时采用默认值，编辑时表单回填接口数据。
+
+## 数据流
+
+1. 新增弹窗初始化 `maxNum = 1`，用户可修改为其他正整数。
+2. 前端提交 `maxNum` 至新增或编辑接口。
+3. 后端校验非空且不小于 1，然后通过现有转换链路写入 `max_num`。
+4. 详情、分页列表和选择弹窗数据源返回 `maxNum` 并展示。
+
+## 异常处理
+
+- 前端通过必填、最小值和整数输入限制减少无效提交。
+- 绕过前端提交空值、0、负数时，后端参数校验拒绝请求并返回现有统一校验错误。
+- 兼容数据库中的历史空值不在本次范围内；编辑历史记录时必须补齐合法值后才能保存。
+
+## 验证
+
+- 检查新增弹窗默认显示 `1`，且只能输入大于等于 1 的整数。
+- 检查编辑弹窗正确回填并提交 `maxNum`。
+- 检查管理列表和选择弹窗展示最大子卷数。
+- 对相关前端文件执行 ESLint。
+- 对 LMS 后端模块及依赖执行跳过测试的 Maven 编译。
+