# 機能設計書 75-ファイル削除

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおけるアップロード済みファイルの削除機能について記載する。

### 本機能の処理概要

ファイル削除機能は、システムにアップロードされたファイルをストレージから削除する機能である。ファイルキー（ID）を指定して削除を実行し、ストレージプロバイダーから対象ファイルを物理的に削除する。

**業務上の目的・背景**：
ECサイト運用において、不要になった商品画像や古いインポートファイルを削除してストレージ容量を管理する必要がある。また、誤ってアップロードしたファイルの即時削除や、商品の削除に伴う関連画像のクリーンアップなど、ファイル管理のライフサイクル全体をサポートする。

**機能の利用シーン**：
- 商品画像の差し替え時に古い画像を削除
- 使用しなくなったインポートCSVファイルの削除
- 誤アップロードファイルの即時削除
- ストレージ容量管理のための定期クリーンアップ
- 商品削除時の関連画像の連動削除

**主要な処理内容**：
1. ファイルキー（ID）の受信
2. ストレージプロバイダーへの削除リクエスト
3. 削除完了レスポンスの返却

**関連システム・外部連携**：
- ファイルモジュール（File Module）
- ストレージプロバイダー（S3、GCS、ローカル等）

**権限による制御**：
- 管理者権限を持つユーザーのみ操作可能
- APIキー認証によるアクセス制御

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | 商品メディア編集画面 | 主画面 | 商品画像の削除処理 |

## 機能種別

ファイル操作 / 削除処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| id | string | Yes | 削除対象のファイルキー（ファイルID） | 有効なファイルキー |

### 入力データソース

- 管理画面からのREST API呼び出し
- DELETE /admin/uploads/{id}

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | 削除されたファイルキー |
| object | string | オブジェクト種別（"file"） |
| deleted | boolean | 削除成功フラグ（true） |

### 出力先

- REST APIレスポンス（JSON形式）
- ストレージプロバイダー（ファイル削除）

## 処理フロー

### 処理シーケンス

```
1. APIリクエスト受信
   └─ DELETE /admin/uploads/{id}
2. ファイルキー取得
   └─ req.params.idからキー取得
3. ワークフロー実行
   └─ deleteFilesWorkflow
4. プロバイダー削除
   └─ FileProviderService.delete()
5. レスポンス返却
   └─ { id, object: "file", deleted: true }
```

### フローチャート

