Documents

# ファイル取込 Design Doc

## 1. 概要

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

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

## 2. 対象範囲

### 対象

- APIでのファイル受付
- オブジェクトストレージへのファイル保存
- キューへの保存先情報の登録
- ワーカーによるファイル取得・解析・DB保存
- 失敗時のステータス管理とログ出力

### 対象外・未決定事項

- キューへの登録失敗時の回復方法
- 利用者への解析結果通知方式
- リトライ回数やデッドレターキューの詳細設計

## 3. 処理フロー

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

## 4. API設計

### 4.1 ファイル取込API

例:

```http
POST /imports
Content-Type: multipart/form-data
```

#### 成功時

APIは以下を実行する。

1. 取込IDを発行する。
2. ファイルをオブジェクトストレージへ保存する。
3. 保存先情報を含むメッセージをキューへ登録する。
4. 非同期処理を受け付けたことを返す。

レスポンス例:

```http
202 Accepted
Content-Type: application/json
```

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

### 4.2 オブジェクトストレージの保存先

保存先キーは取込IDを含め、取込単位で一意になる形式とする。

例:

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

実装上は、利用者が指定したファイル名をそのままパスとして利用せず、パスインジェクションを防止する。必要に応じてファイル名はメタデータとして別途保持する。

### 4.3 保存失敗時

オブジェクトストレージへの保存に失敗した場合は、以下の動作とする。

- HTTP 503 Service Unavailableを返す
- キューには登録しない
- 取込処理を失敗として記録する
- クライアントが再試行可能なレスポンスにする

レスポンス例:

```http
503 Service Unavailable
```

```json
{
  "error": "file_storage_unavailable"
}
```

保存が成功したか不明なタイムアウトの場合は、同一取込IDまたは冪等性キーを利用して重複ファイルを作らない設計を検討する。

### 4.4 キュー登録メッセージ

キューにはファイル本体を載せず、保存先を特定するための情報だけを登録する。

例:

```json
{
  "import_id": "...",
  "object_key": "imports/.../source/file.csv",
  "content_type": "text/csv",
  "size_bytes": 10485760,
  "created_at": "2026-09-20T00:00:00Z"
}
```

メッセージには認証情報や一時URLを直接含めず、ワーカーが適切な権限でオブジェクトを取得する。

## 5. キュー登録失敗時

オブジェクトストレージへの保存後、キュー登録に失敗した場合の回復方法は未決定である。この状態では、ストレージ上にファイルが存在するがワーカーが処理できない孤児データが発生し得る。

実装時点では、少なくとも以下を記録する。

- 取込ID
- オブジェクトキー
- キュー登録の失敗理由
- リクエストID／トレースID
- 再処理対象であることを示すステータス

今後の決定候補:

- DBに取込状態を保存し、未登録状態を定期的に再送する
- Outboxパターンを利用する
- キュー登録を同期的にリトライする
- 運用者が再送できる管理機能を設ける

回復方法が決定するまでは、キュー登録失敗を成功扱いにせず、監視で検知できる状態にする。

## 6. ワーカー処理

ワーカーはキューからメッセージを受け取った後、以下を実行する。

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

解析またはDB保存に失敗した場合は、メッセージを即時ackせず、キューの再配信方針に従う。処理の重複に備え、`import_id`をキーとして解析結果の保存を冪等にする。

## 7. 状態管理

取込状態の例:

```text
received
storage_succeeded
queued
processing
completed
storage_failed
queue_registration_failed
processing_failed
```

状態更新は、API・ワーカー・運用処理のどこで更新したか追跡できるようにする。特に `queue_registration_failed` は、後続の回復処理対象として識別可能にする。

## 8. DB保存

解析結果は取込IDと紐付けて保存する。

最低限必要な項目:

- `import_id`
- 解析結果
- 処理ステータス
- エラー情報
- 作成日時
- 更新日時

同じメッセージが再配信されても、同一取込IDの結果が重複登録されないように、一意制約またはupsertを利用する。

## 9. エラー処理・監視

監視対象:

- オブジェクトストレージ保存失敗数
- キュー登録失敗数
- キュー滞留数・滞留時間
- ワーカー処理失敗数
- 再試行数
- `queue_registration_failed` の件数
- 解析完了までの所要時間

ログには取込ID、リクエストID、オブジェクトキー、エラー分類を含める。ただし、ファイル本体や機密情報はログに出力しない。

## 10. 非同期化による利用者影響

解析結果はAPIリクエスト中には返却せず、受付後にバックグラウンドで生成する。そのため、利用者が結果を確認できるまでの時間が従来より遅くなる。

結果提示方法は別途決定するが、当面は取込IDを返し、ステータス確認APIなどで処理状態を取得できる構成を前提とする。

## 11. セキュリティ・制約

- ファイルサイズ上限は10MBとする
- APIでContent-Type、拡張子、実体形式を検証する
- オブジェクトストレージのアクセス権はワーカーに限定する
- キューにはファイル本体を載せない
- ファイル名をパスとして直接信頼しない
- 必要に応じて保存ファイルを暗号化する
- 一定期間後に不要な原本を削除するライフサイクルを検討する

## 12. 実装・進行メモ

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

## 13. 未決事項

1. キュー登録失敗時の回復方法
2. キュー登録・ワーカー処理のリトライ回数
3. デッドレターキューの採用
4. 取込状態を管理するDBテーブルの確定
5. 利用者向けのステータス確認・結果通知方式
6. 原本ファイルの保持期間