zianxin/desktop-plugin
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
34 Commits 1 Branch 0 Tags
master
Commit Graph
22 Commits
Author SHA1 Message Date
dzc 1cd36f9754 11 2026-09-28 10:44:47 +08:00
dzc 7897e77c52 版本号 2026-09-23 18:45:57 +08:00
dzc 6a9dbf9080 11 2026-09-23 18:11:35 +08:00
dzc eaec48a95b feat:卡片打印机 2026-09-23 16:49:42 +08:00
dzc 726210edcb feat: 本地日志文件系统 + 修复双击打不开/向导完成无反应 
用户实测两个问题（先装好驱动的机器）：
1. 双击 App 图标不一定能打开——根因 single_instance：唤醒端口 38210 被
   残留占用（上次异常退出/TIME_WAIT）时，connect 无应答仍返回 false →
   main 直接 exit(0)。修复：端口被占但无应答判定为残留占用，照常启动
   （仅唤醒功能降级，FileLog 留痕）；有应答才作为第二实例退出。
2. 向导第三步点"完成"没反应——根因 _finish 只有 finally 没有 catch：
   Autostart/UrlScheme(reg 三连)/FirstRun 任一抛异常被静默吞，Navigator.pop
   永不执行=对话框锁死。修复：每步独立 try-catch + 分步日志，成败都关闭
   向导，失败汇总 SnackBar 提示"详见运行日志"。

本地日志文件系统（用户要求：仔细记录、可发回分析、定时删除）：
- lib/utils/file_log.dart：按天滚动 app-YYYYMMDD.log、单文件 5MB 轮转加
  序号、启动清理 7 天前旧文件（按文件名日期判定）；全同步追加写（低频
  日志，保证异常退出前落盘）；目录 mac ~/Library/Logs/zax-desktop-plugin/
  win %APPDATA%\zax-desktop-plugin\logs\（不引第三方依赖）
- AgentLog.write 挂文件输出（一处改动覆盖全部 22 个现有调用点）；
  main.dart FileLog.init 提到最前，bootWarning/startError 全部落日志，
  启动横幅记录平台/exe 路径/参数
- pavo isolate 的 [pavo-diag] 诊断日志传日志路径（纯数据，isolate 安全）
  直接写文件——GUI 模式下 isolate stdout 本来就丢
- 插件页技术详情加"打开日志文件夹"按钮（Explorer/Finder 直达，用户打包
  app-*.log 发回分析）

19 个测试全过、analyze 零问题。
 2026-09-22 15:09:24 +08:00
dzc 98df601f7b fix: main 启动链路全防御——runApp 前异常不再导致白屏窗口 
用户实测：安装包在开发机一切正常，其他电脑白屏（产物完整、开发机可跑）。
结构性隐患：runApp 之前的 windowManager/单实例/scheme 注册/托盘任一步在
目标机环境差异下抛异常，Dart 永远不会 runApp（窗口由原生已创建）= 白屏，
开发机顺利复现不了。全部步骤 try-catch：非关键步骤（scheme/托盘）失败仅记
日志不阻断；关键失败聚合为 bootWarning 在界面错误视图中显示。
 2026-09-21 19:05:06 +08:00
dzc 62909609d1 fix(windows): 枚举解码误判 UTF-16 为 UTF-8 导致设备路径碎片化——0x80 全假象 
用户 Windows 无驱动实测日志破案：PavoApiW_x64 枚举成功（size=256），缓冲是
UTF-16LE 的裸 USB 设备路径（\\?\usb#vid_0d16&pid_0309#serial#{guid}），
但 printableRatio 把 \0 计为可打印字符，UTF-8 误判通过 → 路径被 \0 拆成
单字符碎片（first='\'）→ CheckPrinterStatus/PrintOneCard 全部 0x80——
此前所有"离线"均为碎片名所致，设备与通信从未真正尝试过。

结论反转：**Windows 免驱动成立且必须免驱动**——PavoApi 直连裸 USB 设备
（GUID_DEVINTERFACE_USB_DEVICE）；装 HiTi 驱动反而接管 USB 接口导致枚举为空
（用户实测：装驱动前枚举到、装后 size=0、卸载后又枚举到）。

