# CHANGELOG.md

## 2026-07-23 · v1.6.34（对接说明2：aid + product_name 三段）

- 拉取地址必须含 `?aid=`；缺 aid 拦截并提示
- `product_name`：换行分商品，每行 `材质,品类,克重`（英文逗号）；禁止只按逗号拆商品
- 打印数据生成 `products_text` / 格式化 `product_name`；首行映射 caizhi/guige/weight
- 内置文档 `ERP_PrintLabel.md`；对接说明页同步

## 2026-07-23 · v1.6.33（恢复服务页对接地址 + 版本赶超本机）

- 通道行：选择打印机 | 绑定状态（绿字 + API 输入框）| 绑定/获取数据/测试/导入/编辑
- 线上版本升至 1.6.33（高于本机常见的 1.6.32），检查更新可正常检出

## 2026-07-23 · v1.6.30（恢复服务页对接地址框）

- 通道行恢复截图排版：选择打印机 | 绑定状态（绿字 + API 输入框）| 绑定/获取数据/测试/导入模版/编辑模版
- 对接地址单框可填 ERP 完整网址；绑完优先显示 ERP 地址

## 2026-07-23 · v1.6.29（多机设计三期 + AI 知识库）

- 本机托管 `/designer`（同源免 CORS）；失败再回落线上 designer
- 一键自检：机→通道→模版→Profile 矩阵；纸张不一致；「同步纸张」
- 通道「另存专用」模版；换模版可提示同步纸张
- 开发文档：补 CODEMAP / DESIGN；manifest 升至 1.6.29；`deploy-dev-docs` 同步源码快照

## 2026-07-23 · v1.6.28（多机在线设计二期）

- designer 选通道/按机预览；保存绑当前或另存；PATCH 通道与试打 API；桌面「在线设计」入口

## 2026-07-23 · v1.6.27（多机模版一期）

- 通道模版下拉；「挂到通道」确认范围；禁止静默全挂；试打/设计器按通道机

## 2026-07-22 · v1.6.26（服务页心智收敛）

- 本机路径/ERP 地址分栏；一键自检；挂通道；别名补全；帮助去空壳

## 2026-07-22 · v1.6.25（设计器拖拽）

- 预览点选/拖拽/方向键、字体族、图层上移下移

## 2026-07-22 · v1.6.24（内置编辑主路径）

- 中文 `{{占位符}}`；标签模版页主路径；「导入古法标签并编辑」

## 2026-07-22 · v1.6.23（服务页对齐）

- 通道行对齐；绿色绑定状态单行缩短（Tooltip 详信息）

## 2026-07-22 · v1.6.22（修复宿主更新 ZIP 截断）

- 根因：host 包下载不完整仍去解压 →「找不到中央目录结尾记录」
- 下载后校验 Content-Length / 清单 Size / SHA256 / ZIP 可打开；拒绝 HTML 伪包
- 更新脚本解压前预检；超时放宽至 15 分钟

## 2026-07-22 · v1.6.21（服务页恢复对接地址输入）

- 恢复对接地址输入框；排版：打印机 + 绿色状态 + 地址框 + 右侧按钮

## 2026-07-22 · v1.6.20（服务页通道排版）

- 「服务」通道区：表头「选择打印机 / 绑定状态」+ 外框
- 每行：勾选 | 打印机下拉 | 绿色绑定状态（无空输入框）| 右侧横排五按钮

## 2026-07-22 · v1.6.19（P0 闭环加固）

- ERP 去重：入队后 pending，仅 spooled/succeeded 才永久去重；失败/取消可重打；指纹落盘 `erp-dedup.json`
- 挂模版：通道「编辑模版」只挂当前通道；「设为打印模版」才全挂；默认智能不误伤多机
- MaxRetry：自定义区与「工具→选项」同步为同一真相源

## 2026-07-22 · v1.6.18（服务页去掉对接地址框）

- API配置去掉顶部提示横幅与「对接地址」输入框
- 原位置改为完整「绑定状态」提示（自动换行，模版名不再截断）
- ERP 地址在「ERP拉取」页配置；绑定/获取数据自动沿用

## 2026-07-22 · v1.6.17（关闭说明进帮助菜单）

- 去掉主窗口顶部关闭说明横幅
- 菜单「帮助 → 关闭说明」查看托盘退出说明

