Documents

# ファイル取込 Design Doc

## 1. 概要

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

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

## 2. スコープと前提

### 対象

- APIによるファイル受付
- オブジェクトストレージへの保存
- キューへの保存先情報の登録
- ワーカーによるファイル取得・解析
- 解析結果のDB保存
- 非同期処理状態の管理・通知に必要な基盤

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

- キューへの登録に失敗した場合の回復方法
- 利用者への解析結果提示方法の詳細
- リトライ回数、バックオフ、デッドレターキューの具体値
- オブジェクトストレージ、キュー、DBの製品固有設定

## 3. 確定した設計

1. APIはファイル本体をオブジェクトストレージへ保存する。
2. 保存成功後、保存先をキューへ登録する。
3. オブジェクトストレージへの保存に失敗した場合、APIは503を返し、キューには登録しない。
4. ワーカーはキューに含まれる保存先からファイルを読み込む。
5. ワーカーは解析結果をDBへ保存する。
6. ファイル本体はキューへ載せない。

## 4. 処理フロー

```text
利用者
  │ ファイル送信
  ▼
API
  │ 1. ファイル保存
  ▼
オブジェクトストレージ
  │ 保存成功
  ▼
API
  │ 2. 保存先情報を登録
  ▼
キュー
  │ 3. メッセージ取得
  ▼
ワーカー
  │ 4. オブジェクトストレージから取得
  │ 5. 解析
  │ 6. 解析結果を保存
  ▼
DB
```

### API側の処理

1. リクエストを受け付ける。
2. 取込IDを発行する。
3. ファイルをオブジェクトストレージへ保存する。
4. 保存に失敗した場合、503を返して処理を終了する。この場合、キューには登録しない。
5. 保存成功後、取込IDと保存先情報を含むメッセージをキューへ登録する。
6. キュー登録成功後、非同期受付を示すレスポンスを返す。

### ワーカー側の処理

1. キューからメッセージを取得する。
2. メッセージに含まれる保存先からファイルを読み込む。
3. ファイルを解析する。
4. 解析結果を取込IDと関連付けてDBへ保存する。
5. 正常終了後にキューメッセージを正常処理済みとして確定する。

## 5. API設計

### 受付API

具体的なパス、認証方式、Content-Type、最大ファイルサイズは既存API規約に合わせて決定する。

#### 成功時

- HTTPステータス: 非同期受付を表すステータス（例: `202 Accepted`）
- レスポンスには少なくとも取込IDを含める。
- 利用者は取込IDを使って処理状態または解析結果を確認できる設計とする。

例:

```json
{
  "import_id": "<取込ID>",
  "status": "accepted"
}
```

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

- HTTPステータス: `503 Service Unavailable`
- キューには登録しない。
- レスポンスには再試行可能な一時障害であることを示す。

例:

```json
{
  "error": "storage_unavailable",
  "message": "ファイルを保存できませんでした。時間をおいて再試行してください。"
}
```

## 6. キューメッセージ

キューにはファイル本体ではなく、処理に必要な参照情報のみを登録する。

例:

```json
{
  "message_version": 1,
  "import_id": "<取込ID>",
  "object_key": "<オブジェクトキー>",
  "content_type": "<Content-Type>",
  "file_size": 10485760,
  "created_at": "<登録日時>"
}
```

### 実装上の注意

- `object_key` は利用者入力をそのまま使わず、取込ID等を用いて衝突しない値を生成する。
- メッセージには認証情報やファイル本体を含めない。
- ワーカーが再実行されても同じ取込結果を重複作成しないよう、`import_id`を冪等性キーとして扱う。
- メッセージ形式にはバージョンを持たせる。

## 7. データモデル案

実際のスキーマは既存DB規約に合わせる。

### 取込管理

| 項目 | 説明 |
|---|---|
| `import_id` | 取込を一意に識別するID |
| `status` | `accepted`、`processing`、`completed`、`failed`等 |
| `object_key` | オブジェクトストレージ上の保存先 |
| `file_size` | ファイルサイズ |
| `content_type` | ファイル種別 |
| `created_at` | 受付日時 |
| `updated_at` | 更新日時 |
| `error_code` | 失敗時の内部エラーコード |

### 解析結果

- `import_id`を外部キーまたは一意キーとして保持する。
- 冪等性を担保するため、`import_id`単位で重複登録を防止する。
- 解析結果保存前に、取込状態を`processing`へ更新する。

