0. CEO レビュー用サマリ
プロトタイプ完了: 既存 333 件を手動形式に変換し、新タブ 2026.6 交通費立替（自動） に書き出しました。
スプシ: SUICA 明細管理簿 — 最右端タブを確認してください。
| 確認項目 | 結果 |
|---|---|
| 新タブ名 | 2026.6 交通費立替（自動） |
| 書き出し行数 | 333 件（ヘッダー 1 行 + データ 333 行） |
| 対象期間 | 2025-07-04 〜 2026-06-06 （FY2025 全件） |
| 並び順 | 降順（新しい日付が上）— 手動タブと同じ |
| 列構成 | 月/日 | 種別 | 利用場所 | 種別 | 利用場所 | 残額 | 差額 | 備考 — 8 列同一 |
| 手動タブ無傷確認 | OK 11 枚の手動タブは一切変更なし |
| 本番 suica_poller | 未変更 出力先は SUICA_自動取込 のまま |
| バックアップ | _backups/20260610_002832_suica_all_sheets_before_auto_tab.json |
制約事項（OCR データ欠落）: 現在の PDF OCR はチャージ・バス等をスキップするため、自動タブには以下が含まれません。
- 欠落 チャージ行（ｵｰﾄ / VIEW）: 手動タブでは 38 件 + 2 件 = 40 件
- 欠落 バス等行（ﾊﾞｽ等）: 手動タブでは 12 件
- 欠落 別線乗換行（＊入）: 手動タブでは 6 件
- 欠落 残高データ（最古 PDF 分 39 件）: PDF の書式上取得不可
対応策は §4 に記載。CEO の判断を仰ぐ箇所も明示しています。
1. 背景と目的
従来の SUICA 自動取込パイプライン（Phase A）は、内部管理用の独自形式タブ SUICA_自動取込 に出力していた。しかし CEO が本来欲しかったのは「手動で年来維持してきた交通費立替シートと同じ形式」である。
本設計は、月次 PDF 投入による自動更新を手動形式に揃え、将来的に CEO が手動運用からこちらに移行できる状態を作ることを目的とする。
2. フォーマットマッピング定義
2-A. 列構成の対応
| 列 | 手動タブ（出力形式） | SUICA_自動取込（変換元） | 変換ルール |
|---|---|---|---|
| A | 月/日 |
発生日 (YYYY-MM-DD) | MM/DD に変換。月・日ともゼロ埋め 2 桁。例: 2026-05-08 → 05/08 |
| B | 種別（入側） |
— (固定値) | 乗車レコードは "入" 固定。チャージ行は §3 参照 |
| C | 利用場所（乗車駅） |
乗車駅 | そのまま転記 |
| D | 種別（出側） |
— (固定値) | "出" 固定。チャージ行は空欄 |
| E | 利用場所（降車駅） |
降車駅 | そのまま転記 |
| F | 残額 |
残高 (整数 JPY) | ¥付きカンマ区切り。例: 1068 → \1,068。残高なし(None)の場合は空欄 |
| G | 差額 |
利用金額 (正値 JPY) | 負値でマイナス表記。例: 528 → -528。チャージ行は空欄 |
| H | 備考 |
— (空欄) | 自動生成では空欄。チャージ行は "3000円チャージ" 等 (§3) |
2-B. 行種別の変換パターン
| 行種別 | 手動タブでの表現 | 自動変換後 | 備考 |
|---|---|---|---|
| 通常乗車 | 種別「入」+ 乗車駅 / 種別「出」+ 降車駅 | 完全対応 | 333 件すべてこのパターン |
| ｵｰﾄチャージ | 種別「ｵｰﾄ」+ チャージ駅 / 差額空欄 / 備考「3000円チャージ」 | OCR 欠落 | PDF OCR がスキップ済み。再 OCR で対応可（§4） |
| VIEWチャージ | 種別「VIEW」+ 備考「2000円チャージ」 | OCR 欠落 | 同上 |
| バス等 | 種別「ﾊﾞｽ等」+ 利用場所 / 差額あり | OCR 欠落 | PDF OCR で "交通利用" 抽出するが路線バスは別定義が必要 |
| 別線乗換（＊入） | 種別「＊入」+ 乗車駅 / 差額あり | OCR 欠落 | 通常の「入」に相当。OCR プロンプト改修で対応可 |
| 窓口出金 | 種別「窓出」等 | 未確認 | 当期データでは出現なし |
2-C. 実際の行例（先頭 5 件）
| 月/日 | 種別 | 利用場所（乗） | 種別 | 利用場所（降） | 残額 | 差額 | 備考 |
|---|---|---|---|---|---|---|---|
| 06/06 | 入 | 浦和 | 出 | 大宮 | \2,600 | -209 | |
| 06/06 | 入 | 大宮 | 出 | 浦和 | \2,391 | -209 | |
| 06/04 | 入 | 浦和 | 出 | 上野 | \3,249 | -440 | |
| 06/04 | 入 | 上野 | 出 | 浦和 | \2,809 | -440 | |
| 06/02 | 入 | 浦和 | 出 | 秋葉原 | \1,129 | -440 |
3. 会計年度・タブ振り分けルール
3-A. 会計年度の定義
コネクトエイトの会計年度は 7 月始まり・6 月締め。手動タブ名の「N.6」は「N 年 6 月末締め」を意味する。
| 会計年度 (FY) | 対象月 | 自動タブ名 | 対応手動タブ名 |
|---|---|---|---|
| FY2025 | 2025/07 〜 2026/06 | 2026.6 交通費立替（自動） |
2026.6 交通費立替 |
| FY2026 | 2026/07 〜 2027/06 | 2027.6 交通費立替（自動） |
（将来作成予定） |
タブ命名規則: {FY+1}.6 交通費立替（自動）
3-B. 降順ソートの実装
手動タブと同様に、新しい日付が上（降順）。同一日は SUICA_自動取込 内の出現順を維持。
4. 制約事項と今後の対応策
現状の自動タブに含まれないデータ（チャージ・バス等は OCR 時点でスキップされている）
| 欠落データ種別 | 手動タブ内件数 （FY2025） |
対応策 A（推奨） | 対応策 B |
|---|---|---|---|
| ｵｰﾄ / VIEW チャージ行 | 40 件 | PDF OCR プロンプトを拡張してチャージ行を含める | 手動タブからインポートするスクリプトを別途作成 |
| バス等行（ﾊﾞｽ等） | 12 件 | OCR プロンプトに「バス利用も含める」を追加 | 同上 |
| 別線乗換行（＊入） | 6 件 | OCR プロンプトの「交通利用のみ」定義を緩和 | 正規表現で ＊入 行を抽出 |
| 残高データなし（FY2025 最古 39 件） | 39 件 | PDF 再確認（古い PDF では残高列がない可能性） | 許容（残高は Freee 転記判断に不要） |
CEO への確認事項（要判断）
- チャージ行: 交通費精算の観点から、ｵｰﾄチャージは「残高の補充」であり支出ではない。精算対象に含めるかどうかは CEO の判断が必要。
- バス等・別線乗換: 対応策 A（OCR 拡張）は processed_ids リセット＋再処理が必要。実施するか否かを確認。
- 本番 poller の切り替えタイミング: プロトタイプ確認後、いつ本番 poller の出力先を自動タブに統合するかを確認。
5. 出力先方針（手動タブ保護）
2026.6 交通費立替2025.6 交通費立替2024.6 交通費立替- …（2019 年まで全 8 枚）
代表立替2020 その他立替等
読み取りのみ。書き込み・並べ替え・削除 絶対禁止。
2026.6 交通費立替（自動）2027.6 交通費立替（自動）（来期以降）
月次 PDF 投入で自動更新。手動タブへの移行は CEO 判断後。
スクリプト suica_manual_format_writer.py はタブ書き込み前に「手動タブ保護チェック」を実施。（自動）サフィックスのないタブへの書き込みは例外を throw して中断する。
6. 本番移行フロー（CEO 承認後）
（本設計書 + プロトタイプ確認）
（チャージ・バス等）
出力先追加
自動タブが更新
suica_poller 出力先変更の方針（承認後）
本番 poller は現状 SUICA_自動取込 に書いているため、以下の 2 段階で切り替える。
- Phase A-1（現状）: PDF 投入 → SUICA_自動取込（内部管理形式）に追記
- Phase A-2（移行後）: PDF 投入 → SUICA_自動取込 に追記（変更なし）＋ suica_manual_format_writer.py が自動タブを上書き更新（月次実行）
- Phase A-3（将来）: poller が直接自動タブに書き込む（SUICA_自動取込 廃止可能）
Phase A-2 は cron or LaunchAgent で月 1 回（月末）に suica_manual_format_writer.py を実行するだけで動く。
7. 実装ファイル
| ファイル | 役割 | 状態 |
|---|---|---|
suica_pipeline/suica_manual_format_writer.py |
SUICA_自動取込 → 手動形式タブ変換・書き出し | 実装済 |
suica_pipeline/suica_pipeline.py |
PDF 投入 → SUICA_自動取込 への書き込み（既存） | 変更なし |
suica_pipeline/com.connect8.upan.suica_poller.plist |
LaunchAgent（1 時間毎） | 変更なし |
_backups/20260610_002832_suica_all_sheets_before_auto_tab.json |
全タブバックアップ（作業前） | 取得済 |
suica_manual_format_writer.py の実行方法
# dry-run（確認のみ、書き込みなし） python3 suica_manual_format_writer.py --dry-run # 本番実行（新タブ作成 or 更新） python3 suica_manual_format_writer.py
処理フロー:
- SUICA_自動取込 から全レコードを読み込み
- 会計年度別にグループ化
- 降順ソート
- 手動保護チェック（タブ名に「（自動）」がなければ例外）
- 新タブ作成 or 既存タブのクリア → 再書き込み
- activity_log に報告
8. 検算メモ
残額・差額の符号検証
手動タブの残額は、乗車後の残高（その行の利用後）。差額はマイナスの利用金額。自動タブでも同じ定義を維持している。
| 項目 | 手動タブ（例） | 自動タブ（変換後） | 一致 |
|---|---|---|---|
| 残額形式 | \1,068 | \1,068 | 一致 |
| 差額形式 | -528 | -528 | 一致 |
| 差額ゼロ行 | （除外） | （除外） | 一致 |
| 残額なし行 | — (空欄) | （空欄） | 一致 |
金額の丸めゼロ確認
整数変換時に float() を経由するが、小数部が発生しない整数 JPY データのみ対象。OCR 結果が小数値の場合は手動チェックフラグで CEOに通知する設計（実装は Phase A-3 で追加予定）。
9. 本番 poller 未変更確認
確認済み: suica_pipeline.py の AUTO_SHEET_NAME = "SUICA_自動取込" は変更していない。LaunchAgent com.connect8.upan.suica_poller.plist も変更なし。
本番 poller が SUICA_自動取込 に書き続けても、自動タブには影響しない。次回 suica_manual_format_writer.py 実行時に差分が自動タブに反映される。