```mermaid
flowchart TD
    A[APIリクエスト受信] --> B[ファイルキー取得]
    B --> C[ワークフロー開始]
    C --> D[deleteFilesStep]
    D --> E[FileModuleService.deleteFiles]
    E --> F[FileProviderService.delete]
    F --> G{削除成功?}
    G -->|Yes| H[成功レスポンス]
    G -->|No| I[エラーレスポンス]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-01 | 物理削除 | ファイルはストレージから物理的に削除 | 削除実行時 |
| BR-75-02 | 復元不可 | 削除後のファイルは復元不可 | 削除完了後 |
| BR-75-03 | 参照確認なし | 他リソースからの参照有無は確認しない | 現行実装 |

### 計算ロジック

該当なし

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 削除 | - | - | DBへの直接操作なし（ストレージ操作） |

### ストレージ操作詳細

| 操作 | プロバイダーメソッド | 入力 | 出力 |
|-----|---------------------|------|------|
| 削除 | delete() | ProviderDeleteFileDTO | void |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 404 | NOT_FOUND | 指定ファイルが存在しない | 正しいファイルキーを指定 |
| 401 | UNAUTHORIZED | 認証失敗 | 有効なトークンを使用 |
| 500 | INTERNAL_ERROR | プロバイダーエラー | プロバイダー設定確認 |

### リトライ仕様

ストレージプロバイダーの削除失敗時はワークフローエラー。クライアント側でリトライ。

## トランザクション仕様

- ファイル削除はストレージ操作のため、DBトランザクションなし
- ワークフローの補償アクション（ロールバック）は不可（物理削除のため）

## パフォーマンス要件

- 単一ファイル削除のため特別な要件なし
- バッチ削除は内部的にサポート（deleteFiles(ids[])）

## セキュリティ考慮事項

- 管理者APIのため認証必須
- 削除操作の監査ログ記録（推奨）
- 他リソースからの参照チェックは呼び出し元の責任

## 備考

- ファイル取得API（GET /admin/uploads/{id}）も同じルートファイルで提供
- 削除前にファイルが他のリソース（商品画像等）から参照されていないか確認推奨
- 一括削除はワークフロー内部でサポート

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

削除処理の入出力データを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | delete-files.ts | `packages/core/core-flows/src/file/workflows/delete-files.ts` | DeleteFilesWorkflowInput型 |

**読解のコツ**: idsフィールドがstring[]で、複数ファイルの一括削除に対応。

#### Step 2: エントリーポイントを理解する

API呼び出しの起点を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | [id]/route.ts | `packages/medusa/src/api/admin/uploads/[id]/route.ts` | GET/DELETEハンドラ |

**主要処理フロー**:
1. **37-52行目**: DELETEハンドラの定義
2. **41行目**: req.params.idでファイルキー取得
3. **43-45行目**: deleteFilesWorkflow呼び出し（配列で渡す）
4. **47-51行目**: 削除成功レスポンス返却

#### Step 3: ワークフローを理解する

削除処理のビジネスロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | delete-files.ts | `packages/core/core-flows/src/file/workflows/delete-files.ts` | 削除ワークフロー |

**主要処理フロー**:
- **4行目**: DeleteFilesWorkflowInput型定義
- **29-34行目**: ワークフロー定義
- **32行目**: deleteFilesStepの呼び出し（input.ids）

#### Step 4: サービス層を理解する

モジュールサービスの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | file-module-service.ts | `packages/modules/file/src/services/file-module-service.ts` | deleteFilesメソッド |
| 4-2 | file-provider-service.ts | `packages/modules/file/src/services/file-provider-service.ts` | プロバイダーdeleteメソッド |

**主要処理フロー**:
- **80-89行目（file-module-service.ts）**: deleteFiles - 削除メソッド
- **84-87行目**: 入力をfileKeyオブジェクトに変換
- **43-48行目（file-provider-service.ts）**: delete - プロバイダー呼び出し

### プログラム呼び出し階層図

```
DELETE /admin/uploads/{id} (route.ts)
    │
    └─ deleteFilesWorkflow
           │
           └─ deleteFilesStep
                  │
                  └─ FileModuleService.deleteFiles()
                         │
                         └─ FileProviderService.delete()
                                │
                                └─ IFileProvider.delete()
                                       └─ S3/GCS/Local etc.
```

### データフロー図

```
[入力]                    [処理]                              [出力]

DELETE /admin/uploads/    deleteFilesWorkflow
  {id}                      │
    │                       ├─> ids配列化                      {
    │                       │   [id]                             id: "file_xxx",
    │                       │                                    object: "file",
    │                       ├─> FileModuleService                deleted: true
    │                       │   .deleteFiles([id])             }
    │                       │
    │                       └─> FileProviderService
    │                           .delete([{fileKey: id}])
    │
    └───────────────────────> ストレージから削除
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| [id]/route.ts | `packages/medusa/src/api/admin/uploads/[id]/route.ts` | ソース | 取得・削除エンドポイント |
| delete-files.ts | `packages/core/core-flows/src/file/workflows/delete-files.ts` | ソース | 削除ワークフロー |
| delete-files.ts | `packages/core/core-flows/src/file/steps/delete-files.ts` | ソース | 削除ステップ |
| file-module-service.ts | `packages/modules/file/src/services/file-module-service.ts` | ソース | ファイルモジュールサービス |
| file-provider-service.ts | `packages/modules/file/src/services/file-provider-service.ts` | ソース | プロバイダーラッパー |