## 2026-07-22 · v1.6.16（文字自动换行完整显示）

- 文字默认自动换行，取消省略号截断
- 「高度随内容」：按宽度测高并撑开，下方元素自动下移
- 可视化编辑增加「自动换行 / 高度随内容」选项；元素列表完整显示内容

## 2026-07-22 · v1.6.15（修复脱机误拦打印）

- 根因：HPRT 等 USB 机常被 Windows 标「脱机使用」，任务入队后全部失败（尝试 3 次）
- 打印前自动取消 WorkOffline；驱动仍有效则允许提交
- 离线时不入队、不去重，恢复在线后 ERP 轮询可自动出纸

## 2026-07-22 · v1.6.14（关闭进托盘 + 顶部说明）

- 主窗口顶部增加关闭说明：点「×」后进右下角托盘，后台继续跑 ERP/打印
- 真正退出：托盘图标右键 →【退出】，或菜单「工具 → 退出」
- API 配置页顶部同步提示

## 2026-07-22 · v1.6.13（选中模版即生效）

- 修复：仅点选模版不会改通道 TemplateId，导致保存后仍打旧模版
- 「保存并设为打印模版」立即持久化并挂到所有绑定通道；「保存并重启API」同样以当前选中模版为准
- 模版页显示「当前打印模版」；重启后默认选中通道正在用的模版，不再总跳到列表第一项

## 2026-07-22 · v1.6.12（预览=试打 WYSIWYG）

- 试打改用模版 SampleData（与预览「张三」等一致），不再用「测试客户」假数据
- 预览强制对齐绑定打印机 DPI/偏移/旋转，与 API 光栅出纸同一套参数
- PrintRaster：匹配驱动纸张 + 整页铺满位图，避免 70×50 模版在驱动纸上被裁切
- 保存模版后同步打印机 Profile 纸张尺寸；名称中的旧 60×40 自动改为实际尺寸

## 2026-07-22 · v1.6.11（按设定模版出纸闭环）

- 打印前始终读取 store 最新通道模版；ERP 日志显示实际模版 ID/修订号
- JSON 内容误标为 text 时自动按 JSON 光栅打印，避免把排版 JSON 当纯文本打出
- 可视化「保存并试打」；保存后强制挂到绑定通道并提示是否试打
- 保存/适配画布时自动拉满外边框；防止改 70×50 后仍按旧 60×40 边框出纸
- 通道行显示当前模版名；提交模版编辑时内容像 JSON 则强制 Type=json

## 2026-07-22 · v1.6.10（每条文字独立字号）

- 可视化编辑：仅选中 `[text]` 时显示「文字样式」；每条文字可单独设字号/粗体/对齐
- 字号支持 +/-、Enter/失焦即时应用、8–24 快捷预设；左侧列表显示「字号N」
- 非文字元素不再误改字号字段；预览与 JSON 同步写入各元素 `fontSizePt`

## 2026-07-22 · v1.6.9（模版保存修复 + 按设定模版打印）

- 保存时自动把超界元素裁进画布（如边框误设 70×48 超出 60×40）；新增「适配画布」按钮
- ERP 拉取优先使用通道已绑定模版，不再强制覆盖为 `erp-label-json`
- 可视化「保存到模版」立即持久化，并挂到已绑定/ERP 通道，保证按该排版出纸

## 2026-07-22 · v1.6.8（模版可视化编辑）

- 新增「模版可视化编辑」窗口：标签宽高(mm)、DPI、偏移 OX/OY、旋转 0/90/180/270 实时预览
- 内容排版：添加/删除文字、条码、二维码、线、框；编辑坐标、宽高、内容占位符、字号、粗体、对齐
- 自动带入当前绑定打印机的 Profile 校准参数做预览；文本模版可一键转为 JSON 标签
- 「打印模版」页与通道「编辑模版」入口直达可视化编辑；新建默认打开 JSON 标签设计器

## 2026-07-22 · v1.6.7（修复「绑定像没成功」）

- 绑定 ERP 地址后**不再把输入框改成 127.0.0.1**，继续显示 `https://ylerp.py99999.com/PrintLabel/index`
- 行内增加绿色状态：「已绑定 打印机 · ERP拉取已启用」；按钮变为「已绑定」
- 绑定后校验配置是否真正写入；失败会明确提示
- 左侧勾选框说明：仅用于删除选中，不是绑定状态
- 已实测 ERP 接口返回 `{"state":"success","info":null}` 可访问