## 8. エラー処理

### API

| 失敗箇所 | 動作 |
|---|---|
| 入力不正 | 既存API規約に従った4xxを返す |
| オブジェクトストレージ保存失敗 | 503を返し、キューへ登録しない |
| キュー登録失敗 | 回復方法は未決定。暫定動作と運用方針を別途決定する |

### ワーカー

| 失敗箇所 | 暫定方針 |
|---|---|
| オブジェクトストレージからの取得失敗 | リトライ可能なエラーとして扱う方針を検討する |
| 解析失敗 | 取込状態を失敗に更新し、原因を記録する |
| DB保存失敗 | 重複登録を防止できる形で再実行可能にする |

キュー登録失敗は、ファイルがオブジェクトストレージに存在する一方で処理が開始されない状態を生むため、設計上の主要な未決定事項である。候補として、送信ログの永続化と再送ジョブ、アウトボックスパターン、定期的な未処理オブジェクト検出を比較検討する。

## 9. 非同期処理と利用者体験

非同期化により、受付完了から解析結果の提示まで遅延が発生する。APIのレスポンスでは処理完了を示さず、受付済みであることを明示する。

利用者への結果提示方法は以下から決定する。

- 取込IDによるステータス・結果取得API
- 完了通知
- 既存画面のポーリング

少なくとも、処理中、完了、失敗を利用者が判別できる状態管理を実装する。

## 10. セキュリティ・信頼性

- オブジェクトストレージは非公開設定とし、ワーカーのみに必要な読み取り権限を付与する。
- ファイル名、Content-Type、サイズはサーバー側で検証する。
- オブジェクトキーに利用者入力を直接使用しない。
- ログにファイル本体、認証情報、機密性の高い解析内容を出力しない。
- ストレージ、キュー、DBへの接続失敗をメトリクス化する。
- 取込IDを相関IDとしてAPI、キュー、ワーカー、DBのログに記録する。

## 11. テスト観点

### API

- ファイル保存成功後にキュー登録されること。
- ファイル保存失敗時に503が返ること。
- ファイル保存失敗時にキュー登録されないこと。
- 10MBファイルをキューへ載せず、保存先情報のみが登録されること。
- キュー登録失敗時の現状動作が記録され、未決定事項として扱われること。

### ワーカー

- キューの保存先から正しいファイルを取得できること。
- 解析結果が正しい取込IDでDBへ保存されること。
- 同一メッセージの再処理で結果が重複しないこと。
- ストレージ取得失敗、解析失敗、DB保存失敗を区別できること。

### 結合・障害試験

- ストレージ障害時のAPIレスポンスとキュー未登録を確認する。
- キューとストレージの連携を確認する。
- ワーカー再起動後に処理を継続できることを確認する。
- 大容量ファイルを含む代表的なサイズで処理時間とリソース使用量を確認する。

## 12. 実装計画

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

API実装では、まずファイル保存、保存失敗時の503応答、キュー登録の順序、保存先情報を含むメッセージ生成を実装する。キュー登録失敗時の回復方式は、別途設計判断を行ったうえで実装範囲を確定する。

## 13. 未決定事項と決定タスク

| 論点 | 状態 | 次のアクション |
|---|---|---|
| キュー登録失敗時の回復 | 未決定 | 再送ログ、アウトボックス、未処理検出を比較して決定 |
| 非同期結果の提示方法 | 未決定 | ステータス取得、通知、ポーリングから選定 |
| ワーカーのリトライ・DLQ | 未決定 | 障害種別と運用要件に基づき決定 |
| ファイル保持期間 | 未決定 | 解析完了後の削除可否と監査要件を確認 |
| APIの具体的なパス・認証 | 既存規約確認待ち | 既存API仕様に合わせて確定 |

## 14. 受け入れ条件

- APIが受け取ったファイルをオブジェクトストレージへ保存できる。
- 保存成功後に保存先情報がキューへ登録される。
- 保存失敗時は503を返し、キュー登録が発生しない。
- ワーカーが保存先からファイルを取得し、解析結果をDBへ保存できる。
- ファイル本体がキューメッセージに含まれない。
- 取込IDを用いて受付から解析結果まで追跡できる。
- キュー登録失敗時の回復方式が別途決定され、設計・実装に反映される。