00.overview

管理者管理モジュール

概要説明

管理者管理モジュールは、システムのコアコンポーネントを管理するための包括的な機能セットを提供します。このモジュールにより、管理者はアプリケーション内のユーザー、グループ、お知らせ、ガイドを制御および監視することができます。

このモジュールの主な目的は、管理機能を一元化し、権限のあるスタッフがシステムリソースを効果的に管理し、アクセス権限を制御し、重要な情報をユーザーに配布できるようにすることです。

アクティビティ図

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    %% Main components
    Client[クライアントアプリケーション]
    AuthController[認証コントローラー]
    AdminController[管理者コントローラー]
    UserService(ユーザーサービス)
    GroupService(グループサービス)
    AnnouncementService(お知らせサービス)
    GuideService(ガイドサービス)
    UserDB[(ユーザー)]
    GroupDB[(グループ)]
    AnnouncementDB[(お知らせ)]
    GuideDB[(ガイド)]

    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'>管理者ログイン</p>
        </div>
    ]
    Step1 --> AuthController

    AuthController --- 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'>管理者アクセスの確認</p>
        </div>
    ]
    Step2 --> AdminController

    AdminController --- 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'>ダッシュボードの読み込み</p>
        </div>
    ]
    Step3 --> Client

    Client --- 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'>管理項目の選択</p>
        </div>
    ]
    Step4 --> AdminController

    AdminController --- 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'>リクエスト処理</p>
        </div>
    ]
    Step5 --> UserService
    Step5 --> GroupService
    Step5 --> AnnouncementService
    Step5 --> GuideService

    UserService --- 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 --> UserDB

    GroupService --- Step7[
        <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'>7</span>
            <p style='margin-top: 8px'>グループ管理</p>
        </div>
    ]
    Step7 --> GroupDB

    AnnouncementService --- Step8[
        <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'>8</span>
            <p style='margin-top: 8px'>お知らせ管理</p>
        </div>
    ]
    Step8 --> AnnouncementDB

    GuideService --- Step9[
        <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'>9</span>
            <p style='margin-top: 8px'>ガイド管理</p>
        </div>
    ]
    Step9 --> GuideDB

    %% Styling
    style Client fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style AuthController fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style AdminController fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style UserService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style GroupService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style AnnouncementService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style GuideService fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style UserDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style GroupDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style AnnouncementDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style GuideDB 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

API: 管理者管理API

ケースドキュメント

ケース1: 管理者ダッシュボードアクセス

説明

管理者が認証成功後に管理ダッシュボードにアクセスします。

シーケンス図

sequenceDiagram
    participant Admin as 管理者
    participant API as 管理者コントローラー
    participant Auth as 認証サービス
    participant UserDB as ユーザー
    participant GroupDB as グループ
    participant AnnouncementDB as お知らせ
    participant GuideDB as ガイド

    Note over Admin,API: ステップ1: ダッシュボードアクセス
    Admin->>API: GET /api/admin/dashboard
    
    Note over API,Auth: ステップ2: アクセス確認
    API->>Auth: verifyAdminAccess()
    Auth-->>API: 確認結果を返す
    
    Note over API,UserDB: ステップ3: ユーザー統計の読み込み
    API->>UserDB: getActiveUsersCount()
    UserDB-->>API: ユーザー数を返す
    
    Note over API,GroupDB: ステップ4: グループ統計の読み込み
    API->>GroupDB: getActiveGroupsCount()
    GroupDB-->>API: グループ数を返す
    
    Note over API,AnnouncementDB: ステップ5: お知らせの読み込み
    API->>AnnouncementDB: getRecentAnnouncements()
    AnnouncementDB-->>API: お知らせを返す
    
    Note over API,GuideDB: ステップ6: ガイドの読み込み
    API->>GuideDB: getRecentGuides()
    GuideDB-->>API: ガイドを返す
    
    Note over API,Admin: ステップ7: ダッシュボードの返却
    API-->>Admin: 200 OKとダッシュボードデータ

ステップ

ステップ1: ダッシュボードアクセス

  • 説明: 管理者がダッシュボードデータをリクエスト
  • リクエスト: GET /api/admin/dashboard
  • ヘッダー:
    • Authorization: Bearerトークン
  • 検証:
    • トークン存在チェック
    • 管理者ロール確認
    • レート制限チェック（60リクエスト/分）

ステップ2: アクセス確認

  • 説明: 管理者権限の確認
  • アクション:
    • 認証トークンのチェック
    • 管理者ロールの確認
    • セッションステータスの検証

ステップ3: ユーザー統計の読み込み

  • 説明: ユーザー統計を取得
  • アクション:
    • アクティブユーザー数のカウント
    • 最近のユーザーアクティビティの取得
    • ユーザーメトリクスの計算

ステップ4: グループ統計の読み込み

  • 説明: グループ統計を取得
  • アクション:
    • アクティブグループ数のカウント
    • 最近のグループアクティビティの取得
    • グループメトリクスの計算

ステップ5: お知らせの読み込み

  • 説明: 最近のお知らせを取得
  • アクション:
    • 最近のお知らせを取得
    • ステータスによるフィルタリング
    • 日付による並べ替え

