02.store-upload-history

アップロード履歴の保存

概要説明

アップロード履歴保存機能により、クライアントはGoogle Cloud Storageへのファイルアップロードに関するメタデータを保存できます。この機能は、ファイル名、GCSパス、アップロードステータス、エラー理由などのアップロードされたファイルに関する情報を保存します。この履歴は、アップロードの進行状況の追跡、失敗したアップロードのデバッグ、ファイル管理操作の監査証跡の提供に使用されます。

Swaggerリンク

API: アップロード履歴API

ケースドキュメント

ケース1: 成功したアップロード履歴の保存

説明

クライアントがアップロード履歴を追跡するために、正常にアップロードされたファイルに関するメタデータを保存します。

シーケンス図

sequenceDiagram
    participant Client
    participant API as UploadGcsController
    participant Service as ImportReviewService
    participant Repository as ReviewUploadHistoryRepository
    participant Database as Database
    
    Note over Client,Database: アップロード履歴保存フロー
    
    rect rgb(200, 255, 200)
    Note right of Client: 成功ケースフロー
    
    Client->>API: POST /api/v1/general/upload-file/gcs/upload-history
    
    rect rgb(200, 230, 255)
    Note right of API: 入力検証
    API->>API: StoreUploadHistoryRequestを使用したリクエストデータの検証
    end
    
    rect rgb(200, 255, 255)
    Note right of API: ビジネスロジック
    API->>Service: createHistory(request->all())
    Service->>Service: ログインユーザーとグループの情報を取得
    Service->>Repository: create(historyData)
    Repository->>Database: INSERT INTO review_upload_histories
    Database-->>Repository: 作成されたレコードを返す
    Repository-->>Service: ReviewUploadHistoryモデルを返す
    Service-->>API: 履歴データを返す
    end
    
    API-->>Client: 200 OK (履歴データ)
    end
    
    rect rgb(255, 200, 200)
    Note right of Client: エラー処理
    rect rgb(255, 230, 230)
    alt 検証エラー
        API-->>Client: 422 検証エラー
    else データベースエラー
        Database-->>Repository: データベースエラー
        Repository-->>Service: エラー結果
        Service-->>API: エラー結果
        API-->>Client: 400 Bad Request
    else サービスエラー
        Service-->>API: エラー結果
        API-->>Client: 400 Bad Request
    end
    end
    end

ステップ

ステップ1: アップロード履歴の送信

  • 説明: クライアントがファイルアップロード成功後に履歴データを送信
  • リクエスト: POST /api/v1/general/upload-file/gcs/upload-history
  • パラメータ:
    • file_name: アップロードされたファイル名（必須）
    • gcs_path: ファイルが保存されているGoogle Cloud Storageのパス（必須）
    • error_reason: アップロード失敗時のエラーメッセージ（オプション）
  • バリデーション:
    • ファイル名は文字列で255文字以下である必要があります
    • GCSパスは文字列である必要があります
    • エラー理由は文字列で255文字以下である必要があります（提供される場合）

ステップ2: 履歴保存の処理

  • 説明: システムがユーザーとグループのコンテキストでアップロード履歴を保存
  • アクション:
    • 現在ログインしているユーザー情報を取得
    • グループメンバーシップからユーザーのグループIDを取得
    • user_id、group_id、提供されたデータで履歴レコードを作成
    • デフォルトステータスを'Notyet'（0）に設定

ステップ3: 履歴データを返す

  • 説明: 作成された履歴レコードをクライアントに返す
  • レスポンス:
    • 成功: 200 OK（ID、タイムスタンプ、リレーションシップを含む完全な履歴データ）
    • エラー: 適切なエラーコードとメッセージ

データベース関連テーブルとフィールド

erDiagram
    review_upload_histories {
        bigint id PK
        bigint user_id FK "usersテーブルへの参照"
        bigint group_id FK "groupsテーブルへの参照"
        string file_name "アップロードされたファイル名"
        string gcs_path "ファイルが保存されているGoogle Cloud Storageのパス"
        tinyInteger status "アップロードステータス: 0=未処理, 1=処理中, 2=成功, 3=失敗"
        string error_reason "アップロード失敗時のエラーメッセージ（null可）"
        timestamp validated_at "ファイルが検証された時刻（null可）"
        timestamp created_at
        timestamp updated_at
    }
    users {
        bigint id PK
        string name "ユーザーのフルネーム"
        string email "ユーザーのメールアドレス"
    }
    groups {
        bigint id PK
        string name "グループ名"
    }

    review_upload_histories ||--o{ users : 所属
    review_upload_histories ||--o{ groups : 所属

エラー処理

  • ログ記録
    • 履歴保存エラーはアプリケーションログに記録されます
  • エラー詳細:
    ステータスコード エラーメッセージ 説明
    422 検証失敗 リクエストパラメータが無効な場合
    400 履歴を保存できません データベース操作が失敗した場合

ケース2: 失敗したアップロード履歴の保存

説明

クライアントがデバッグのために、エラー情報を含む失敗したファイルアップロードのメタデータを保存します。

ステップ

ステップ1: 失敗したアップロード履歴の送信

  • 説明: クライアントがエラー情報を含むアップロード履歴を送信
  • リクエスト: POST /api/v1/general/upload-file/gcs/upload-history
  • パラメータ:
    • file_name: アップロードに失敗したファイル名
    • gcs_path: 意図したGCSパス
    • error_reason: 失敗を説明する詳細なエラーメッセージ

ステップ2: 失敗した履歴保存の処理

  • 説明: システムがエラーコンテキストで失敗したアップロード履歴を保存
  • アクション:
    • error_reasonフィールドが入力された履歴レコードを保存
    • 成功したアップロードと同じユーザーとグループコンテキストを維持
    • エラー追跡とデバッグ機能を有効化

ステップ3: 失敗した履歴データを返す

  • 説明: 失敗した履歴レコードをクライアントに返す
  • レスポンス:
    • 成功: 200 OK（エラー情報を含む履歴データ）
    • エラー: 適切なエラーコードとメッセージ

エラー処理

  • ログ記録
    • 失敗したアップロード履歴保存はデバッグのためにログに記録されます
  • エラー詳細:
    ステータスコード エラーメッセージ 説明
    422 検証失敗 リクエストパラメータが無効な場合
    400 履歴を保存できません データベース操作が失敗した場合

主要機能

  • ユーザーコンテキスト: ログインユーザーとそのグループへの自動関連付け
  • エラー追跡: 詳細なエラーメッセージの保存サポート
  • ステータス管理: 新しいアップロード履歴のデフォルトステータス設定
  • 検証: すべてのフィールドの包括的な入力検証
  • 監査証跡: アップロード試行と結果の完全な追跡

セキュリティ考慮事項

  • グループ分離: 履歴レコードはユーザーのグループに自動的に関連付けられます
  • 入力検証: 保存前にすべてのフィールドが検証されます
  • エラーログ記録: 失敗した操作は監視のためにログに記録されます
  • ユーザー認証: グループメンバーシップを持つ認証されたユーザーが必要です