修复：
- decodeAuto 增加 UTF-16LE 特征判定（奇数位字节全零）优先于比例启发；
  新增守护测试（设备路径形态整串不碎片化）
- 向导 Windows 分支反转：不再提供驱动安装（mac only），文案明确
  "SDK 直连无需驱动；已装 HiTi 驱动请卸载（驱动占用 USB 接口导致无法直连）"
 2026-09-21 17:49:15 +08:00
dzc 0fea65018b chore: Pavo 枚举链路加 [pavo-diag] 诊断日志（Windows 枚举空问题定位） 
用户 Windows 实测：驱动装好后（cs2xxhcd.inf 入库、安装器触发过真实打印、
打印机本体正常——同一台机器 mac 全通）枚举反而返回空（"打印机未连接"），
且装驱动前能枚举到（status=0x80）——枚举走的设备通道在驱动绑定前后变化。

对枚举内部加 stdout 诊断：两段式返回码、原始缓冲前 96 字节 hex、
解码与拆分结果（flutter run 控制台可见），下次运行即可区分
"DLL 层失败(ret/size)"还是"解码拆分层问题"。
 2026-09-21 17:18:02 +08:00
dzc d1c34cb833 fix(向导): Windows 第 2 步"已连接"误报——online 不等于设备可用 
Pavo 后端的 online 只要枚举到打印机就为 true（与 C# 版语义一致），
status 可能同时是 0x80 离线；向导 ready 原判定只看 online，掩盖了
"打印机已断开连接或已关机"的真实状态（管理端如实显示，App 却说已连接，
用户实测被误导）。改为 status 为就绪/打印中才算通过，离线等状态走
badText 如实显示 statusText。
 2026-09-21 16:58:16 +08:00
dzc 9ece6cc294 fix(windows): 驱动安装假成功——InstallShield 壳提前退出骗过 -Wait，改 pnputil 实时校验 
用户实测：一键安装日志显示 12 秒"装完"但打印机仍离线。根因：HiTi 的
Setup64.exe 是自解压壳（InstallShield 类），Start-Process -Wait 等的是壳进程，
内层安装向导未真正完成即返回；且旧的注册表标记机制把这次假安装记成了"已装"。

修复：
- 安装流程尾部增加 pnputil /enum-drivers 校验（匹配 cs2xxhcd/htitahcd/hiti），
  未发现驱动即报"校验未通过"（引导重试或手动运行 Setup64），不再盲写标记
- queryInstalled 改为 pnputil 实时校验驱动商店（唯一真源，废弃注册表标记——
  假安装误写后向导会错误地不再显示安装按钮）
- 成功日志改为提示"拔插 USB 重新枚举设备后再检测"
 2026-09-21 16:46:31 +08:00
dzc 170e9ddc5e feat(windows): 向导内置 HiTi Windows 驱动一键安装（对齐 mac 的"装 App 即用"体验） 
用户实测定论：CS-2xx 的 USB 是自定义设备（驱动包内含 CS2xxhcd.inf 内核驱动），
PavoApi 直打依赖驱动建立的 USB 通道——无驱动时枚举到设备但状态返回离线，
"免驱动"假设不成立。产品要求两平台一致：驱动随 App 内置、向导一键安装。

- assets/drivers/CS2xx_Windows_Driver.zip：HiTi 官网 CS-2xx Windows 驱动
  （2.6.25.48）整目录 zip（含 CS2xx/Setup64.exe），33MB，不入 git
- DriverInstall Windows 分支：Expand-Archive 解压到临时目录 → 递归定位
  Setup64.exe（兜底 setup/autorun）→ PowerShell Start-Process -Verb RunAs -Wait
  提权安装（UAC 一次）→ 写安装标记（HKCU\Software\zax\desktop-plugin，
  系统驱动安装状态无统一可查标志）→ finally 清理临时目录
- 向导第 2 步统一双平台状态机：驱动未装（异步查标记/目录）→"一键安装驱动
  （内置安装包）"；轮询 3 秒自动刷新安装/连接状态
- bundledInstallerPath 双平台资产路径推导（mac .dmg / win .zip）；
  .gitignore 增 *.zip；assets/drivers/README 更新双平台放置约定
 2026-09-21 16:38:11 +08:00
