Documents

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

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

## コンテキスト

請求書PDFの生成には最大45秒かかる。同期的に生成するとAPI接続が長時間維持され、接続が切断される可能性がある。そのため、生成完了までAPIリクエストを待機させる方式は安定しない。

## 決定

請求書PDFの生成はキューを利用した非同期処理として実装する。APIはPDFそのものを返さず、生成依頼を受け付けたことを示す受付IDを返す。利用者または呼び出し元は、その受付IDを使って生成状況や完成したPDFを確認する。

## 却下した選択肢

### 同期生成

同期生成では、生成完了まで最大45秒かかり、処理中に接続が切れる可能性があるため採用しない。

## 結果

### 利点

- API接続の長時間維持を避けられる。
- PDF生成処理をキューで分離でき、APIの応答性を保ちやすい。
- 一時的な負荷増加に対して、処理をキューに蓄積できる。

### 欠点・留意点

- 非同期処理のため、利用者はPDFが完成するまで待つ必要がある。
- 生成状況の確認方法と、完成後のPDF取得方法が必要になる。
- 生成失敗時の通知・再処理方針が必要になる。
- 再試行の上限は、この決定時点では未決定である。実装時に別途決定し、設定値と運用方針を文書化する。

## 追加検討事項

- 受付IDの状態モデル（受付済み、処理中、完了、失敗など）
- ポーリングまたは通知による完成確認方式
- PDFの保持期間と再取得可否
- 冪等性の扱い
- 再試行回数、間隔、対象エラー、最終失敗時の扱い

## 参考

原資料の作業メモには、関連作業として **BILL-218**、**PR #106**、進捗 **70%** と記載されている。進捗は作業メモ時点の情報であり、本ADRの採否を示すものではない。