Artifacts

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

- **ステータス:** 採用
- **決定日:** 2026-08-20
- **関連:** BILL-218、PR #106（作業メモ時点の進捗: 70%）

## コンテキスト

請求書PDFの生成には最大45秒かかる場合があり、同期処理ではAPI接続が切れる可能性がある。同期生成を採用すると、利用者や呼び出し元が長時間レスポンスを待つことになり、タイムアウトや再送の扱いも複雑になる。

## 決定

請求書PDFの生成はキューに投入して非同期で処理する。APIは生成完了を待たず、受付IDを返す。受付IDを使って、後続の処理で生成状況や結果を確認できるようにする。

## 影響

### 利点

- API接続が最大45秒維持されることによる切断リスクを避けられる。
- PDF生成処理をワーカー側で実行でき、APIの応答性を保てる。
- キューによる負荷平準化や処理の再実行を設計しやすい。

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

- API呼び出し時点ではPDFは完成していない。
- 利用者は、PDFの完成まで待つか、受付IDで状態を確認する必要がある。
- キュー滞留やワーカー障害により、完成までの時間が延びる可能性がある。

## 却下した選択肢

同期生成は採用しない。最大45秒かかるため、処理中に接続が切れるリスクがあるためである。

## 未決事項

生成処理の再試行回数の上限は未決定である。障害時の重複生成、キュー滞留、恒久的失敗の扱いを踏まえて、運用開始前に決定する必要がある。

## 将来の保守者向け注意

同期レスポンスでPDF本体を返す実装へ変更する場合は、接続タイムアウト、負荷特性、利用者が完成を待つ必要がある点を再評価すること。非同期処理を変更する際は、受付IDと生成状態の対応、および再試行上限の決定を併せて見直すこと。