dzc 527baf7ec5 fix(windows): 托盘图标不显示——tray_manager 原生 LoadImage 只认 .ico 
用户 Windows 实测：日志"托盘已就绪"无报错、不在折叠区，但任务栏无图标。
源码级定位：tray_manager 0.5.3 Windows 原生端用
LoadImage(IMAGE_ICON, LR_LOADFROMFILE) 加载图标文件——该 Win32 API 只认
.ico，传入 png 返回 NULL → Shell_NotifyIcon 添加成功但图标为空 → 任务栏
不显示且全程无任何报错（mac 走 base64+NSImage 另一条路径所以正常）。

修复：Windows 托盘改用 assets/tray_icon_win.ico（16/24/32 三尺寸 PNG-in-ICO，
gen_app_icons.dart 生成，python struct 校验目录项 offset 严格对齐；ico 随
flutter_assets 打包，Debug/Release/Inno 全形态生效）；删除无效的
tray_icon_win.png；AppTray 按平台选路径。
 2026-09-21 16:27:03 +08:00
dzc 1deb3125be fix: Pavo 布局自检期望值错误（80→88）——上一轮审查时手数错了指针数 
用户 Windows 实测触发 HitiCardPrintParameter 布局 assert。mac 实测 sizeOf
坐实：HitiCardPrintParameter=88（4×uint32 + 8×uint8 + 8×pointer = 24+64，
8 个指针=front BGR/K/O + back BGR/K/O + Reserve×2），其余三个（32/16/48）
正确——结构体布局本身与 C# 实机版一致，错的只是 assert 里手写的期望值 80。

顺带：此错误当时被 pavo_isolate_test 的 catch 转 offline 文案掩盖（断言只查
unsendable），新增 test/pavo_ffi_layout_test 直接 expect 四个 sizeOf，
布局回归在 mac 上即红，不必等 Windows 实机。15 测试全过。
 2026-09-21 16:19:32 +08:00
dzc e00086c01c fix: Pavo 后端 isolate 闭包捕获实例链导致 Windows 状态查询必炸（unsendable） 
用户 Windows 实测：未装驱动点跳过后页面报"状态读取失败 Illegal argument in
isolate message: object is unsendable - _Timer"。堆栈定位：

Isolate.run(_statusSync) 的方法 tear-off 会连带 this（PavoPrintBackend）→
_log（agent.log.write tear-off）→ AgentLog → StreamController → UI 日志订阅链
→ 向导轮询 Timer——Timer 不可跨 isolate 发送，消息序列化直接抛错。mac 上
CUPS 后端不走 Isolate.run，从未暴露。

修复：isolate 入口全部改为顶层函数（pavoStatusSync / pavoPrintSync），不捕获
任何实例状态；printOneCard 先解出纯字符串（data URL/份数）再进闭包，最小化
捕获面。新增守护测试 pavo_isolate_test：在活跃日志订阅下调 getStatus，
回归捕获 this 时会立即复现 unsendable。14 测试全过、analyze 零问题。
 2026-09-21 16:15:27 +08:00
dzc e88c9dcfa2 fix(向导): Windows 文案改为"SDK 直连免驱动优先，官方驱动仅可选兜底" 
用户在 Windows 上误读引导为"需要装驱动"。实际 Windows 走 PavoApi SDK 直连
USB 打印（DLL 已随 App 打包），大概率无需官方驱动；原文案把"去官网下载驱动"
放在第一位造成误导。改为：① 连 USB 开机重新检测（主路径）；② 反复检测不到
再考虑官方驱动（可选兜底，链接标注"可选"）。mac 文案不变。
 2026-09-21 16:08:14 +08:00
dzc fb399ae8f6 fix(windows): 全量代码审查修复——中文乱码风险/Inno 兼容/ffi 布局自检/部署说明 
系统性把 mac 踩过的坑逐一在 Windows 对应路径排查后修复四处：

1. runner 加 /utf-8 编译选项（高危）：MSVC 默认按系统代码页（中文 Windows=GBK）
   解析 UTF-8 源码，main.cpp 的 L"资安信插件助手" 窗口标题会乱码
