ガイド管理

概要説明

ガイド管理機能により、管理者はシステムユーザー向けの指導コンテンツを作成、管理、公開することができます。ガイドは、ユーザーがプラットフォームを効果的に活用するのを支援するためのステップバイステップの指示、ベストプラクティス、およびコンテキストヘルプを提供します。管理者は様々なガイドを作成し、そのコンテンツを更新し、表示状態を変更し、古くなったガイドを削除することができます。この機能は、システム内で直接アクセス可能なドキュメントを提供することでユーザー体験を向上させます。

アクティビティ図

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TD
    %% Main components
    AdminUser[管理者ユーザー]
    AdminInterface[ガイド管理インターフェース]
    ActionSelect{アクション選択}
    
    %% Action components
    ViewGuides[ガイド一覧]
    GuideDetails[ガイド詳細]
    CreateForm[ガイド作成フォーム]
    EditForm[ガイド編集フォーム]
    ToggleStatus[ガイドステータス切替]
    DeleteConfirm{削除確認}
    
    %% Processing components
    ValidateCreate{入力検証}
    ValidateEdit{入力検証}
    SaveGuide[ガイドをデータベースに保存]
    UpdateGuide[データベース内のガイドを更新]
    UpdateStatusDB[データベース内のステータスを更新]
    DeleteFromDB[データベースから削除]
    
    %% Flow connections with numbered steps
    AdminUser --- 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 --> AdminInterface
    
    AdminInterface --- 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 --> ActionSelect
    
    ActionSelect --- Step3A[
        <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'>3A</span>
            <p style='margin-top: 8px'>ガイド表示</p>
        </div>
    ]
    Step3A --> ViewGuides
    
    ActionSelect --- Step3B[
        <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'>3B</span>
            <p style='margin-top: 8px'>詳細表示</p>
        </div>
    ]
    Step3B --> GuideDetails
    
    ActionSelect --- Step3C[
        <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'>3C</span>
            <p style='margin-top: 8px'>ガイド作成</p>
        </div>
    ]
    Step3C --> CreateForm
    
    ActionSelect --- Step3D[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3D</span>
            <p style='margin-top: 8px'>ガイド更新</p>
        </div>
    ]
    Step3D --> EditForm
    
    ActionSelect --- Step3E[
        <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'>3E</span>
            <p style='margin-top: 8px'>ステータス変更</p>
        </div>
    ]
    Step3E --> ToggleStatus
    
    ActionSelect --- Step3F[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc6666 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3F</span>
            <p style='margin-top: 8px'>ガイド削除</p>
        </div>
    ]
    Step3F --> DeleteConfirm
    
    CreateForm --- Step4C[
        <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'>4C</span>
            <p style='margin-top: 8px'>検証</p>
        </div>
    ]
    Step4C --> ValidateCreate
    
    EditForm --- Step4D[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4D</span>
            <p style='margin-top: 8px'>検証</p>
        </div>
    ]
    Step4D --> ValidateEdit
    
    ToggleStatus --- Step4E[
        <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'>4E</span>
            <p style='margin-top: 8px'>ステータス更新</p>
        </div>
    ]
    Step4E --> UpdateStatusDB
    
    DeleteConfirm --- Step4F[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc6666 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4F</span>
            <p style='margin-top: 8px'>レコード削除</p>
        </div>
    ]
    Step4F -->|確認| DeleteFromDB
    
    ValidateCreate --- Step5C1[
        <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'>5C</span>
            <p style='margin-top: 8px'>ガイド保存</p>
        </div>
    ]
    Step5C1 -->|有効| SaveGuide
    
    ValidateEdit --- Step5D1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5D</span>
            <p style='margin-top: 8px'>ガイド更新</p>
        </div>
    ]
    Step5D1 -->|有効| UpdateGuide
    
    SaveGuide --- Step6C[
        <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'>6C</span>
            <p style='margin-top: 8px'>インターフェースに戻る</p>
        </div>
    ]
    Step6C --> AdminInterface
    
    UpdateGuide --- Step6D[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>6D</span>
            <p style='margin-top: 8px'>インターフェースに戻る</p>
        </div>
    ]
    Step6D --> AdminInterface
    
    UpdateStatusDB --- Step5E[
        <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'>5E</span>
            <p style='margin-top: 8px'>インターフェースに戻る</p>
        </div>
    ]
    Step5E --> AdminInterface
    
    DeleteFromDB --- Step5F[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc6666 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5F</span>
            <p style='margin-top: 8px'>インターフェースに戻る</p>
        </div>
    ]
    Step5F --> AdminInterface
    
    ValidateCreate -.->|無効| CreateForm
    ValidateEdit -.->|無効| EditForm
    DeleteConfirm -.->|キャンセル| AdminInterface
    
    %% Styling
    style AdminUser fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style AdminInterface fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style ActionSelect fill:#f5f0ff,stroke:#9966cc,stroke-width:2px
    style ViewGuides fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style GuideDetails fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style CreateForm fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style EditForm fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ToggleStatus fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style DeleteConfirm fill:#f5f0ff,stroke:#9966cc,stroke-width:2px
    style ValidateCreate fill:#f5f0ff,stroke:#9966cc,stroke-width:2px
    style ValidateEdit fill:#f5f0ff,stroke:#9966cc,stroke-width:2px
    style SaveGuide fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style UpdateGuide fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style UpdateStatusDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style DeleteFromDB 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 Step3A fill:transparent,stroke:transparent,stroke-width:1px
    style Step3B fill:transparent,stroke:transparent,stroke-width:1px
    style Step3C fill:transparent,stroke:transparent,stroke-width:1px
    style Step3D fill:transparent,stroke:transparent,stroke-width:1px
    style Step3E fill:transparent,stroke:transparent,stroke-width:1px
    style Step3F fill:transparent,stroke:transparent,stroke-width:1px
    style Step4C fill:transparent,stroke:transparent,stroke-width:1px
    style Step4D fill:transparent,stroke:transparent,stroke-width:1px
    style Step4E fill:transparent,stroke:transparent,stroke-width:1px
    style Step4F fill:transparent,stroke:transparent,stroke-width:1px
    style Step5C1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step5D1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step5E fill:transparent,stroke:transparent,stroke-width:1px
    style Step5F fill:transparent,stroke:transparent,stroke-width:1px
    style Step6C fill:transparent,stroke:transparent,stroke-width:1px
    style Step6D fill:transparent,stroke:transparent,stroke-width:1px

