# moon-ipp 使用指南

## 接入设备

需要设备或打印服务提供 IPP 地址，及它支持的已有文档格式。先用虚拟 CUPS 复现，再换实际设备地址。不要把网页地址、共享文件夹路径或 USB 名称当作 IPP 地址。

Linux/macOS 使用 MoonBit 和所需 C 编译工具；Windows 需 MSVC C++ Build Tools/Windows SDK，可用 `moon run scripts/verify.mbtx --run` 作为下述命令前缀。验证范围为 Windows/Linux，macOS 仍需在目标环境验证。

```sh
moon run cmd/main --target native -- capabilities --uri ipp://localhost:8631/ipp/print
moon run cmd/main --target native -- health --uri ipp://localhost:8631/ipp/print
moon run cmd/main --target native -- plan --uri ipp://localhost:8631/ipp/print --input examples/report.pdf --copies 1
```

计划包含输入字节数、最终选项和诊断。`can_submit=false` 会返回非零退出码，但不会创建打印任务。能力缺失会给出警告；计划不保证传输和最终纸面输出成功。`--format` 可指定格式；扩展名推断不会转换数据。

## 提交并保存凭据

每次明确授权的新打印操作，使用一个尚不存在的凭据路径：

```sh
moon run cmd/main --target native -- print --uri ipp://localhost:8631/ipp/print --input examples/report.pdf --name "Monthly report" --wait --interval 500 --polls 120 --output monthly-report-001.json
```

凭据包含 schema、printer、state、document_bytes、options、job、observations、error。任务被接受后即保存 job.id，终态时更新。stdout 输出同一份 JSON，stderr 提供已接受任务编号的提示。`--output` 父目录需存在且可写；已有文件会在联网前拒绝，不覆盖旧凭据。

Windows 上凭据更新遇到短暂的访问、共享或锁冲突时，仅对同目录文件替换进行有限重试：最多 8 次，累计退避 1,270 ms，不含文件系统调用耗时。不会重发打印请求，不会先删除原凭据；持续失败仍返回错误并保留可用记录。

| state | 含义与处理 |
| --- | --- |
| prepared | 本地凭据已建立，尚未进入提交阶段；先核实此调用是否仍运行。 |
| submitting | 提交过程未结束，可能包含预检；若进程已中断，应先核对设备。 |
| accepted | 已有任务编号，可继续查询或等待。 |
| completed | 设备报告任务完成。虚拟设备只证明接收与协议流程。 |
| canceled / aborted | 设备取消或中止，命令失败；查看观察记录中的原因。 |
| tracking-error | 已有任务编号，但跟踪或凭据记录发生错误；使用 job.id 继续查询。 |
| outcome-unknown | 可能已被设备接收，但没有可靠结果；先按任务名、用户名及队列核对。 |
| not-submitted | 当前调用未取得接受结果，且未遇到提交结果不确定错误；查看 error 后处理。 |

## 中断后恢复查询

从凭据读取 `printer` 和 `job.id`，将它们填入下面的命令：

```sh
moon run cmd/main --target native -- job --uri ipp://localhost:8631/ipp/print --job-id 27
moon run cmd/main --target native -- wait --uri ipp://localhost:8631/ipp/print --job-id 27 --interval 1000 --polls 120
moon run cmd/main --target native -- jobs --uri ipp://localhost:8631/ipp/print --which all --mine
```

`--user` 应与原提交用户一致。独立的 job/wait 命令只查询，不重发文档，也不会回写旧凭据。任务被设备清理后可能查不到，应结合业务日志核实。没有 job.id 时先查队列，不能把“查不到”直接等同于从未接收。

本地凭据不提供设备端去重。同一操作不要换文件名重试；存在 `.moon-ipp-tmp` 时先核对旧进程与凭据，程序不会覆盖它。没有自动重试提交、自动取消任务或自动删除凭据。

## 认证与验证

认证由环境变量 `MOON_IPP_AUTHORIZATION` 提供，要求 `ipps://` 和有效的系统信任证书；不要把认证头写入命令参数、凭据或 Git。TLS/认证结果以实际目标设备为准。

执行 `moon run scripts/verify.mbtx` 验证本机；Ubuntu 安装 README 中 CUPS/Avahi 后，可运行 `moon run --deny-warn scripts/interop_workflow.mbtx` 复现计划、打印凭据、防重复和取消退出码全过程。日志和结果写入忽略的 `interop-output/`。