Documents

# ADR: 請求書PDF生成を非同期キュー処理にする

- **決定日**: 2026-08-20
- **ステータス**: 採用
- **関連**: BILL-218、PR #106

## コンテキスト

請求書PDFの生成には最大45秒かかる場合がある。同期的に生成すると、処理中にAPI接続が切断される可能性があるため、利用者に安定して受付結果を返せない。

## 決定

請求書PDFの生成はキューに投入して非同期で処理する。APIはPDFそのものを待って返却せず、処理の受付IDを返す。

利用者は受付IDを使って処理状況および生成結果を確認し、PDFの完成後に取得する。

## 却下した選択肢

### 同期生成

同期的にPDFを生成してAPIレスポンスで返す方式は採用しない。最大45秒の処理時間により、API接続が切断される可能性があるためである。

## 影響

### 利点

- 長時間のPDF生成中もAPI接続を維持する必要がない。
- APIは受付IDを速やかに返せる。
- PDF生成処理をキューおよびワーカー側で管理できる。

### 欠点・利用者への影響

- PDFが完成するまで利用者は待つ必要がある。
- 利用者またはクライアントは、受付IDを保持して状況確認と結果取得を行う必要がある。
- 生成失敗時の状態や、再試行の扱いを利用者に伝える必要がある。

## 運用上の留意事項

- 受付IDと生成状態の対応を追跡できるようにする。
- 未完了、完了、失敗などの状態をクライアントが判別できるようにする。
- 生成完了後のPDF取得方法と、失敗時のエラー通知方法を維持する。
- キュー滞留やワーカー停止により、完成までの時間が延びる可能性を監視する。

## 未決事項

- 再試行回数の上限は未決定である。運用開始前、または実運用での失敗率・コスト・重複生成の影響を確認したうえで決定する。
- 受付IDの有効期限、状態確認の方式、PDFの保存期間は必要に応じて別途決定する。

## 進捗・出典メモ

原資料の作業メモには、BILL-218、PR #106、進捗70%と記録されている。進捗は本ADRの採否を示すものではなく、関連作業の進行状況を示すメモとして扱う。