API: ガイド管理API

ケースドキュメント

ケース1: ガイド一覧の取得

説明

管理者はシステム内のすべてのガイドのページ分けされたリストを取得します。

シーケンス図

sequenceDiagram
    participant Admin as 管理者
    participant API as ガイドコントローラー
    participant Repository as ガイドリポジトリ
    participant DB as データベース

    Note over Admin,DB: ステップ1: ガイドリストのリクエスト
    Admin->>API: GET /api/admin/guides (クエリパラメータ付き)
    
    Note over API,Repository: ステップ2: ガイドの取得
    API->>Repository: paginate(params)
    Repository->>DB: ガイドのクエリ
    DB-->>Repository: 該当ガイドを返す
    Repository-->>API: ページ分けされた結果を返す
    
    Note over API,Admin: ステップ3: ガイドリストの返却
    API-->>Admin: 200 OK (ガイドコレクション)

ステップ

ステップ1: ガイドリストのリクエスト

• 説明: 管理者はオプションのページネーションを使用してガイドのリストをリクエスト
• リクエスト: GET /api/admin/guides
• クエリパラメータ:
  • per_page: ページあたりのアイテム数
  • page: ページ番号

ステップ2: ガイドの取得

• 説明: システムはデータベースからガイドを取得
• アクション:
  • ページネーションパラメータを適用
  • ガイドを順番に取得（おそらく最新のものが最初）

ステップ3: ガイドリストの返却

• 説明: ページ分けされたガイドリストを返す
• レスポンス:
  • 成功: 200 OKとガイドコレクションおよびページネーションメタデータ
  • エラー: 適切なエラーメッセージ