2. installer.iss 的 x64compatible → x64：前者需 Inno 6.3+，旧版 iscc 直接报错
3. PavoApi 构造加结构体布局 assert（80/32/16/48 字节，对齐 C# 实机验证值），
   Windows 首跑（debug）即暴露 ffi 对齐差异
4. README 补 Windows 部署注意：VC++ Redistributable（PavoApiW_x64.dll 可能
   动态依赖 vcruntime140.dll）、SmartScreen 未签名提示、Inno 6.x 要求

其余复查项确认无问题：reg 命令引号（空格路径安全）、Dart/Inno 的 Run 键名
一致（ZaxDesktopPlugin）、vendor DLL 拷贝用生成器表达式（Debug/Release 通用）、
pavo 全部 ffi 调用在 Isolate.run、scheme 注册表路径拼接、关窗拦截走
window_manager 的 WM_CLOSE 主路径（无 mac 的 _close: 私有 selector 问题）。
 2026-09-21 14:22:16 +08:00
dzc 78d6b82305 fix: 向导第 2 步自动轮询——手动装驱动/插打印机后页面自动刷新 
用户实测反馈：手动安装驱动输密码后向导页面无变化。排查确认驱动实际已装上
（/Library/Printers/HiTi 存在），问题是向导只在按钮事件时刷新——用户在 App
外装完驱动没有任何事件触发重建，页面停在"尚未安装"旧文案。

修复：向导停留在第 2 步期间每 3 秒静默轮询（驱动目录判断 + 打印机状态），
装完驱动/插上打印机/系统识别出队列后页面自动切换分支；驱动未装分支同时
补"重新检测"按钮；一键安装执行中暂停轮询避免打断。
 2026-09-21 14:09:13 +08:00
dzc d475cac6ab feat: 向导内置 HiTi Mac 驱动一键安装（补齐计划 §3.2"驱动 dmg 放包内"设计） 
- setup/driver_install.dart：检测已装（/Library/Printers/HiTi）+ 内置 dmg 定位
  （从 resolvedExecutable 反推 flutter_assets/assets/drivers/，缺失降级官网链接）
  + 静默安装（hdiutil 挂载→定位 pkg→osascript 提权 installer→finally detach；
  挂载点名带随机序号必须从 attach 输出解析）
- 向导第 2 步重做状态机：驱动未装 → "一键安装驱动（内置安装包）"按钮
  （安装中提示输管理员密码，失败显示原因）；驱动已装但无队列 → 连接/添加队列
  引导；无内置 dmg 的构建回退官网链接
- assets/drivers/ 收驱动 dmg（.gitignore 不入库，打包脚本检查缺失并警告，
  当前从 card-printer-agent/dist 拷入 2.4.2 版，25MB）
- 实测：挂载/pkg 定位/detach 免密链路全通过；打包 47MB dmg 内含驱动，
  冒烟启动正常（服务已占主端口 38200）；一键安装的提权弹窗待用户实测
 2026-09-21 14:04:55 +08:00
dzc 3ecac9a302 feat: Phase 4 收尾 + Phase 5 打包（首启向导/开机自启/URL scheme 闭环/mac dmg） 
Phase 4 剩余三项：
- 首次引导向导（setup/first_run + ui/setup_wizard）：服务自检（含 C# 助手共存
  提示）→ 打印机检测与 HiTi 驱动安装指引（官网链接/重新检测，mac 与 win 文案
  分支，允许无打印机完成）→ 开机自启开关 + scheme 注册；侧栏底部常驻设置区
  （自启开关 + 重新运行引导）
- 开机自启（setup/autostart）：mac 写 LaunchAgent（RunAtLoad 一次性，不用
  KeepAlive——托盘退出不能被拉回）；Windows 走 HKCU Run（reg 命令免 win32 依赖）
- URL scheme 闭环：单实例唤醒端口 38210（setup/single_instance）——zaxprint://
  唤起或重复双击启动第二进程时通知常驻实例弹窗后自退，跨平台一致（弃用
  app_links 的 mac 事件转发不确定性）；Windows 启动时幂等注册 HKCU scheme；
  前端 cardPrinter.ts 加 launchAgent()（zaxprint://open），开卡抽屉离线时显示
  "启动打印助手"按钮，点击唤起后 1s×6 轮询自动上线（biz 前端改动待用户提交）

