receipt-compiler

レシートコンパイラー

概要

Receipt Compiler は、スマートフォンのカメラで撮影したレシート写真のフォルダーを、コピーした経費精算書類のような A4 PDF にまとめます。各レシートの傾きを補正し（透視変換、傾き補正）、白黒の「スキャン風」に変換して、均一な見た目のサイズで A4 に配置し、番号を付け、任意の表紙ページに概要をまとめます。

確認ゲートが必須の 4 つのサブコマンド：

1. scan — 各写真の傾き補正、スキャン風加工、OCR を行い、manifest.json を生成します
2. review — 抽出した経費一覧を表示します
3. confirm — ユーザーの承認を記録し、確認済みのデータを紐付けます（ダイジェスト）
4. pack — A4 PDF を作成します（confirm の実行前は実行できません）

使用する場面

• 「レシートを PDF にまとめて、経費精算に使いたい」
• 「このレシート写真から精算用書類を作成して」
• 「このレシートの傾きを補正して白黒にし、A4 に並べて」
• 対象外：フラットベッドスキャナーでのスキャン、請求書の PDF（pdf スキルを使用してください）。

前提条件

pip install opencv-python-headless pillow pillow-heif pytesseract reportlab numpy
# PyMuPDF is needed only to run the self-test (tests/), not the script itself

さらに、システムの tesseract-ocr が PATH に設定されている必要があります。tesseract --version で確認してください。

ワークフロー（エージェントはゲートに従う必要があります）

ステップ 1 — scan

python3 ~/.hermes/skills/productivity/receipt-compiler/scripts/receipt_compiler.py \
    scan <photos_dir> -o <workdir> [--mode bw|photo]

デフォルトの --mode bw は、ユーザーが求めているコピー風の見た目になります。グレースケールにするには --mode photo を使用してください。完了条件：写真ごとに 1 件のエントリーがある manifest が存在し、ocr_confidence と needs_review のフラグが設定されていること。

ステップ 2 — review + confirm（必須、ユーザーの確認が必要）

python3 .../receipt_compiler.py review <workdir>
# ... apply any corrections to manifest.json, THEN re-run review so the user
# ... sees the corrected table ...
python3 .../receipt_compiler.py review <workdir>
# ... after the user approves the corrected table ...
python3 .../receipt_compiler.py confirm <workdir>

表示された表をチャットでユーザーに提示します。次の点を確認してください。

1. 抽出された日付／店舗名／金額は正しいですか？必要に応じて manifest.json のフィールドを修正してください。
2. 任意の要件 — 毎回確認し、決めつけないでください：
   • 表紙ページ（申請者／期間／メモを記載）
   • レシートごとの番号バッジ
   • レシートごとのキャプション（日付 · 店舗名 · 金額）
   • 合計への通貨記号の表示
3. 除外 — 外すレシートはありますか（"include": false）？
4. 表紙に記載する目的／メモのテキスト。

ユーザーの承認を得てから、confirm <workdir> を実行します。これにより confirmed: true が設定され、承認時点で確認したフィールドに対する review_digest が紐付けられます。confirm の実行後に変更（日時、金額、通貨、対象に含めるかどうか）があると、再度 confirm を実行するまで pack は拒否されます。その場合、変更後の表をもう一度ユーザーに提示する必要があります。回避フラグはありません。confirm の実行前に、ユーザーの修正を manifest.json に反映してください。

ステップ 3 — pack

python3 .../receipt_compiler.py pack <workdir> -o claim.pdf \
    [--cover --number --captions] \
    --title "Expense Claim — <purpose>" --claimant "MH" --period "..." --notes "..."

完了条件：PDF が存在し、JSON 出力でページ数が報告されていること。 その後、現在のチャンネルで PDF をドキュメント／ファイルとしてユーザーに送信します。

レイアウトルール（レシートの配置方法）

• A4 縦、余白 15 mm、間隔 5 mm。
• 非常に縦長のレシート（縦横比 ≥ 2.2）は、行全体の高さを使って 1 行に 3 枚配置します。 通常のレシートは 1 行に 2 枚配置し、コンテンツ領域の高さの 52%（ページ全体の約 47%）を上限とします。拡大縮小はセル単位です （各レシートはセルいっぱいに配置されます）。レシートの少ない行ではセルの幅が広くなります。
• すべての画像は縦横比を保って拡大縮小します。歪みや切り抜きはありません。
• レシートはページをまたいで配置されます。30 枚以上でも問題なく収まります。
• 縦長のレシートが通常のレシートより先に印刷されます。必要に応じて manifest で順序を変更してください。

よくある落とし穴

1. 確認ゲートを省略する — pack は confirmed: false、ブール値以外の確認値、確認後の編集（ダイジェストチェック）で必ず失敗します。 バイパスフラグはありません。まずユーザーに表を確認してもらう必要があります。
2. 暗い写真や影のある写真 — 2/98 パーセンタイルのストレッチでほとんどの場合に対応できます。OCR の信頼度が 55 未満の場合、または金額が抽出されなかった場合、その項目には needs_review のフラグが付けられます。 これらの項目をユーザーに提示してください。
3. 射影変換の失敗 — 光沢のあるレシートやしわの寄ったレシートでは、きれいな四角形を検出できない場合があります。その場合、スクリプトはフレーム全体に対して小角度の傾き補正を行います。 マニフェストの method を確認してください。明らかにトリミングが必要なレシートで deskew になっている場合は、PIL で手動でトリミングするか、現在のフレーミングをそのまま使用してください。
4. HEIC 写真 — iPhone の写真は .heic 形式です。pillow-heif がインストールされていれば処理できます。インストールされていない場合は、ユーザーに JPG を依頼するか、pillow-heif をインストールしてください。
5. 複数の通貨 — 合計は通貨ごとに集計されます（レビュー出力と表紙には通貨ごとに 1 行ずつ表示され、合計額はまとめられません）。申請内容をすっきりさせるには、1 つのパックにつき通貨を 1 種類にしてください。合計額をまとめるために、有効な金額を 0 にしたり編集したりしないでください。
6. 表紙の表に入れる説明が長い — 説明は 70 文字で切り捨てられます。表紙の注記は短くするか、詳細を notes に記載してください。

検証チェックリスト

• scan により、写真ごとに項目を含む manifest.json が生成された
• review の表をユーザーに提示し、マニフェストに修正を反映した
• 任意の要件（表紙／番号付け／キャプション）を毎回確認した
• ユーザーの承認後にのみ confirm を実行した（confirmed を手動で編集しない）
• pack の出力 PDF が存在し、ページ数が想定と一致している
• 正しい出力パスの PDF をユーザーに送信した