受信メール添付を案件フォルダへ自動取込するパイプライン（2アプリ跨ぎ／原本保持／重複防止）

顧客がメールで送ってきた資料（マニュアル・図面・写真・見積等）を、案件ごとの 共有ドライブフォルダへ無人で保存する仕組みの作り方。メールを読むアプリと ドライブに書くアプリが別という現実的な構成を前提にする。

適用条件

• 受信メールを既にDBへ取り込んでいるアプリ A がある（Web/SaaS。例: 営業管理システム）
• 案件フォルダの場所を知っているアプリ B がある（例: スプレッドシート連動のスクリプト）
• A と B は別サービス・別認証。片方のロジックをもう片方に写すと二重管理になる

設計の要点（ここを外すと破綻する）

1. 「メールを読む側」と「ドライブに書く側」を分けたまま繋ぐ

書く側にメール読み取り権限を追加したくなるが、やらない。

• 権限スコープを増やすと再認証が終わるまで既存の初期化処理が黙って止まる （メニューが消える等）。実際に踏む事故
• 案件フォルダの解決ロジック（設定セル → 台帳の列 → 親フォルダ探索の優先順）は 書く側にしかない。読む側へ写すとフォルダ二重作成などの既知バグを再発させる

→ A に「添付の一覧」と「実バイト」を返す内部APIを足し、B が引いてドライブに書く。

2. 添付の実バイトは保存しない

DBやオブジェクトストレージに置かず、要求時にメールAPIから都度取得する。 メール側が原本を保持しているので冗長保存はコストだけ増える。 DBに持つのは座標（messageId / attachmentId / どのメールボックスか）のみ。

mailboxUser（どのアカウントを impersonate すれば取れるか）を必ず記録する。 複数メールボックスを巡回している場合、これが無いと後から実バイトを引けない。

3. 認証は既存の内部APIトークンを流用する

同種の内部APIが既にあるなら同じトークン環境変数を使い回す。 新しい秘密値を作ると、配布・設定作業が人間に発生する。

4. 実行時間制限のある環境では「予算3本立て」にする

スクリプト実行に上限（例: 6分）がある環境では、次の3つを別の値で持つ。

新しい案件に着手してよい締切   2.5分
1案件あたりの上限            3.0分
実行全体のハード締切          5.2分

不変条件は 着手締切 + 案件予算 < 実行上限。 「締切」と「予算」に同じ値を使うと、締切直前に着手した1件が単独で予算を使い切り上限を超えて死ぬ。 案件内ループにも呼び出し元のハード締切を渡してクランプする。

5. 保存対象が1件以上あると判ってからフォルダを解決する

フォルダ解決関数が「無ければ作る」実装なら、添付0件の案件で呼ぶと 空フォルダを全案件に作ってしまう。かつ解決は設定ファイルを開くので遅く、 全案件で回すと実行時間上限を超える。先に一覧を取り、0件なら即 return。

6. 重複防止は二重にする

• 取込ログ（案件ID / ファイル名 / messageId / attachmentId / 状態）を1行ずつ残し、 messageId:attachmentId をキーに二度目をスキップ
• 保存先の「同名＋同サイズ」照合もする。同じ添付が原メールと転送/返信の2通に 入ると messageId が別になり、ログキーでは弾けない（実際に起きる）
• 照合キーにはメールAPI申告サイズと実バイト長の両方を登録する。ずれると二重保存になる

7. エラー行を「決着済み」にしない

「取得できなかった」を恒久エラー扱いにすると、自分のバグを直した後もその添付が 永久にスキップされる。恒久扱いは構成上どうしても無理なものだけに限り、 それ以外は回数を数えて N 回（例: 3回）で諦める。 重複キー集合は「保存済み／意図的スキップ」だけから作る。

8. 分類はファイル名キーワードで、既定は中立に

下流の処理がファイル名で資料種別を判定している場合、保存時に接頭辞を付けると そのまま乗る。判定できないものは無理に分類せず中立な既定（メール添付_ 等）に落とす。 実際に届く名前は想定より素朴（1F平面.pdf 外観立面.pdf）なので、 実データを見てから辞書を足す。

9. 金額系ファイル（見積・請求）は保存する

読み取り側が名前キーワードで既に除外しているなら、保存段階で捨てると原本が残らない。 保存はする／AIに読ませない、を分ける。

10. ノイズ除外は保存側とAPI側の二段