エラー処理

• ログ
  • ガイドリスト取得失敗はアプリケーションログに記録
• エラー詳細:

  ステータスコード	エラーメッセージ	説明
  400	例外メッセージを含む一般的なエラー	予期しないエラーが発生した場合

ケース2: 特定のガイドの表示

説明

管理者が特定のガイドの詳細を表示します。

シーケンス図

sequenceDiagram
    participant Admin as 管理者
    participant API as ガイドコントローラー
    participant Repository as ガイドリポジトリ
    participant DB as データベース

    Note over Admin,DB: ステップ1: ガイド詳細のリクエスト
    Admin->>API: GET /api/admin/guides/{id}
    
    Note over API,Repository: ステップ2: ガイドの取得
    API->>Repository: findById(id)
    Repository->>DB: IDによるクエリ
    DB-->>Repository: ガイドデータを返す
    Repository-->>API: ガイドを返す
    
    Note over API,Admin: ステップ3: ガイド詳細の返却
    API-->>Admin: 200 OK (ガイドリソース)

ステップ

ステップ1: ガイド詳細のリクエスト

• 説明: 管理者が特定のガイドの詳細をリクエスト
• リクエスト: GET /api/admin/guides/{id}

ステップ2: ガイドの取得

• 説明: システムはIDによってガイドを取得
• アクション: 完全なガイドレコードを取得

ステップ3: ガイド詳細の返却

• 説明: ガイドの詳細を返す
• レスポンス:
  • 成功: 200 OKとガイドリソース
  • エラー: ガイドが見つからない場合は適切なエラーメッセージ

エラー処理

• ログ
  • ガイド取得失敗はアプリケーションログに記録
• エラー詳細:

  ステータスコード	エラーメッセージ	説明
  400	例外メッセージを含む一般的なエラー	予期しないエラーが発生した場合

ケース3: 新しいガイドの作成

説明

管理者がシステムに新しいガイドを作成します。

シーケンス図

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

    Note over Admin,DB: ステップ1: ガイド作成の送信
    Admin->>API: POST /api/admin/guides (guide_data)
    
    Note over API,API: ステップ2: 入力検証
    API->>API: リクエストデータを検証
    
    Note over API,Service: ステップ3: ガイド作成
    API->>Service: create(validated_data)
    Service->>DB: 新しいガイドを保存
    DB-->>Service: 作成されたガイドを返す
    
    Note over API,Admin: ステップ4: レスポンス返却
    Service-->>API: ガイドデータを返す
    API-->>Admin: 200 OK (ガイドリソース)

ステップ

ステップ1: ガイド作成の送信

• 説明: 管理者が新しいガイドを作成するフォームを送信
• リクエスト: POST /api/admin/guides
• 必須フィールド:
  • title: ガイドのタイトル
  • content: ガイドの内容（フォーマットを含む場合あり）
  • status: ガイドの表示状態
  • 実装によって必要なその他のフィールド

ステップ2: 入力検証

• 説明: システムがすべての入力データを検証
• アクション: GuideCreateRequestから検証ルールを実行
• 発生しうるエラー: 検証失敗

ステップ3: ガイド作成

• 説明: システムが新しいガイドを作成
• アクション: データベースにガイドレコードを保存

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

• 説明: 作成されたガイドデータを返す
• レスポンス:
  • 成功: 200 OKとガイドデータ
  • エラー: 適切なエラーメッセージ

エラー処理

• ログ
  • ガイド作成失敗はアプリケーションログに記録
• エラー詳細:

  ステータスコード	エラーメッセージ	説明
  400	例外メッセージを含む一般的なエラー	ガイド作成が失敗した場合

ケース4: ガイドの更新

説明

管理者が既存のガイドを更新します。

シーケンス図

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

    Note over Admin,DB: ステップ1: ガイド更新の送信
    Admin->>API: PUT /api/admin/guides/{id} (updated_data)
    
    Note over API,API: ステップ2: 入力検証
    API->>API: リクエストデータを検証
    
    Note over API,Service: ステップ3: ガイド更新
    API->>Service: update(id, validated_data)
    Service->>DB: ガイドレコードを更新
    DB-->>Service: 更新されたガイドを返す
    
    Note over API,Admin: ステップ4: レスポンス返却
    Service-->>API: ガイドデータを返す
    API-->>Admin: 200 OK (ガイドリソース)