## 2026-07-22 · v1.6.6（服务页绑定即拉 ERP 数据）

- 「服务」页绑定 `PrintLabel/index` 或粘贴 `https://ylerp.py99999.com/PrintLabel/index` 时，自动启用 ERP 拉取并关联本机通道
- 通道行新增「获取数据」：立即 GET ERP、展示响应 JSON，并写入「数据查看」
- 「数据查看」合并 API 推送与 ERP 拉取记录；支持「立即获取ERP数据」
- 「ERP拉取」页点绑定默认启用轮询（不再因未勾选导致“绑了但不拉”）

## 2026-07-22 · v1.6.5（ERP 拉取生产化）

- 按 `ts`（无 ts 则按客户/电话/地址/商品）去重，避免 ERP 未清空时重复出纸；手动「立即拉取」不去重
- 空轮询不再刷屏日志；连续失败计入状态；`GetStatus()` 供底栏与诊断
- 主界面底栏显示 `ERP: 轮询中/未启用/连续失败/刚出纸`；快捷入口「ERP拉取」
- 故障排除诊断增加 ERP 拉取区块（地址、最近出纸、连续失败）
- 内置 `erp-label-json` 60×40mm JSON 标签（客户/电话/地址/商品），绑定 ERP 时优先使用

## 2026-07-21 · v1.6.4（ERP 打印标签拉取对接）

- 按《打印标签对接说明》实现 ERP 拉取：定时 `GET {ERP}/PrintLabel/index`，`state=success` 且 `info≠null` 时打一张标签
- API配置新增「ERP拉取」页：填写 `https://ylerp.py99999.com/PrintLabel/index`、绑定本机通道、启用轮询、立即拉取一次、拉取日志
- 内置 `erp-label` 文本模版（customer_name / phone / address / product_name）；商品名整段打印不按逗号拆单
- 纠正误区：ERP 地址不要填进「服务」页本机 API（127.0.0.1）；本机地址仅用于网页推送

## 2026-07-21 · v1.6.3（绑定即时生效 + 请求数据查看）

- 「绑定」按钮即时持久化通道（`UpsertChannel`），端口/Token 未变时无需再点「保存并重启API」即可调用
- 新增 API 请求数据记录：每次 print / dry-run / preview / 测试 的请求 JSON、通道、打印机、HTTP 状态、结果码、任务 ID、来源与 IP（最近 200 条，落盘 `api-requests.json`）
- API配置窗口新增「数据查看」页：列表 + 完整 JSON 详情、刷新、清空
- 新增 `GET /api/requests`（?limit=）、`GET /api/requests/{id}`、`DELETE /api/requests`

## 2026-07-21 · v1.6.2（绑定诊断 + 入口打通）

- 「帮助 → 故障排除」改为绑定诊断窗口：失效通道 / 缺 Profile / 无通道 Profile / 队列；支持一键修复
- 「打印机配置」改为打开校准向导（驱动属性仍在「驱动设置」）
- `PaperDirection` 在旋转为 0 时可映射到 90/270；显式 `RotationDegrees` 优先
- 打印任务支持「仅显示当前打印机任务」过滤

## 2026-07-21 · v1.6.1（WPF 校准向导）

- 新增「校准打印机」窗口：偏移/DPI/旋转/标签尺寸预览、试打、保存
- 主界面底栏显示校准参数与组件队列（执行中/等待）；快捷入口「校准」
- 十字校准模板抽为共用 `CalibrationPattern`，API 与桌面共用

## 2026-07-21 · v1.6.0（多打印机 Profile 校准 + 队列可视化）

- 新增 `GET/PUT /api/profiles`、`POST /api/profiles/{device}/calibrate`：偏移/DPI/旋转预览与试打，可选保存
- 新增 `GET /api/queues`：按打印机汇总排队/执行中/近期成败（同机串行、跨机并行）
- `/api/diagnostics` 增加 Profile 数量、缺 Profile 通道、无通道 Profile、队列快照
- 添加打印机窗口支持偏移与旋转；Profile 读写统一规范化与克隆

## 2026-07-21 · v1.5.3（模板旋转 + 打印机方向 Profile）

