| name | hlzd-logistics-planner |
| description | B2B 工业品海运/空运/铁路物流装箱方案 —— py3dbp 3D 装箱 + 标准集装箱尺寸库 + 三家比价 + 3D 预览 + HS 编码归类。INCOTERMS 2020 适配。 |
| license | MIT |
| metadata | {"author":"HLZD (海联智达 / 海良数科)","version":"0.1.0","industry":"cross-border-b2b","category":"logistics","triggered_by":["物流装箱","装柜方案","海运装箱","集装箱装箱","3D 装箱","装柜优化","装箱率","container loading","海运报价","空运报价","中欧班列","多式联运","HS 编码","归类","INCOTERMS 2020","load plan","container optimization","freight quote"]} |
HLZD 物流装箱 v0.2
v0.2 关键升级（基于 GitHub 调研 6 个高星标开源项目）：
- 借鉴 py3dbp（454 stars）—— 直接 pip install，6 方向旋转 + 支点算法 + 体积利用率计算
- 借鉴 alibaba/drl_binpacking（89 stars）—— 阿里巴巴 Cainiao 真实业务 DRL 装箱方案
- 借鉴 alexfrom0815/Online-3D-BPP-PCT（1039 stars）—— 深度强化学习 3D 装箱
- 借鉴 three.js + drei（113,546 stars）—— 3D 装箱预览
- 借鉴 GreaterWMS（4,311 stars）—— 福特汽车仓储管理系统模块
- 借鉴 BoxPacker（656 stars）—— 4D 装箱 PHP 实现
核心原则：不自己实现装箱算法——直接用 py3dbp，把精力放在 HLZD 业务场景适配（标准集装箱 + 物流比价 + HS 编码 + 危险品 + 3D 预览）。
定位
| 对比项 | 手工 Excel 计算 | HLZD-物流装箱 v0.2 |
|---|
| 装箱方案 | 人工经验估算 | py3dbp 算法（6 方向旋转 + 支点） |
| 体积利用率 | 凭感觉 | 精确计算 ≥ 80% 算 PASS |
| 集装箱选型 | 拍脑袋 | 自动选最优集装箱（20GP/40GP/40HQ/45HQ/LCL） |
| HS 编码 | 查海关手册 | HLZD 数据库 + LLM 自动归类 |
| 危险品 | 容易漏报 | HS + 关键字自动识别 |
| 物流比价 | 打 4-5 家公司电话 | API 自动比价（COSCO/MAERSK/MSC/CMA-CGM） |
| 3D 装箱预览 | 无 | three.js + drei 实时预览 |
| 装箱单 | 手工制作 | HLZD-办公文档自动生成 |
数据源借鉴（GitHub 调研 6 个高星标项目）
| 借鉴项目 | Stars | 借鉴内容 | HLZD 价值 |
|---|
| 🏆 enzoruiz/3dbinpacking (py3dbp) | 454 | Python 3D 装箱库（直接 pip install） | ⭐ 核心算法 |
| 🏆 alibaba/drl_binpacking | 89 | Cainiao DRL 装箱实战 | ⭐ 表面积最小化 |
| 🏆 alexfrom0815/Online-3D-BPP-PCT | 1039 | DRL 在线 3D 装箱 | 高级算法 v0.3 |
| 🏆 mrdoob/three.js | 113,546 | JavaScript 3D Library | ⭐ 3D 预览 |
| 🏆 pmndrs/drei | 9,727 | React Three Fiber helpers | 快速构建 3D |
| GreaterWMS | 4,311 | 福特汽车仓储系统 | 系统模块参考 |
核心能力矩阵
| 能力 | 实现 | v0.2 升级 | 耗时 |
|---|
| 3D 装箱算法 | py3dbp（pip install） | ⭐ v0.2 升级（不再自己写） | < 5s/订单 |
| 6 方向旋转 | py3dbp rotation | ⭐ v0.2 升级 | 算法自动 |
| 自动选最优集装箱 | py3dbp distribute_items | ⭐ v0.2 升级 | < 5s |
| 体积利用率计算 | py3dbp get_volume_utilization | ⭐ v0.2 升级 | 即时 |
| 3D 装箱预览 | three.js + drei | ⭐ v0.2 升级（手机可看） | < 3s 渲染 |
| HS 编码自动归类 | HLZD 数据库 + LLM | v0.1 保留 + v0.2 升级 | < 2s |
| 危险品识别 | HS 前 4 位 + 关键字 | v0.1 保留 | < 1s |
| 物流公司比价 | COSCO/MAERSK/MSC/CMA-CGM API | ⭐ v0.2 升级 | < 10s |
| 装箱单生成 | 复用 HLZD-办公文档 | v0.1 保留 | < 3s |
| ASN/DN 流程 | 借鉴 GreaterWMS | ⭐ v0.2 升级（v0.3 实现） | — |
| 关联 HLZD-智能报价 | 价格联动 | v0.1 保留 | 即时 |
| 关联 HLZD-客户画像 | 国别风险 + 物流偏好 | ⭐ v0.2 升级 | 即时 |
工作流 v0.2
输入（订单 ID 或产品清单）
↓
[1] 拉取订单详情（关联 HLZD-智能报价） ⭐ v0.2 关联
↓
[2] 产品清单 → py3dbp Items（每个产品 L×W×H×重量）
↓
[3] py3dbp 装箱算法 ⭐ v0.2 核心
├─ 添加 5 种候选集装箱（20GP/40GP/40HQ/45HQ/LCL）
├─ 6 方向旋转 + 支点算法
└─ 体积利用率 ≥ 80% 算 PASS
↓
[4] HS 编码自动归类 ⭐ v0.2 升级
├─ 查 HLZD-B2B工业品调研数据库
└─ LLM 推理（参考海关编码规则）
↓
[5] 危险品识别 ⭐ v0.2 升级
├─ HS 编码前 4 位（锂电池 8507/炸药等）
└─ 关键字匹配（lithium/battery/explosive）
↓
[6] 3D 装箱预览生成 ⭐ v0.2 升级（three.js + drei）
↓
[7] 物流公司比价（4-5 家 API） ⭐ v0.2 升级
├─ COSCO / MAERSK / MSC / CMA-CGM
└─ 推荐最优报价
↓
[8] 装箱单生成（复用 HLZD-办公文档） v0.1 保留
↓
[9] 飞书卡片返回
├─ 装箱方案（文字 + 表格）
├─ 3D 预览链接
├─ 物流报价对比
└─ HS 编码 + 危险品标识
↓
[10] 业务员一键确认 → 触发 ASN/DN 流程 ⭐ v0.2 升级（借鉴 GreaterWMS）
HLZD 标准集装箱尺寸库
container_sizes:
"20GP":
name: "20英尺标准箱"
L: 5.90
W: 2.35
H: 2.39
volume: 33.1
max_weight: 21000
use_case: "重货、钢管"
"40GP":
name: "40英尺标准箱"
L: 12.03
W: 2.35
H: 2.39
volume: 67.5
max_weight: 26500
use_case: "通用"
"40HQ":
name: "40英尺高箱"
L: 12.03
W: 2.35
H: 2.69
volume: 76.2
max_weight: 26500
use_case: "轻泡货（家电/家具）"
"45HQ":
name: "45英尺高箱"
L: 13.56
W: 2.35
H: 2.69
volume: 85.7
max_weight: 27600
use_case: "大批量轻泡货"
"LCL":
name: "散货拼箱（1.2m 立方体）"
L: 1.20
W: 1.20
H: 1.20
volume: 1.7
max_weight: 500
use_case: "样品/小批量"
logistics_carriers:
- "COSCO"
-
-
-
-
scripts/load_optimizer.py 完整设计（基于 py3dbp）
"""
HLZD 物流装箱优化器 v0.2
基于 py3dbp (454 stars) — 直接 pip install py3dbp
"""
from py3dbp import Packer, Bin, Item
from typing import Literal
class LoadOptimizer:
"""HLZD 物流装箱优化器（v0.2 升级，借鉴 py3dbp）"""
CONTAINER_SIZES = {
"20GP": (5.90, 2.35, 2.39, 21000),
"40GP": (12.03, 2.35, 2.39, 26500),
"40HQ": (12.03, 2.35, 2.69, 26500),
"45HQ": (13.56, 2.35, 2.69, 27600),
"LCL": (1.20, 1.20, 1.20, 500),
}
def optimize(self, products: list, container_type: str = "AUTO") -> dict:
"""主入口：装箱优化（借鉴 py3dbp）"""
packer = Packer()
if container_type == "AUTO":
for code, (L, W, H, max_w) in self.CONTAINER_SIZES.items():
packer.add_bin(Bin(code, L, W, H, max_w))
:
L, W, H, max_w = .CONTAINER_SIZES[container_type]
packer.add_bin(Bin(container_type, L, W, H, max_w))
p products:
packer.add_item(Item(
p[],
p[], p[], p[],
p[],
))
packer.pack(bigger_first=, distribute_items=)
results = []
packer.bins:
(.items) > :
results.append({
: .name,
: .get_volume_utilization(),
: .get_weight_utilization(),
: [
{
: item.name,
: item.position,
: item.rotation_type,
: item.get_dimension(),
}
item .items
],
})
r results:
r[] = r[] >=
{
: (products),
: (results),
: results,
: ._recommend(results),
}
() -> :
results:
best = (results, key= r: r[])
scripts/generate_3d_preview.py 完整设计（基于 three.js）
"""
HLZD 物流装箱 3D 预览生成
基于 three.js (113,546 stars) + drei (9,727 stars)
"""
import json
def generate_3d_preview_html(optimization_result: dict) -> str:
"""生成 3D 装箱预览 HTML（手机可看）"""
containers = []
for container in optimization_result["results"]:
items = []
for item in container["items"]:
items.append({
"name": item["name"],
"position": list(item["position"]),
"size": list(item["size"]),
"color": hash_to_color(item["name"]),
})
containers.append({
"type": container["container_type"],
"items": items,
})
react_code = """
import React from 'react'
import { Canvas } from '@react-three/fiber'
import { OrbitControls, Box, Text } from '@react-three/drei'
const CONTAINER_DIMS = {
"20GP": [5.90, 2.35, 2.39],
"40GP": [12.03, 2.35, 2.39],
"40HQ": [12.03, 2.35, 2.69],
"45HQ": [13.56, 2.35, 2.69],
}
export default function ContainerPacker3D({ containers }) {
return (
<Canvas camera={{ position: [15, 15, 15], fov: 50 }}>
<ambientLight intensity={{0.6}} />
<pointLight position={{[15, 15, 15]}} />
<axesHelper args={{[5]}} />
{{containers.map((c, ci) => {{
const dims = CONTAINER_DIMS[c.type] || [12, 2.35, 2.69]
return (
<group key={{ci}} position={{[0, 0, ci * 15]}}>
{{/* 集装箱线框 */}}
<Box args={{dims}} position={{[dims[0]/2, dims[1]/2, 0]}}>
<meshStandardMaterial color="lightgray" wireframe />
</Box>
{{/* 产品 */}}
{{c.items.map((item, i) => (
<Box
key={{i}}
args={{item.size}}
position={{[
item.position[0] + item.size[0]/2,
item.position[1] + item.size[1]/2,
item.position[2] + item.size[2]/2,
]}}
onClick={{() => alert(`${item.name}\\n${item.size.join('×')}m`)}}
>
<meshStandardMaterial color={{item.color}} />
</Box>
))}}
</group>
)
}})}}
<OrbitControls />
</Canvas>
)
}
"""
html =
html
scripts/compare_logistics.py 完整设计
"""
物流公司比价 v0.2
借鉴 GreaterWMS 模块化设计
"""
from typing import Literal
import asyncio
class CarrierAPI:
"""物流公司 API 抽象（v0.2 升级）"""
async def get_rate(self, origin: str, destination: str, containers: list, weight_kg: float) -> dict:
"""获取海运报价"""
raise NotImplementedError
class COSCOAPI(CarrierAPI):
"""中远海运 API"""
async def get_rate(self, origin, destination, containers, weight_kg):
return {"carrier": "COSCO", "rate_usd": 1200, "transit_days": 25}
class MAERSKAPI(CarrierAPI):
"""马士基 API"""
async def get_rate(self, origin, destination, containers, weight_kg):
return {"carrier": "MAERSK", "rate_usd": 1350, "transit_days": 22}
():
():
{: , : , : }
():
():
{: , : , : }
():
():
{: , : , : }
() -> :
carriers = [COSCOAPI(), MAERSKAPI(), MSCAPI(), CMACGMAPI(), EVERGREENAPI()]
tasks = [carrier.get_rate(origin, destination, containers, weight_kg) carrier carriers]
quotes = asyncio.gather(*tasks)
(quotes, key= x: x[])
scripts/classify_hs_code.py 完整设计
更多细节
完整设计文档（v0.1.x 实现细节 + 错误地图 + 性能目标）见 references/deep-dive.md。