ステップ

ステップ1: ガイド更新の送信

• 説明: 管理者がガイド情報を更新するフォームを送信
• リクエスト: PUT /api/admin/guides/{id}
• 更新可能フィールド:
  • title: ガイドのタイトル
  • content: ガイドの内容
  • status: ガイドの表示状態
  • 実装によって許可されるその他のフィールド

ステップ2: 入力検証

• 説明: システムがすべての入力データを検証
• アクション: GuideUpdateRequestから検証ルールを実行
• 発生しうるエラー: 検証失敗

ステップ3: ガイド更新

• 説明: システムがガイド情報を更新
• アクション: 新しいデータでガイドレコードを更新

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

• 説明: 更新されたガイドデータを返す
• レスポンス:
  • 成功: 200 OKと更新されたガイドデータ
  • エラー: 適切なエラーメッセージ

エラー処理

• ログ
  • ガイド更新失敗はアプリケーションログに記録
• エラー詳細:

  ステータスコード	エラーメッセージ	説明
  400	例外メッセージを含む一般的なエラー	ガイド更新が失敗した場合

ケース5: ガイドステータスの変更

説明

管理者がガイドのアクティブステータスを切り替えて、ユーザーへの表示を制御します。

シーケンス図

sequenceDiagram
    participant Admin as 管理者
    participant API as ガイドコントローラー
    participant Repository as ガイドリポジトリ
    participant DB as データベース

    Note over Admin,DB: ステップ1: ステータス変更リクエスト
    Admin->>API: POST /api/admin/guides/{id}/change-status
    
    Note over API,Repository: ステップ2: 現在のガイドを取得
    API->>Repository: findById(id)
    Repository->>DB: IDによるクエリ
    DB-->>Repository: ガイドデータを返す
    
    Note over API,Repository: ステップ3: ガイドステータス切替
    API->>Repository: update(id, {status: !current_status})
    Repository->>DB: ステータスを更新
    DB-->>Repository: 更新されたガイドを返す
    
    Note over API,Admin: ステップ4: レスポンス返却
    Repository-->>API: ガイドデータを返す
    API-->>Admin: 200 OK (ガイドリソース)

ステップ

ステップ1: ステータス変更リクエスト

• 説明: 管理者がガイドの表示状態を変更するリクエスト
• リクエスト: POST /api/admin/guides/{id}/change-status

ステップ2: 現在のガイドを取得

• 説明: システムは現在のガイドを取得してステータスを確認
• アクション:
  • IDでガイドを検索
  • ガイドが存在するか確認
• 発生しうるエラー: ガイドが見つからない

ステップ3: ガイドステータス切替

• 説明: システムがガイドのアクティブステータスを切り替え
• アクション:
  • ステータスを反対の値に更新（アクティブから非アクティブへ、またはその逆）

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

• 説明: 更新されたガイドデータを返す
• レスポンス:
  • 成功: 200 OKと新しいステータスを含む更新されたガイドデータ
  • エラー: 適切なエラーメッセージ

エラー処理

• ログ
  • ステータス変更失敗はアプリケーションログに記録
• エラー詳細:

  ステータスコード	エラーメッセージ	説明
  404	"messages.error.not-found"	要求されたガイドが存在しない場合
  400	例外メッセージを含む一般的なエラー	ステータス更新が失敗した場合

ケース6: ガイドの削除

説明

管理者がシステムからガイドを削除します。

シーケンス図

sequenceDiagram
    participant Admin as 管理者
    participant API as ガイドコントローラー
    participant Repository as ガイドリポジトリ
    participant DB as データベース

    Note over Admin,DB: ステップ1: ガイド削除リクエスト
    Admin->>API: DELETE /api/admin/guides/{id}
    
    Note over API,Repository: ステップ2: ガイド削除
    API->>Repository: delete(id)
    Repository->>DB: ガイドレコードを削除
    DB-->>Repository: 削除を確認
    
    Note over API,Admin: ステップ3: レスポンス返却
    API-->>Admin: 200 OK (成功メッセージ)

