容器管理 · 需求文档（BM-05）

模块定位

容器管理是 WMS 的物流载具档案层，维护仓储作业所需的容器（周转箱/托盘）档案，供波次拣货、复核封箱、播种出库等作业引用。容器是"边拣边分"和"播种出库"模式中商品暂存与流转的物理载体，与 ERP 业务主数据无直接关联。

要解决的问题

• 出库作业（拣货/复核/封箱）缺少统一的容器载体管理，难以追踪"某波次/任务绑定了哪些容器、是否释放"。
• 容器状态若靠人工记忆或线下台账，极易出现"被占用的容器又被其他任务重复绑定""已停用的容器仍被误用"。
• 手工逐条登记容器编号工作量大、易重号，缺少系统级的唯一性约束与批量初始化手段。

目标（可衡量）

• 容器档案 100% 本地维护，零 ERP 同步依赖，作为独立物流资源存在。
• 容器编号租户内唯一，新建/导入均做重复校验，杜绝重号。
• 以 四态状态机（初始/占用/空闲/停用）精确控制"哪些容器可编辑、哪些可删除、哪些可被作业绑定"。
• 支持批量导入 + 批量打印，降低初始化与现场作业成本。

2.1 核心约束与设计原则

① 数据来源 —— 本地维护，不从 ERP 同步。容器是 WMS 作业层面的物流资源（周转箱/托盘），与 ERP 业务主数据无直接关联，因此完全本地新建与维护，不提供 ERP 接口拉取，也无需回写。

② 唯一性 —— 容器编号租户内唯一。同一租户下容器编号不允许重复；新建与导入时均校验唯一性，重复则拦截（新建）或跳过（导入并记失败原因）。

③ 状态驱动 —— 四态状态机控制可编辑 / 可删除性。容器的"可编辑字段"与"是否可删除"完全由当前状态决定：占用状态全程锁定、仅初始状态可删除、停用的容器不可删除但可重新启用。状态流转见 2.5。

2.2 数据模型（容器档案字段）

容器记录以 容器编号（租户内唯一）+ 租户维度 标识。字段如下：

#	字段	来源 / 可编辑性	说明
1	容器ID	系统生成	系统内部主键，保存时自动生成，不可编辑
2	容器编号	本地 · 必填	容器唯一业务编号，支持手动录入或自动生成；同一租户下不可重复；支持模糊查询
3	容器类型	本地 · 必填	周转箱/托盘等，关联系统字典"容器类型"
4	状态	本地 · 必填	初始 / 占用 / 空闲 / 停用，新增时默认为"初始"
5	创建时间	系统生成	容器创建时间，自动记录
6	备注	本地 · 可选	可选备注信息

2.3 查询与筛选条件

#	查询字段	类型	默认值	说明
1	容器编号	文本	空	支持模糊匹配
2	容器类型	下拉框	全部	全部 / 周转箱 / 托盘等，来源于系统字典
3	状态	下拉框	全部	全部 / 初始 / 占用 / 空闲 / 停用

列表展示字段：容器编号、容器类型、状态、创建时间、备注。

2.4 功能清单与详细需求

