README.md

# 云印享 - 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 云印享 版权所有