- 渲染链支持 0/90/180/270 旋转；打印机 Profile 增加 `rotationDegrees`，预览与打印共用同一方向
- `POST /api/templates/preview` 支持 `rotationDegrees`；设计器提供预览旋转选项
- 非法角度会被拒绝，物理宽高随旋转交换

## 2026-07-21 · v1.5.2（模板图片安全 + Table/Repeat）

- Image 元素仅允许 `data:image/*;base64` 或 `%LocalAppData%\PrintComponent\templates\assets` 相对路径
- 拒绝绝对路径、盘符路径与 `..` 目录穿越；base64 解码后限制 ≤ 512KB
- 校验阶段即可发现非法图片来源；补充相关回归测试
- 修复 WPF「保存并重启 API」绕过 revision 历史的问题；整体配置保存和单模板保存统一生成版本快照
- 新增 `PUT /api/templates/{id}`；网页设计器支持按模板 ID 加载、保存、查看历史 revision 与回滚
- JSON 模板新增 `table` / `repeat` 和 `collections` 明细集合；支持行高、最大行数及 clip/error 溢出策略
- 网页设计器可添加 Table/Repeat，并编辑 dataSource、行参数、columns/children 结构

## 2026-07-21 · v1.5.1（可视化模板设计 + 宿主更新加固）

- 网页设计器升级为 mm 画布，支持添加、选择和拖动 Text、Barcode、QR、Image、Line、Rect
- 提供元素坐标、尺寸、内容、字号、粗体和对齐属性编辑，支持 JSON 双向编辑与导出
- 新增 `POST /api/templates/preview`，编辑中的模板无需保存或绑定通道即可按指定 DPI 生成 PNG
- capabilities 增加 `directTemplatePreview` 能力标识
- 宿主更新器在覆盖前结束安装目录内残留进程；单文件复制最多重试 20 次，占用文件先改名再替换
- 下载更新包时若 `update-packages` 旧文件被占用，自动改用唯一文件名，避免下载失败

## 2026-07-21 · v1.5.0（作业闭环与模板扩展）

- 作业关联 Windows Spooler JobId/状态；支持 `POST /api/jobs/{id}/cancel` 与 `/reprint`，并记录事件日志
- 新增 `/api/capabilities`、`/api/diagnostics`、`POST /api/printers/{name}/probe`；兼容 `/api/v1/*` 别名
- JSON 模板新增 QR、Line、Image；文本支持对齐；模板 revision 历史与 rollback
- 提供网页 JSON 设计器 `dev/designer.html`（校验 + 通道 PNG 预览）
- 继续兼容旧文本模板；HTML 模板仍禁止静默打印

## 未发布 · v1.4.0（JSON 标签渲染闭环）

- 新增版本化 `TemplateDefinition`（schemaVersion / revision / mm 画布 / fields / sampleData / elements）
- 首批支持 Text、Code 128 Barcode、Rect 元素，提供元素越界、必填字段和条码字符校验
- 新增 `POST /api/templates/validate`；JSON 模板 dry-run 返回结构化校验结果
- JSON 模板 preview 生成 PNG 并返回 base64、像素尺寸和 DPI
- 正式打印与 PNG 预览共用 GDI Raster 渲染器，按毫米物理尺寸输出
- 打印机档案增加 profileId、纸张尺寸与 X/Y 偏移；DPI 和偏移接入渲染链
- 内置 `label-json-demo` 50×30mm 示例；旧文本模板继续兼容，HTML 模板不再被静默当文本打印
- 配置 schema 升到 v3，`api-config.json` 改为临时文件写入后原子替换

## 2026-07-21 · v1.3.2（作业持久化与 API 详情）

- 打印作业写入 `%LocalAppData%\PrintComponent\print-jobs.json`，重启后仍可通过 `GET /api/jobs` 查询；未完成作业标记为「已中断」且不自动重发
- 新增 `GET /api/channels/{id}`、`GET /api/templates/{id}`（含 `{{placeholders}}` 字段列表）
- 新增 `POST /api/print/{channel}/dry-run`（只解析不打印）、`POST /api/print/{channel}/preview`（写入预览目录）
- 添加打印机 / 一键匹配后可一键生成 API 通道并写入 `api-config.json`
- 合并此前安全热修复与真实异步作业链（202 / jobId / Idempotency-Key）

## 未发布 · 安全热修复

