技术	说明
框架	.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 日志和异常堆栈落盘到本地日志目录

项目结构

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. 还原依赖

dotnet restore .\CloudPrint.Client.csproj

2. 启动客户端

dotnet run --project .\CloudPrint.Client.csproj

3. 配置客户端

在“系统设置”页配置：

服务器地址：Go gRPC 后端地址，例如 http://localhost:8080
API Key：后端为门店打印客户端分配的认证 Key
门店名称：当前打印店名称
本地文库目录：门店本地资料目录
允许 HTTP gRPC：本地开发或内网明文 HTTP/2 时启用，生产环境建议关闭
最大上传大小、心跳间隔等运行参数

4. 注册并订阅任务

在主界面选择真实打印机
点击连接后端
点击订阅打印任务
保持客户端在线，后端推送任务后自动进入打印队列

开发命令

# 构建客户端
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 删除/取消真实系统队列任务

配置与安全

本地设置保存到：

%APPDATA%\CloudPrint.Client\settings.json

安全策略：

API Key 使用 Windows DPAPI 按当前用户加密保存
管理员 access token 使用 Windows DPAPI 按当前用户加密保存
设置文件复制到其他 Windows 用户后无法解密敏感字段
生产环境建议使用 HTTPS/TLS gRPC，并关闭 HTTP gRPC

日志

日志目录：

%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

README.md Unescape Escape

云印享 - Windows 门店打印客户端

技术栈

功能模块

项目结构

环境要求

快速开始

1. 还原依赖

2. 启动客户端

3. 配置客户端

4. 注册并订阅任务

开发命令

对接服务

文件处理能力

打印行为

配置与安全

日志

注意事项

后续优化

许可证

README.md