Artifacts

# ファイル取込 Design Doc

## 1. 概要

ファイル本体をオブジェクトストレージに保存し、保存先をキューへ登録する非同期取込方式を採用する。ワーカーはキューから保存先を取得し、オブジェクトストレージ上のファイルを読み込んで解析し、結果をDBへ保存する。

## 2. 背景と制約

- ファイル本体をキューに載せる方式は不採用とする。
  - キューのメッセージ上限は1MB。
  - 取込対象ファイルは最大10MBであり、制限を超える可能性がある。
- 非同期処理のため、利用者が解析結果を確認できるまでの時間は従来より遅くなる。

## 3. 処理フロー

### API

1. APIがファイルを受け取る。
2. ファイルをオブジェクトストレージへ保存する。
3. 保存に成功した場合、保存先を示す情報をキューへ登録する。
4. リクエストには受付済みを示すレスポンスを返す。

保存に失敗した場合は、以下のように処理する。

- HTTP 503を返す。
- キューには登録しない。
- クライアントが再試行できるよう、エラーを記録する。

### ワーカー

1. キューから保存先情報を受け取る。
2. オブジェクトストレージからファイルを読み込む。
3. ファイルを解析する。
4. 解析結果をDBへ保存する。
5. 成功時にメッセージを完了扱いにする。

## 4. メッセージ設計

キューにはファイル本体ではなく、少なくとも次の情報を含むメッセージを登録する。

```json
{
  "job_id": "取込ジョブを一意に識別するID",
  "object_key": "オブジェクトストレージ上の保存先",
  "created_at": "受付日時"
}
```

`object_key` は利用者入力をそのままパスとして使用せず、サーバー側で生成した一意なキーを使用する。ワーカーが解析結果とジョブを対応付けられるよう、`job_id` を必須とする。

## 5. API仕様の方針

- 保存成功かつキュー登録成功の場合、非同期受付済みとしてジョブIDを返す。
- オブジェクトストレージへの保存失敗時は503を返す。
- 保存成功後にキュー登録が失敗した場合の回復方法は未決定であり、実装前に仕様を確定する。
- 非同期処理中の状態確認方法（ジョブ状態取得APIなど）は、既存のAPI設計に合わせて決定する。

## 6. エラー処理と運用上の注意

### 保存失敗

保存処理の失敗を検知したら、キュー登録を行わず503を返す。不要な一時オブジェクトが残る場合は、削除またはライフサイクル設定を検討する。

### キュー登録失敗

オブジェクトストレージへの保存後にキュー登録が失敗すると、ファイルは保存済みだが処理されない状態になり得る。回復方法は未決定のため、少なくとも以下を記録できるようにする。

- `job_id`
- オブジェクトストレージのキー
- キュー登録の失敗内容
- リトライ回数と最終失敗時刻

回復方式の候補には、登録リトライ、未処理ジョブの定期スキャン、再送可能な中間状態のDB管理などがあるが、採用案は別途決定する。

### ワーカー処理失敗

解析またはDB保存に失敗した場合は、メッセージを再処理可能な状態にする。再試行回数、恒久失敗時の隔離先、重複処理を防ぐための冪等性については、利用するキューと既存基盤の仕様に合わせて設計する。

## 7. 実装方針

- API実装では、保存処理とキュー登録処理を明確に分離する。
- 保存先キーとジョブIDを生成し、ログおよび後続処理で一貫して利用する。
- 外部サービスのタイムアウト、失敗、再試行回数を監視可能にする。
- ワーカーはキューのメッセージからファイルを取得し、ファイル本体をメッセージとして扱わない。
- 解析結果のDB保存は、同一ジョブの再処理を考慮して冪等にする。
- 結果提示の遅延を利用者へ伝えられるよう、受付状態と処理状態を区別する。

## 8. 未決事項

1. APIがオブジェクトストレージへの保存後にキュー登録へ失敗した場合の回復方法。
2. キュー登録失敗時にAPIへ返すHTTPステータスと利用者向けメッセージ。
3. ジョブ状態の保持先と状態確認APIの仕様。
4. ワーカーの再試行回数、デッドレター処理、重複実行時の扱い。
5. 保存済みだが未処理となったオブジェクトの削除・再送・保持期間。

## 9. 進行状況

- 今週の対象: API実装
- 担当: 佐藤

作業追跡情報は、チケットまたは進捗管理文書で管理する。