# 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 指令实现的,见下文「特殊标签实现举例」。 --- ## 🚀 推荐使用流程 **① 示例打印挑标签**:进入「标签打印 → 示例打印」,按箱体类型或编码筛出目标标签,点「预览」先看效果。 ![示例打印](docs/images/screenshot-sample.png) **② 打印工作台填表并预览**:选标签后填写料号、追溯码等字段,点「预览」即可看到真实 ZPL 渲染出的标签图(与打印下发的是同一份 ZPL,不会消耗流水号)。 ![打印工作台预览](docs/images/screenshot-print.png) **③ 提交打印并追溯**:确认无误后提交,打印任务经 TCP 9100 下发;随后在「打印历史」按标签编码 / 追溯码 / 打印时间,并可叠加工厂 / 产线 / 工序 / 工位四级联动检索,失败或需要重打时点「补打」。 ![打印历史](docs/images/screenshot-printlog.png) > 打印历史里的工厂 / 产线 / 工序 / 工位是打印时写入的快照,四个下拉按工厂建模档案级联联动,并可与标签编码、追溯码、打印时间组合,列表与导出使用同一套条件,补打按单条日志原样重发。早期从老系统迁移的历史未记录这四项,可在下拉中选「未指定(迁移历史)」单独筛出(当前 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` 等老模板字段。越界元素会高亮并在保存前确认,未保存修改在切换模板或离开页面时会拦截提醒。 ![模板设计器](docs/images/screenshot-designer.png) --- ## 📸 界面总览 | 示例打印 | 打印工作台(预览) | |---|---| | ![示例打印](docs/images/screenshot-sample.png) | ![打印工作台](docs/images/screenshot-print.png) | | 打印历史 | 本机打印服务 | |---|---| | ![打印历史](docs/images/screenshot-printlog.png) | ![CoolPrintService](docs/images/coolprintservice-ui.png) | --- ## 🧪 综合演示案例:工厂外箱出货标签 系统内置一套完整的演示数据,覆盖「模板设计器 → 标签定义 → 追溯码规则 → 打印预览」全链路,可直接用于验收或培训演示。案例取自**工厂外箱出货/装箱追溯**场景,字段结构参照真实客户外箱标签(客户、料号、订单号、数量、箱号、供应商等),不再使用消费电子成品示例。 - 模板 `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` | 打印工作台(预览) | 标签成品 | |---|---| | ![综合演示标签-工作台](docs/images/demo-label-workbench.png) | ![综合演示标签-预览](docs/images/demo-label-preview.png) | 使用方式:进入「标签打印 → 打印工作台」,选择「综合演示标签(外箱出货)」,字段已预填,点「打印预览」即可复现上图;预览不消耗流水号、不写打印日志。演示数据可用幂等脚本一键重建(见「快速开始 → 数据库」)。 --- ## 🧷 特殊标签实现举例 产线上常碰到「成品标签尺寸 ≠ 现场纸张尺寸」「标签要横贴、纸却是竖的」这类非常规需求。这类问题不必重画版式、也不必换纸,在 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 横版) | |---|---| | DELL 旋转打印输出 | DELL 旋转标签阅读视图 | 左图即打印机真正吐出来的样子:外框竖放、文字与条码顺时针转了 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) 。 > 收款码是我夫人的,她不相信我的项目能挣到钱 😄

微信支付

--- ## 📝 License MIT