Documents

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

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

## コンテキスト

請求書のPDF生成には時間がかかり、同期処理では最大45秒を要する場合がある。その間API接続を維持すると、タイムアウトや接続切断によって利用者が結果を受け取れない可能性がある。

一方、非同期処理を採用すると、利用者はPDF生成が完了するまで待つ必要がある。また、生成失敗時の再試行上限は現時点で未決定である。

## 決定

請求書のPDF生成はキューを介した非同期処理として実装する。APIはPDFそのものを同期的に返さず、処理を受け付けたことを示す受付IDを返す。

利用者またはクライアントは、受付IDを用いて処理状況および生成結果を確認する。PDF生成が完了するまで待機が必要であることを、API仕様および利用者向けUIで明示する。

同期生成は採用しない。最大45秒の処理時間により、API接続が切断されるリスクがあるためである。

## 影響

### 利点

- 長時間のPDF生成によるAPI接続のタイムアウト・切断を回避できる。
- APIサーバーとPDF生成処理を分離でき、処理の負荷を制御しやすい。
- キューによって処理量を平準化できる。

### 欠点・運用上の注意

- 利用者は受付直後にPDFを取得できず、生成完了まで待つ必要がある。
- クライアントは受付IDを保持し、状態確認または完了通知の仕組みを扱う必要がある。
- キュー滞留やワーカー停止が、PDF完成までの時間に影響する。
- 失敗時の再試行上限が未決定であり、無限再試行や過剰な再試行を防ぐ運用設計が必要である。

## 実装・運用方針

- 受付IDは一意に生成し、生成処理と請求書を関連付ける。
- APIレスポンスには、受付ID、現在の処理状態、および状態確認方法を含める。
- 少なくとも「受付済み」「処理中」「完了」「失敗」を識別できる状態を管理する。
- 生成完了後は、受付IDからPDFを取得できるようにする。
- キューの滞留時間、処理時間、成功率、失敗件数、再試行回数を監視する。
- 再試行上限、バックオフ方式、最終失敗時の扱いは別途決定し、本ADRまたは関連ADRを更新する。

## 未決事項

1. PDF生成失敗時の再試行上限
2. 再試行間隔およびバックオフ方式
3. 最終失敗時の利用者への通知方法
4. 状態確認APIのポーリング間隔または完了通知方式
5. 受付IDおよび生成済みPDFの保持期間

## 進捗

原資料の作業メモでは進捗70%と記録されている。実装の完了条件と未完了項目は、BILL-218およびPR #106を参照する。