Phase 5：
- tool/package_macos.sh：构建 → ad-hoc 就地签名（--deep，勿加 --options=runtime：
  hardened runtime 库校验会因 ad-hoc 无 Team ID 拒载 framework，实测踩坑）→
  hdiutil dmg；实测产出 22MB dmg + 签名后冒烟通过
- windows/installer.iss：Inno Setup 安装包脚本（快捷方式/桌面图标/开机自启
  Tasks/zaxprint scheme 注册与卸载清理/HiTi SDK DLL 随 Release 目录打包）

依赖 +url_launcher +shared_preferences；13 测试全过、analyze 零问题。
 2026-09-21 13:51:42 +08:00
dzc bee734fd5b feat: 后台托盘 + 资安信品牌化 + 修复布局断言（Phase 4 部分） 
- 后台托盘（mac/Windows）：window_manager 拦截关窗改隐藏，服务持续运行；
  托盘单击恢复窗口、右键菜单（显示主界面/退出），退出入口仅放托盘菜单
- 品牌：App 更名"资安信插件助手"（mac PRODUCT_NAME/xib、win main.cpp+Runner.rc(code_page 65001)、
  MaterialApp/侧栏/托盘 tooltip/日志）；图标全家桶换资安信盾牌 logo
  （tool/gen_app_icons.dart 生成 mac AppIcon 7 尺寸/win ICO 7 尺寸/托盘白底圆盘版/assets logo）
- 修复启动布局断言：SliverList 内 Row(stretch) 需 IntrinsicHeight 包裹，
  否则子项收到 h=Infinity 约束（用户实测报错，test/ui_smoke_test.dart 守护复现）
- Agent.stop 幂等（托盘退出与窗口销毁竞态安全）
- 测试修复：smoke 测试改 tester.runAsync 包真实 socket I/O（fake async zone 里会永久挂起）、
  显式 pump 替代 pumpAndSettle；13 个测试全过，analyze 零问题，release 构建实测通过
 2026-09-21 13:16:23 +08:00
dzc 0a78ff1b58 feat: Windows PavoApi ffi 直打后端（Phase 3 代码完成，待实机验收） 
- lib/print/pavo/：PavoApiW_x64.dll 的 dart:ffi 绑定（结构体布局对齐 C#，W 后缀导出名回退兼容）
- pavo_printer.dart：枚举（UTF-8/UTF-16 自动解码）/状态/色带信息/单卡直打/忙碌轮询（3 分钟超时）/LayerHolder 非托管内存管理
- pavo_backend.dart：全部 ffi 调用与像素转换跑在 Isolate.run，主 isolate HTTP 服务零阻塞
- lib/image/card_image.dart：PNG data URL → 纵横比选卡面 → 手动 alpha 铺白底 → BGR24/Gray8 紧凑像素（image 包 compositeImage 对全透明像素非 src-over 语义，改为逐像素混合对齐 C#）
- windows/ 目录：从 Flutter SDK windows.tmpl 手动实例化（mac 上 flutter create 拒绝生成的绕过），窗口标题"饭卡打印助手"
- windows/vendor/：收录 SDK 的 PavoApiW_x64.dll/PavoCardSDK_x64.dll/HeatTB3.dll/heatthcd.bin，CMake POST_BUILD 自动拷到 exe 旁
- backend.dart 工厂接通 Windows 分支；analyze 零问题、单测 12 个全过
 2026-09-21 12:19:07 +08:00
dzc 689a07ca44 feat: 饭卡打印助手 Flutter 版（Phase 1/2：协议服务器 + macOS CUPS 真机打印） 
- 协议与 C# 版 card-printer-agent 逐字段对齐（38200-38202 顺延、CORS *、串行任务队列、30 分钟保留）
- macOS CUPS 后端：lpoptions 队列发现 + lp 参数列表提交（LC_ALL=C 防本地化粘连坑）
- --mock 模拟模式 + bin/agent.dart headless 入口 + 测试卡生成工具
- 真机验收：HiTi CS-200e status 就绪 + 真实出卡；macOS 通用二进制构建通过
- App Sandbox 已关闭（服务需绑回环端口并调用 lp 子进程）；zaxprint URL scheme 已注册
 2026-09-21 12:03:27 +08:00