Artifacts

# ファイル取込 Design Doc

## 1. 概要

APIで受け付けたファイルをオブジェクトストレージへ保存し、保存先をキューへ登録する。ワーカーはキューから保存先を取得し、オブジェクトストレージ上のファイルを読み込んで解析し、解析結果をDBへ保存する。

## 2. 背景・目的

ファイル解析を非同期化し、APIのリクエスト処理と解析処理を分離する。ファイル本体をキューに載せる方式は、10MBのファイルがキューの1MB制限を超えるため採用しない。

## 3. 処理フロー

1. クライアントがAPIへファイルを送信する。
2. APIがファイルをオブジェクトストレージへ保存する。
3. 保存に成功した場合、保存先を示す情報をキューへ登録する。
4. APIが受付結果をクライアントへ返す。
5. ワーカーがキューから保存先を取得する。
6. ワーカーがオブジェクトストレージからファイルを読み込む。
7. ワーカーがファイルを解析する。
8. ワーカーが解析結果をDBへ保存する。

## 4. API仕様

### 成功時

- ファイルをオブジェクトストレージへ保存する。
- キューへ保存先を登録する。
- 非同期処理であることを示す受付結果を返す。
- 解析結果は受付時点では確定していないため、利用者への結果提示は後続処理となる。

### オブジェクトストレージ保存失敗時

- HTTPステータス `503 Service Unavailable` を返す。
- キューには登録しない。
- クライアントが再試行可能なエラーとして扱えるよう、エラー内容を記録する。

### キュー登録失敗時

回復方法は未決定である。保存済みオブジェクトを残し、失敗を検知できるログ・メトリクスを出力する。自動リトライ、再登録用ジョブ、定期的な未登録オブジェクト検出のいずれを採用するかは、実装開始前に決定する。

## 5. キューメッセージ

キューにはファイル本体を登録せず、少なくとも以下の情報を含む保存先情報を登録する。

- オブジェクトストレージのバケットまたはコンテナ
- オブジェクトキー
- 取込要求を一意に識別するID
- 必要に応じてファイル名、Content-Type、サイズなどのメタデータ

10MBのファイル本体はキューの1MB制限を超えるため、キューメッセージには含めない。

## 6. ワーカー実装方針

- キューメッセージから保存先を取得する。
- 保存先からファイルをストリーミングまたは適切な方法で読み込む。
- 解析結果をDBへ保存する。
- 同一メッセージの再処理に備え、取込要求IDを用いて冪等に結果を保存できるようにする。
- オブジェクト取得失敗、解析失敗、DB保存失敗を区別して記録する。
- 失敗時の再試行・デッドレターキューへの送付方針は、既存のキュー運用ルールに従う。ルールがない場合は、ワーカー実装前に運用担当と決定する。

## 7. 整合性・障害時の扱い

APIでは、オブジェクトストレージへの保存成功後にキュー登録を行う。保存に失敗した場合はキュー登録を行わない。キュー登録に失敗すると、保存済みオブジェクトが未処理のまま残る可能性がある。この状態を追跡できるよう、取込要求ID、保存先、各処理の成否をログまたは管理用データに記録する。

## 8. 利用者への影響

解析を非同期化するため、API受付直後には解析結果を提示できない。利用者が結果を確認する方法（ステータス照会API、通知、画面更新など）は別途設計する。少なくとも、受付状態と処理完了状態を識別できる取込要求IDを返す設計を推奨する。

## 9. 監視・運用

以下を監視対象とする。

- オブジェクトストレージ保存失敗数
- キュー登録失敗数
- キュー滞留数・処理遅延
- オブジェクト取得失敗数
- 解析失敗数
- DB保存失敗数
- キュー登録されていない保存済みオブジェクトの件数

エラーには取込要求IDとオブジェクトキーを含め、追跡可能にする。

## 10. 今回のスコープ

- 今週：API実装
- 担当：佐藤
- 関連課題・PR：進行管理資料を参照

## 11. 未決事項

1. キューへの登録失敗時の回復方法（自動リトライ、再登録ジョブ、補償処理など）。
2. 解析結果を利用者へ提示する方式。
3. ワーカーの失敗時リトライおよびデッドレターキューの運用。
4. 保存済みだがキュー未登録のオブジェクトを検出・回収する仕組み。
5. APIの詳細なレスポンス形式、認証・認可、ファイルサイズ上限。

## 12. 決定事項

- ファイル本体はオブジェクトストレージへ保存する。
- キューには保存先を登録する。
- オブジェクトストレージ保存失敗時は503を返し、キューには登録しない。
- ワーカーは保存先からファイルを読み、解析結果をDBへ保存する。
- 10MBのファイル本体をキューに載せる方式は採用しない。