214 lines
7.6 KiB
Markdown
214 lines
7.6 KiB
Markdown
# 云印享 - Windows 门店打印客户端
|
||
|
||
云印享 Windows 门店打印客户端是部署在打印店本地 Windows 电脑上的 WPF 程序，负责连接真实 Go gRPC 后端、注册本机打印机、订阅打印任务、预处理文件并调用 Windows 打印系统执行打印。
|
||
|
||
本客户端只承担 **门店本地管理与打印执行** 职责，不替代微信小程序、React 管理后台或 Go 后端服务。
|
||
|
||
## 技术栈
|
||
|
||
| 技术 | 说明 |
|
||
|------|------|
|
||
| 框架 | .NET 8 + WPF |
|
||
| 语言 | C# |
|
||
| 架构 | MVVM |
|
||
| 通信 | gRPC + WebSocket |
|
||
| 协议 | Protobuf |
|
||
| 打印 | Windows Print Spooler API / PrintDocument |
|
||
| 文件处理 | PDFsharp / SharpCompress / LibreOffice Headless |
|
||
| 配置安全 | Windows DPAPI |
|
||
|
||
## 功能模块
|
||
|
||
- 🖨️ **打印机管理** - 枚举本机实体/网络打印机，过滤 PDF、XPS、OneNote、Fax 等虚拟输出设备
|
||
- 📋 **打印任务队列** - 订阅后端任务流，自动顺序处理，支持暂停、恢复、取消任务
|
||
- 📄 **文件预处理** - 支持 PDF、图片、Office/TXT、ZIP、RAR 等文件处理
|
||
- 📌 **PDF 处理** - 支持订单页码范围裁剪
|
||
- 📁 **文库管理** - 管理员上传本地资料到后端文库服务
|
||
- 🔐 **认证与配置** - API Key 注册打印机，管理员登录，敏感配置 DPAPI 加密保存
|
||
- 🔄 **连接保活** - 心跳、订阅恢复、指数退避重连、任务去重
|
||
- 📝 **日志记录** - UI 日志和异常堆栈落盘到本地日志目录
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
client/
|
||
├── App.xaml # 应用入口
|
||
├── CloudPrint.Client.csproj # WPF 项目文件
|
||
├── Helpers/ # Windows API 与 PDF 工具
|
||
│ ├── PdfProcessor.cs
|
||
│ └── WindowsPrintApi.cs
|
||
├── Infrastructure/ # MVVM 基础设施
|
||
│ ├── AsyncRelayCommand.cs
|
||
│ ├── ObservableObject.cs
|
||
│ ├── RelayCommand.cs
|
||
│ └── WpfUiDispatcher.cs
|
||
├── Models/ # 领域模型
|
||
│ ├── ClientSettings.cs
|
||
│ ├── Document.cs
|
||
│ ├── Printer.cs
|
||
│ └── PrintJob.cs
|
||
├── Services/ # 业务服务
|
||
│ ├── Abstractions/ # 服务接口
|
||
│ ├── Grpc/ # gRPC metadata 与模型映射
|
||
│ ├── Printing/ # 打印执行器与队列服务
|
||
│ ├── FileService.cs # 文件校验、解压、转换
|
||
│ ├── GrpcService.cs # 后端 gRPC 通信
|
||
│ ├── JsonSettingsService.cs # 本地配置持久化
|
||
│ ├── PrintJobCoordinator.cs # 打印任务协调流程
|
||
│ ├── PrintService.cs # 打印服务门面
|
||
│ └── WebSocketService.cs # WebSocket 备用通道
|
||
├── ViewModels/ # 页面 ViewModel
|
||
│ ├── MainViewModel.cs
|
||
│ ├── PrintQueueViewModel.cs
|
||
│ ├── LibraryViewModel.cs
|
||
│ └── SettingsViewModel.cs
|
||
├── Views/ # WPF 页面
|
||
│ ├── MainWindow.xaml
|
||
│ ├── PrintQueueView.xaml
|
||
│ ├── LibraryView.xaml
|
||
│ └── SettingsView.xaml
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Windows 10/11
|
||
- .NET 8 SDK 或 .NET 8 Desktop Runtime
|
||
- 可用的 Go gRPC 后端服务
|
||
- 真实有效的打印客户端 API Key
|
||
- 至少一台实体或网络 Windows 打印机
|
||
- PDF 打印建议安装 SumatraPDF
|
||
- Office/TXT 转 PDF 需要安装 LibreOffice 或配置 `SOFFICE_PATH`
|
||
|
||
## 快速开始
|
||
|
||
### 1. 还原依赖
|
||
|
||
```powershell
|
||
dotnet restore .\CloudPrint.Client.csproj
|
||
```
|
||
|
||
### 2. 启动客户端
|
||
|
||
```powershell
|
||
dotnet run --project .\CloudPrint.Client.csproj
|
||
```
|
||
|
||
### 3. 配置客户端
|
||
|
||
在“系统设置”页配置：
|
||
|
||
- 服务器地址：Go gRPC 后端地址，例如 `http://localhost:8080`
|
||
- API Key：后端为门店打印客户端分配的认证 Key
|
||
- 门店名称：当前打印店名称
|
||
- 本地文库目录：门店本地资料目录
|
||
- 允许 HTTP gRPC：本地开发或内网明文 HTTP/2 时启用，生产环境建议关闭
|
||
- 最大上传大小、心跳间隔等运行参数
|
||
|
||
### 4. 注册并订阅任务
|
||
|
||
1. 在主界面选择真实打印机
|
||
2. 点击连接后端
|
||
3. 点击订阅打印任务
|
||
4. 保持客户端在线，后端推送任务后自动进入打印队列
|
||
|
||
## 开发命令
|
||
|
||
```powershell
|
||
# 构建客户端
|
||
dotnet build .\CloudPrint.Client.csproj
|
||
|
||
# 检查依赖漏洞
|
||
dotnet list .\CloudPrint.Client.csproj package --vulnerable
|
||
```
|
||
|
||
## 对接服务
|
||
|
||
客户端基于 `backend/cloudprint-backend/proto/cloudprint.proto` 生成 C# gRPC Stub，主要对接以下服务：
|
||
|
||
| 服务 | 用途 |
|
||
|------|------|
|
||
| PrintService.RegisterPrinter | 注册本机打印机 |
|
||
| PrintService.PrinterHeartbeat | 上报打印机心跳和状态 |
|
||
| PrintService.SubscribeJobs | 订阅后端打印任务流 |
|
||
| PrintService.ReportJobStatus | 上报打印任务进度和结果 |
|
||
| PrintService.CancelPrintJob | 取消后端打印任务 |
|
||
| FileService.GetFile | 下载待打印文件 |
|
||
| LibraryService.UploadFile | 上传门店文库文件 |
|
||
| AdminService.Login | 管理员登录 |
|
||
|
||
## 文件处理能力
|
||
|
||
| 类型 | 格式 | 处理方式 |
|
||
|------|------|----------|
|
||
| PDF | `.pdf` | 支持页码范围裁剪，直接提交 PDF 打印 |
|
||
| 图片 | `.jpg`, `.jpeg`, `.png`, `.bmp`, `.gif` | 使用 `PrintDocument` 等比缩放打印 |
|
||
| Office | `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx` | 通过 LibreOffice Headless 转 PDF 后打印 |
|
||
| 文本 | `.txt` | 通过 LibreOffice Headless 转 PDF 后打印 |
|
||
| 压缩包 | `.zip`, `.rar` | 使用 SharpCompress 解压首个可打印文件后继续处理 |
|
||
|
||
压缩包处理会限制条目数量、嵌套层级和单文件大小，并清理压缩包内路径，避免路径穿越。
|
||
|
||
## 打印行为
|
||
|
||
- 客户端只展示实体/网络打印机，默认过滤虚拟输出设备
|
||
- PDF 打印优先使用 SumatraPDF，未安装时回退系统默认 PDF 打印程序的 `printto` 动作
|
||
- 图片打印使用 `PrintDocument`
|
||
- 其他格式在预处理后无法匹配专用执行器时回退 RAW 打印
|
||
- Windows 队列 JobId 优先通过 WinSpool `EnumJobs` 捕获，WMI 兜底
|
||
- 取消任务时优先通过 WinSpool `SetJob` 删除/取消真实系统队列任务
|
||
|
||
## 配置与安全
|
||
|
||
本地设置保存到：
|
||
|
||
```text
|
||
%APPDATA%\CloudPrint.Client\settings.json
|
||
```
|
||
|
||
安全策略：
|
||
|
||
- API Key 使用 Windows DPAPI 按当前用户加密保存
|
||
- 管理员 access token 使用 Windows DPAPI 按当前用户加密保存
|
||
- 设置文件复制到其他 Windows 用户后无法解密敏感字段
|
||
- 生产环境建议使用 HTTPS/TLS gRPC，并关闭 HTTP gRPC
|
||
|
||
## 日志
|
||
|
||
日志目录：
|
||
|
||
```text
|
||
%APPDATA%\CloudPrint.Client\logs
|
||
```
|
||
|
||
记录内容包括：
|
||
|
||
- 连接和注册结果
|
||
- 打印任务状态
|
||
- 文件下载和预处理结果
|
||
- 打印失败异常
|
||
- 全局未处理异常
|
||
|
||
## 注意事项
|
||
|
||
- 本客户端不提供模拟后端或 DryRun，运行时必须连接真实后端和真实打印机
|
||
- Windows 自带的 `Microsoft Print to PDF`、`XPS Document Writer`、`OneNote`、`Fax` 等不会作为门店打印机展示
|
||
- 若门店电脑只安装虚拟打印设备，客户端打印机列表会为空
|
||
- Office/TXT 文件转换依赖 LibreOffice，请提前安装或配置 `SOFFICE_PATH`
|
||
- PDF 打印建议安装 SumatraPDF，以获得更稳定的命令行打印能力
|
||
|
||
## 后续优化
|
||
|
||
- 根据后端最终 WebSocket 消息结构，将备用通道消息映射为打印任务或控制事件
|
||
- 按后端任务字段接入 PDF 水印和合并业务流程
|
||
- 增强 LibreOffice/SumatraPDF 路径检测和设置页提示
|
||
- 增加托盘常驻、开机自启动、单实例运行和安装包
|
||
- 继续提升同名文档并发场景下的 Windows JobId 匹配准确性
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
© 2026 云印享 版权所有
|