# coolCodeTrace
**Repository Path**: afeng124/coolcodetrace
## Basic Information
- **Project Name**: coolCodeTrace
- **Description**: 通用包装追溯系统,vue3+net 10。演示数据迁移至真实客户,如有侵权实属巧合(请通知整改)。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 2
- **Forks**: 1
- **Created**: 2024-07-23
- **Last Updated**: 2026-11-10
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# CoolCodeTrace · 标签包装追溯系统
一套面向制造业 MES 的条码/二维码标签打印与追溯码管理平台。后端基于 ZRAdmin 框架(.NET 8 + SqlSugar + JWT),前端 Vue3 + Element Plus + Vite,内置 ZPL 渲染引擎、可视化模板设计器,并配套本机打印服务完成 TCP 9100 下发。
---
## ✨ 功能一览
| 模块 | 能力 |
|---|---|
| 📊 Dashboard | 统计卡片(标签/规则/客户端/累计打印量)+ 近 7 天折线、TOP 标签、箱体类型、打印结果图表 |
| 📦 示例打印 | 202 个真实标签卡片画廊,按箱体类型/关键词筛选,一键预览、一键打印 |
| 🖨️ 打印工作台 | 选标签 → 动态表单(含字段校验)→ 服务端渲染预览 → 提交打印 |
| 📝 打印历史 | 7218 条打印日志,含真实 BarCodeSN/QRCode 与完整 ZPL;按标签编码 / 追溯码 / 打印时间 + 工厂 / 产线 / 工序 / 工位筛选,支持导出、补打、查看 ZPL |
| 🏷️ 标签定义 | 标签编码、箱体类型(2S/3S/2S&3S…)、DPI(203/300/600)、版本、共享组、模板绑定 |
| 🎨 模板设计器 | 画布可视化编辑(文本 / Code128·39·93 / QR·DataMatrix / 图形 / 条件图标),毫米网格与标尺、拖放定位 + 8 向缩放、吸附对齐、图层顺序、撤销重做、中文分组属性(旋转 / 字宽 / ^FB / 条码参数 / QR 纠错),模板级预览,保存即生效 |
| 🔁 连续打印 | 数量(不同追溯号张数)× 份数(每张份数),合并一次下发;支持 2S&3S 内外箱组合连续打印 |
| 📦 装箱作业 | 读码器逐个扫内箱码(`eventId` 幂等、同箱去重、跨箱拦截)→ 满规格自动生外箱码并打印;缺料尾箱(11/12)按实际数量出标,支持作废重装、箱明细追溯 |
| 🔢 标签字段 | PartNo / Qty / Date / TraceCode 等字段元数据,与模板里的 `{占位符}` 同名对接,支持默认值、控件类型、必填、AIAG 前缀、二维码入库 |
| 🔗 追溯码规则 | CONST + SERIAL 段组合,Day/Month/AppleWeek/Year 周期推断,流水号当前值/最大值管理 |
| 🔧 设备管理 | 打印客户端状态/心跳、流水号管理 |
| 🏭 工厂建模 | 工厂 / 产线 / 工序 / 工位档案,打印记录可按层级过滤 |
> 📖 非常规标签(横竖转换、旋转打印)是怎么用 ZPL 指令实现的,见下文「特殊标签实现举例」。
---
## 🚀 推荐使用流程
**① 示例打印挑标签**:进入「标签打印 → 示例打印」,按箱体类型或编码筛出目标标签,点「预览」先看效果。

**② 打印工作台填表并预览**:选标签后填写料号、追溯码等字段,点「预览」即可看到真实 ZPL 渲染出的标签图(与打印下发的是同一份 ZPL,不会消耗流水号)。

**③ 提交打印并追溯**:确认无误后提交,打印任务经 TCP 9100 下发;随后在「打印历史」按标签编码 / 追溯码 / 打印时间,并可叠加工厂 / 产线 / 工序 / 工位四级联动检索,失败或需要重打时点「补打」。

> 打印历史里的工厂 / 产线 / 工序 / 工位是打印时写入的快照,四个下拉按工厂建模档案级联联动,并可与标签编码、追溯码、打印时间组合,列表与导出使用同一套条件,补打按单条日志原样重发。早期从老系统迁移的历史未记录这四项,可在下拉中选「未指定(迁移历史)」单独筛出(当前 7218 条中 7215 条);新发生的打印会自动记录四维快照。
**④ 需要改版式时进设计器**:在「标签配置 → 模板设计器」选择模板(下图为 `DEMO-COMP-01` 工厂外箱出货标签),画布上可直接拖拽元素或改属性;画布里的 `{字段名}` 是占位符,点「预览」会用示例值生成 ZPL 查看效果,确认后保存立即生效。
设计器按 ZPL `^FO` 左上角定位,单位统一为 mm。元素可点击添加或拖到指定位置,选中后拖动 8 个手柄缩放、方向键 0.5mm 微调(Shift 加速),并提供 1mm 网格吸附、对齐辅助线、对齐到画布、图层顺序与撤销/重做;属性面板按「模板 / 位置与尺寸 / 内容 / 文字样式 / 条码 / 二维码 / 图形 / 条件图标」分组,暴露渲染引擎已支持的打印方向(N/R/I/B)、字宽、`^FB` 字段块、条码注释行与模块宽、QR 纠错等级等参数,另有「编辑元素 JSON」可直接维护 `ft`、`fontCmd`、`mask`、`textOffsetX/Y` 等老模板字段。越界元素会高亮并在保存前确认,未保存修改在切换模板或离开页面时会拦截提醒。

