Documents

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

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

## コンテキスト

請求書PDFの生成には最大45秒かかる場合があり、同期処理ではAPI接続がタイムアウトまたは切断される。利用者がAPI応答を待ち続ける設計は安定しない。

## 決定

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

同期生成は、接続切断のリスクがあるため採用しない。

## 影響

### 利点

- 長時間のPDF生成によるAPI接続切断を避けられる。
- APIの応答時間を短く保てる。
- PDF生成処理をキューによって平準化・再実行できる。

### 欠点・留意点

- 利用者はPDFの完成まで待つ必要がある。
- 処理状況、完了通知または取得方法など、非同期処理向けの利用者体験が必要になる。
- キューやワーカーなどの運用対象が増える。
- 再試行の上限は未決定であり、別途決定する必要がある。上限を決める際は、重複生成、恒久的な失敗、運用コストへの影響を考慮する。

## 運用上の前提

1. APIは受付IDを返す。
2. 受付IDから処理状態を確認できる仕組みを用意する。
3. PDF完成後に利用者が取得できるようにする。
4. 失敗状態と再試行結果を利用者および運用者が確認できるようにする。
5. 再試行上限は未決定事項として追跡し、決定後に本ADRを更新する。

## 代替案

### 同期生成

APIリクエスト中にPDFを生成し、完成したPDFを同じ応答で返す案。最大45秒かかり接続が切れるため、不採用とした。

## 未決定事項

- PDF生成失敗時の再試行上限
- 完成通知の方式
- 受付IDによる処理状況確認APIの詳細