ステップ6: ガイドの読み込み

  • 説明: 最近のガイドを取得
  • アクション:
    • 最近のガイドを取得
    • ステータスによるフィルタリング
    • 日付による並べ替え

ステップ7: ダッシュボードの返却

  • 説明: ダッシュボードデータの送信
  • レスポンス:
    • 成功: 200 OKとダッシュボードデータ
    • すべての統計と最近のアイテムを含む

エラー処理

  • ログ

    • ログイン失敗はアプリケーションログに記録
    • ロール確認エラーを記録
    • （オプション）セキュリティイベントのSlackメッセージ送信

  • エラー詳細:

    ステータスコード エラーメッセージ 説明
    401 "ログイン情報が正しくありません。" ユーザーが管理者ロールで見つからない場合
    401 "認証情報と一致するレコードがありません。" ログインが失敗した場合
    401 "問題が発生しました。申し訳ございませんが、もう一度お試しください。" 予期しないエラーが発生した場合

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

erDiagram
    users {
        bigint id PK
        string name "ユーザーのフルネーム"
        string email "ユーザーのメールアドレス（一意）"
        string uid "Firebase UID"
        int status "アカウントステータス"
        boolean is_first_login "ユーザーが初回ログインを完了したかどうかを示すフラグ"
        string payment_provider_customer_id "決済プロバイダーの顧客ID"
        boolean show_free_plan_modal "無料プランモーダルを表示するフラグ"
        bigint group_id FK "groupsテーブルへの参照"
        timestamp created_at
        timestamp updated_at
    }
    groups {
        bigint id PK
        string name "グループ名"
        timestamp created_at
        timestamp updated_at
    }
    group_members {
        bigint id PK
        bigint user_id FK "usersテーブルへの参照"
        bigint group_id FK "groupsテーブルへの参照"
        bigint group_role_id FK "group_rolesテーブルへの参照"
        timestamp created_at
        timestamp updated_at
    }
    group_roles {
        bigint id PK
        string name "ロール名"
        string slug "ロールスラッグ"
        timestamp created_at
        timestamp updated_at
    }
    admin_roles {
        bigint id PK
        string name "ロール名"
        string slug "ロールスラッグ"
        timestamp created_at
        timestamp updated_at
    }
    admin_role_user {
        bigint user_id FK "usersテーブルへの参照"
        bigint admin_role_id FK "admin_rolesテーブルへの参照"
        timestamp created_at
        timestamp updated_at
    }

    users ||--o{ group_members : has
    groups ||--o{ group_members : has
    group_roles ||--o{ group_members : has
    users ||--o{ admin_role_user : has
    admin_roles ||--o{ admin_role_user : has

ケース2: リソース管理

説明

管理者がシステムリソース（ユーザー、グループ、お知らせ、ガイド）を管理します。

シーケンス図

sequenceDiagram
    participant Admin as 管理者
    participant API as 管理者コントローラー
    participant Service as リソースサービス
    participant DB as データベース

    Admin->>API: POST /api/admin/resources (アクション付き)
    API->>Service: processResourceAction(action, data)
    Service->>DB: executeAction(action, data)
    DB-->>Service: 結果を返す
    Service-->>API: 処理されたデータを返す
    API-->>Admin: 200 OKと結果

ステップ

ステップ1: リソースアクションの送信

  • 説明: 管理者がリソース管理アクションを送信
  • リクエスト: POST /api/admin/resources
  • ボディパラメータ:
    • action: アクションのタイプ（作成/更新/削除）
    • resource_type: リソースのタイプ
    • data: リソースデータ
  • 検証:
    • アクションタイプの検証
    • リソースタイプの検証
    • データフォーマットの検証

ステップ2: アクション処理

  • 説明: リソース管理アクションの処理
  • アクション:
    • 権限の検証
    • リソースの存在確認
    • ビジネスルールの適用

ステップ3: アクション実行

  • 説明: データベースアクションの実行
  • アクション:
    • データベース操作の実行
    • 関連レコードの更新
    • 変更のログ記録

ステップ4: レスポンス返却

  • 説明: アクション結果の送信
  • レスポンス:
    • 成功: 200 OKと結果
    • 更新されたリソースデータを含む

追加メモ

  • レート制限: リソース管理アクションは管理者あたり1分間に30件に制限
  • すべての変更は管理者IDとタイムスタンプでログに記録
  • 実装を検討すべき機能:
    • リソースのバージョン管理
    • 変更履歴の追跡
    • 一括操作のサポート
    • リソース依存関係の検証
    • 大きな変更前の自動バックアップ

モジュールリスト

名前 概要リンク 説明
認証 認証 ログイン、ログアウト、代表者ログイン、パスワードリセット
ユーザー管理 ユーザー管理 ユーザーアカウントの作成、更新、ステータス変更、削除を含む管理者インターフェース
グループ管理 グループ管理 ユーザーグループの作成、更新、ステータス変更、削除を含む管理ツール
お知らせ管理 お知らせ管理 コンテンツと画像アップロードを含むお知らせの作成と管理システム
ガイド管理 ガイド管理 システムガイドとドキュメントの作成と管理機能