---
## 📸 界面总览
| 示例打印 | 打印工作台(预览) |
|---|---|
|  |  |
| 打印历史 | 本机打印服务 |
|---|---|
|  |  |
---
## 🧪 综合演示案例:工厂外箱出货标签
系统内置一套完整的演示数据,覆盖「模板设计器 → 标签定义 → 追溯码规则 → 打印预览」全链路,可直接用于验收或培训演示。案例取自**工厂外箱出货/装箱追溯**场景,字段结构参照真实客户外箱标签(客户、料号、订单号、数量、箱号、供应商等),不再使用消费电子成品示例。
- 模板 `DEMO-COMP-01`(工厂外箱出货标签):100×80mm、203DPI,含标题与英文副标题、分隔线、6 行字段、追溯码 Code128、料号 Code128、结构化 QR、矩形框、条件 CE 图标与 PASS 检验圆标
- 标签定义「综合演示标签(外箱出货)」:箱体类型「外箱」,绑定上述模板与规则;字段为 `CustomerName` 客户、`PartNo` 料号、`SaleOrderNo` 订单号、`ProductDesc` 产品描述、`Quantity` 数量、`BoxNo` 箱号、`PrintDate` 日期、`SupplierName` 供应商、`EnvFlag` 环保标识,均已预填示例值
- 追溯码规则 `DEMO-COMP-01`:`DEMO` + `YYMMDD` + 4 位日流水,生成形如 `DEMO2611080001` 的追溯码;QR 码内容为 `PN:料号 QTY:数量 SN:追溯码`
- 示例数据:`HAIER SMART HOME` / `HX-CB-2026A` / `SO-20261108-0137` / `CONTROL BOARD ASSY` / `240 PCS` / `001/020` / `SUZHOU HX MFG`
| 打印工作台(预览) | 标签成品 |
|---|---|
|  |  |
使用方式:进入「标签打印 → 打印工作台」,选择「综合演示标签(外箱出货)」,字段已预填,点「打印预览」即可复现上图;预览不消耗流水号、不写打印日志。演示数据可用幂等脚本一键重建(见「快速开始 → 数据库」)。
---
## 🧷 特殊标签实现举例
产线上常碰到「成品标签尺寸 ≠ 现场纸张尺寸」「标签要横贴、纸却是竖的」这类非常规需求。这类问题不必重画版式、也不必换纸,在 ZPL 指令层就能解决。本节用系统里一条**真实历史标签**完整拆解实现细节,给出可直接下发的样本与效果对照;后续如有镜像、倒置、多联等案例,继续追加到本节。
| 场景 | 实现手段 | 样本 / 代码 |
|---|---|---|
| 150×100mm 横版标签,只有 100×150mm 竖纸 | `^FWR` 整场旋转 90° + `^LH` 原点偏移 | [`docs/samples/BC-DELL-01-rotated.zpl`](docs/samples/BC-DELL-01-rotated.zpl) |
| 仅个别元素需要旋转(新版模板) | 元素 `orientation:"R"` → `^A0R` / `^BCR` | `ZplRenderEngine.cs` 的 text / barcode128 分支 |
| 装箱尾箱(两级包装:内箱 → 外箱,规格 12、实际只有 11 只) | 外箱码规则不动,`Quantity` / `QuantityText` / `IsTail` 按实际值渲染 | 装箱作业页 + `cct_pack_demo.sql` |
### 案例:100×150mm 竖纸打印 150×100mm 横版标签(DELL `BC-DELL-01`)
#### 需求与约束
| | 成品(贴标后) | 现场(打印时) |
|---|---|---|
| 尺寸 | 150 × 100 mm 横版 | 100 × 150 mm 竖向标签纸 |
| 方向 | 文字、条码正常横向可读 | 文字、条码沿出纸方向竖排 |
| 分辨率 | 300 dpi | 300 dpi(≈ 11.81 dots/mm) |
横版长边 150mm 超过纸宽 100mm,直接印必然裁切。**解法不是缩放,而是把整版内容旋转 90° 打到竖纸上**,贴标时逆时针转回来即可正常阅读。
#### 实现原理:一条 `^FWR` 把横版标签「侧躺」进竖纸
`^FWR` 把**后续所有字段内容**(`^FD` 文本、`^BC` 条码)的方向设为顺时针 90°;`^FO` 仍使用纸张物理坐标(x 水平、y 垂直),`^GB` 画出的框与分隔线也不随 `^FW` 旋转(实测 `^FWR` 与 `^FWN` 两版外框像素边界完全一致)。于是写版式时相当于把横版标签转置:
| 概念 | 竖纸打印(样本写法) | 旋转回横版后等价于 |
|---|---|---|
| 长边 150mm | 由 `^FO` 的**第二个参数 y** 承载(0~1700 dots) | 横向位置 |
| 短边 100mm | 由 `^FO` 的**第一个参数 x** 承载(0~1130 dots) | 纵向行位置 |
| `^FD` / `^BC` | 沿 y 向下展开,条码条方向横过来 | 正常从左到右 |
| `^GB1130,1700,3` | 1130 宽 × 1700 高的**竖框** | 1700 宽 × 1130 高的横框 |
样本里不写 `^PW` / `^LL`:纸张尺寸交给打印机的介质校准,避免把 150×100mm 的横版尺寸锁进指令。
| 指令 | 作用 |
|---|---|
| `^PON` | 正常打印方向,不倒置/镜像,保证贴标时的旋转方向可预期 |
| `^FWR` | **核心**:后续字段内容整体顺时针旋转 90° |
| `^LH35,25` | 原点偏移 35×25 dots(≈3.0×2.1mm),给外框留边距 |
| `^FO10,10^GB1130,1700,3` | 外框 1130×1700 dots ≈ 95.7×143.9mm,正好落在 100×150mm 竖纸内 |
| `^FO420/800,10^GB0,1090,3`、`^FO10,1100^GB1130,0,3` | 两条竖线 + 一条横线;旋转后正好变成横版的两条横线 + 一条竖线分区 |
| `^CF0,45,45` | 45 dots 字体;`^CF` 没有方向参数,文本方向由 `^FW` 决定 |
| `^BC,225,N,N,N,N` | Code128,高 225 dots、不打印解释行。**第一个方向参数留空才会继承 `^FWR`**;写成 `^BCN,...` 条码就不会旋转 |
| `^BY2,2` / `^BY3,2` | 条码模块宽度与宽窄比,按字段密度切换 |
| `^FWN` + `^JUS` | 收尾恢复默认字段方向并保存配置,避免旋转状态影响后续打印任务 |
#### 尺寸换算(300 dpi)
| 项 | dots | mm | 说明 |
|---|---|---|---|
| 纸张 | 1181 × 1772 | 100 × 150 | 由介质校准给出,不写进 ZPL |
| 外框 `^GB1130,1700,3` | 1130 × 1700 | 95.7 × 143.9 | 竖框 |
| 原点 `^LH35,25` + `^FO10,10` | 45 × 35 | 3.8 × 3.0 | 左 / 上边距 |
| 外框右下角 | 1175 × 1735 | 99.5 × 146.9 | 右 / 下仍留约 0.5 / 3.1 mm |
| 逆时针转回 90° | 1700 × 1130 | 143.9 × 95.7 | 落在 150×100mm 横版的可用区 |
#### 效果
| 打印机实际输出(100×150mm 竖纸,文字竖排) | 逆时针转 90° 后的贴标效果(150×100mm 横版) |
|---|---|
|
|
|
左图即打印机真正吐出来的样子:外框竖放、文字与条码顺时针转了 90°,7 个字段区(PKG ID(3S) / DP/N / BOX QTY / Made in China / Vendor ID | Loc ID / Mfg ID / REV A)全部在纸内。把标签逆时针转 90° 贴到箱体上,就是右图的正常横版:上部 PKG ID 长条码、左列 DP/N 与 BOX QTY / Made in China、右列 REV A 与 Vendor / Mfg ID,分区线与内容一一对应,无裁切、无错位。
> ⚠️ 样本文件的 `^FX` 注释里**不要再出现任何 `^` 字符**:部分 ZPL 解析器会把注释里的 `^FWR` / `^GB` 当成指令解析(实测造成约 1.7 万像素偏差)。这也是样本注释全部写成纯文本的原因。
#### ZPL 指令保存在哪里
- 当前模板库 `coolcodetrace_db.cct_zpl_template.elements`(longtext,结构化元素 JSON;老模板用 `{"type":"raw_zpl","content":"^XA…^XZ"}` 存整段原始 ZPL)。库里的 `BC-DELL-01`、`BC-DELL-02` 是迁移后的版本,元素带 `orientation:"R"`(逐元素 `^A0R` / `^BCR`),已不含 `^FWR`;带版本号后缀的 `BC-DELL-01-R` / `BC-DELL-001-C` / `BC-DELL-002-A` / `BC-DELL-02-G` 等历史变体已在演示数据精简时移除,其历史下发 ZPL 仍保存在 `cct_print_log` 中。
- 每次打印**实际下发的完整 ZPL** 保存在 `coolcodetrace_db.cct_print_log.zpl_content`。本样本取自 `BC-DELL-01` 在 2026-06-23 10:41:57 的真实打印记录(该条件下共 7 条,2026-06-17~06-23):
### 案例:两级包装(内箱 → 外箱)与缺料尾箱(`PACK-DEMO-01`,12 装 1 缺料)
#### 场景与三条约束
本案例是**两级包装**:一个工位把内箱码逐个扫进外箱,满 12 个生外箱码。三级包装(内箱 → 中箱 → 外箱)属于另一层关系,本期代码未实现,扩展方案见 [`docs/pack-scan-design.md`](docs/pack-scan-design.md) 第十二节。
相机每读到一个内箱码上报一次,累计到包装规格 12 就生成外箱码、打外箱标。最后一批因原料缺料只有 11 个,要按 11 出标,同时账上还得看得出「这箱原本应该是 12」。
| 约束 | 原因 |
|---|---|
| 外箱码结构不能改 | 下游客户系统按固定规则解析,尾箱、满箱必须共用同一套取号规则 |
| 不能凑数 | 拿空盒或下一批的码补齐,会让箱内实物与码上数量不一致,追溯直接失效 |
| 不能靠「空闲 N 秒」自动封箱 | 误封一箱要整箱返工重贴,空闲只能提示,封箱必须由人或 PLC 显式触发 |
#### 实现:码不动,只动数量字段
同一个外箱模板(`DEMO-COMB` 外箱),渲染时按实际数量替换占位符,版面不变:
| 表单键 | 满箱 12 | 尾箱 11 | 说明 |
|---|---|---|---|
| `Quantity` | 2880 | 2640 | 总 PCS = 箱内数 × 每内箱 240 |
| `BoxQty` | 12 | 11 | 箱内内箱数 |
| `PackQty` | 12 | 12 | 包装规格,用于打印 `11/12` |
| `QuantityText` | `12/12` | `11/12` | 模板里直接写 `{QuantityText}` |
| `IsTail` | `0` | `1` | 需要区分尾箱时用条件元素 |
#### 操作路径(装箱作业页)
1. 「标签打印 → 装箱作业」,选方案 `PACK-DEMO-01`(12 内箱/箱、240 PCS/内箱、外箱标签 `DEMO-COMB`)。
2. 看板每 2 秒轮询一次:进度环显示 `2/12`、还差 10 个、空闲秒数;空闲超过 `idle_prompt_seconds`(演示 30 秒)变黄,提示「如需按实际数量出标请封尾箱」。
3. 装满 12 个时第 12 次扫码直接返回外箱码并下发打印,看板提示「满箱封箱完成:`DEMO…`」。
4. 缺料只剩 11 个:点「尾箱封箱」,实际数量默认取已扫数量,填原因(缺料/生产尾数),确定后按 11 出标,箱记录 `is_tail=1`、`seal_type=1`。
5. 贴错或数错:点「作废本箱」,外箱码失效,箱内内箱码释放可重新装箱。
6. 点「箱明细」:抽屉里是已装内箱码(序号/码/扫描时间)与被拒事件(同箱重读、已装入其他箱、码格式不符)。
> 页面与接口用的都是同一个 `scan` 接口,手工补扫和相机上报没有两条逻辑;区别只是 `eventId` 由前端生成,重发同样安全。
#### 落地文件
| 目的 | 文件 |
|---|---|
| 建表(可重复执行) | [`app-frame/document/mysql/coolcodetrace/cct_pack_schema.sql`](app-frame/document/mysql/coolcodetrace/cct_pack_schema.sql) |
| 演示方案(幂等 upsert) | [`cct_pack_demo.sql`](app-frame/document/mysql/coolcodetrace/cct_pack_demo.sql) |
| 页面与按钮菜单 | [`cct_pack_menu.sql`](app-frame/document/mysql/coolcodetrace/cct_pack_menu.sql) |
| 服务 | `ZR.Service/Cct/PackScanService.cs`(`Scan` / `Close` / `Void` / `Status` / `Cartons`) |
| 页面 | `webui-vue3/src/views/cct/pack/index.vue` |
| 设计与实测 | [`docs/pack-scan-design.md`](docs/pack-scan-design.md) |
#### 实测
- 满箱:第 12 个返回 `isFull=true`、外箱码 `DEMO2611080001`,箱 `status=2`、`actual_qty=12`。
- 尾箱:`close(actualQty=11)` 后 ZPL 里 `QTY:2640 PCS`、`QuantityText=11/12`、`is_tail=1`;重复封箱幂等返回同一码。
- 短装下限:3/12(25%)低于 50% 被拒,`force=true` 才放行。
- 2026-11-09 页面联调:扫 2 个码 → 空闲 51 秒返回封尾箱提示 → 尾箱封箱得到 `DEMO2611090001` → 箱列表/明细一致;测完已清库(箱 0、明细 0,标签 202 / 模板 218 / 日志 7218 不变)。
---
## 🔁 连续打印
打印工作台的「数量」与「份数」组合即可连续打印:一次提交、一次下发,无需重复录入表单。
| 参数 | 取值 | 作用 |
|---|---|---|
| 数量 `quantity` | 1 ~ 9999 | 打印多少张**不同追溯码**的标签;每张单独取流水号、逐张渲染,最后合并成一份 ZPL |
| 份数 `copies` | 1 ~ 99 | 每张标签重复打印的份数,写入 ZPL 的 `^PQ{copies}`,由打印机完成复制 |
| 每箱内箱数 `packageRate` | 1 ~ N | 仅 2S&3S 组合打印时使用,表示一个外箱装多少内箱 |
### 例 1:同一版式连续打印 20 张,每张 2 份
```
数量 = 20,份数 = 2
→ 消耗 20 个流水号(20 个不同追溯码)
→ 生成 20 段标签 ZPL,每段带 ^PQ2
→ 合并为一份 ZPL,一次 TCP 9100 下发
→ 实际出纸 40 张;打印历史追溯码记为 “首码~尾码”
```
接口调用示例:
```jsonc
POST /cct/print/submit
{
"labelId": "BC-SONY-01",
"boxType": "3S",
"clientId": "<打印客户端ID>",
"quantity": 20,
"copies": 2,
"formData": { "PartNo": "TEST-PN", "TraceCode": "TEST0001" }
}
```
返回 `{ "logId": "...", "traceCode": "TEST0001~TEST0020", "quantity": 20, "copies": 2 }`。
### 例 2:2S&3S 内外箱组合连续打印
箱体类型选 `2S&3S` 时,「数量」表示外箱数,「每箱内箱数」表示一个外箱内的内箱数:
```
外箱数量 = 5,每箱内箱数 = 10
外箱 1 → 连续打印 10 个内箱(流水号 0001~0010)→ 打印 1 个外箱(追溯码带内箱区间)
外箱 2 → 连续打印 10 个内箱(流水号 0011~0020)→ 打印 1 个外箱
... 共 5 组
→ 一次下发 55 段标签 ZPL,日志 totalQty = 5 × (10 + 1) = 55
```
外箱标签通过 `InnerStartSerial` / `InnerEndSerial` 占位符取到本箱内箱流水号的起止值;起止值的基数、长度、忽略字符由内箱的追溯码规则(SERIAL 段)决定。
> 🧪 **演示数据**:系统内置组合演示标签 `DEMO-COMB`(内箱 2S + 外箱 3S 两条定义,绑定 `DEMO-COMP-01` 模板与追溯规则),标签打印页选 `DEMO-COMB`、箱体类型选 `2S&3S` 即可实际体验组合预览 / 打印。可用 `cct_demo_comb.sql` 幂等重建。
### 使用要点
- **预览不耗号**:`/cct/print/preview` 只渲染不取流水号,可以放心反复预览
- **提交才耗号**:只有 `/cct/print/submit` 才真正递增流水号
- **断线重打用补打**:连续打印已合并为一份 ZPL 下发,重试请在打印历史点「补打」,补打原样重发原 ZPL,不会再取新号
- **份数走打印机**:份数通过 `^PQ` 交给打印机,不额外生成追溯码,因此份数再多也只消耗「数量」个流水号
---
## 🧩 模板占位符与打印栏位
模板只管「版面长什么样」,具体印什么由**占位符**和**标签字段**对接:模板里写 `{PartNo}`,标签定义里配一个 `field_name = PartNo` 的字段,打印工作台就会多出一个输入框,录入的值在渲染时替换进去。
```
模板元素 content:{PartNo} ←→ 标签字段 field_name:PartNo ←→ 工作台输入框:料号
```
### ZPL 模板里怎么用 `{}` 占位符
在「标签配置 → 模板设计器」选中文本 / 条码 / 二维码元素,在属性面板「内容」里把固定文字和占位符混写即可;「插入字段」下拉可直接追加(内置 `SN`、`TraceCode`、`PartNo`、`Qty`、`BoxNo`… 以及当前模板里已用过的占位符)。
| 写法 | 渲染结果 | 说明 |
|---|---|---|
| `PN: {PartNo}` | `PN: HX-CB-2026A` | 固定文字与占位符可混排,一个元素里能放多个 |
| `{TraceCode}` | `DEMO2611080001` | 引擎内置:追溯码,提交打印时按规则取号 |
| `QRDATA` 或 `{Qrcode}` | 二维码内容 | 整串二维码数据,由「入码」字段按排序拼装(见下) |
| `{PartNoBarCode}` | 与 `{PartNo}` 同值 | 老模板习惯写法,引擎自动去掉 `BarCode` 后缀回退到主字段 |
| `{CustomerName}` | `HAIER SMART HOME` | 占位符名必须是字母开头,只能含字母 / 数字 / 下划线 |
规则要点:
- **字段名只认 ASCII**:匹配正则为 `\{([A-Za-z][A-Za-z0-9_]*)\}`,`{客户料号}`、`{2026}` 这类不会被替换。中文放到字段的「显示名」,模板里用英文键。
- **大小写不敏感**:`{partno}` 与 `{PartNo}` 等价,但建议与字段名写法保持一致,便于排查。
- **没配字段也能跑**:模板里出现、标签里又没定义的 `{Xxx}`,工作台会自动补一个 `input` 栏位(`PrintService.EnsurePlaceholderFields`),中文名取内置词典(`PartNo→料号`、`Qty→数量`、`Dc→日期代码`…),词典没有就直接显示原名。这个补的字段只在内存生效,要改必填 / 控件类型 / 默认值,得自己在标签定义里加。
- **写错占位符不会报错,只会静默变空**:`{PratNo}` 拼错后既对不上字段也没词典,渲染时替换成空字符串,标签上那一块就是空白。保存前用设计器的「预览」看一眼。
- **raw_zpl 模式同样支持**:直接贴整段 ZPL 时,`^FO..^FD{PartNo}..^FS` 里的占位符照样被替换(`ZplRenderEngine.ReplacePlaceholders`),整段 ZPL 里出现多次也只按同一个字段取值。
- **预览里的占位符值**:设计器预览把 `{Xxx}` 统一填成 `SAMPLE`(条件图标按其「条件值」填),专门用来看版式;`{TraceCode}` / `{Qrcode}` 要取号,所以设计器预览为空,工作台预览才会给出预览码(同样不耗号)。
- **AIAG 前缀**:字段填了前缀且「显示」=1,文本里的 `{Field}` 显示成 `前缀+值`;「入码」=1 的字段才进二维码,带前缀的按 `(P)值` 拼接,若整张标签没有任何 `S` 前缀字段,引擎自动在末尾补 `(S)追溯码`。例:`BC-TEKC-16` 四个入码字段无前缀,二维码内容是 `PN1` + `5` + `2026-11-08` + `(S)BC-TEKC-16000100010001`。
- **条件图标不算占位符**:CE / RoHS 这类图标由元素的「条件字段 / 条件值」控制,两者相等才画出来(`DEMO-COMP-01` 用 `EnvFlag`),跟 `{}` 是两套机制。
`DEMO-COMP-01` 里的真实写法可直接对照:
| 元素 | 内容 | 效果 |
|---|---|---|
| text | `PART NO:` 与 `{PartNo}` 两个元素 | 固定标签名与取值分列对齐,改版式不动文字 |
| text | `QTY:` 与 `{Quantity} PCS` | 占位符后面可以跟单位 |
| barcode128 | `{TraceCode}` | 条码内容就是追溯码,无需另存一份 |
| qrcode | `PN:{PartNo} QTY:{Quantity} SN:{TraceCode}` | 结构化 QR 直接混写占位符,比配一堆 AIAG 前缀更直观 |
### 打印页面怎么加栏位
路径:**标签配置 → 标签定义 → 选中标签「编辑」→「字段配置」页签 →「新增字段」**,填完连同「基本信息」一起「提交」。保存后打开「标签打印 → 打印工作台」,选该标签即出现对应输入框(标签与字段没有走 Redis 缓存,保存即刻生效,不用重启)。
| 列 | 填什么 | 影响 |
|---|---|---|
| 字段名 | **必须等于模板里的占位符名**,如 `PartNo` | 渲染时靠它把值填进 `{PartNo}`,写不一致就等于没配 |
| 显示名 | 中文名,如「料号」 | 只影响工作台输入框的标签,与模板无关 |
| 控件类型 | `input` / `date` / `select` / `number` / `textarea` | 决定工作台用什么控件;日期默认 `YYYY-MM-DD` |
| 必填 | 开关 | 必填项不填,预览和打印都会被表单校验拦住 |
| 默认值 | 如 `2026-11-08`、`HAIER SMART HOME` | 打开工作台即预填,演示与批量打印省事 |
| 数据源 | 字典类型(如 `sys_yes_no`)或 JSON 数组 `[{"label":"内箱","value":"2S"}]` | 仅 `select` 使用 |
| AIAG 前缀 | `P` / `Q` / `S` … | 文本显示前缀 + 二维码里的 `(P)值` |
| 入码 | 开关 | 1 = 参与二维码内容拼装,按「排序」拼接 |
| 显示 | 开关 | 目前只控制文本占位符是否附加 AIAG 前缀,**不是**「是否印到标签」的总开关 |
| 适用箱体 | `内箱,外箱`,留空=全部 | 同一标签在 2S&3S 组合打印时,按箱体给不同栏位 |
| 排序 | 数字,小的在前 | 工作台表单顺序,同时决定二维码拼装顺序 |
---
## 🖨️ 配套打印服务 CoolPrintService
本系统负责生成 ZPL 并通过 TCP 9100 下发,**实际打印由配套的 [CoolPrintService](https://gitee.com/afeng124/coolprintservice) 完成**(Windows 桌面程序,部署在连接打印机的电脑上)。
- 支持 **Windows 驱动**(Zebra/佳博等已安装驱动)和 **串口** 两种打印通道
- TCP 9100 接收 ZPL 任务,自动归档,自带 Swagger 管理 API(:5990)
- 同时提供 `POST /api/preview`,把 ZPL 渲染成 PNG —— 打印工作台与设计器的预览图都由后端转发到这里
- 打印工作台的「客户端」下拉框旁有「下载打印服务」直达链接
---
## 🏗️ 技术栈
| 层 | 选型 |
|---|---|
| 后端 | ASP.NET Core 8 / SqlSugar / MySQL 8 / JWT / Redis(CSRedisCore,已启用)/ SignalR |
| 前端 | Vue 3 + Element Plus + Vite + Pinia + ECharts |
| 渲染 | ZplRenderEngine(元素 → ZPL)+ LegacyZplConverter(raw_zpl → 元素) |
| 预览 | 后端代理本机 CoolPrintService,BinaryKits.Zpl.Viewer 渲染 PNG |
| 打印 | TCP 9100 RAW 下发 |
| 数据 | 演示库以完整备份文件交付(私有部署请向作者索取) |
| 运行时 | .NET SDK 10.0+ / Node.js 18+ |
---
## 🧠 Redis 缓存
默认已启用本机 Redis(`127.0.0.1:6379`)。导航菜单、数据字典、系统参数、用户权限、图形验证码及登录短时状态统一走 Redis;写操作通过「业务域版本号 +1」立即失效,不需要遍历删键。所有键以 `cct:v1:` 开头,不会触碰同机其它项目的键。
| 能力 | 做法 |
|---|---|
| 读 | Cache-Aside:命中即返回,未命中回源并回填;per-key 锁防缓存击穿,空值不缓存 |
| 写 | 写库成功 → `INCR` 版本号,旧键逻辑失效并由 TTL 自动回收 |
| 可靠性 | 全键 TTL + 抖动、显式 JSON 序列化、Redis 故障 30 秒冷却降级内存、恢复后自动切回 |
| 验证码 | `RedisDistributedCache` 实现标准 `IDistributedCache`,60 秒过期、校验后一次性删除,支持多实例 |
| 自检 | 启动日志打印缓存后端与验证码存储实现;`GET /monitor/appcache` 查看键数、分组与版本号 |
> 📖 完整设计说明、键规范、失效机制、运维命令与代码阅读顺序见 **[docs/redis-cache-guide.md](docs/redis-cache-guide.md)**。
---
## 📂 目录结构
```
coolcodetrace/
├── app-frame/ # 后端(ZRAdmin 框架改造)
│ ├── ZR.Admin.WebApi/ # WebApi 入口 :5991
│ ├── ZR.Service/Cct/ # 业务服务
│ │ ├── ZplRenderEngine.cs # 元素 → ZPL 渲染
│ │ ├── LegacyZplConverter.cs # raw_zpl → 设计器元素
│ │ ├── CctZplTemplateService.cs# 模板 CRUD + 批量迁移
│ │ ├── PrintService.cs # 工作台/预览/提交/补打
│ │ └── PrintDispatchService.cs # TCP 9100 下发
│ ├── ZR.ServiceCore/ # 框架核心 + Model/Dto
│ ├── ZR.Repository/ # 仓储基类
│ ├── Infrastructure/ # App 静态入口 + DbScoped
│ │ └── Cache/ # CacheKeys / AppCache / RedisServer / RedisDistributedCache
│ ├── document/mysql/coolcodetrace/# cct_schema.sql / cct_menu.sql / cct_demo_case.sql / cct_demo_comb.sql
│ └── CoolCodeTrace.sln
├── webui-vue3/ # 前端 :80,/dev-api 代理 → :5991
│ └── src/
│ ├── api/cct/ # cct 模块 API
│ └── views/cct/
│ ├── print/ # 打印工作台
│ ├── printlog/ # 打印历史
│ ├── sample/ # 示例打印(202 卡片画廊)
│ ├── label/ # 标签定义
│ ├── tracerule/ # 追溯码规则
│ ├── designer/ # 模板设计器(网格标尺画布 + 元素/图层/属性面板)
│ ├── client/ # 打印客户端
│ └── components/ZplPreviewDialog.vue
├── CoolPrintService/ # 本机打印服务 :5990 / TCP 9100
├── docs/ # 文档资源
│ ├── images/ # README 截图 + 标签成品样本
│ ├── samples/ # BC-DELL-01-rotated.zpl(DELL 旋转打印,可直接下发)
│ └── redis-cache-guide.md # Redis 缓存设计与实现笔记
└── README.md
```
---
## 🚀 快速开始
### 前置条件
- .NET SDK 10.0+
- Node.js 18+
- MySQL 5.7+(库名 `coolcodetrace_db`,连接串见 `app-frame/ZR.Admin.WebApi/appsettings.json`,把 `你的数据库服务器IP` 换成实际地址)
- Redis(默认已启用 `127.0.0.1:6379`;`RedisServer:open=0` 或连不上会自动降级为进程内存缓存,详见 [docs/redis-cache-guide.md](docs/redis-cache-guide.md))
### 1. 后端
```bash
cd app-frame
dotnet restore
dotnet build
dotnet run --project ZR.Admin.WebApi/ZR.Admin.WebApi.csproj # 监听 :5991
```
关键配置(`ZR.Admin.WebApi/appsettings.json`):
```jsonc
{
"dbConfigs": [
{ "Conn": "Data Source=数据库IP;Database=coolcodetrace_db;Port=3306;charset=utf8;uid=root;pwd=xxx;SslMode=none;", "DbType": 0, "ConfigId": "0" }
],
// Redis 已启用:open=0 或连不上会自动降级为进程内存缓存,不影响启动
"RedisServer": {
"open": 1,
"Cache": "127.0.0.1:6379,defaultDatabase=0,poolsize=20,ssl=false,writeBuffer=10240",
"Session": "127.0.0.1:6379,defaultDatabase=0,poolsize=20,ssl=false,writeBuffer=10240"
},
"CacheSettings": { "DefaultTtlMinutes": 30, "ConfigTtlMinutes": 30, "DictTtlMinutes": 30, "MenuTtlMinutes": 30, "PermTtlMinutes": 1440 },
"CaptchaOptions": { "ExpirySeconds": 60, "IgnoreCase": true, "StoreageKeyPrefix": "cct:v1:auth:captcha:" },
// 本机打印服务(预览渲染由后端转发,避免浏览器跨域)
"CoolPrintService": { "ApiUrl": "http://127.0.0.1:5990" },
"InitDb": false
}
```
> 先确认本机 Redis 在 `127.0.0.1:6379` 监听;没启动也不会报错,后端会在启动日志里注明已降级为内存缓存。缓存键、失效机制与运维命令见 [docs/redis-cache-guide.md](docs/redis-cache-guide.md)。
### 2. 前端
```bash
cd webui-vue3
npm install
npm run dev # http://localhost,/dev-api → :5991
npm run build # 生产产物 dist/
```
### 3. 登录
- 默认账号:`admin` / `123456`
- 验证码开关 `captchaOnOff` 已关闭,`uuid` 传空即可
### 4. 路由表
| 路径 | 菜单 | 功能 |
|---|---|---|
| `/index` | — | Dashboard |
| `/cctprint/sample` | 标签打印 → 示例打印 | 202 标签卡片画廊 |
| `/cctprint/print` | 标签打印 → 打印工作台 | 选标签 → 填表 → 预览 → 打印 |
| `/cctprint/printlog` | 标签打印 → 打印历史 | 按标签 / 追溯码 / 时间 / 工厂 / 产线 / 工序 / 工位检索,导出 / 补打 / 查看 ZPL |
| `/cctconf/label` | 标签配置 → 标签定义 | CRUD + 模板绑定 |
| `/cctconf/tracerule` | 标签配置 → 追溯码规则 | CONST / SERIAL 段管理 |
| `/cctconf/designer` | 标签配置 → 模板设计器 | 拖放 / 缩放 / 吸附 / 图层 / 撤销重做 + 分组属性 + 模板预览 |
| `/cctdev/client` | 设备管理 → 打印客户端 | 心跳 / 状态 |
| `/cctdev/serialno` | 设备管理 → 流水号管理 | 当前值 / 最大值 |
---
## 🖨️ 打印链路
```
预览:
浏览器 [POST /cct/print/preview-image] → 后端代理 → CoolPrintService :5990 → PNG
打印:
浏览器 [POST /cct/print/submit]
→ PrintController.Submit
→ PrintService.Submit(校验 + 取流水号 + 写日志)
→ ZplRenderEngine.Render(元素 → ZPL)
→ PrintDispatchService.Send(TCP 9100)
→ CoolPrintService / Zebra / Honeywell 打印机
```
### 无打印机时自测
- 用 CoolPrintService 的 `:5990/api/preview` 或 [labelary.com/viewer.html](https://labelary.com/viewer.html) 查看 ZPL 渲染效果
- 或本地监听 9100 抓包:
```powershell
$listener = [System.Net.Sockets.TcpListener]::new([System.Net.IPAddress]::Any, 9100)
$listener.Start()
$client = $listener.AcceptTcpClient()
$reader = New-Object System.IO.StreamReader($client.GetStream())
Write-Host $reader.ReadToEnd()
$reader.Close(); $listener.Stop()
```
---
## 🧪 已验证
- 老功能:登录、菜单/路由、RBAC、用户/角色/字典接口
- 新功能:Dashboard、标签定义、追溯码规则、打印工作台(预览/提交/历史)、示例打印、工厂建模
- 老模板迁移:转换后的模板预览图与原始模板 SHA256 全部一致
- 设计器:模板下拉显示名称,画布元素可选中/拖拽/缩放/对齐,预览与打印输出一致;29 项交互 + 15 项保存校验用例通过,图标 `size`、图形 `thickness` 单位、模板名称保存等字段错配已修复
- 特殊标签样本:DELL `^FWR` 旋转打印样本与历史下发 ZPL 逐像素一致(0 差异),`^FWR` / `^FWN` 外框边界一致
- 演示数据精简:删除 175 个带版本号模板、193 个带版本号标签(另清理 2 条 `TEST-COMB` 测试残留)及 774 条字段配置;清理后 218 模板 / 7218 打印日志,标签字段与模板绑定悬空引用均为 0。随后补入组合演示标签 `DEMO-COMB`(内箱 + 外箱各 1 条、18 个表单字段),当前 202 标签 / 828 字段,组合工作台与预览 12/12 实测通过
- 打印历史四维过滤:工厂 / 产线 / 工序 / 工位精确匹配(3 条)与「未指定(迁移历史)」空值匹配(7215 条)均验证通过,导出带条件;并修正打印时间、打印结果、打印人三列的字段绑定与结果字典语义
- Redis 缓存:菜单 / 字典 / 系统参数 / 用户权限 / 验证码全部落 Redis,写操作版本号失效、缓存一次性消费、Redis 不可达自动降级均实测通过;专项 35/35,基线接口与 33 页面 UI 无回归
- 模板占位符:`{PartNo}` 大小写不敏感、`{PartNoBarCode}` 回退主字段、未知占位符静默为空均实测符合预期;`{QRCode}` / `QRDATA` 按「入码」字段排序拼装(`BC-TEKC-16` 实测 `PN152026-11-08(S)BC-TEKC-16000100010001`);`BC-SONY-01` 模板里未配字段的 12 个占位符由工作台自动补成栏位(库内 4 条 → 返回 16 条),字段名与占位符不一致时该位置渲染为空(同标签实测)
---
## ☕ 捐赠支持和业务合作
如果这个项目对你有帮助,欢迎捐赠一点买菜的零钱,谢谢! 另外申明: **承接标签定制业务,介绍业务可得佣金**(微信咨询请加wx:6857740733) 。
> 收款码是我夫人的,她不相信我的项目能挣到钱 😄