- 修复 `POST /api/printers` 等路径可能被 `/api/print` 前缀误判为打印请求
- Token 改为仅允许 `X-Print-Token` Header，禁止空 Token 与 URL Query Token，并使用恒定时间比较
- CORS 默认改为站点精确 Origin 白名单；补浏览器 Private Network Access 预检响应
- 默认禁止请求绕过通道直接覆盖打印机或模版；请求体限制为 1 MB；API 并发限制为 8
- API 内部异常不再直接回传；配置升级到 schema v2
- 更新包缺少 SHA256 时拒绝安装；机群读取接口增加管理 Token
- 心跳 machineId 增加格式校验，避免路径穿越和无限字段
- 移除部署脚本及源码快照中的明文 SSH 密码回退
- 新增 xUnit 回归测试项目，覆盖路由、Token、Origin、模版替换和 SHA256 校验
- API 打印改为真实异步作业链：先入队再由 Printing 模块调用驱动，不再“先直打、后插入假任务”
- `POST /api/print/{channel}` 返回 HTTP 202 + `jobId`；新增 `GET /api/jobs`、`GET /api/jobs/{jobId}`
- 支持 `Idempotency-Key` 防止网页重试重复出纸；不同打印机可并行、同一打印机串行
- 驱动调用发生异常后不自动重发，避免“已入 Spooler 但返回异常”导致重复标签
- 主界面任务表增加尝试次数和错误详情；回归测试覆盖路由、Token、Origin、模版、作业幂等与持久化

## 2026-07-21 · v1.3.1（打印机状态）

- 「打印机 → 刷新打印机列表」点击后强制重扫，并弹窗汇总：本机打印机总数、在线数、离线/不可用数
- 弹窗逐台列出名称、连接状态（在线/离线/已停止/正在打印等）、端口、是否默认
- 顶部打印机标签同步显示在线/离线状态；扫描放到后台线程，避免卡顿
- WMI 查询补充 `WorkOffline`/`PrinterStatus`，`PrinterInfoDto` 新增 `ConnectionStatus`
- 下载页安装入口改为真正的安装程序 `PrintComponent-Setup.exe`

## 2026-07-21 · v1.3.0（性能）

- 打印机枚举改为一次性 WMI 查询 + 5 秒缓存，消除“每台打印机各扫一次 WMI”的开销
- 底栏状态 2 秒定时刷新改到后台线程，避免 UI 卡顿
- 启动时打印机枚举移到窗口显示后后台预热，开启更快
- 打印机增删/一键匹配/手动刷新时主动失效缓存，保证即时
- 模块与宿主版本统一到 1.3.0，装整包后不再误报模块可更新

## 2026-07-21 · v1.2.0

- **宿主自更新**：更新清单新增 `host` 主程序完整包
- 客户端下载并校验 host 包后，退出主程序、覆盖安装目录并自动重启
- 安装在受保护目录时自动请求管理员权限
- 更新失败写入 `%LocalAppData%\PrintComponent\update-staging\host-update.log`，并尝试恢复启动旧程序
- 修复完整安装覆盖后 host 版本登记不刷新的问题
- **升级说明：v1.1.0 及更早版本需最后手工安装一次 v1.2.0；从 v1.2.0 起主界面可在线更新**

## 2026-07-21 · v1.1.0

- API配置「服务」页每行前加**勾选框**，底部「删除选中」可勾选删除通道
- 通道行控件整体缩小，排版更紧凑
- 版本号提升到 1.1.0（标题栏 + 更新清单同步）
- 重新发布完整安装包与更新中心模块

## 2026-07-20

### API 配置（多打印机通道）

- 菜单增加 **API配置**
- 「服务」页按行绑定：打印机 + API 地址 + 绑定/测试/导入模版/编辑模版
- 本机服务 `http://127.0.0.1:17891`，支持 `POST /api/print/{channel}`
- 配置持久化：`%LocalAppData%\PrintComponent\api-config.json`

### 此前已具备

- WPF 宿主 + printing / labelmatrix / customarea 模块
- 更新中心部署：`/opt/print-component-update`，systemd `print-update`
- 外网更新：`https://py99999.com/print-update`
- 下载页：`https://py99999.com/print-component/`
- LABEL MATRIX 多格式导入；打印机自动匹配（汉印/Godex 等）；测试打印

## 文档目录上线

- 本目录 `https://py99999.com/print-component/dev/` 提供 AI/开发者可读说明与源码快照