条件	理由
image00N.png 等	署名・インライン画像の典型
.p7s .ics .vcf winmail.dat	メール由来の付随物
画像 かつ 30KB未満	ロゴ・アイコン
サイズ0 / 座標欠落	取得不能
上限超（例: 25MB）	保存はせず元メールへの直リンク付きでログに残す

実装で必ず踏む罠

• メールAPIは base64url を返す。標準base64しか復号できない環境では -→+ _→/ とパディングを補う。間違えるとファイルが静かに壊れる
• ドライブのURLの形では Office ファイルの変換有無を判定できない。 非変換のままでもエディタで開くURLを返す。判定はMIMEタイプとバイト数を見る。 変換を確実に避けたいなら、変換しないアップロードAPI（multipart upload）を使い、 失敗時は通常APIへフォールバックする（変換されるより取りこぼす方が悪い）
• RESTのDB APIは既定で行数上限（例: 1000件）で切る。limit を大きくしても増えない。 Range ヘッダ等でページングする。総数を誤認して到達率を誤判定した
• DBエラーオブジェクトを String() すると [object Object] になり原因が完全に隠れる。 message / details / hint / code を連結して返す
• ジョブキューに排他ロックがある場合、重い処理の実行中は後続が拾われない。 「結果が出ない＝死んだ」と早合点せず、ロック待ちを先に疑う
• タイムスタンプのタイムゾーンを読み違えると「数分経ったのに動かない＝壊れた」と誤診する
• 一覧APIと実バイトAPIの両方に案件識別パラメータを渡す。片方だけ渡して 「全件取得できない」になりやすい

案件↔顧客のマッチング（ここが本当の律速）

配管が動いても、メールをどの案件に紐づけるかで詰まる。

• 「アプリBの案件IDをアプリAに書き込んでリンクする」機能があっても、実運用では 一度も使われていないことがある。まず本番の件数を数える。0件なら別経路を設計する
• 案件IDを持つのは B 側だけ、という状況では B が自分の台帳を回して案件ごとに A を叩く （A 側から案件を列挙できない）
• メッセージの引き当ては複数経路の OR にする: ①案件レコード直結 ②顧客ID一致 ③送信元ドメイン一致（ただし顧客未確定のメールに限る）。 ③を顧客確定済みメールに広げると他社のメールを奪う
• 社名の正規化一致をかける前の事前絞り込みに生の社名を使うと敬称付き（「〜様」）が 当たらない。正規化文字列と生文字列の両方で候補を引いて union する （正規化だけにすると中黒等が落ちた社名が今度は当たらなくなる。どちらか一方では取りこぼす）

同一顧客の名寄せは「候補提示＋人の承認」にする

英語表記と日本語表記のように正規化では繋がらない同一顧客がいる。自動統合は禁物。

• 判定に使うのは 独自ドメインのメール一致（フリーメール・自社ドメインは除外）と 電話番号の完全一致（数字のみ正規化・桁数不足は内線として無効）
• info@ support@ 等ローカル部が共有語のアドレスは使わない。共有メールボックス経由の 他社問い合わせを誤って吸着する
• 承認と同じ重みで「却下」も記録する。 記録先が無いと「別法人だから繋げない」と 判断したペアが毎回また候補に出る
• ペアは (A,B) と (B,A) を同一視して正規化して保存する。逆順で別行になると復活する
• 承認済みの展開は双方向に1段だけ（再帰しない）。テーブル未作成・取得失敗時は 例外を投げず「広げないだけ」にする
• 承認の効果は顧客マスタを書き換えない設計にできる。専用テーブルに記録し、 この用途の解決処理だけが参照する。既存の売上・通知・担当の帰属を動かさずに済む
• ドメイン一致は「同一企業の表記揺れ」と「グループ内の別法人」が混在する。 だから人が判断する。自動承認は絶対にしない
• 非エンジニアが判断する導線を用意する。CLI出力だけでは読めない。 スプレッドシートへ一括出力し、判断列にドロップダウンを付ける

有効化の順序（重要）

共有ドライブのファイルは運用上あとから消せないことが多い。だから:

1. 読み取り専用の下見コマンドを先に作る（どの案件に何が入るか・除外理由つき）
2. その出力を依頼者に見せる
3. 1案件だけ実書き込みして着地を read-back で確認する
4. そこで初めて定期実行を有効化する

3 を飛ばすと、定期実行を入れた後に「全件エラーで保存0件」が判明する（実際に起きた）。

定期実行の登録

既存の定期実行がある環境では、登録前の削除をハンドラ名でフィルタする。 無条件に全削除すると他の定期処理を巻き添えで殺してアプリ全体が止まる。