Documents

# ファイル取込 Design Doc

## 1. 概要

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

## 2. 背景・目的

- APIリクエスト内での解析処理を避け、APIの応答時間と負荷を抑える。
- 最大10MBのファイルを扱う。
- ファイル本体をキューへ登録する案は、キューの1MB制限を超えるため採用しない。

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

## 3. 処理フロー

```text
利用者
  │ ファイル送信
  ▼
API
  │ 1. ファイルをオブジェクトストレージへ保存
  │ 2. 保存先情報をキューへ登録
  ▼
キュー ───────────────► ワーカー
                              │ 保存先からファイル取得
                              │ ファイル解析
                              ▼
                            DBへ解析結果保存
```

### API

1. リクエストからファイルを受け取る。
2. 一意な取込IDとオブジェクトキーを生成する。
3. ファイルをオブジェクトストレージへ保存する。
4. 保存成功後、キューへメッセージを登録する。
5. 受付完了と取込IDを返す。

キューメッセージにはファイル本体を含めず、少なくとも以下を含める。

- 取込ID
- オブジェクトストレージの保存先（バケット、オブジェクトキー等）
- 必要に応じてファイル名、Content-Type、サイズ、登録日時

### ワーカー

1. キューからメッセージを取得する。
2. メッセージに含まれる保存先からファイルを読み込む。
3. ファイルを解析する。
4. 解析結果をDBへ保存する。
5. 成功時にキューメッセージを正常終了（ACK等）する。

解析失敗、ファイル取得失敗、DB保存失敗時の再試行・隔離方法は、既存のキュー運用方針に従う。既存方針がない場合は別途決定する。

## 4. エラー処理

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

- APIはHTTP 503 Service Unavailableを返す。
- キューにはメッセージを登録しない。
- 取込IDや保存先の扱いは、ストレージ側の保存結果を確認できる実装とする。

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

回復方法は未決定であり、本Design Docでは確定しない。実装前に以下のいずれかを決定する必要がある。

- APIで失敗を返し、後続の再登録処理を行う。
- 永続的な中間状態をDB等へ記録し、再送ジョブで登録する。
- Outbox等を利用して保存とキュー登録の整合性を補償する。
- 保存済みファイルを一定期間後に削除する運用を設ける。

登録失敗時に保存済みファイルだけが残る可能性があるため、回復方法とあわせて不要ファイルのクリーンアップ方針も決定する。

## 5. API設計の実装方針

- APIは解析結果を待たず、キュー登録完了後に受付結果を返す。
- レスポンスには取込IDを含め、利用者が後から状態・結果を照会できるようにする。
- 解析結果の状態（例: `accepted`、`processing`、`completed`、`failed`）を管理する設計を推奨する。
- 同一リクエストの再送に備え、必要に応じて冪等性キーを受け付ける。
- ファイルサイズ上限（10MB）、Content-Type、認証・認可、保存先へのアクセス権をAPIで検証する。

## 6. データ・整合性

取込IDをAPI、キューメッセージ、オブジェクトキー、解析結果で共通利用する。これにより、処理追跡と障害調査を可能にする。

DBには少なくとも以下の状態を保持することを推奨する。

- 取込ID
- オブジェクト保存先
- 受付日時
- 処理状態
- 処理開始日時・完了日時
- エラー情報（必要な場合）

キュー登録失敗時のDB記録方法は、回復方法の決定時に確定する。

## 7. 運用・監視

以下を監視対象とする。

- オブジェクトストレージ保存失敗数、HTTP 503数
- キュー登録失敗数
- キュー滞留数・処理遅延
- ワーカーの解析失敗数・再試行数
- DB保存失敗数
- 保存後にキュー登録されていないファイル数
- 受付から解析結果保存までの所要時間

## 8. 未決事項

1. キュー登録失敗時の回復方式。
2. キュー登録失敗後に残るオブジェクトの削除・保持期間。
3. ワーカーの再試行回数、バックオフ、デッドレターキュー運用。
4. 解析結果の状態照会APIの仕様。
5. 解析失敗時に利用者へ提示するエラー内容。
6. 保存済みファイルの暗号化、保持期間、アクセス制御。

## 9. 進行メモ

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

## 10. 実装チェックリスト

- [ ] ファイルサイズ上限10MBを検証する
- [ ] オブジェクトストレージへファイルを保存する
- [ ] 保存失敗時に503を返し、キュー登録しない
- [ ] キューメッセージにファイル本体を含めず保存先を含める
- [ ] 取込IDを一貫して付与・記録する
- [ ] キュー登録失敗を検知・記録する
- [ ] 受付レスポンスを非同期処理前提で実装する
- [ ] キュー登録失敗時の回復方法を実装前に確定する
- [ ] API・キュー・ワーカーの監視項目を追加する