Documents

# ファイル取込 Design Doc

## 1. 概要

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

## 2. 背景と目的

- APIリクエスト中に解析処理を実行せず、APIの処理時間と負荷を抑える。
- ファイル本体をキューに載せず、キューのメッセージサイズ制限に収める。
- 解析処理をワーカーに分離し、再実行や水平スケールを可能にする。

非同期化により、利用者が解析結果を確認できるまでの時間は同期処理より遅くなる。この遅延は本方式の前提とする。

## 3. 確定事項

- APIはファイル本体をオブジェクトストレージへ保存する。
- 保存成功後、保存先をキューへ登録する。
- オブジェクトストレージへの保存に失敗した場合、APIはHTTP 503を返し、キューには登録しない。
- ワーカーは保存先からファイルを読み込み、解析結果をDBへ保存する。
- ファイル本体をキューへ載せる方式は採用しない。想定ファイルサイズ10MBに対し、キューのメッセージサイズ上限が1MBのため。
- キューへの登録失敗時の回復方法は未決定であり、本Design Docでは確定しない。

## 4. 処理フロー

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

## 5. API仕様（実装方針）

### 5.1 リクエスト

- APIはファイルをmultipart/form-data等で受け付ける。
- ファイルサイズ上限は、少なくとも想定上限10MBを考慮して設定する。
- 受信したファイルには一意な取込IDを付与する。

### 5.2 オブジェクトストレージへの保存

保存先キーには、他の取込と衝突しない値を使用する。例：

```text
imports/{import_id}/source
```

保存時には、実体とあわせて以下のメタデータを管理できるようにする。

- 取込ID
- 元ファイル名
- Content-Type
- ファイルサイズ
- 保存日時
- ハッシュ値（必要に応じて）

保存に失敗した場合は以下を行う。

1. エラーをログへ出力する。
2. HTTP 503 Service Unavailableを返す。
3. キューへの登録処理を実行しない。
4. クライアントが再試行可能なレスポンスであることを明示する。

### 5.3 キューへのメッセージ

キューにはファイル本体ではなく、ワーカーが取得に必要な情報だけを登録する。例：

```json
{
  "import_id": "01J...",
  "object_key": "imports/01J.../source",
  "content_type": "application/pdf",
  "created_at": "2026-09-22T00:00:00Z"
}
```

実際のキューサービスに応じて、バケット名、オブジェクトURI、バージョンIDなどを追加する。

### 5.4 APIレスポンス

キュー登録まで成功した場合は、解析完了を待たずに受付結果を返す。推奨例：

- HTTP 202 Accepted
- 取込ID
- 状態確認用のリソース情報（提供する場合）

```json
{
  "import_id": "01J...",
  "status": "queued"
}
```

解析結果はAPIレスポンスには含めず、別途状態確認APIまたは既存の結果参照手段で取得する。

## 6. ワーカー処理

ワーカーはキューからメッセージを受け取ったら、次の順で処理する。

1. メッセージから取込IDとオブジェクトキーを取得する。
2. オブジェクトストレージからファイルを読み込む。
3. ファイル形式・サイズ等の入力検証を行う。
4. ファイルを解析する。
5. 解析結果をDBへ保存する。
6. 成功時にキューのメッセージを完了扱いにする。

### 6.1 DB保存

取込IDを一意キーとして扱い、同一メッセージが再配信された場合でも解析結果が重複しないようにする。DB保存は冪等に実装する。

推奨する状態例：

- `queued`: キュー登録済み
- `processing`: ワーカー処理中
- `completed`: 解析結果保存済み
- `failed`: 解析または保存に失敗

状態更新と解析結果保存の整合性を保つため、可能な範囲で同一トランザクションにまとめる。

### 6.2 エラー処理

- オブジェクトストレージからの読み込み失敗：一時障害か恒久障害かを判定し、キューサービスの再試行機構に従う。
- 解析失敗：取込状態を`failed`にし、原因を記録する。
- DB保存失敗：結果が保存できるまでメッセージを再処理可能にする。
- 再処理時に既に`completed`の場合は、重複保存せず成功扱いにする。

リトライ回数、デッドレターキューへの移送条件、失敗ファイルの保持期間は実装時に決定する。

## 7. 重要な未決事項

### キュー登録失敗時の回復方法

オブジェクトストレージへの保存後、キュー登録に失敗すると、ファイルは保存済みだがワーカーへ届かない状態になる。回復方法は未決定である。

候補として以下があるが、採用案は別途決定する。

- DBに取込状態と保存先を記録し、定期ジョブが未登録データを再送する。
- Outboxパターンでキュー登録要求を永続化する。
- キュー登録失敗時に同期リトライする。
- オブジェクトストレージのイベント通知を利用する。

この事項が決まるまで、キュー登録処理の失敗時にファイルを削除するか、保存済みファイルをどの期間保持するかも確定しない。

## 8. 非機能要件・実装上の注意

- 10MBのファイルを扱えるAPI、オブジェクトストレージ、ワーカーの設定にする。
- キューにはファイル本体を格納しない。メッセージサイズは1MB未満に収める。
- オブジェクトストレージのアクセス権はワーカーに必要最小限だけ付与する。
- ログには取込IDを必ず含め、API、キュー、ワーカー、DBの処理を追跡できるようにする。
- ファイル名やContent-Typeなどの外部入力をログやキーに利用する場合は、エスケープおよびバリデーションを行う。
- 一時ファイルは処理完了後に削除し、メモリにファイル全体を保持し続けない。
- APIのタイムアウトは、ファイル保存完了までを基準に設定する。解析完了は待機しない。
- 監視対象として、保存失敗数、キュー登録失敗数、キュー滞留時間、ワーカー失敗数、解析完了時間を計測する。

## 9. テスト観点

- ファイル保存成功後にキューへ正しい保存先が登録されること。
- ファイル保存失敗時にHTTP 503が返り、キュー登録されないこと。
- 10MBのファイルを処理できること。
- キューのメッセージにファイル本体が含まれないこと。
- ワーカーが保存先からファイルを取得し、解析結果をDBへ保存できること。
- 同一メッセージの再配信で結果が重複しないこと。
- オブジェクトストレージ読み込み失敗、解析失敗、DB保存失敗時に想定した再試行・状態遷移になること。
- APIが解析完了を待たず、受付完了を返すこと。

## 10. スコープと進行状況

- 今週の実装範囲：API実装
- 担当：佐藤
- 関連チケット：DATA-64
- 関連PR：#203

今週は、ファイル保存、保存失敗時の503応答、キュー登録に必要なメッセージ生成、および受付レスポンスまでを実装対象とする。キュー登録失敗時の回復機構は未決定のため、実装範囲外として明示的に扱う。