Documents

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

- **ステータス:** 採用
- **決定日:** 2026-08-20
- **関連:** BILL-218、PR #106
- **原資料の進捗:** 70%

## コンテキスト

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

## 決定

請求書PDFの生成はキューを利用した非同期処理とする。

1. APIはPDF生成要求を受け付ける。
2. APIは生成処理をキューに登録する。
3. APIは、受付を識別するための受付IDを返す。
4. ワーカーがキューから要求を取得し、請求書PDFを生成する。
5. 利用者は受付IDを使って生成状況または完成したPDFを確認する。

## 採用しなかった案

### 同期生成

APIリクエスト中にPDFを生成し、完成したPDFを直接返す方式は採用しない。最大45秒かかり、接続が切れるためである。

## 影響

### 利点

- 長時間のPDF生成中にAPI接続を維持する必要がない。
- APIは受付IDを速やかに返せる。
- ワーカー数やキューの処理能力を調整しやすい。
- 一時的な処理失敗に対して、再試行の仕組みを設けられる。

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

- PDFはAPI呼び出し時点では完成していない。
- 利用者は完成まで待つ必要がある。
- 生成状況、完了通知、取得方法などの非同期フローを提供する必要がある。
- キュー滞留やワーカー障害により、完成までの時間が延びる可能性がある。

## 運用上の留意点

- 受付IDと生成要求の状態を永続化する。
- 少なくとも「受付済み」「処理中」「完了」「失敗」を識別できるようにする。
- 受付IDだけで他の利用者の請求書を取得できないよう、認可を行う。
- キューの滞留件数、処理時間、失敗件数を監視する。
- 同一要求の重複登録や、重複したPDF生成への対策を検討する。
- 失敗時の再試行上限は未決定である。無限再試行を避けるため、上限、再試行間隔、最終失敗時の扱いを別途決定する。

## 未決事項

- 再試行回数の上限
- 再試行間隔とバックオフ方式
- 生成完了・失敗の通知方法
- 受付IDによる状態確認APIの仕様
- 完成したPDFの保存期間と再取得可能期間
- 再試行上限に達した要求の運用対応

## 参考

- 課題: BILL-218
- プルリクエスト: PR #106
- 原資料の作業メモに記載された進捗: 70%