#	功能项	优先级	需求说明与验收要点
1	容器档案查询与筛选	P0	列表（分页）+ 按 容器编号（模糊）/ 容器类型 / 状态 筛选；列表展示编号、类型、状态、创建时间、备注。 验收：可按三类条件组合检索；模糊匹配容器编号生效。
2	容器新增	P0	弹窗填写：容器ID系统生成、容器编号必填且租户内唯一、容器类型必填（系统字典）、状态默认"初始"、备注可选；保存前校验编号唯一性。 验收：重复编号拦截并提示；成功保存后状态为"初始"；容器编号支持手动录入或自动生成。
3	容器编辑（按状态差异化）	P0	初始/停用：可编辑全部字段（容器编号除外，停用状态）；空闲：仅可编辑容器类型、备注；占用：不可编辑（提示"该容器正在使用中，不可编辑"）。 验收：各状态可编辑范围与规则一致；占用态编辑被拦截并提示。
4	容器删除（单条/批量，仅初始）	P0	仅"初始"状态可删除；占用/空闲/停用删除时提示"该容器状态为XX，不可删除"；支持单条与批量删除，批量时仅删符合条件的初始记录并提示非初始条数。 验收：非初始态删除被拦截并给出具体状态；批量删除只删初始并报告跳过数。
5	容器批量导入（Excel）	P1	支持 Excel 按模板（容器编号、容器类型、状态、备注）批量导入；校验编号唯一性，重复跳过并记录失败原因；成功后状态默认"初始"。异常：编号重复→"容器编号已存在"；类型不存在→"容器类型不存在"；必填为空→"必填字段为空"。 验收：各类异常被正确跳过并记因；成功行状态为初始。
6	容器标签打印（单条/批量）	P1	支持单条与批量打印容器标签；打印内容：容器编号（条形码/二维码）、容器类型；模板在【系统管理→打印管理】配置；勾选后调用打印方案发送至指定打印机。 验收：标签含编号条码/二维码与类型；批量勾选可一次输出。
7	容器状态流转与操作日志	P0	维护四态状态机：初始↔空闲（手动启用/停用）、空闲↔占用（系统自动绑定/释放）、停用→空闲（手动启用）；状态变更须记录操作日志（谁、何时、从XX状态变为XX状态）。 验收：流转符合规则；占用/空闲自动切换；日志可追溯。

Future（P2，本期不做但架构预留）：容器与货位关联；容器容量/体积维护；容器状态流转可视化看板；容器使用率与周转分析。

2.5 状态机与流转规则

容器状态由 初始 / 占用 / 空闲 / 停用 四态构成，流转如下：

#	流转	触发条件	触发方式
1	初始 → 空闲	手动启用，或首次被任务绑定	手动 / 系统
2	空闲 → 占用	被波次 / 任务绑定	系统自动
3	占用 → 空闲	任务完成，容器释放	系统自动
4	空闲 → 停用	手动停用	手动
5	停用 → 空闲	手动启用	手动

各状态可执行操作：初始——可编辑、可删除、可启用；占用——不可编辑、不可删除；空闲——可编辑（容器编号除外）、不可删除；停用——可编辑（容器编号除外）、可启用、不可删除。
关键依赖：只有"空闲"状态的容器才能被拣货任务绑定，"占用"表示已被某任务锁定。

2.6 导入规则与异常处理

• 导入模板字段：容器编号、容器类型、状态、备注。
• 导入时校验容器编号唯一性，重复则跳过并记"容器编号已存在"。
• 容器类型不存在 → 跳过并记"容器类型不存在"。
• 必填字段为空 → 跳过并记"必填字段为空"。
• 导入成功后状态默认"初始"。

2.7 打印规则

• 支持单条与批量打印容器标签。
• 打印内容：容器编号（条形码/二维码）、容器类型。
• 打印模板在【系统管理→打印管理】中配置；勾选后调用打印方案配置，生成指令发送至指定打印机。

2.8 用户故事

• 作为仓储作业人员，我希望在 WMS 里本地登记一批周转箱/托盘，以便出库作业有统一的容器载体，且不必依赖 ERP。
• 作为仓储作业人员，我希望容器编号在租户内唯一，以便不会出现两个相同编号的容器导致作业混乱。
• 作为出库操作员，我希望只有"空闲"容器能被拣货任务绑定、"占用"容器被锁定，以便不会重复占用同一容器。
• 作为仓储管理员，我希望按状态（初始/占用/空闲/停用）筛选容器，以便快速掌握在库容器的使用情况。
• 作为仓储管理员，我希望批量导入容器、批量打印标签，以便大批量初始化与现场贴标高效完成。
• 作为系统管理员，当容器状态变更时我希望看到谁、在何时、从什么状态改成了什么状态，以便可追溯。

2.9 非目标（Non-goals）

