# KAGI HEROS Mac 列印助手

這是現有 Render 攝影棚的現場設備連接程式。照片、每人份數、品檢與領取仍在同一個後台管理；助手只接收工作、下載原核准列印檔、交給選定的 CP1500，並回報 macOS 工作狀態。

## 適用環境

- macOS 12 以上；同一安裝包包含 Apple 晶片及 Intel 版本，不需要另外裝 Python、Node 或套件。
- 每台 Mac 最多兩台 CP1500，兩台 Mac 合計四台。相印機各自接 USB 資料線與原廠電源；Mac 插電、保持開蓋。原廠不保證 USB Hub，因此優先使用兩個獨立資料埠。
- 必須先在 macOS「印表機與掃描器」加入相印機。助手以 USB 序號或 USB-AirPrint 設備 UUID 核對 CP1500，並確認 Postcard 100×148 mm 紙張。兩台同型號的名稱可以帶「- 1」等後綴；不同名稱若指向同一設備，不會當成兩台接單。
- 本輪目的地固定為工業會既有 Render Staging，不會連其他客戶或 Production。

## 初次安裝與接線

1. 從後台「列印與領取」下載 ZIP，解壓縮，把 **KAGI HEROS Print Assistant.app** 放入「應用程式」。目前為本機簽署，未經 Apple 公證；另一台 Mac 初次開啟可能需要本人依 macOS 的標準確認流程開啟。不要關閉整台 Mac 的安全防護。
2. 在現有後台為第一台電腦取得 **Mac 1** 配對碼；第二台取得 **Mac 2**。每個碼短效、僅能用一次，不是來賓登入。將碼貼進助手按「配對」。
3. 按「重新偵測相印機」，選擇本台電腦接的兩台。Mac 1 對應 A/B，Mac 2 對應 C/D。
4. 按「開始接單」，助手先讀回原送印紀錄並回報兩台設備。首次在後台確認機器對應與 Postcard 紙張設定後，才會開始接照片；不是每張重新批准。
5. 先各印一張核准測試照片，核對圖像方向、文字、Logo、四邊及膚色。完成接線／實印驗收之前，不將軟體通過當作活動可用。

目前整場演練使用 Mac 2 的 C/D 兩個位置（cp-3/cp-4）。第二台依上面步驟在既有管理頁確認機器與紙張後即可接單，不需逐台請工程人員私下放行。其他活動的印務範圍仍依原設定。

## 更新至 1.0.2

先關閉原助手，再以新 App 取代原 App。保留原配對與本機送印紀錄；不要刪除「Application Support」內的資料。開啟後重新偵測，核對 C/D 兩個位置，再按「開始接單」。更新本身不會送印。

## 平常操作

打開助手，保留已配對的站別與機器，按「開始接單」。工作人員在原後台審圖通過後，符合資格的每位來賓各建立一張紙本工作；不用逐張下載，也不用跳出列印視窗。

「暫停新工作」停止接新單，原有工作仍繼續核對。「開啟列印管理」回到同一個 Render 後台。關閉助手不會清空紀錄，macOS 已接到的工作可能仍繼續印；下次打開先核對原單。

助手不設登入自動啟動、背景常駐服務、cron 或 AI 定時任務。只有人員開啟並按開始，才會連線接單。工作期間暫時阻止系統閒置休眠，關閉時解除，不修改全機電源設定。

## 異常處理

- 一台缺紙／離線：處理該台；其他機器繼續接新工作。
- 顯示「送印結果待核對」：先看原機器、原 macOS 佇列與已出紙張，不要直接在另一台重印。助手不會因回覆逾時而重送。
- 缺紙或墨匣：恢復原佇列，先確認原單是否繼續；不要另開同張工作。
- 紙張瑕疵：後台記錄技術補印原因。這不扣來賓的重拍次數。
- 來賓重拍：沿用每人一次規則；舊紙尚未交付要攔下核對，已領取者只更新電子照。
- 另一台電腦接手同一機器：先在後台核對舊站與未明工作，再重新綁定。不要複製本機送印紀錄當成另一台電腦，也不要刪除紀錄來解除鎖定。

macOS 顯示「完成」只代表列印系統的回報；實體出紙、品檢與來賓領取分別在後台確認。

## 資料與技術邊界

- 配對後的工作憑證保存於 macOS 鑰匙圈；不寫入一般設定檔、網址、聊天或紀錄。
- 本機工作紀錄：`~/Library/Application Support/KAGI HEROS Print Assistant/`。照片快取上限64 MiB／8檔；只清除已獲雲端回覆的終態暫存，未明送單紀錄永久保留供核對。不要手動清空資料夾。
- 僅向既定 HTTPS 後台主動取件；不開放公網或本地瀏覽器控制埠。每份檔案上限9 MiB，核對 SHA-256，不重新生圖、不重畫文字、不裁切核准成品。
- `--self-test` 使用合成資料與替身設備，不接雲端、不印紙。`--inspect` 列出本機 CP1500 佇列、設備識別摘要、不同識別數及被排除的原因，不送印。macOS 保存的佇列存在，不等於相印機此刻已接線或出紙正常。
- Apple 晶片與 Intel 均已編譯；第二台 Mac、真實 CP1500、耗材、裁切、色彩與持續速度仍須逐項實測，不能由編譯或替身測試推定。

## 工程重建

使用本機既有 Xcode Command Line Tools，在讀過容量規則並確認空間後執行 `bash build.sh`。只產生本目錄 `build/` 下的 App、雙架構執行檔與 ZIP，不安裝或下載依賴；編譯器既有模組快取沿用。每次改版均需重跑原生測試、核對 ZIP 雜湊與發布檔案。

## 更新至 1.0.3

結束舊助手後，以新版替換原應用程式，再開啟並按「開始接單」。不需重新配對，也不要刪除原工作紀錄。新版會重新核對原先選定的兩個 USB 佇列及相紙，支援已改為 USB-AirPrint 的設定；同一設備的佇列名稱或傳輸網址變動不再直接視為另一台設備。

忙碌、待命、暫停與設備檢查失敗會分開顯示，詳細檢查代碼會回報到列印管理頁。更換傳輸方式造成設備識別碼變動時，後台須核對最新設備綁定；原有未結送印仍保留在原單，不會自動重印。