125 lines
5.3 KiB
Markdown
125 lines
5.3 KiB
Markdown
# WareShipManifest · 装箱单报表系统
|
||
|
||
基于 **ReportBro**（`reportbro-lib`，纯 Python）生成装箱单 PDF。报表定义（SQL / 模板 / 数据装配）均为纯文本，可被 Git 管理；后期对接真实打印机时，PDF 方案可直接复用。
|
||
|
||
> 业务背景：把 CargoTrace 成品库分拣系统的装箱数据，打印成装箱单随货流转。
|
||
> 一个箱子一份 PDF，展示该箱装了哪些内容物（总排号）及其产品信息。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 1. 建虚拟环境并装依赖
|
||
python -m venv .venv
|
||
.venv/Scripts/python.exe -m pip install -r requirements.txt # Windows / Git Bash
|
||
|
||
# 2. 配置数据库（复制模板并填凭据，或直接复用 services/fastapi 的 settings.yaml）
|
||
cp config/settings.example.yaml config/settings.yaml
|
||
# 编辑 config/settings.yaml 填入真实 host/数据库/账号密码
|
||
|
||
# 3. 生成装箱单
|
||
.venv/Scripts/python.exe run.py --report packing_list \
|
||
--param paichan_no=R04398 --param box_no=1 \
|
||
--output out/R04398_box1.pdf
|
||
# → out/R04398_box1.pdf
|
||
```
|
||
|
||
## 用法
|
||
|
||
```bash
|
||
python run.py --report packing_list \
|
||
--param paichan_no=<排产号> \
|
||
--param box_no=<箱号> \
|
||
--output <输出路径.pdf> # 可选，默认 out/<排产号>_box<箱号>.pdf
|
||
```
|
||
|
||
- 缺少参数 → 提示缺少哪个参数。
|
||
- 排产号 + 箱号无装箱明细 → 提示「找不到该箱」。
|
||
- 均以非零退出码退出，便于脚本集成。
|
||
|
||
## 报表内容
|
||
|
||
| 区域 | 内容 |
|
||
|---|---|
|
||
| 标题 | 装箱单 / PACKING LIST + 分隔线 |
|
||
| 信息条 | 排产号、箱号、装箱日期、订单号（2×2 网格，标签灰 + 值黑） |
|
||
| 列头 | 序号 · 总排号 · 产品型号 · 量程 · 位号 · 数量 · 工令号（小号灰） |
|
||
| 明细 | 逐行文本，行间细灰线；无网格边框 |
|
||
| 合计 | 合计 N 件（右对齐于数量列下） |
|
||
| 页脚 | 生成时间 |
|
||
|
||
- **无边框、单色、字体驱动**：靠字号 / 字重 / 留白 / 细灰分隔线建立层次，不用表格网格。
|
||
- **位号**：合同表字段，多数订单为空，有则显示、无则留白。
|
||
- **产品型号**为超长编码串，按列宽换行，行高自适应。
|
||
|
||
## 数据来源
|
||
|
||
| 表 | 作用 |
|
||
|---|---|
|
||
| `CargoTrace.finished_goods_box` | 箱头（排产号 + 箱号 + 装箱时间） |
|
||
| `CargoTrace.finished_goods_box_item` | 箱内明细（总排号 + 装入数量） |
|
||
| `productionContractData.26年压力表合同数据` / `26年温度计合同数据` | 产品信息（型号/量程/位号/工令号/订单号） |
|
||
|
||
同一总排号只命中压力表或温度计其中一张表，用双 `LEFT JOIN + COALESCE` 取产品字段，
|
||
避免前缀误匹配（`26BW` 不会被 `26B%` 命中）。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
WareShipManifest/
|
||
├── config/
|
||
│ ├── settings.example.yaml # 配置模板（提交）
|
||
│ └── settings.yaml # 真实凭据（gitignore）
|
||
├── core/
|
||
│ ├── settings.py # 读 yaml → mssql+pyodbc 连接 URL
|
||
│ ├── db.py # run_query(sql, params) 参数化绑定
|
||
│ └── fonts.py # 中文字体注册（simhei via additional_fonts）
|
||
├── reports/packing_list/
|
||
│ ├── query.sql # 参数化查询（:paichan_no / :box_no）
|
||
│ ├── transform.py # build_context(rows) → 预展开标量参数 + 行高估算（纯逻辑）
|
||
│ ├── _build_template.py # 样式 + 运行时按数据动态布局的文档元素（无边框列表式）
|
||
│ └── config.yaml # 报表元信息（参数/字段说明）
|
||
├── tests/test_transform.py # 纯逻辑单测
|
||
├── run.py # CLI 入口
|
||
├── requirements.txt
|
||
└── README.md
|
||
```
|
||
|
||
## 开发
|
||
|
||
### 改报表版式（列宽 / 字号 / 边距 / 配色 / 行距）
|
||
|
||
版式全部在 `reports/packing_list/_build_template.py` 中以代码定义（常量 + 样式工厂）。
|
||
文档元素在运行时按数据动态生成（明细行高度自适应），无需预生成模板文件——
|
||
直接改代码后重跑 `run.py` 即生效。
|
||
|
||
> 不使用 ReportBro 可视化设计器，也不用其表格元素（行高不自适应、行不自动堆叠）；
|
||
> 改用纯文本元素 + 细横线手工排版，坐标完全可控，靠字号/字重/留白建立层次。
|
||
|
||
### 改查询 / 数据装配
|
||
|
||
- SQL：`reports/packing_list/query.sql`（参数化，禁字符串拼接）。
|
||
- 数据装配：`reports/packing_list/transform.py` 的 `build_context`（纯逻辑，含单测）。
|
||
|
||
### 跑测试
|
||
|
||
```bash
|
||
.venv/Scripts/python.exe -m pytest -q
|
||
```
|
||
|
||
### 中文字体
|
||
|
||
核心字体（helvetica 等）无法编码中文，故通过 `core/fonts.py` 注册
|
||
`C:/Windows/Fonts/simhei.ttf`（黑体），模板样式 `font="simhei"`。
|
||
跨机器部署若缺该字体，可用环境变量 `REPORT_CJK_FONT` 指定其它支持中文的 ttf。
|
||
|
||
## 技术说明
|
||
|
||
- **reportbro-lib**：纯 Python（`pip install reportbro-lib`），无需 Docker / 浏览器 / 设计器常驻服务。
|
||
- 数据处理与展示分离：排序在 SQL、合计与日期在 transform、模板只渲染。
|
||
- 生成的 PDF 可用 `pymupdf`（`fitz`）渲染 PNG 做肉眼核对（验证用，非运行时依赖）。
|
||
|
||
## 路线图
|
||
|
||
- [ ] 后期对接真实打印机（PDF 方案可直接复用）。
|
||
- [ ] 发货信息单（地址 / 收件人 / 总件数 / 物料编码）—— 与装箱单拆分，另出报表。
|