ステップ

ステップ1: ガイド削除リクエスト

• 説明: 管理者がガイドを削除するリクエスト
• リクエスト: DELETE /api/admin/guides/{id}

ステップ2: ガイド削除

• 説明: システムがデータベースからガイドを削除
• アクション: ガイドレコードを削除

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

• 説明: 削除成功を確認
• レスポンス:
  • 成功: 200 OKと成功メッセージ
  • エラー: 削除が失敗した場合は適切なエラーメッセージ

エラー処理

• ログ
  • ガイド削除失敗はアプリケーションログに記録
• エラー詳細:

  ステータスコード	エラーメッセージ	説明
  400	例外メッセージを含む一般的なエラー	削除が失敗した場合

ケース7: アクティブなガイドリストの取得

説明

管理者が参照用にアクティブなガイドのみのリストを取得します。

シーケンス図

sequenceDiagram
    participant Admin as 管理者
    participant API as ガイドコントローラー
    participant Repository as ガイドリポジトリ
    participant DB as データベース

    Note over Admin,DB: ステップ1: アクティブガイドのリクエスト
    Admin->>API: GET /api/admin/guides/active
    
    Note over API,Repository: ステップ2: アクティブガイドの取得
    API->>Repository: findByField({status: Active})
    Repository->>DB: アクティブガイドのクエリ
    DB-->>Repository: アクティブガイドを返す
    
    Note over API,Admin: ステップ3: アクティブガイドリストの返却
    API-->>Admin: 200 OK (ガイドコレクション)

ステップ

ステップ1: アクティブガイドのリクエスト

• 説明: 管理者がアクティブなガイドのみのリストをリクエスト
• リクエスト: GET /api/admin/guides/active

ステップ2: アクティブガイドの取得

• 説明: システムがデータベースからアクティブなガイドのみを取得
• アクション: Activeステータスのガイドをクエリ

ステップ3: アクティブガイドリストの返却

• 説明: アクティブなガイドのリストを返す
• レスポンス:
  • 成功: 200 OKとアクティブガイドコレクション
  • エラー: 適切なエラーメッセージ

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

erDiagram
    guides {
        bigint id PK "主キー"
        string category_name "ガイドのカテゴリ名"
        string icon "ガイドのアイコン（NULL許容）"
        string title "ガイドのタイトル"
        text content "ガイドの内容"
        bigint created_by FK "ガイドを作成したユーザーID"
        tinyint status "ガイドステータス: 1=アクティブ, 0=非アクティブ"
        timestamp created_at "作成タイムスタンプ"
        timestamp updated_at "最終更新タイムスタンプ（NULL許容）"
        timestamp deleted_at "ソフトデリートタイムスタンプ（NULL許容）"
    }
    users {
        bigint id PK "主キー"
        string name "ユーザー名"
        string email "ユーザーのメールアドレス"
        timestamp created_at "作成タイムスタンプ"
        timestamp updated_at "最終更新タイムスタンプ"
    }

    guides ||--o{ users : "created_by"

エラー処理

• ログ
  • ガイドリスト取得失敗はアプリケーションログに記録
• エラー詳細:

  ステータスコード	エラーメッセージ	説明
  400	例外メッセージを含む一般的なエラー	予期しないエラーが発生した場合

追加メモ

• ガイド管理機能は読みやすさを向上させるためのフォーマット済みコンテンツをサポートしています
• アクティブステータスの切り替えによって、エンドユーザーへのガイドの表示を制御します
• ガイドは、オンボーディング手順、機能紹介、ベストプラクティスなど、さまざまな目的に使用できます
• アクティブガイドリストエンドポイントは、現在ユーザーに表示されているガイドを簡単にプレビューする方法を提供します
• 管理者はステータスフィールドを通じて、ガイドを重要性と関連性によって整理することができます