Documents

# ファイル取込 Design Doc

## 1. 概要

ファイル取込処理を非同期化する。APIは受け付けたファイル本体をオブジェクトストレージへ保存し、保存先情報をキューへ登録する。ワーカーはキューから保存先情報を取得してファイルを読み込み、解析結果をDBへ保存する。

## 2. 背景・目的

- ファイル本体をキューに載せず、キューのサイズ制限を回避する。
- APIと解析処理を分離し、解析処理をワーカーで非同期実行する。
- 10MBのファイルを扱えるようにする。ファイル本体をキューに載せる案は、キューの1MB制限を超えるため採用しない。

## 3. 処理フロー

```text
利用者
  │ ファイル送信
  ▼
API
  │ 1. ファイルをオブジェクトストレージへ保存
  ├─ 保存失敗 ──> 503を返却（キュー登録なし）
  │
  │ 2. 保存先をキューへ登録
  ▼
キュー
  │ 保存先情報
  ▼
ワーカー
  │ 3. オブジェクトストレージからファイル取得
  │ 4. ファイル解析
  │ 5. 解析結果をDBへ保存
  ▼
DB
```

## 4. コンポーネント仕様

### 4.1 API

1. リクエストからファイルを受け取る。
2. ファイルをオブジェクトストレージへ保存する。
3. 保存成功後、キューへ保存先を登録する。
4. 非同期処理の受付結果を利用者へ返す。

キューへ登録する情報には、少なくとも以下を含める。

- オブジェクトストレージ上の保存先（バケット、キーなど）
- 取込処理を識別するID（必要な場合）
- 受付日時またはリクエストID（必要な場合）

ファイル本体はキューへ登録しない。

### 4.2 オブジェクトストレージ

- APIが受け付けたファイル本体を保存する。
- ワーカーがキューから取得した保存先を使って読み込む。
- 保存先キーは取込処理を一意に識別できる形式とする。

### 4.3 キュー

- メッセージにはファイル本体ではなく、オブジェクトストレージの保存先を登録する。
- ワーカーへの処理依頼を非同期で伝達する。
- メッセージの再配信や重複配信を考慮し、ワーカー処理は冪等にする。

### 4.4 ワーカー

1. キューから保存先情報を取得する。
2. 保存先からファイルを読み込む。
3. ファイルを解析する。
4. 解析結果をDBへ保存する。
5. 成功時にキューのメッセージを正常終了させる。

ファイル取得、解析、DB保存のいずれかに失敗した場合のリトライ・失敗メッセージの扱いは、利用するキューの標準機能と既存方針に合わせて実装する。重複実行により解析結果が二重登録されないよう、取込処理IDなどをキーに冪等性を確保する。

## 5. エラー処理

### 5.1 オブジェクトストレージへの保存失敗

- APIはHTTP 503を返す。
- キューへの登録は行わない。
- 保存が部分的に成功する可能性がある場合は、孤立オブジェクトを残さないための削除または後続のクリーンアップ方法を実装時に確認する。

### 5.2 キューへの登録失敗

オブジェクトストレージへの保存後にキュー登録が失敗した場合の回復方法は未決定である。このため、以下は設計上の未決事項として残す。

- キュー登録のリトライ方法・回数・間隔
- 保存済みオブジェクトを再登録する仕組み
- 未登録オブジェクトの検知方法
- APIのレスポンス方針
- 二重登録時の扱い

キュー登録失敗時にファイルが保存済みであるため、単純にAPIリクエストを再実行すると同一ファイルが重複保存される可能性がある。回復方法が決まるまで、保存先と取込処理の状態を追跡できる設計を妨げないように実装する。

## 6. 利用者への影響

解析は非同期で実行されるため、API受付直後には解析結果を返せない。非同期化により、利用者が結果を確認できるまでの時間が従来より遅くなる可能性がある。

結果提示方法（ステータス確認API、通知など）は本資料では未確定とする。APIは受付処理と解析完了を分離し、取込処理を識別できるIDを返せる構造にしておくことが望ましい。

## 7. 採用しない案

### ファイル本体をキューへ登録する

不採用。対象ファイルが10MBであり、キューの1MB制限を超えるため。

## 8. 実装スコープ

今週はAPI実装を行う。

- 担当: 佐藤
- 関連チケット: DATA-64
- 関連PR: #203
- ファイルのオブジェクトストレージ保存
- 保存成功後のキュー登録
- オブジェクトストレージ保存失敗時の503返却
- 保存失敗時にキュー登録しない制御
- キューへ登録する保存先情報の定義

ワーカー実装、解析結果のDB保存、キュー登録失敗時の回復方法は、別タスクまたは後続作業として扱う。ただしAPI実装では、ワーカーが利用できる保存先情報と処理IDをメッセージに含められるようにする。

## 9. 未決事項

1. キュー登録失敗時の回復方法。
2. キュー登録失敗時にAPIが返すステータスとレスポンス。
3. 保存済みオブジェクトのクリーンアップ方針。
4. ワーカーのリトライ、デッドレター、重複処理の詳細。
5. 利用者への解析結果提示方法。

## 10. 受け入れ条件

- APIがファイルをオブジェクトストレージへ保存できる。
- 保存成功後、保存先情報がキューへ登録される。
- ファイル本体がキューに登録されない。
- オブジェクトストレージへの保存に失敗した場合、APIが503を返す。
- オブジェクトストレージへの保存に失敗した場合、キューへ登録されない。
- ワーカーがキューの保存先情報からファイルを取得し、解析結果をDBへ保存できる設計になっている。
- キュー登録失敗時の未決事項が実装上追跡可能な形で残る。