Artifacts

# ファイル取込 Design Doc

## 1. 概要

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

ファイル本体をキューへ登録する方式は、最大10MBのファイルがキューの1MB制限を超えるため採用しない。

## 2. 対象範囲

- APIによるファイル受付
- オブジェクトストレージへの保存
- 保存先情報のキュー登録
- ワーカーによるファイル取得・解析
- 解析結果のDB保存
- 保存失敗時のAPIエラー処理

キューへの登録失敗時の回復方法は、現時点では未決定とする。

## 3. 処理フロー

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

## 4. API仕様・エラー処理

### 4.1 保存成功時

オブジェクトストレージへの保存後に、保存先を示すキーまたはURIをキューへ登録する。APIレスポンスには、必要に応じて受付IDなど、非同期処理の状態を追跡できる識別子を含める。

### 4.2 保存失敗時

オブジェクトストレージへの保存に失敗した場合は、HTTP 503を返す。この場合、キューへの登録は行わない。

保存成功後にキュー登録が失敗した場合の回復方法は未決定であるため、実装前に以下を決定する必要がある。

- 再試行の有無と回数
- 再試行間隔およびバックオフ方式
- 未登録ファイルの検出方法
- 重複登録時の扱い
- 運用担当者による再処理方法

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

キューにはファイル本体を登録せず、少なくとも以下のメタデータを登録する。

- 受付IDまたはファイルID
- オブジェクトストレージ上の保存先キーまたはURI
- 必要に応じてファイル形式、サイズ、登録日時

保存先情報だけを登録することで、キューの1MB制限を回避する。最大10MBのファイル本体はオブジェクトストレージで扱う。

## 6. ワーカー処理

ワーカーはキューメッセージを受信後、保存先からファイルを読み込んで解析する。解析に成功した場合は、受付IDまたはファイルIDと紐付けて解析結果をDBへ保存する。

実装時には、少なくとも以下を考慮する。

- 保存先が存在しない場合のエラー処理
- 一時的な読み込み失敗時の再試行
- 同一メッセージの重複処理に対する冪等性
- 解析失敗時の状態記録と再処理方針
- DB保存失敗時に解析結果を失わない設計

## 7. 非同期処理に伴う利用者影響

解析を非同期化するため、ファイル受付から解析結果の提示までに遅延が発生する。利用者には受付完了と解析完了を区別して提示し、結果取得方法および処理状態を確認できる仕組みを用意する必要がある。

## 8. 未決定事項

- キュー登録失敗後の回復方法
- 解析処理の再試行および失敗時の扱い
- 処理状態を取得するAPIの詳細
- 解析完了通知の方式
- ファイル保持期間と削除タイミング

## 9. 実装計画

- 対象: DATA-64
- 関連PR: #203
- 今週の作業: API実装
- 担当: 佐藤

今週は、ファイルのオブジェクトストレージ保存、保存失敗時の503応答、保存先情報のキュー登録までを実装対象とする。キュー登録失敗時の回復仕様は、別途決定後に実装へ反映する。