升鲜宝供应链管理系统
box_周转物功能设计模块详细开发文档
|-----------|--------------------------------------------|
| 文档版本 | V1.0 |
| 适用系统 | 升鲜宝供应链管理系统 / 订单式物流配送模块 / 周转物管理 |
| 技术栈建议 | Spring Boot + MyBatis-Plus + MySQL + Redis |
| 数据来源 | 义乌供应链管理系统数据库SQL.txt 中 tms_box_* 周转物相关表 |
| 输出日期 | 2020-01-18 |
| 文档定位 | 研发设计、数据库建模、接口开发、业务联调、测试验收依据 |
说明：本文档在现有 tms_box_* 表结构基础上，整理周转物模块的完整业务闭环，并给出建议升级为独立 box_ 模块的数据库结构、作业流程、接口与落地方案。
修订记录
|--------|------------|-----------------------------------------|--------|
| 版本 | 日期 | 说明 | 作者 |
| V1.0 | 2020-01-18 | 首次整理：基于 tms_box_* 表分析并补齐 box_ 周转物模块设计。 | 升鲜宝 |
1. 文档目标与范围
本文档用于指导升鲜宝供应链管理系统中 box_ 周转物模块的功能设计、数据库建模、接口开发、库存与押金联动、配送签收回收联调及测试验收。
• 覆盖周转物基础资料、库存、购入、发出、归还、报损、押金、客户余额、司机暂存、库存流水。
• 兼容现有义乌供应链 SQL 中的 tms_box_* 表，并给出后续统一为 box_ 模块的重构表结构。
• 重点适配订单式物流配送：按客户配送点聚合订单、装箱、司机配送、客户签收、旧箱回收。
• 不把周转物作为普通商品库存处理，周转物是物流资产库存，不能混入 wms_goods_inventory 商品库存。
2. 现状表识别与模块边界
当前 SQL 中周转物相关表使用 tms_box_* 前缀，说明该能力原先放在配送 TMS 模块下。实际业务上，周转物需要同时服务订单、仓库、配送、司机、客户、财务押金，因此建议升级为独立 box_ 业务域。
|-----------------------|----------|-----------------------------|----------------------------------|
| 当前表 | 当前含义 | 建议新表 | 优化说明 |
| tms_box_type | 周转物类型表 | box_type | 保留分类能力，补充类型编码。 |
| tms_box | 周转物定义表 | box_item | 将长宽高重量改为 decimal，支持体积和装载计算。 |
| tms_box_inventory | 周转物库存表 | box_inventory | 补充 workhouse_id、可用、锁定、客户占用、司机暂存。 |
| tms_box_operation | 购入/报损操作表 | box_operation_bill + detail | 从单表升级为主从单据，支持一单多箱型。 |
| tms_box_out_record | 发出表 | box_out_bill + detail | 关联订单、配送任务、司机、车辆、客户配送点。 |
| tms_box_return_record | 归还表 | box_return_bill + detail | 支持原发出明细回收、损坏、丢失、赔偿。 |
| tms_box_record_log | 周转物日志表 | box_inventory_flow | 升级为统一库存流水，支持幂等与审计。 |
模块边界定义如下：
|----------|------------------|----------------------------------|
| 业务域 | 是否属于 box_ 模块 | 说明 |
| 周转物资料 | 是 | 类型、编码、名称、押金、规格、审核。 |
| 周转物库存 | 是 | 公司仓库周转物库存、客户占用、司机暂存。 |
| 商品库存 | 否 | 商品库存属于 wms_/hwms_，周转物不能作为商品库存核算。 |
| 配送任务 | 联动 | 配送任务生成周转物发出/归还，但任务本身属于物流配送模块。 |
| 客户押金/赔偿 | 联动 | 押金占用、释放、扣罚需要与财务/客户余额联动。 |
| 订单商品体积重量 | 联动 | 用于推荐周转箱数量和类型，来源订单明细/商品资料。 |
3. 业务角色与核心对象
|-----------|---------------------------------|-----------------------------------------------------|
| 角色/对象 | 职责 | 关联数据 |
| 仓库管理员 | 维护周转物资料、购入、装箱、发出审核、归还入库、盘点报损。 | box_item、box_inventory、box_out_bill、box_return_bill |
| 物流调度员 | 根据订单和线路安排车辆、司机、客户配送点，生成周转物发出计划。 | 配送任务、线路、客户点、box_out_bill |
| 司机 | 配送时携带周转物，到客户处交付、回收、拍照登记，回仓交接。 | box_driver_balance、box_return_bill |
| 客户 | 接收周转物、归还旧箱、承担押金或赔偿责任。 | box_customer_balance、押金/赔偿记录 |
| 财务/客服 | 处理押金释放、赔偿扣款、客户对账。 | 客户余额、应收、赔偿金额 |
| 系统任务 | 自动根据配送任务生成发出单、更新库存流水、生成预警。 | box_inventory_flow、box_customer_balance |
4. 核心业务口径
|--------|------------------------------|-------------------------------------------|
| 口径 | 定义 | 实现要点 |
| 周转模式 | 长期客户/固定线路客户只记录借出与归还，不立即收取押金。 | opt_type=1，客户余额记录未还数量。 |
| 押金模式 | 对新客户、临时客户或高价值周转物收取押金。 | opt_type=2，发出占用押金，归还释放押金，损坏/丢失扣押金。 |
| 公司库存 | 仓库可用周转物数量。 | box_inventory.stock_qty / available_qty。 |
| 客户占用 | 客户已收到但未归还的周转物数量。 | box_customer_balance.unreturn_qty。 |
| 司机暂存 | 司机装车带出、回收后尚未交回仓库的周转物。 | box_driver_balance.hold_qty。 |
| 库存流水 | 每一次审核、反审核、冲销都必须落库记录。 | box_inventory_flow，使用 idempotent_key 防重复。 |
5. 总体作业流程图
图 5-1 周转物模块总体作业流程图
5.1 订单配送发出流程
图 5-2 订单配送发出流程图
5.2 司机回收归还流程
图 5-3 司机回收归还流程图
6. 详细作业流程说明
6.1 周转物资料建档流程
|--------|--------------------------------------------|
| 步骤 | 说明 |
| 1 | 新增周转物类型，如周转箱、保温箱、托盘、冰袋、筐盖。 |
| 2 | 新增周转物资料，录入编码、名称、押金单价、资产价值、长宽高、重量、单位。 |
| 3 | 审核周转物资料。只有已审核且启用的周转物允许购入、发出、归还。 |
| 4 | 资料修改时如果已经被库存或历史单据引用，限制修改关键字段，例如编码、类型、押金单价。 |
6.2 期初/购入流程
|--------|------------------------------------------------|
| 步骤 | 说明 |
| 1 | 仓库管理员录入购入或期初单，选择仓库和周转物明细。 |
| 2 | 保存时不影响库存，单据状态为待审核。 |
| 3 | 审核时增加 box_inventory.stock_qty 与 available_qty。 |
| 4 | 写入 box_inventory_flow，biz_type=3购入或6盘盈。 |
| 5 | 反审核时必须按原流水冲销，不能直接删除历史记录。 |
6.3 配送装箱与发出流程
|--------|-----------------------------------------|
| 步骤 | 说明 |
| 1 | OMS订单审核后进入配送池。 |
| 2 | 系统按客户固定线路自动归线，未配置固定线路的订单进入未排线池。 |
| 3 | 配送排线按客户配送点聚合订单，计算该客户点下订单商品总体积、总重量、温控要求。 |
| 4 | 系统根据周转物体积、重量、类型推荐周转箱数量，仓库可人工调整。 |
| 5 | 生成 box_out_bill 与 box_out_bill_detail。 |
| 6 | 审核发出单后扣减库存、增加客户未还数量、增加司机暂存或配送任务携带数量。 |
| 7 | 押金模式下生成押金占用金额，后续归还或赔偿时释放/扣减。 |
6.4 客户签收与旧箱回收流程
|--------|---------------------------------|
| 步骤 | 说明 |
| 1 | 司机到达客户配送点，客户签收订单。 |
| 2 | 司机端显示本客户点：本次发出箱数、历史未还箱数、建议回收箱数。 |
| 3 | 司机录入归还周转物类型、数量，支持扫码、拍照、备注。 |
| 4 | 完好归还进入正常归还单；损坏或丢失进入异常归还/报损待处理。 |
| 5 | 客户确认后，后台或司机回仓交接时审核归还单。 |
| 6 | 审核后增加公司库存，减少客户未还，释放押金。 |
6.5 损坏、丢失、赔偿流程
|--------|------------------------------------|
| 步骤 | 说明 |
| 1 | 司机或仓库发现周转物损坏、丢失时登记异常。 |
| 2 | 客服/仓库确认责任方：客户原因、司机原因、公司自然损耗。 |
| 3 | 客户原因时，可按押金单价或资产价值生成赔偿金额。 |
| 4 | 押金模式下优先用押金抵扣；周转模式下生成客户赔偿/应收。 |
| 5 | 公司原因或自然损耗时，生成报损单，审核后减少公司资产库存或记录损耗。 |
6.6 盘点与调整流程
|--------|-----------------------------------------------|
| 步骤 | 说明 |
| 1 | 仓库定期对周转物进行盘点，系统带出账面库存。 |
| 2 | 录入实盘数量，自动计算盘盈/盘亏。 |
| 3 | 确认差异原因后生成调整单。 |
| 4 | 审核调整单后更新 box_inventory 并写 box_inventory_flow。 |
| 5 | 盘亏涉及客户/司机责任时，可转赔偿流程。 |
7. 单据状态机与审核规则
图 7-1 周转物单据通用状态机
|------------|----------------------|--------------|------------|
| 状态 | 含义 | 可执行动作 | 是否影响库存 |
| 0 待审核 | 单据已保存但未生效。 | 修改、删除、审核、作废 | 否 |
| 1 已审核 | 单据生效，已经更新库存/客户余额/流水。 | 查看、打印、反审核/冲销 | 是 |
| -1 已作废 | 单据无效，不再参与业务。 | 查看 | 否 |
| 2 已反审核/已冲销 | 原审核影响已通过反向流水冲销。 | 修改后重新审核或关闭 | 反向影响 |
审核与反审核必须遵循幂等原则：同一单据同一动作只能影响库存一次。建议每次写入 box_inventory_flow 时生成 idempotent_key，例如：BOX_OUT_AUDIT:{outCode}:{detailId}。
8. 数据模型 E-R 关系
图 8-1 box_ 周转物模块建议 E-R 关系图
E-R 设计重点：box_item 是基础资料，box_inventory 是公司仓库库存汇总；box_out_bill/detail 和 box_return_bill/detail 是作业单据；box_customer_balance 与 box_driver_balance 是高频查询余额表；box_inventory_flow 是所有库存变化的事实流水。
9. 当前 tms_box_* 表结构数据字典
|-----------------------|---------|------------------------------|
| 表名 | 表说明 | 用途说明 |
| tms_box_type | 周转物类型表 | 维护周转物分类，如周转箱、保温箱、托盘、冰袋等。 |
| tms_box | 周转物定义表 | 维护周转物编码、名称、价值、长宽高重量、审核状态。 |
| tms_box_inventory | 周转物库存表 | 维护周转物库存、借出总数、归还总数、购入数量、销毁数量。 |
| tms_box_operation | 周转物操作表 | 记录购入、报损等操作，当前为单表设计。 |
| tms_box_out_record | 周转物发出表 | 记录订单/客户维度的周转物借出、押金发出。 |
| tms_box_return_record | 周转物归还表 | 记录客户或司机归还周转物。 |
| tms_box_record_log | 周转物日志表 | 记录借出、归还、购入、销毁、报损等异动流水。 |
9.x tms_box_type
|-------------|--------------|--------------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键ID |
| type_name | varchar(100) | 类型名称 |
| enabled | int | 状态：1启用，0禁用 |
| del_flag | int | 删除标记：0正常，1删除 |
| sort_code | int | 排序码 |
| creator | bigint | 创建人ID |
| create_date | bigint | 创建时间 |
| updater | bigint | 修改人ID |
| update_date | bigint | 修改时间 |
| remark | varchar(250) | 备注 |
| use_count | int | 引用次数 |
| dept_id | bigint | 机构ID |
9.x tms_box
|-------------|---------------|----------------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键ID |
| box_type_id | bigint | 周转物类型ID |
| box_code | varchar(100) | 周转物编码 |
| box_name | varchar(100) | 周转物名称 |
| box_amount | decimal(10,3) | 周转物价值 |
| box_long | varchar(100) | 长，建议改 decimal |
| box_wide | varchar(100) | 宽，建议改 decimal |
| box_high | varchar(100) | 高，建议改 decimal |
| box_weight | varchar(100) | 重量，建议改 decimal |
| audit_state | int | 审核状态：0待审核，1已审核 |
| audit_id | bigint | 审核人 |
| audit_date | bigint | 审核时间 |
| use_count | int | 引用次数 |
| enabled | int | 状态 |
| del_flag | int | 删除标记 |
| sort_code | int | 排序码 |
| creator | bigint | 创建人 |
| create_date | bigint | 创建时间 |
| updater | bigint | 修改人 |
| update_date | bigint | 修改时间 |
| remark | varchar(250) | 备注 |
| dept_id | bigint | 机构ID |
9.x tms_box_inventory
|---------------|--------------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键ID |
| box_id | bigint | 周转物ID |
| inventory | int | 当前库存数 |
| return_total | int | 累计归还数量 |
| out_total | int | 累计借出数量 |
| buy_count | int | 购入数量 |
| destroy_count | int | 销毁数量 |
| version | int | 版本号 |
| enabled | int | 状态 |
| del_flag | int | 删除标记 |
| sort_code | int | 排序码 |
| creator | bigint | 创建人 |
| create_date | bigint | 创建时间 |
| updater | bigint | 修改人 |
| update_date | bigint | 修改时间 |
| remark | varchar(250) | 备注 |
| dept_id | bigint | 机构ID |
9.x tms_box_operation
|---------------|---------------|----------------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键ID |
| box_id | bigint | 周转物ID |
| move_count | int | 变动数量 |
| box_amount | decimal(12,3) | 周转物价值 |
| turnover_type | int | 类型：1购入，2报损 |
| audit_state | int | 审核状态：0待审核，1已审核 |
| audit_id | bigint | 审核人 |
| audit_date | bigint | 审核时间 |
| enabled | int | 状态 |
| del_flag | int | 删除标记 |
| sort_code | int | 排序码 |
| creator | bigint | 创建人 |
| create_date | bigint | 创建时间 |
| updater | bigint | 修改人 |
| update_date | bigint | 修改时间 |
| remark | varchar(250) | 备注 |
9.x tms_box_out_record
|-----------------|---------------|------------------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键ID |
| box_id | bigint | 周转物ID |
| order_code | varchar(100) | 订单编码 |
| shop_id | bigint | 客户ID |
| shop_account_id | bigint | 客户子账号ID，现注释为不用 |
| opt_type | int | 操作类型：1周转司机，2押金客户 |
| box_order_type | int | 单据类型：1手动，2自动 |
| order_type | int | 订单类型 |
| out_count | int | 发出数量 |
| out_time | bigint | 发出时间 |
| out_amount | decimal(12,3) | 借出金额/押金金额 |
| out_status | int | 借出状态：0未发出，1已发出 |
| audit_state | int | 审核状态：0待审核，1已审核 |
| audit_id | bigint | 审核人 |
| audit_date | bigint | 审核时间 |
| enabled | int | 状态 |
| del_flag | int | 删除标记 |
| sort_code | int | 排序码 |
| creator | bigint | 创建人 |
| create_date | bigint | 创建时间 |
| updater | bigint | 修改人 |
| update_date | bigint | 修改时间 |
| remark | varchar(250) | 备注 |
9.x tms_box_return_record
|-----------------|---------------|------------------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键ID |
| box_id | bigint | 周转物ID |
| order_code | varchar(100) | 订单编码 |
| shop_id | bigint | 客户ID |
| shop_account_id | bigint | 客户账号ID |
| opt_type | int | 操作类型：1周转司机，2押金客户 |
| box_order_type | int | 单据类型：1手动，2自动 |
| order_type | int | 订单类型 |
| return_count | int | 归还数量 |
| return_time | bigint | 归还时间 |
| return_amount | decimal(12,3) | 归还金额/押金释放金额 |
| return_status | int | 归还状态：0未归还，1已归还 |
| audit_state | int | 审核状态：0待审核，1已审核 |
| audit_id | bigint | 审核人 |
| audit_date | bigint | 审核时间 |
| enabled | int | 状态 |
| del_flag | int | 删除标记 |
| sort_code | int | 排序码 |
| creator | bigint | 创建人 |
| create_date | bigint | 创建时间 |
| updater | bigint | 修改人 |
| update_date | bigint | 修改时间 |
| remark | varchar(250) | 备注 |
9.x tms_box_record_log
|---------------|---------------|------------------------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键ID |
| box_id | bigint | 周转物ID |
| order_code | varchar(100) | 订单编码，现注释建议去掉 |
| order_type | int | 单号类型，现注释建议去掉 |
| move_count | int | 异动数量 |
| move_time | bigint | 异动时间 |
| box_amount | decimal(12,3) | 周转物价值 |
| turnover_type | int | 类型：1借出，2归还，3购入，4销毁，5报损 |
| enabled | int | 状态 |
| del_flag | int | 删除标记 |
| sort_code | int | 排序码 |
| creator | bigint | 创建人 |
| create_date | bigint | 创建时间 |
| updater | bigint | 修改人 |
| update_date | bigint | 修改时间 |
| remark | varchar(250) | 备注 |
10. 建议正式落地的 box_ 表结构设计
建议把周转物能力从 tms_box_* 下沉为独立 box_ 模块。以下表结构可分阶段落地：第一阶段补余额表和流水表；第二阶段重构发出/归还为主从表；第三阶段补盘点、押金、赔偿与财务联动。
|---------------------------|----------|---------------------------------|
| 建议表 | 表说明 | 核心用途 |
| box_type | 周转物类型表 | 类型编码、类型名称、启停状态。 |
| box_item | 周转物资料表 | 编码、名称、押金单价、资产价值、长宽高、体积、重量、审核状态。 |
| box_inventory | 周转物库存汇总表 | 按机构、仓库、周转物汇总库存、可用、锁定、客户占用、司机暂存。 |
| box_operation_bill | 周转物操作主表 | 购入、报损、销毁、盘盈、盘亏、调整等操作单据主表。 |
| box_operation_bill_detail | 周转物操作明细表 | 一张操作单可包含多种周转物。 |
| box_out_bill | 周转物发出主表 | 关联配送任务、线路、司机、车辆、客户、仓库。 |
| box_out_bill_detail | 周转物发出明细表 | 记录各周转物发出数量、押金金额、已还/未还数量。 |
| box_return_bill | 周转物归还主表 | 司机回收、客户主动归还、手工归还。 |
| box_return_bill_detail | 周转物归还明细表 | 正常、损坏、丢失、赔偿、原发出明细关联。 |
| box_customer_balance | 客户周转物余额表 | 客户维度未还数量、押金占用、赔偿累计。 |
| box_driver_balance | 司机周转物暂存表 | 司机配送任务维度的装车、回收、回仓交接。 |
| box_inventory_flow | 周转物库存流水表 | 所有审核动作写流水，支持审计、幂等和追溯。 |
10.x box_type（周转物类型表）
|-----------------------------------------|--------------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| type_code | varchar(64) | 类型编码 |
| type_name | varchar(100) | 类型名称 |
| sort_code | int | 排序 |
| enabled | tinyint | 启用状态 |
| del_flag | tinyint | 删除标记 |
| dept_id | bigint | 机构ID |
| creator/create_date/updater/update_date | bigint | 审计字段 |
| remark | varchar(255) | 备注 |
10.x box_item（周转物资料表）
|--------------------------|----------------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| box_type_id | bigint | 周转物类型ID |
| box_code | varchar(64) | 周转物编码 |
| box_name | varchar(100) | 周转物名称 |
| deposit_price | decimal(12,3) | 押金单价 |
| asset_price | decimal(12,3) | 资产价值 |
| length/width/height | decimal(12,3) | 长宽高 |
| volume | decimal(18,6) | 体积 |
| weight | decimal(12,3) | 重量 |
| unit_name | varchar(20) | 单位 |
| audit_state | tinyint | 审核状态 |
| audit_id/audit_date | bigint | 审核信息 |
| enabled/del_flag/dept_id | tinyint/bigint | 公共字段 |
10.x box_inventory（周转物库存汇总表）
|---------------------|----------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| dept_id | bigint | 机构ID |
| workhouse_id | bigint | 仓库ID |
| box_id | bigint | 周转物ID |
| stock_qty | int | 当前库存 |
| available_qty | int | 可用数量 |
| locked_qty | int | 锁定数量 |
| out_total_qty | int | 累计发出 |
| return_total_qty | int | 累计归还 |
| buy_total_qty | int | 累计购入 |
| damage_total_qty | int | 累计报损 |
| destroy_total_qty | int | 累计销毁 |
| customer_occupy_qty | int | 客户占用 |
| driver_hold_qty | int | 司机暂存 |
| version | int | 乐观锁 |
10.x box_out_bill（周转物发出主表）
|---------------------|---------------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| out_code | varchar(64) | 发出单号 |
| out_date | bigint | 发出日期 |
| source_type | tinyint | 来源类型 |
| source_code | varchar(64) | 来源单号 |
| delivery_task_id | bigint | 配送任务ID |
| route_id | bigint | 线路ID |
| driver_id | bigint | 司机ID |
| vehicle_id | bigint | 车辆ID |
| shop_id | bigint | 客户ID |
| workhouse_id | bigint | 发出仓库 |
| opt_type | tinyint | 周转/押金 |
| total_qty | int | 总数量 |
| total_amount | decimal(12,3) | 总金额 |
| bill_state | tinyint | 单据状态 |
| audit_id/audit_date | bigint | 审核信息 |
10.x box_out_bill_detail（周转物发出明细表）
|----------------------|---------------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| out_code | varchar(64) | 发出单号 |
| box_id | bigint | 周转物ID |
| out_qty | int | 发出数量 |
| deposit_price | decimal(12,3) | 押金单价 |
| out_amount | decimal(12,3) | 发出金额 |
| source_order_id | bigint | 来源订单ID |
| source_order_code | varchar(64) | 来源订单号 |
| source_order_info_id | bigint | 来源订单明细ID |
| customer_point_id | bigint | 客户配送点ID |
| return_qty | int | 已归还 |
| unreturn_qty | int | 未归还 |
| damage_qty/lost_qty | int | 损坏/丢失 |
10.x box_return_bill（周转物归还主表）
|------------------|---------------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| return_code | varchar(64) | 归还单号 |
| return_date | bigint | 归还日期 |
| source_type | tinyint | 来源类型 |
| source_code | varchar(64) | 来源单号 |
| delivery_task_id | bigint | 配送任务ID |
| route_id | bigint | 线路ID |
| driver_id | bigint | 司机ID |
| vehicle_id | bigint | 车辆ID |
| shop_id | bigint | 客户ID |
| workhouse_id | bigint | 归还仓库 |
| opt_type | tinyint | 周转/押金 |
| total_qty | int | 总数量 |
| total_amount | decimal(12,3) | 释放/退还金额 |
| bill_state | tinyint | 单据状态 |
10.x box_return_bill_detail（周转物归还明细表）
|---------------|---------------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| return_code | varchar(64) | 归还单号 |
| out_code | varchar(64) | 原发出单号 |
| out_detail_id | bigint | 原发出明细ID |
| box_id | bigint | 周转物ID |
| return_qty | int | 归还数量 |
| normal_qty | int | 完好数量 |
| damage_qty | int | 损坏数量 |
| lost_qty | int | 丢失数量 |
| deposit_price | decimal(12,3) | 押金单价 |
| return_amount | decimal(12,3) | 释放押金金额 |
| damage_amount | decimal(12,3) | 赔偿金额 |
| image_url | varchar(500) | 图片附件 |
10.x box_customer_balance（客户周转物余额表）
|--------------------------------|---------------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| dept_id | bigint | 机构ID |
| shop_id | bigint | 客户ID |
| box_id | bigint | 周转物ID |
| out_qty | int | 累计借出 |
| return_qty | int | 累计归还 |
| unreturn_qty | int | 当前未还 |
| damage_qty | int | 损坏 |
| lost_qty | int | 丢失 |
| deposit_amount | decimal(12,3) | 押金占用 |
| compensate_amount | decimal(12,3) | 赔偿累计 |
| last_out_date/last_return_date | bigint | 最近借出/归还 |
| version | int | 乐观锁 |
10.x box_driver_balance（司机周转物暂存表）
|------------------------|----------|----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| dept_id | bigint | 机构ID |
| driver_id | bigint | 司机ID |
| vehicle_id | bigint | 车辆ID |
| delivery_task_id | bigint | 配送任务ID |
| box_id | bigint | 周转物ID |
| load_qty | int | 装车数量 |
| delivered_qty | int | 已交付客户 |
| recovered_qty | int | 回收数量 |
| returned_warehouse_qty | int | 回仓交回 |
| hold_qty | int | 司机暂存 |
10.x box_inventory_flow（周转物库存流水表）
|-----------------------------|---------------|-----------|
| 字段名 | 字段类型 | 字段说明 |
| id | bigint | 主键 |
| flow_code | varchar(64) | 流水号 |
| dept_id/workhouse_id/box_id | bigint | 机构/仓库/周转物 |
| biz_type | tinyint | 业务类型 |
| source_code | varchar(64) | 来源单号 |
| source_detail_id | bigint | 来源明细ID |
| shop_id | bigint | 客户ID |
| driver_id | bigint | 司机ID |
| before_qty | int | 变动前数量 |
| change_qty | int | 变动数量 |
| after_qty | int | 变动后数量 |
| unit_amount | decimal(12,3) | 单价/押金 |
| change_amount | decimal(12,3) | 变动金额 |
| biz_date | bigint | 业务时间 |
| idempotent_key | varchar(128) | 幂等键 |
11. 库存与押金核心规则
|--------|--------------------------------------------------------------------------------------------|---------------------------|
| 规则 | 公式/处理 | 说明 |
| 当前可用库存 | available_qty = stock_qty - locked_qty | 发出审核前必须校验可用库存。 |
| 发出审核 | stock_qty -= out_qty；out_total_qty += out_qty；customer.unreturn_qty += out_qty | 押金模式下同时增加 deposit_amount。 |
| 归还审核 | stock_qty += normal_qty；return_total_qty += return_qty；customer.unreturn_qty -= return_qty | 损坏/丢失数量不直接进入正常库存。 |
| 押金占用 | deposit_amount += out_qty × deposit_price | 仅 opt_type=2 时执行。 |
| 押金释放 | deposit_amount -= normal_return_qty × deposit_price | 归还完好数量释放。 |
| 损坏赔偿 | damage_amount = damage_qty × compensation_price | 赔偿价格可取押金单价或资产价值。 |
| 流水幂等 | 同一来源单据+明细+动作只能写一条 flow | 唯一索引 idempotent_key 保证。 |
注意：周转物库存不参与商品成本核算，不走 product_sku_id + unit_id 商品库存主口径；它是物流资产数量管理。
12. 后端接口设计
接口命名遵循升鲜宝后端对象命名规范：请求对象使用 Req 前缀，返回对象使用 Resp 前缀；Service 接口不返回 Result，Controller 层再统一包装 Result。
|--------|---------------------------------|----------------------------|----------------------------|-----------------|
| 方法 | 接口地址 | 请求对象 | 返回对象 | 说明 |
| POST | /admin/box/type/page | ReqBoxTypePage | RespBoxTypePage | 周转物类型分页查询 |
| POST | /admin/box/type/save | ReqBoxTypeSave | RespId | 新增/修改周转物类型 |
| POST | /admin/box/item/page | ReqBoxItemPage | RespBoxItemPage | 周转物资料分页查询 |
| POST | /admin/box/item/save | ReqBoxItemSave | RespId | 保存周转物资料 |
| POST | /admin/box/item/audit | ReqBoxItemAudit | RespBoolean | 审核/反审核周转物资料 |
| POST | /admin/box/inventory/page | ReqBoxInventoryPage | RespBoxInventoryPage | 周转物库存查询 |
| POST | /admin/box/out/createByDelivery | ReqBoxOutCreateByDelivery | RespBoxOutBill | 按配送任务生成发出单 |
| POST | /admin/box/out/save | ReqBoxOutSave | RespId | 手工保存发出单 |
| POST | /admin/box/out/audit | ReqBoxOutAudit | RespBoolean | 审核发出单，扣库存、增客户占用 |
| POST | /admin/box/return/save | ReqBoxReturnSave | RespId | 保存归还单 |
| POST | /admin/box/return/audit | ReqBoxReturnAudit | RespBoolean | 审核归还单，增库存、减客户占用 |
| POST | /admin/box/customerBalance/page | ReqBoxCustomerBalancePage | RespBoxCustomerBalancePage | 客户周转物余额查询 |
| POST | /admin/box/flow/page | ReqBoxFlowPage | RespBoxFlowPage | 周转物流水查询 |
| POST | /b2bmall/box/customer/balance | ReqBoxCustomerBalanceQuery | RespBoxCustomerBalance | 客户订货端查看未还/押金 |
| POST | /driver/box/recycle/save | ReqDriverBoxRecycleSave | RespId | 司机端配送签收时登记回收 |
12.1 关键请求对象字段建议
|---------------------------|-------------------------------------------------------------------------------------------------------------------------|
| 请求对象 | 核心字段 |
| ReqBoxOutCreateByDelivery | deliveryTaskId, routeId, driverId, vehicleId, workhouseId, shopIdList, autoRecommendFlag |
| ReqBoxOutSave | outCode, sourceType, sourceCode, deliveryTaskId, routeId, driverId, vehicleId, shopId, workhouseId, optType, detailList |
| ReqBoxOutAudit | outCode, auditFlag, auditRemark, idempotentToken |
| ReqBoxReturnSave | returnCode, sourceType, deliveryTaskId, driverId, vehicleId, shopId, workhouseId, optType, detailList |
| ReqDriverBoxRecycleSave | deliveryTaskId, customerPointId, shopId, driverId, boxList, imageList, signRemark |
| ReqBoxCustomerBalancePage | shopId, boxId, unreturnOnlyFlag, optType, beginDate, endDate, page, limit |
13. Service 与领域服务设计
|----------------------|---------------|----------------------------------------------------------------------------|
| 服务类 | 职责 | 关键方法 |
| BoxItemService | 周转物资料管理。 | saveBoxItem, auditBoxItem, disableBoxItem, pageBoxItem |
| BoxInventoryService | 库存汇总查询与安全更新。 | getOrCreateInventory, increaseStock, decreaseStock, lockStock, unlockStock |
| BoxOutBillService | 发出单主流程。 | createByDeliveryTask, saveOutBill, auditOutBill, reverseAuditOutBill |
| BoxReturnBillService | 归还单主流程。 | saveReturnBill, auditReturnBill, reverseAuditReturnBill |
| BoxBalanceService | 客户余额与司机暂存。 | increaseCustomerOccupy, decreaseCustomerOccupy, updateDriverHold |
| BoxFlowService | 统一流水落库与幂等校验。 | writeFlowOnce, buildIdempotentKey, listFlow |
| BoxRecommendService | 按订单体积重量推荐周转物。 | recommendByOrder, recommendByCustomerPoint, recommendByDeliveryTask |
审核流程建议通过一个领域编排服务完成，例如 BoxPostingService，避免库存、客户余额、司机暂存、押金、流水散落在多个 Controller 或 ServiceImpl 中。
public interface BoxPostingService {
void auditOutBill(String outCode, Long auditUserId);
void reverseAuditOutBill(String outCode, Long auditUserId);
void auditReturnBill(String returnCode, Long auditUserId);
void reverseAuditReturnBill(String returnCode, Long auditUserId);
void postOperationBill(String operationCode, Long auditUserId);
}
14. 幂等、并发与数据一致性
• 发出审核、归还审核、购入审核、报损审核都必须使用事务。
• 库存更新使用 where version = oldVersion 或 MyBatis-Plus 乐观锁，避免并发扣成负数。
• 审核前校验 bill_state，只有待审核单据允许审核。
• 审核动作写入 box_inventory_flow，幂等键唯一，重复请求直接返回成功或提示已处理。
• 所有余额表都是汇总表，最终以 box_inventory_flow 作为审计依据。
• 反审核不删除原流水，而是写反向流水，保证审计链完整。
• 发出审核时，如果 available_qty 小于 out_qty，应阻止审核或进入人工确认流程。
15. 与配送、订单、财务模块联动
|---------|--------------------------------|-----------------------------------------------------------------|
| 模块 | 联动点 | 实现建议 |
| OMS订单 | 订单进入配送池后，按客户配送点聚合商品体积、重量、温控要求。 | 订单明细提供 sku_unit_id、数量、体积、重量，供 BoxRecommendService 推荐周转物。 |
| 物流配送 | 配送任务生成周转物发出单，司机端签收时登记归还。 | box_out_bill 关联 delivery_task_id、route_id、driver_id、vehicle_id。 |
| 客户资料 | 客户可配置默认周转模式/押金模式、是否必须回收、押金规则。 | 可在客户扩展配置或新增 box_customer_policy 表。 |
| 财务/客户余额 | 押金占用、释放、赔偿扣款。 | 押金流水可单独落财务表，box 表保存业务依据。 |
| 打印/小票 | 配送单打印显示本次发出箱数、历史未还箱数、应回收箱数。 | 配送打印模板增加 boxList。 |
| 消息提醒 | 客户长期未归还、司机未交回、库存不足触发提醒。 | 接入统一消息组件。 |
16. 后台页面与司机端功能
|-------|-----------|-----------------------------------|
| 端 | 页面/功能 | 主要字段/操作 |
| 后台 | 周转物类型 | 类型编码、类型名称、排序、启用/禁用。 |
| 后台 | 周转物资料 | 编码、名称、类型、押金单价、资产价值、长宽高、体积、重量、审核。 |
| 后台 | 周转物库存 | 仓库、周转物、当前库存、可用、客户占用、司机暂存、累计发出/归还。 |
| 后台 | 周转物发出 | 来源单号、配送任务、客户、司机、车辆、周转物明细、审核、打印。 |
| 后台 | 周转物归还 | 客户、司机、归还明细、完好/损坏/丢失、照片、审核。 |
| 后台 | 客户周转物账本 | 客户、周转物、累计发出、累计归还、当前未还、押金占用、赔偿。 |
| 后台 | 周转物流水 | 业务类型、来源单号、变动前、变动数、变动后、操作人。 |
| 司机端 | 配送签收回收 | 展示应送/应回，录入回收数量，拍照，客户确认。 |
| 客户端 | 我的周转物 | 查看未归还数量、押金占用、历史发出/归还。 |
17. 分阶段落地计划
|--------|------------------------|---------------------------------------------------------|---------------------|
| 阶段 | 目标 | 开发内容 | 风险控制 |
| 第一阶段 | 在现有 tms_box_* 基础上补齐闭环 | 补客户余额、司机暂存、流水；发出归还继续兼容老表。 | 不大改原业务，先解决对账和追溯。 |
| 第二阶段 | 发出/归还单据主从化 | 新增 box_out_bill/detail、box_return_bill/detail，兼容迁移历史数据。 | 通过适配层读取新旧表，逐步切换。 |
| 第三阶段 | 配送深度集成 | 配送任务生成发出单，司机端签收回收，配送单打印箱数。 | 先在部分线路试点，校验客户未还准确性。 |
| 第四阶段 | 押金与财务闭环 | 押金占用、释放、扣罚、客户对账。 | 明确财务入账口径，避免重复应收。 |
| 第五阶段 | 盘点和预警 | 周转物盘点、盘盈盘亏、超期未还提醒、库存不足预警。 | 以流水为准，余额表可重算。 |
18. 测试用例清单
|----------|----------------------|-------------------|----------------------|
| 测试场景 | 前置条件 | 操作 | 期望结果 |
| 购入审核 | 周转物资料已审核 | 新增购入单并审核 | 库存增加，流水 biz_type=3。 |
| 发出审核 | 库存充足，客户存在 | 按配送任务生成发出单并审核 | 库存减少，客户未还增加，押金占用增加。 |
| 库存不足发出 | available_qty 小于发出数量 | 审核发出单 | 系统阻止审核并提示库存不足。 |
| 正常归还 | 客户存在未还数量 | 录入归还并审核 | 库存增加，客户未还减少，押金释放。 |
| 损坏归还 | 客户归还损坏箱 | 录入 damage_qty 并审核 | 正常库存不增加损坏数量，生成赔偿/报损。 |
| 重复审核 | 同一单据重复点击审核 | 连续提交审核请求 | 只影响库存一次，幂等键拦截重复流水。 |
| 反审核 | 已审核发出单 | 执行反审核 | 写反向流水，恢复库存和客户余额。 |
| 司机回仓交接 | 司机回收多个客户周转物 | 回仓确认 | 司机暂存减少，仓库库存增加。 |
附录 A：建议 box_ 核心表 MySQL 8.0 DDL
以下 DDL 为建议核心表，实际落地时可结合现有统一字段、租户字段、审计字段、数据权限字段进行微调。
CREATE TABLE `box_type` (
`id` bigint NOT NULL COMMENT '主键ID',
`type_code` varchar(64) NOT NULL COMMENT '类型编码',
`type_name` varchar(100) NOT NULL COMMENT '类型名称',
`sort_code` int NOT NULL DEFAULT 1 COMMENT '排序码',
`enabled` tinyint NOT NULL DEFAULT 1 COMMENT '1启用 0禁用',
`del_flag` tinyint NOT NULL DEFAULT 0 COMMENT '0正常 1删除',
`dept_id` bigint DEFAULT 0 COMMENT '机构ID',
`creator` bigint DEFAULT 0 COMMENT '创建人ID',
`create_date` bigint DEFAULT NULL COMMENT '创建时间',
`updater` bigint DEFAULT 0 COMMENT '修改人ID',
`update_date` bigint DEFAULT NULL COMMENT '修改时间',
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_dept_type_code` (`dept_id`,`type_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='周转物类型表';
CREATE TABLE `box_item` (
`id` bigint NOT NULL COMMENT '主键ID',
`box_type_id` bigint NOT NULL COMMENT '周转物类型ID',
`box_code` varchar(64) NOT NULL COMMENT '周转物编码',
`box_name` varchar(100) NOT NULL COMMENT '周转物名称',
`deposit_price` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '押金单价',
`asset_price` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '资产价值',
`length` decimal(12,3) DEFAULT 0.000 COMMENT '长',
`width` decimal(12,3) DEFAULT 0.000 COMMENT '宽',
`height` decimal(12,3) DEFAULT 0.000 COMMENT '高',
`volume` decimal(18,6) DEFAULT 0.000000 COMMENT '体积',
`weight` decimal(12,3) DEFAULT 0.000 COMMENT '重量',
`unit_name` varchar(20) DEFAULT '个' COMMENT '单位名称',
`audit_state` tinyint NOT NULL DEFAULT 0 COMMENT '0待审核 1已审核 -1作废',
`audit_id` bigint DEFAULT 0 COMMENT '审核人ID',
`audit_date` bigint DEFAULT NULL COMMENT '审核时间',
`enabled` tinyint NOT NULL DEFAULT 1 COMMENT '1启用 0禁用',
`del_flag` tinyint NOT NULL DEFAULT 0 COMMENT '0正常 1删除',
`dept_id` bigint DEFAULT 0 COMMENT '机构ID',
`creator` bigint DEFAULT 0 COMMENT '创建人ID',
`create_date` bigint DEFAULT NULL COMMENT '创建时间',
`updater` bigint DEFAULT 0 COMMENT '修改人ID',
`update_date` bigint DEFAULT NULL COMMENT '修改时间',
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_dept_box_code` (`dept_id`,`box_code`),
KEY `idx_box_type_id` (`box_type_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='周转物资料表';
CREATE TABLE `box_inventory` (
`id` bigint NOT NULL COMMENT '主键ID',
`dept_id` bigint NOT NULL DEFAULT 0 COMMENT '机构ID',
`workhouse_id` bigint NOT NULL DEFAULT 0 COMMENT '仓库ID',
`box_id` bigint NOT NULL COMMENT '周转物ID',
`stock_qty` int NOT NULL DEFAULT 0 COMMENT '当前库存',
`available_qty` int NOT NULL DEFAULT 0 COMMENT '可用数量',
`locked_qty` int NOT NULL DEFAULT 0 COMMENT '锁定数量',
`out_total_qty` int NOT NULL DEFAULT 0 COMMENT '累计发出数量',
`return_total_qty` int NOT NULL DEFAULT 0 COMMENT '累计归还数量',
`buy_total_qty` int NOT NULL DEFAULT 0 COMMENT '累计购入数量',
`damage_total_qty` int NOT NULL DEFAULT 0 COMMENT '累计报损数量',
`destroy_total_qty` int NOT NULL DEFAULT 0 COMMENT '累计销毁数量',
`customer_occupy_qty` int NOT NULL DEFAULT 0 COMMENT '客户占用数量',
`driver_hold_qty` int NOT NULL DEFAULT 0 COMMENT '司机暂存数量',
`version` int NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
`enabled` tinyint NOT NULL DEFAULT 1 COMMENT '1启用 0禁用',
`del_flag` tinyint NOT NULL DEFAULT 0 COMMENT '0正常 1删除',
`creator` bigint DEFAULT 0 COMMENT '创建人ID',
`create_date` bigint DEFAULT NULL COMMENT '创建时间',
`updater` bigint DEFAULT 0 COMMENT '修改人ID',
`update_date` bigint DEFAULT NULL COMMENT '修改时间',
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_dept_wh_box` (`dept_id`,`workhouse_id`,`box_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='周转物库存汇总表';
CREATE TABLE `box_out_bill` (
`id` bigint NOT NULL COMMENT '主键ID',
`out_code` varchar(64) NOT NULL COMMENT '发出单号',
`out_date` bigint DEFAULT NULL COMMENT '发出日期',
`source_type` tinyint NOT NULL DEFAULT 3 COMMENT '来源类型 1订单 2配送任务 3手工',
`source_code` varchar(64) DEFAULT NULL COMMENT '来源单号',
`delivery_task_id` bigint DEFAULT NULL COMMENT '配送任务ID',
`route_id` bigint DEFAULT NULL COMMENT '线路ID',
`driver_id` bigint DEFAULT NULL COMMENT '司机ID',
`vehicle_id` bigint DEFAULT NULL COMMENT '车辆ID',
`shop_id` bigint DEFAULT NULL COMMENT '客户ID',
`workhouse_id` bigint NOT NULL DEFAULT 0 COMMENT '发出仓库ID',
`opt_type` tinyint NOT NULL DEFAULT 1 COMMENT '1周转 2押金',
`total_qty` int NOT NULL DEFAULT 0 COMMENT '发出总数量',
`total_amount` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '押金/借出金额',
`bill_state` tinyint NOT NULL DEFAULT 0 COMMENT '0待审核 1已审核 -1作废',
`audit_id` bigint DEFAULT 0 COMMENT '审核人ID',
`audit_date` bigint DEFAULT NULL COMMENT '审核时间',
`enabled` tinyint NOT NULL DEFAULT 1 COMMENT '1启用 0禁用',
`del_flag` tinyint NOT NULL DEFAULT 0 COMMENT '0正常 1删除',
`dept_id` bigint DEFAULT 0 COMMENT '机构ID',
`creator` bigint DEFAULT 0 COMMENT '创建人ID',
`create_date` bigint DEFAULT NULL COMMENT '创建时间',
`updater` bigint DEFAULT 0 COMMENT '修改人ID',
`update_date` bigint DEFAULT NULL COMMENT '修改时间',
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_out_code` (`out_code`),
KEY `idx_shop_date` (`shop_id`,`out_date`),
KEY `idx_delivery_task` (`delivery_task_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='周转物发出主表';
CREATE TABLE `box_out_bill_detail` (
`id` bigint NOT NULL COMMENT '主键ID',
`out_code` varchar(64) NOT NULL COMMENT '发出单号',
`box_id` bigint NOT NULL COMMENT '周转物ID',
`out_qty` int NOT NULL DEFAULT 0 COMMENT '发出数量',
`deposit_price` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '押金单价',
`out_amount` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '发出金额',
`source_order_id` bigint DEFAULT NULL COMMENT '来源订单ID',
`source_order_code` varchar(64) DEFAULT NULL COMMENT '来源订单号',
`source_order_info_id` bigint DEFAULT NULL COMMENT '来源订单明细ID',
`customer_point_id` bigint DEFAULT NULL COMMENT '客户配送点ID',
`return_qty` int NOT NULL DEFAULT 0 COMMENT '已归还数量',
`unreturn_qty` int NOT NULL DEFAULT 0 COMMENT '未归还数量',
`damage_qty` int NOT NULL DEFAULT 0 COMMENT '损坏数量',
`lost_qty` int NOT NULL DEFAULT 0 COMMENT '丢失数量',
`enabled` tinyint NOT NULL DEFAULT 1 COMMENT '1启用 0禁用',
`del_flag` tinyint NOT NULL DEFAULT 0 COMMENT '0正常 1删除',
`creator` bigint DEFAULT 0 COMMENT '创建人ID',
`create_date` bigint DEFAULT NULL COMMENT '创建时间',
`updater` bigint DEFAULT 0 COMMENT '修改人ID',
`update_date` bigint DEFAULT NULL COMMENT '修改时间',
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (`id`),
KEY `idx_out_code` (`out_code`),
KEY `idx_box_id` (`box_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='周转物发出明细表';
CREATE TABLE `box_return_bill` (
`id` bigint NOT NULL COMMENT '主键ID',
`return_code` varchar(64) NOT NULL COMMENT '归还单号',
`return_date` bigint DEFAULT NULL COMMENT '归还日期',
`source_type` tinyint NOT NULL DEFAULT 1 COMMENT '来源类型 1司机回收 2客户主动归还 3手工',
`source_code` varchar(64) DEFAULT NULL COMMENT '来源单号',
`delivery_task_id` bigint DEFAULT NULL COMMENT '配送任务ID',
`route_id` bigint DEFAULT NULL COMMENT '线路ID',
`driver_id` bigint DEFAULT NULL COMMENT '司机ID',
`vehicle_id` bigint DEFAULT NULL COMMENT '车辆ID',
`shop_id` bigint DEFAULT NULL COMMENT '客户ID',
`workhouse_id` bigint NOT NULL DEFAULT 0 COMMENT '归还仓库ID',
`opt_type` tinyint NOT NULL DEFAULT 1 COMMENT '1周转 2押金',
`total_qty` int NOT NULL DEFAULT 0 COMMENT '归还总数量',
`total_amount` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '释放/退还押金金额',
`bill_state` tinyint NOT NULL DEFAULT 0 COMMENT '0待审核 1已审核 -1作废',
`audit_id` bigint DEFAULT 0 COMMENT '审核人ID',
`audit_date` bigint DEFAULT NULL COMMENT '审核时间',
`enabled` tinyint NOT NULL DEFAULT 1 COMMENT '1启用 0禁用',
`del_flag` tinyint NOT NULL DEFAULT 0 COMMENT '0正常 1删除',
`dept_id` bigint DEFAULT 0 COMMENT '机构ID',
`creator` bigint DEFAULT 0 COMMENT '创建人ID',
`create_date` bigint DEFAULT NULL COMMENT '创建时间',
`updater` bigint DEFAULT 0 COMMENT '修改人ID',
`update_date` bigint DEFAULT NULL COMMENT '修改时间',
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_return_code` (`return_code`),
KEY `idx_shop_date` (`shop_id`,`return_date`),
KEY `idx_delivery_task` (`delivery_task_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='周转物归还主表';
CREATE TABLE `box_return_bill_detail` (
`id` bigint NOT NULL COMMENT '主键ID',
`return_code` varchar(64) NOT NULL COMMENT '归还单号',
`out_code` varchar(64) DEFAULT NULL COMMENT '原发出单号',
`out_detail_id` bigint DEFAULT NULL COMMENT '原发出明细ID',
`box_id` bigint NOT NULL COMMENT '周转物ID',
`return_qty` int NOT NULL DEFAULT 0 COMMENT '归还数量',
`normal_qty` int NOT NULL DEFAULT 0 COMMENT '完好数量',
`damage_qty` int NOT NULL DEFAULT 0 COMMENT '损坏数量',
`lost_qty` int NOT NULL DEFAULT 0 COMMENT '丢失数量',
`deposit_price` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '押金单价',
`return_amount` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '释放押金金额',
`damage_amount` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '损坏赔偿金额',
`image_url` varchar(500) DEFAULT NULL COMMENT '图片附件',
`enabled` tinyint NOT NULL DEFAULT 1 COMMENT '1启用 0禁用',
`del_flag` tinyint NOT NULL DEFAULT 0 COMMENT '0正常 1删除',
`creator` bigint DEFAULT 0 COMMENT '创建人ID',
`create_date` bigint DEFAULT NULL COMMENT '创建时间',
`updater` bigint DEFAULT 0 COMMENT '修改人ID',
`update_date` bigint DEFAULT NULL COMMENT '修改时间',
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (`id`),
KEY `idx_return_code` (`return_code`),
KEY `idx_out_detail` (`out_detail_id`),
KEY `idx_box_id` (`box_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='周转物归还明细表';
CREATE TABLE `box_customer_balance` (
`id` bigint NOT NULL COMMENT '主键ID',
`dept_id` bigint NOT NULL DEFAULT 0 COMMENT '机构ID',
`shop_id` bigint NOT NULL COMMENT '客户ID',
`box_id` bigint NOT NULL COMMENT '周转物ID',
`out_qty` int NOT NULL DEFAULT 0 COMMENT '累计借出数量',
`return_qty` int NOT NULL DEFAULT 0 COMMENT '累计归还数量',
`unreturn_qty` int NOT NULL DEFAULT 0 COMMENT '当前未还数量',
`damage_qty` int NOT NULL DEFAULT 0 COMMENT '损坏数量',
`lost_qty` int NOT NULL DEFAULT 0 COMMENT '丢失数量',
`deposit_amount` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '当前押金占用金额',
`compensate_amount` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '累计赔偿金额',
`last_out_date` bigint DEFAULT NULL COMMENT '最近借出时间',
`last_return_date` bigint DEFAULT NULL COMMENT '最近归还时间',
`version` int NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
`enabled` tinyint NOT NULL DEFAULT 1 COMMENT '1启用 0禁用',
`del_flag` tinyint NOT NULL DEFAULT 0 COMMENT '0正常 1删除',
`creator` bigint DEFAULT 0 COMMENT '创建人ID',
`create_date` bigint DEFAULT NULL COMMENT '创建时间',
`updater` bigint DEFAULT 0 COMMENT '修改人ID',
`update_date` bigint DEFAULT NULL COMMENT '修改时间',
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_shop_box` (`dept_id`,`shop_id`,`box_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客户周转物余额表';
CREATE TABLE `box_inventory_flow` (
`id` bigint NOT NULL COMMENT '主键ID',
`flow_code` varchar(64) NOT NULL COMMENT '流水号',
`dept_id` bigint NOT NULL DEFAULT 0 COMMENT '机构ID',
`workhouse_id` bigint NOT NULL DEFAULT 0 COMMENT '仓库ID',
`box_id` bigint NOT NULL COMMENT '周转物ID',
`biz_type` tinyint NOT NULL COMMENT '1借出 2归还 3购入 4销毁 5报损 6盘盈 7盘亏 8调整',
`source_code` varchar(64) DEFAULT NULL COMMENT '来源单号',
`source_detail_id` bigint DEFAULT NULL COMMENT '来源明细ID',
`shop_id` bigint DEFAULT NULL COMMENT '客户ID',
`driver_id` bigint DEFAULT NULL COMMENT '司机ID',
`before_qty` int NOT NULL DEFAULT 0 COMMENT '变动前数量',
`change_qty` int NOT NULL DEFAULT 0 COMMENT '变动数量，出库为负，入库为正',
`after_qty` int NOT NULL DEFAULT 0 COMMENT '变动后数量',
`unit_amount` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '单个价值或押金',
`change_amount` decimal(12,3) NOT NULL DEFAULT 0.000 COMMENT '变动金额',
`biz_date` bigint DEFAULT NULL COMMENT '业务时间',
`idempotent_key` varchar(128) NOT NULL COMMENT '幂等键',
`creator` bigint DEFAULT 0 COMMENT '创建人ID',
`create_date` bigint DEFAULT NULL COMMENT '创建时间',
`remark` varchar(255) DEFAULT NULL COMMENT '备注',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_idempotent_key` (`idempotent_key`),
KEY `idx_box_biz_date` (`box_id`,`biz_date`),
KEY `idx_source_code` (`source_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='周转物库存流水表';
附录 B：术语表
|--------|-------------------------------|
| 术语 | 说明 |
| 周转物 | 可重复使用的物流包装/容器资产，如周转箱、保温箱、托盘等。 |
| 客户占用 | 客户已收到但未归还的周转物数量。 |
| 司机暂存 | 司机配送或回收后尚未交回仓库的周转物数量。 |
| 押金占用 | 押金模式下客户未归还周转物对应的押金金额。 |
| 发出单 | 从公司仓库或配送任务发出周转物的业务单据。 |
| 归还单 | 客户或司机归还周转物的业务单据。 |
| 库存流水 | 记录周转物库存每一次变动的审计流水。 |