更新记录

1.0.0（2026-11-03）

首个版本：出货明细算出装箱方案。按每箱装量或每箱限重切箱，尾箱单独列出（不足满箱 20% 时提示合箱）；单箱毛净重、外箱体积、体积重、计费重逐箱计算；混装模式支持多料号装同一种外箱，受每箱限重与「外箱体积 × 装载率」双约束，逐箱输出内含料号与件数；箱唛数据与装箱单 CSV（带 BOM）；体检覆盖缺装量、单箱超限重、外箱超长边、体积估算、料号重复、数量非数字。UTS→Kotlin 编译通过（index.kt 1663 行、classes.dex 已生成），116 项回归测试全部通过；真机未执行（adb devices 为空），市场截图为 H5 渲染并标注示例数据。

平台兼容性

uni-app

Vue2	Vue3	Chrome	Safari	app-vue	app-nvue	Android	iOS	鸿蒙
×	√	×	×	√	×	√	×	×

微信小程序	支付宝小程序	抖音小程序	百度小程序	快手小程序	京东小程序	鸿蒙元服务	QQ小程序	飞书小程序	小红书小程序	快应用-华为	快应用-联盟
×	×	×	×	×	×	×	×	×	×	×	×

装箱分箱与箱唛计算

给做出口出货、外贸跟单、货代报价的人用：把一张出货明细变成「几箱、每箱多重、多少方、计费重多少、箱唛怎么写」。

一张明细进去，三样东西出来：逐箱明细（第几箱装什么、多少件、毛净重、外箱尺寸、单箱计费重）、装箱单 CSV、箱唛数据（箱号 n/N、订单号、目的港、品名、数量、毛净重、尺寸、产地）。

购买前必读

只支持 Android（minSdkVersion 23，Android 6.0 起）。iOS 与鸿蒙本版本未实现，市场平台声明里已标不支持，不要当跨端插件买。
不做 3D 装柜排布。本插件回答的是「这套货要打多少箱、每箱怎么装、箱唛怎么写」，不回答「这个 40HQ 还能塞几箱」。要装柜优化请另选工具，两者不冲突。
数量单位是「件」，尺寸单位是 mm，重量单位是 kg。detail 里填了「箱」或「cm」会算错一个数量级。
没给外箱尺寸的料号，体积是估算值（单件体积 × 装量 ÷ 装载率），输出里 estimated 为 true、装箱单「尺寸来源」列写「估算」。要精确报给货代，请把外箱长宽高填上。
计价口径按货代常见做法：体积重 = 长×宽×高(cm) ÷ 除数（默认 6000），计费重 = 毛重与体积重取大后逐箱按步长（默认 0.5kg）向上进位。不同承运商规则不同，参数都开放，别拿默认值当合同。

解决什么问题

出货前一天最容易出三类错，都是手工算出来的：

箱数算错：1000 支按每箱 25 支该是 40 箱，手算成 39 箱，到现场少一个箱子；
尾箱被忽略：997 支按 25 支一箱是 39 箱 + 尾箱 22 支，尾箱往往被当成满箱报给货代，重量对不上；
计费重按错口径：灯管这类长条货体积重远大于实重，按实重报价，运费直接亏。

本插件把这三件事一次算清，并且把「哪一箱、为什么是这个数」保留在输出里，客户问起能翻。

与同类的边界

你可能已有的	它做什么	本插件做什么
多级 BOM 展开（本店 `szhzy-bom-explode`）	一个成品要备多少料	一批货要打多少箱
报价核算（本店 `szhzy-quote-cost`）	单件成本与报价	单箱体积重与计费重
标签打印（本店 `szhzy-labelprint`）	把内容打成 TSPL 标签	只产箱唛数据（CSV / 数组），打印交给标签软件或上面的插件
Excel 导出（本店 `szhzy-xlsx-export`）	通用报表落盘	装箱单与箱唛的列定义与口径已按出货习惯定好

市面上的在线体积重计算器能算单箱，但不会替你切箱、不会处理尾箱、不会把多料号混装进同一种箱，也不产出箱唛。

快速上手

import { packPlan, exportPacking } from '@/uni_modules/szhzy-carton-pack'

const r = packPlan({
  csv: `料号,品名,数量,单件长,单件宽,单件高,净重,装量,限重,箱重,外箱长,外箱宽,外箱高
T8-1200-18W,T8 灯管 18W 1.2m,250,1200,30,30,0.32,25,0,0.55,1240,320,340`,
  divisor: 6000,        // 体积重除数：空运 6000 / 快递 5000 / 海运 1000
  step: 0.5,            // 计费重进位步长
  fillRate: 0.85,       // 未给箱规时的体积装载率
  po: 'PO-2026-1108',
  dest: 'HAMBURG',
  customer: 'SZHZY GMBH',
  origin: 'MADE IN CHINA'
})

