ファイルストレージモジュール概要

概要説明

ファイルストレージモジュールは、Google Cloud Storage（GCS）へのファイルアップロードの管理とアップロード履歴の追跡のための包括的な機能を提供します。このモジュールには、直接アップロード用の署名付きURLの生成、アップロードメタデータの保存、アップロード履歴の取得、エラー報告の管理などの機能が含まれています。このモジュールは、検証エラーの追跡を伴うCSVファイルアップロードをサポートするように設計されており、APIレスポンスとCSVエクスポート機能の両方を提供します。

アクティビティ図

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TD
    Client[クライアントアプリケーション]
    API[UploadGcsController]
    GCSService[GcsService]
    ImportService[ImportReviewService]
    ExportService[ExportService]
    Repository[ReviewUploadHistoryRepository]
    Database[(データベース)]
    GCS[(Google Cloud Storage)]
    
    Client --- Step1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>1</span>
            <p style='margin-top: 8px'>署名付きURLを要求</p>
        </div>
    ]
    Step1 --> API

    API --- Step2[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>2</span>
            <p style='margin-top: 8px'>署名付きURLを生成</p>
        </div>
    ]
    Step2 --> ImportService

    ImportService --- Step3[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3</span>
            <p style='margin-top: 8px'>GCSからURLを要求</p>
        </div>
    ]
    Step3 --> GCSService

    GCSService --- Step4[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4</span>
            <p style='margin-top: 8px'>署名付きURLを返す</p>
        </div>
    ]
    Step4 --> GCS

    GCS --- Step5[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5</span>
            <p style='margin-top: 8px'>クライアントにURLを返す</p>
        </div>
    ]
    Step5 --> GCSService
    GCSService --> ImportService
    ImportService --> API
    API --> Client

    Client --- Step6[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>6</span>
            <p style='margin-top: 8px'>ファイルを直接アップロード</p>
        </div>
    ]
    Step6 --> GCS

    Client --- Step7[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #99cc66 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>7</span>
            <p style='margin-top: 8px'>アップロード履歴を保存</p>
        </div>
    ]
    Step7 --> API

    API --- Step8[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #99cc66 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>8</span>
            <p style='margin-top: 8px'>データベースに保存</p>
        </div>
    ]
    Step8 --> Repository

    Repository --- Step9[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #99cc66 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>9</span>
            <p style='margin-top: 8px'>履歴レコードを保存</p>
        </div>
    ]
    Step9 --> Database

    Client --- Step10[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>10</span>
            <p style='margin-top: 8px'>履歴リストを要求</p>
        </div>
    ]
    Step10 --> API

    API --- Step11[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>11</span>
            <p style='margin-top: 8px'>データベースをクエリ</p>
        </div>
    ]
    Step11 --> Repository

    Repository --- Step12[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>12</span>
            <p style='margin-top: 8px'>履歴データを返す</p>
        </div>
    ]
    Step12 --> Database

    Client --- Step13[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #ff9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>13</span>
            <p style='margin-top: 8px'>エラーCSVをダウンロード</p>
        </div>
    ]
    Step13 --> API

    API --- Step14[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #ff9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>14</span>
            <p style='margin-top: 8px'>CSVファイルを生成</p>
        </div>
    ]
    Step14 --> ExportService

    ExportService --- Step15[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #ff9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>15</span>
            <p style='margin-top: 8px'>CSVダウンロードを返す</p>
        </div>
    ]
    Step15 --> API
    API --> Client
    
    style Client fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style API fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style GCSService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ImportService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ExportService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style Repository fill:#fff0f5,stroke:#cc6699,stroke-width:2px
    style Database fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style GCS fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style Step1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step2 fill:transparent,stroke:transparent,stroke-width:1px
    style Step3 fill:transparent,stroke:transparent,stroke-width:1px
    style Step4 fill:transparent,stroke:transparent,stroke-width:1px
    style Step5 fill:transparent,stroke:transparent,stroke-width:1px
    style Step6 fill:transparent,stroke:transparent,stroke-width:1px
    style Step7 fill:transparent,stroke:transparent,stroke-width:1px
    style Step8 fill:transparent,stroke:transparent,stroke-width:1px
    style Step9 fill:transparent,stroke:transparent,stroke-width:1px
    style Step10 fill:transparent,stroke:transparent,stroke-width:1px
    style Step11 fill:transparent,stroke:transparent,stroke-width:1px
    style Step12 fill:transparent,stroke:transparent,stroke-width:1px
    style Step13 fill:transparent,stroke:transparent,stroke-width:1px
    style Step14 fill:transparent,stroke:transparent,stroke-width:1px
    style Step15 fill:transparent,stroke:transparent,stroke-width:1px

モジュールリスト

APIエンドポイント

データベーススキーマ

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
    }
    review_upload_errors {
        bigint id PK
        bigint review_upload_history_id FK "review_upload_historiesテーブルへの参照"
        string header "エラーを引き起こしたフィールドヘッダー（null可）"
        string value "問題のあるデータ値（null可）"
        integer error_line "エラーが発生した行番号（null可）"
        json error_messages "フィールドのエラーメッセージ配列"
        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 : 所属
    review_upload_histories ||--o{ review_upload_errors : 複数持つ

主要機能

• 直接アップロードサポート: クライアントからGCSへの直接アップロード用の署名付きURLを生成
• アップロード追跡: ステータスとエラー情報を含む包括的な履歴追跡
• エラー管理: フィールドレベルの検証エラーを含む詳細なエラー追跡
• CSVエクスポート: データ修正のためのエラー報告をCSV形式でダウンロード
• ページネーション: 設定可能なページネーションによる大規模データセットのサポート
• グループベースアクセス: データセキュリティのためのユーザーのグループによる自動フィルタリング
• リソース変換: Laravelリソースを使用した一貫したAPIレスポンス
• グループベースのパス構造: ユーザーのグループと日付に基づく自動パス生成

セキュリティ考慮事項

• グループ分離: ユーザーは自分のグループのアップロード履歴のみにアクセス可能
• 署名付きURLの有効期限: 生成されたURLは15分で期限切れ
• 入力検証: すべてのエンドポイントに包括的な入力検証が含まれる
• エラーログ記録: 失敗した操作は監視とデバッグのためにログに記録
• ファイルパスセキュリティ: ファイルはグループ固有のディレクトリに日付ベースの整理で保存