Artifacts

# ファイル取込 Design Doc

## 1. 概要

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

ファイル本体をキューへ直接載せる方式は、キューのメッセージ上限が1MBであり、最大10MBのファイルを扱えないため採用しない。

## 2. 処理フロー

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

## 3. API仕様

### リクエスト

- ファイル本体をリクエストで受け取る。
- ファイルサイズ上限は10MBとする。
- 受付時に処理を同期完了させず、非同期処理として扱う。

### 成功時

オブジェクトストレージへの保存およびキュー登録が完了した場合、受付成功を返す。レスポンスには、取込処理を追跡するための取込IDを含める。

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

- HTTPステータス503を返す。
- キューには登録しない。
- 後続のワーカー処理を発生させない。

### キュー登録失敗時

オブジェクトストレージへの保存後にキュー登録が失敗した場合の回復方法は未決定である。実装では、失敗を検知できるログおよび監視情報を残し、回復方式の決定後に差し替えられる構造にする。ストレージ上にファイルが残るため、孤児ファイルの扱いも回復方式と併せて決定する。

## 4. オブジェクトストレージ

### 保存内容

最低限、以下の情報を管理する。

- 取込ID
- オブジェクトキー
- 元ファイル名
- ファイルサイズ
- Content-Type
- 受付日時

オブジェクトキーには取込IDなどの一意な値を使用し、ファイル名の衝突を避ける。キューにはファイル本体ではなく、取込IDとオブジェクトキーなどの保存先情報のみを登録する。

## 5. キュー

メッセージには以下を含める。

- 取込ID
- オブジェクトストレージのバケットまたはコンテナ情報
- オブジェクトキー
- 必要なメタデータ

キューのメッセージサイズ制限を超えないよう、ファイル本体は含めない。

## 6. ワーカー

ワーカーは次の順序で処理する。

1. キューからメッセージを取得する。
2. 指定されたオブジェクトストレージのオブジェクトを読み込む。
3. ファイルを解析する。
4. 解析結果をDBへ保存する。
5. 成功時にキューメッセージを完了扱いにする。

読み込み、解析、DB保存のいずれかに失敗した場合は、再実行可能な設計とする。解析結果の重複保存を防ぐため、取込IDをキーとした冪等性を確保する。

## 7. DB

取込状態を管理し、少なくとも以下の状態を記録する。

- 受付済み
- 保存済み
- キュー登録済み
- 処理中
- 完了
- 失敗

解析結果は取込IDと関連付けて保存する。利用者が非同期処理の進捗および結果を確認できるよう、状態取得方法は既存API設計に合わせて実装する。

## 8. エラー処理・運用

- オブジェクトストレージ保存失敗は503として返し、キュー登録を行わない。
- キュー登録失敗は検知、記録、監視できるようにする。回復処理は別途決定する。
- ワーカー処理は再試行を考慮する。
- 解析結果保存は冪等にする。
- ストレージに残った未処理ファイルを特定できるよう、取込IDとログを関連付ける。
- 非同期化により、API受付から利用者が結果を確認できるまでの時間が遅くなる。UIまたは結果取得APIでは処理中状態を提示する。

## 9. 実装範囲と進行状況

- チケット: DATA-64
- 関連PR: #203
- 今週の実装対象: API実装
- 担当: 佐藤

今週は、ファイル受信、オブジェクトストレージ保存、保存失敗時の503応答、およびキュー登録までを主な対象とする。キュー登録失敗時の回復方式は未決定事項として残す。