# PrintAgentGo

**Repository Path**: bukuta/print-agent-go

## Basic Information

- **Project Name**: PrintAgentGo
- **Description**: 本地打印机代理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PrintAgentGo

基于 Go + Nuxt 4 的跨平台打印代理服务，替代现有 C# WPF 版本。

## 架构

```
PrintAgentGo/
├── cmd/server/main.go          # 入口
├── internal/
│   ├── api/                    # Gin HTTP API + SSE
│   ├── config/                 # YAML 配置读写
│   ├── db/                     # SQLite + GORM 模型
│   ├── printer/                # 打印机枚举 + 规则匹配
│   ├── printengine/            # 打印后端（SumatraPDF/GS/RawPrint）
│   └── jobqueue/               # 任务队列 + EventBus
├── web/                        # Nuxt 4 前端
│   ├── pages/                  # 6 个页面
│   ├── components/             # UI 组件
│   └── composables/            # useApi / useSse
├── scripts/
│   └── build.mjs               # 一键构建部署脚本
├── tools/                      # 打印后端可执行文件（SumatraPDF/GS/RawPrint）
└── test/                       # 测试用 PDF
```

## pnpm Workspace

项目使用 pnpm workspace，根目录统一管理前端依赖。

```bash
pnpm install           # 安装所有 workspace 包依赖
```

子包 `web/` 的包名为 `printagentgo-web`，通过 `--filter` 操作：

```bash
pnpm --filter printagentgo-web add some-package
```

## 快速开始

### 后端

```bash
go run ./cmd/server
```

服务启动在 `http://localhost:8520`，自动从 `www/` 目录（若存在）或内置 fallback 提供 Web UI。

### 前端开发

从项目根目录：

```bash
pnpm dev          # 启动 Nuxt 开发服务器（端口 3004，代理 /api/ → 8520）
pnpm build-www    # 构建前端
pnpm generate     # 生成静态文件到 .output-nuxt/public/
```

开发时需同时运行后端（`go run ./cmd/server`）和前端 dev server，前端通过 proxy 访问后端 API。

### 一键发布

```bash
pnpm release
```

或直接：

```bash
node scripts/build.mjs
```

流程：编译 Go 二进制 → `pnpm generate` → 复制 `www/` + `tools/` + `test/` + `appsettings.yaml` 到 `release/`。

## 脚本参考

| 命令 | 说明 |
|------|------|
| `pnpm dev` | 前端开发服务器（port 3004） |
| `pnpm build-go` | 编译 Go 二进制 |
| `pnpm build-www` | 构建前端 |
| `pnpm generate` | 生成前端静态文件 |
| `pnpm release` | 全量构建并打包到 `release/` |
| `node scripts/build.mjs` | 同上，同 `pnpm release` |

## API 参考

所有接口以 `/api/v1/` 为前缀。

### 健康检查

```
GET /api/v1/health
```

### 打印机

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/printers` | 打印机列表 |
| `GET` | `/api/v1/printers/detail?name=` | 打印机详情（query 参数） |
| `POST` | `/api/v1/printers/test?name=` | 测试打印（query 参数） |

### 打印任务

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/v1/print` | 提交打印任务（multipart/form-data） |
| `GET` | `/api/v1/jobs` | 任务列表（分页） |
| `GET` | `/api/v1/jobs/:id` | 任务详情 |
| `GET` | `/api/v1/jobs/:id/pdf` | 下载原始 PDF |
| `POST` | `/api/v1/jobs/:id/retry` | 重试失败任务 |
| `DELETE` | `/api/v1/jobs/:id` | 取消任务 |

**提交打印示例：**

```bash
curl -X POST http://localhost:8520/api/v1/print \
  -F "file=@label.pdf" \
  -F "paperType=标签纸" \
  -F "paperSize=80x297mm" \
  -F "copies=2"
```

仅接受 `multipart/form-data`，`file` 字段上传 PDF 文件，`paperType`/`paperSize`/`copies` 为可选字段。

### 规则

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/rules` | 获取规则 |
| `PUT` | `/api/v1/rules` | 全量更新规则 |
| `POST` | `/api/v1/rules` | 添加规则 |
| `DELETE` | `/api/v1/rules/:id` | 删除规则 |

### 其他

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/v1/stats` | 统计概览 |
| `GET` | `/api/v1/config` | 读取配置 |
| `PUT` | `/api/v1/config` | 保存配置 |
| `GET` | `/api/v1/events` | SSE 状态推送 |

## 打印后端

系统按优先级自动检测可用打印后端。可执行文件查找顺序为：当前目录 → `tools/` 目录 → exe 同目录 → 系统安装路径。

| 优先级 | 后端 | 查找文件 |
|--------|------|----------|
| 1 | Ghostscript + RawPrint | `gswin64c.exe` + `RawPrint.exe` |
| 2 | SumatraPDF | `SumatraPDF.exe` |
| 3 | RawPrint | `RawPrint.exe` |

将对应可执行文件放在 `tools/` 目录下即可被自动识别。

## 配置

首次运行在当前工作目录自动生成 `appsettings.yaml`。

```yaml
server:
  port: 8520                     # HTTP 监听端口
storage:
  dbPath: ./data/printagent.db   # SQLite 数据库路径（支持相对/绝对路径）
  pdfDir: ./data/pdfs            # PDF 存储目录
  maxRetain: 1000                # 最大保留任务数，超限时自动清理旧记录
  testPdfPath: ""                # 测试打印 PDF 路径，空串时自动查找 test/ 目录
logging:
  level: info                    # 日志级别：debug / info / warn / error
  file: ""                       # 日志文件路径，空串表示仅输出到控制台
printers:
  cacheSeconds: 5                # 打印机列表缓存秒数
```

## 已知问题

### SumatraPDF 中文路径

SumatraPDF 打开 PDF 时，内部将绝对路径转换为 `\\?\` 前缀格式（Windows 扩展长度路径语法）。该组件的文件打开实现对非 ASCII 字符（如中文）兼容性不佳 — 疑似使用了 `CreateFileA`（ANSI）而非 `CreateFileW`（Unicode）API。

**表现：** 当 PDF 路径包含中文时，SumatraPDF 报错 `Couldn't open file`；纯 ASCII 路径正常。

**解决方案：** `POST /api/v1/printers/test?name=` 测试打印时，服务端自动将源文件复制到 ASCII-only 临时路径（`%TEMP%\testprint-*.pdf`）再传给引擎。正式打印任务不涉及此问题（PDF 文件名为纯 UUID）。

## 测试

```bash
go test ./internal/... -v
```