r.summary.cartons     // 10
r.summary.chargeKg    // 计费重合计
r.cartons[0].grossKg  // 单箱毛重
r.marks[0].sizeText   // '124×32×34cm'
r.warnings            // 尾箱过碎 / 超限重 / 超长边 / 尺寸估算

导出到应用私有目录（零存储权限）：

exportPacking({ csv, po: 'PO-2026-1108', kind: 'packing' })  // 装箱单 CSV
exportPacking({ csv, po: 'PO-2026-1108', kind: 'marks' })    // 箱唛 CSV

明细列

带表头时按列名定位（顺序随意），无表头时按下面顺序取：

列	说明
料号 / 品名	输出到箱唛与装箱单
数量	件数
单件长 / 宽 / 高	单件包装后尺寸，mm
净重	单件净重，kg
装量	每箱装几件；填 0 则按限重推算
限重	每箱毛重上限 kg；与装量同时给时，两者都校验
箱重	纸箱自重 kg
外箱长 / 宽 / 高	外箱外尺寸 mm；不填则按体积估算并标注

列名别名：单件长 = 长 = 长度，装量 = 每箱数量，箱重 = 纸箱自重，限重 = 每箱限重。分隔符逗号与制表符都认，带引号的字段会正确还原。

API

方法	用途
`packPlan(options)`	一次算完：分箱、箱唛、两份 CSV、汇总、提示
`cartonList(options)`	只要逐箱明细与汇总（列表页刷新用）
`markList(options)`	只要箱唛数组与箱唛 CSV
`exportPacking(options)`	导出装箱单（`kind:'packing'`）或箱唛（`kind:'marks'`）到文件
`boxWeight({lenMm,widMm,heiMm,grossKg,divisor,step})`	单箱随手算：体积、体积重、计费重
`packDefaults()`	默认口径与输出目录

全部返回统一信封 { ok, code, message, ... }，不抛异常。ok=false 时看 code：EMPTY 明细为空、NO_ROW 没有可用行、TOO_LARGE 行数超限、NEED_BOX 混装没给外箱、READ_FAILED 读文件失败。

混装

多料号装同一种外箱时打开 mixed: true，并给外箱内尺寸与自重：

packPlan({
  csv: mixCsv,
  mixed: true,
  boxLen: 600, boxWid: 400, boxHei: 400,   // mm
  boxCartonKg: 0.6,                          // 纸箱自重 kg
  fillRate: 0.85                             // 外箱容积利用率
})

装法按明细顺序依次装入，同时受两个约束：每箱净重不超过「该批料号的最小限重 − 箱重」，累计货物体积不超过「外箱体积 × 装载率」。任一约束触顶就封箱。输出每箱的 members 列出装了哪些料号、各多少件，箱唛的品名会写成 灯管×40 / 支架×60 这样的形式。

顺序装载不是最优解（装箱本身是 NP 难问题），但对应现场「按单从第一行开始装」的真实做法，结果可复现、可对账。

提示（warnings）

kind	含义	处理建议
`TAIL_BAD`	尾箱件数不足满箱 20%	与前一批合箱，或用小一号纸箱
`OVER_WEIGHT`	按装量算出的单箱毛重超限重	减少装量或换纸箱
`OVERSIZE`	外箱单边超过 2400mm	快递与托盘可能拒收
`NO_CAPACITY`	既没装量也没限重	按整单 1 箱计，需人工确认
`ESTIMATE`	没给外箱尺寸	体积为估算值
`DUP_SKU`	同一料号出现多行	按两行分别装箱；同一批请先合并
`BAD_NUM` / `ZERO_QTY`	数量或净重不是数字 / 数量为 0	该行不参与分箱

能力边界与已知限制

单次明细上限 2000 行；明细文件上限 12 MB；
单个料号只支持一种箱规，同一料号要出两种箱请拆成两行；
尾箱沿用满箱的箱规（现场通常只有几种固定纸箱），不会为尾箱单独优化尺寸；
不留纸箱库存台账，也不算纸箱成本（要算成本请配 szhzy-quote-cost）；
不打印标签。marksCsv() 输出的是数据，打印交给标签软件或 szhzy-labelprint。

验证状态

纯逻辑回归测试：116 项全部通过（dev-tools-uts/verify/carton-pack/run-tests.mjs），覆盖解析、切箱、尾箱、体积重、计费重进位、混装重量与容积双约束、箱唛与两份 CSV；
Kotlin 编译：cli launch app-android --compile true 输出「编译成功」，产物 index.kt 1663 行、classes.dex 已生成，说明过了 Kotlin 类型检查（不是只做 UTS→Kotlin 转写）；
真机：未执行。开发机上没有可用的 Android 设备（adb devices 为空），平台层的文件读写与 content:// 授权未在真机上跑过。市场截图来自 H5 渲染的同一套页面，页面标注「示例数据」，不是真机截图。
iOS / 鸿蒙：未实现。

以上口径与市场详情页、日报一致，没有把未验证项写成已通过。

授权

普通授权与源码授权两档，源码版含 utssdk/ 全部实现与演示工程。商用请遵守 license.md。