• 不与 ERP 同步容器数据——容器是 WMS 作业层面物流资源，不承载业务主数据。
• 不做容器与货位绑定（一期不需要，二期可扩展）。
• 不维护容器容量 / 体积（一期不需要，二期可扩展）。
• 不替代出库作业逻辑——本模块只管理容器档案与状态，绑定/释放由出库模块在作业中触发。

2.10 主要风险

• 容器编号重号 → 作业绑定冲突、数据串；缓解：新建/导入双重唯一性校验。
• 占用态被误删/误改 → 在途任务失去容器载体；缓解：占用态强制锁定，删除/编辑均拦截并提示。
• 状态机与作业脱节 → 空闲↔占用未与拣货/复核联动，导致"空闲却被占用"或"占用却未释放"；缓解：状态切换由作业事件驱动并记日志。
• 导入异常淹没 → 大批量导入部分失败无感知；缓解：逐条跳过+失败原因记录+结果汇总。

下游：出库管理 / 拆零拣货

• 拣货时绑定容器（边拣边分 / 播种出库模式），容器作为商品暂存载体。
• 只有"空闲"状态的容器才能被拣货任务绑定。

下游：出库管理 / 扫码复核

• 复核时校验容器状态（占用 / 空闲），确保容器处于预期作业态。

下游：出库管理 / 播种复核

• 播种墙作业时容器流转，占用/空闲随作业推进自动切换。

配置依赖：系统管理 / 打印管理

• 容器标签打印模板在此配置，决定标签格式与条码/二维码样式。

配置依赖：系统管理 / 字典管理

• 容器类型（周转箱/托盘等）来源于系统字典，新增编辑时下拉选项依赖字典维护。

关联配置项汇总

#	配置项	路径	说明
1	容器类型字典	系统管理 → 字典管理	维护容器类型（周转箱/托盘等）
2	容器标签打印模板	系统管理 → 打印管理	配置容器标签打印格式

• 性能：列表查询响应时间不超过 1 秒（本地数据）；批量导入速度不低于 100 条/秒。
• 数据一致性：容器编号租户内唯一，不允许重复；容器状态变更需记录操作日志（谁、何时、从 XX 状态变为 XX 状态）。
• 安全性与权限：多租户隔离——所有查询与写操作须按 tenant_id 维度隔离，跨租户不可见彼此容器；占用态容器前后端双重锁定（无编辑入口 + 后端写拦截）。
• 可用性与容错：批量导入失败隔离（单条异常不影响整体批次），失败明细可查；占用态的编辑/删除请求须明确提示原因而非静默失败。
• 可维护性与扩展性：容器类型走系统字典，便于类型增减；状态机可扩展（二期货位关联、容量维护）。
• 异常处理：容器编号重复提示"容器编号已存在，请重新输入"；占用状态容器被编辑提示"该容器正在使用中，不可编辑"；非初始状态容器被删除提示"该容器状态为XX，不可删除"。

评审核对清单

• 数据来源是否明确为"本地维护、不依赖 ERP"，且不与商品/供应商的 ERP 同步逻辑混淆？
• 容器编号租户内唯一性约束是否在新建与导入两条链路都生效？
• 四态状态机的可编辑 / 可删除矩阵是否完整且前后端一致？
• 占用↔空闲的自动切换是否由出库作业事件可靠驱动，并配套操作日志？
• 批量导入的异常跳过 + 失败原因记录 + 结果汇总是否满足大批量场景？
• 打印模板与条形码/二维码内容是否已在【系统管理→打印管理】定义清晰？
• 与出库拣货/复核的容器绑定、状态校验、流转口径是否对齐？
• 多租户隔离（tenant_id）是否满足安全与合规要求？
• 非目标边界是否清晰（不绑定货位、不维护容量、不替代出库逻辑），避免范围蔓延？

当前 PRD 结论（已记录开放问题）

#	评审问题	当前结论
P01	容器编号是否支持自动生成？	支持，同时支持手动录入
P02	容器是否需要与货位关联？	一期不需要，二期可扩展
P03	容器容量 / 体积是否需要维护？	一期不需要，二期可扩展
P04	容器状态流转是否全部自动？	空闲↔占用为自动，其余为手动