printServer/README.md

128 lines
4.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# printServer
## 项目概况
printServer 是一个面向 Windows 的本地打印服务应用。
它当前由以下几部分组成:
- 本地 WebSocket 服务,监听 3001 端口
- 前端页面 views/index.html(由 Electron 直接静态加载),用于绑定工作台、查看打印机、查看组件状态、执行注册服务等操作
- Windows PowerShell 脚本,用于打印机状态轮询
- 打印组件与远程 WebSocket 通信逻辑,用于接收远端指令并驱动本地打印
- Electron 桌面壳,用于后续安装包、托盘图标和桌面启动能力
## 当前能力
- 查询 Windows 打印机列表
- 监听打印机状态变化
- 通过页面查看本地打印组件状态
- 通过 WebSocket 调用本地服务方法
- 页面点击注册/注销服务状态
- 已开始接入 Electron 桌面入口与托盘常驻能力
## 技术结构
- 入口文件:index.js
- 核心框架:core/
- 服务层:services/
- 页面:views/
- Windows 脚本:printer.ps1
- 配置文件:config.json
## 目录说明
- core/
- 主应用、WebSocket 服务、WebSocket 客户端、打印组件核心逻辑
- services/
- 业务服务,如打印机、设置、绑定
- views/
- 页面模板,目前主要是 index.html
- 临时/
- 临时分析文档、测试脚本、临时日志的统一目录,可在任务结束后整体清理
## 本地运行
环境要求:
- Windows
- Node.js
- PowerShell
- 已安装并可调用的打印机驱动
启动方式:
```bash
node index.js
```
开发模式:
```bash
npm run dev
```
打开页面:
- 由 Electron 主窗口直接加载 views/index.html
## 页面与服务调用关系
页面通过浏览器连接本地 WebSocket 服务:
- 页面由 Electron 静态加载
- 页面中的按钮通过 wsSendWithCallback 发送 method
- WebSocket 服务按 method 路由到 services/ 下对应实例方法
示例:
- setting.info -> services/setting.js
- printer.getWindowsPrinters -> services/printer.js
## 当前打包方向
当前已确定的桌面化与 EXE 打包方向为:
- Electron 作为桌面壳
- electron-builder 作为打包工具
- NSIS 作为 Windows 安装包输出方式
选择这个方向的原因:
- 需要桌面图标启动
- 需要系统托盘图标常驻
- 需要安装包体验
- 需要打开页面并继续复用现有 index.html 和本地服务能力
- 比单纯将 Node 打成 exe 更容易控制窗口、托盘、安装和运行态
## 后续打包目标
- 支持可重复打包
- 输出完整安装包 EXE
- 安装后创建桌面快捷方式
- 启动后保留系统托盘图标
- 能打开页面并完成注册到服务
- 打包时纳入配置文件、页面资源、PowerShell 脚本与相关依赖
## 发布版本规则
- 打包前会校验 `package.json` 的 `version` 是否已有安装包产物。
- 若当前版本在 `dist/` 或 `versioning/releases/<version>/` 已存在产物,将直接阻止打包。
- 需要手动更新版本号后再执行打包。
## 更新下发产物
- 每次成功打包会自动归档安装包到 `versioning/releases/<version>/`。
- 同步生成 `versioning/update-feed.json`,包含 `latest` 与历史 `releases` 元数据(版本、文件路径、SHA256、构建时间)。
- 服务器可直接读取该清单实现后续版本更新下发。
## 应用内更新
- 页面提供“检查更新”和“应用内下载并安装”能力。
- 更新流程:检查版本 -> 下载更新包(进度条展示)-> 启动安装向导。
- 下载进度通过 WebSocket 事件 `update.downloadProgress` 实时推送到前端。
- 若安装向导未正常弹出,可使用“再次打开安装包”按钮重试。
## Linux 服务器发布
- 默认发布命令:`npm run release:linux`
- 本地私有配置发布命令:`npm run release:linux:local`
- 默认配置文件:`scripts/deploy.config.json`
- 本地覆盖配置:`scripts/deploy.config.local.json`(已默认 git 忽略)
- 发布脚本会自动执行:
- 选择最新安装包(默认 `dist/printServer-*-setup.exe`)
- 上传到 Linux 目录
- 自动清理远端历史版本(保留 `keepReleases` 个)
- 写入远端 `latest.json`(version/file/url/sha256/publishedAtUtc)
- 线上链接格式:`https://wms.wms.gztbyc.com/printServer/<installer>.exe`
## 打包排障
- 若 `electron-builder` 报 `Unexpected token ... package.json is not valid JSON`,请检查 `package.json` 是否存在 UTF-8 BOM。
- 可执行一次 BOM 清理:`node -e "const fs=require('fs');const p='package.json';const s=fs.readFileSync(p,'utf8').replace(/^\uFEFF/,'');JSON.parse(s);fs.writeFileSync(p,s,'utf8');"`
- 临时测试需要跳过版本产物校验时,可设置环境变量:`PRINTSERVER_SKIP_VERSION_CHECK=1`(仅建议测试场景使用)。
## 注意事项
- 当前项目包含明显的 Windows 依赖
- dm 相关能力已从本项目移除,不再属于当前交付范围
- 3001 端口需避免被占用(3000 端口当前不再承载页面服务)
- 临时测试与分析文件统一放在 临时/ 目录