カスタムプラン詳細表示

概要説明

カスタムプラン詳細表示機能により、管理者は特定のカスタムプランに関する完全な情報（すべての関連データと履歴を含む）を取得できます。

前提条件

• ユーザーは管理者として認証されている必要があります（SuperAdminまたはAdminStaffロール）
• カスタムプランが存在する必要があります

依存関係

• なし（読み取り専用操作）

Swaggerリンク

API: カスタムプラン詳細表示

ケースドキュメント

ケース1: 契約詳細取得成功

説明

管理者が特定のカスタムプランに関する詳細情報（すべての関係とメタデータを含む）を正常に取得します。

Sequence Diagram

sequenceDiagram
    participant Admin
    participant Controller as CustomContractController
    participant Repository as CustomContractRepository
    participant Database
    
    Note over Admin,Database: GET /api/v1/admin/custom-contracts/{id}
    
    rect rgb(200, 255, 200)
    Note right of Admin: Happy Case Flow
    
    Admin->>Controller: GET request with contract ID
    
    rect rgb(200, 255, 255)
    Note right of Controller: Data Retrieval
    Controller->>Repository: findById(contractId)
    Repository->>Database: SELECT * FROM custom_contracts WHERE id = ?
    Database-->>Repository: Return contract record
    Repository->>Repository: Load relationships (eager loading)
    Repository->>Database: SELECT related records
    Database-->>Repository: Return related data
    Repository-->>Controller: Return contract with all relations
    end
    
    Controller-->>Admin: 200 OK (contract_data)
    end
    
    rect rgb(255, 200, 200)
    Note right of Admin: Error Scenarios
    rect rgb(255, 230, 230)
    alt Contract Not Found
        Repository-->>Controller: Null returned
        Controller-->>Admin: 404 Not Found
    else Database Error
        Database-->>Repository: Database error
        Repository-->>Controller: Error result
        Controller-->>Admin: 400 Bad Request
    end
    end
    end

ステップ

ステップ1: 契約取得

• 説明: すべての関係を含む契約レコードを取得します
• リクエスト: GET /api/v1/admin/custom-contracts/{id}
• 認証: ユーザーはSuperAdminまたはAdminStaffロールを持つ必要があります
• パスパラメータ:
  • id: カスタムプランID（必須、整数）

ステップ2: 関係の読み込み

• 説明: すべての関連データを積極的に読み込みます
• 読み込まれる関係:
  • group: メンバーを含むグループ情報
  • group.groupMembers: すべてのグループメンバー
  • packagePlan: ベースパッケージプランの詳細
  • subscription: 関連するサブスクリプションデータ
• データベース操作:
  • custom_contractsからSELECT
  • groups、package_plans、subscriptionsとのLEFT JOIN
  • グループメンバー用の追加クエリ

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

• 説明: 完全な契約データを返却します
• レスポンスデータ:
  • すべての契約フィールド
  • グループ詳細（name, status, created_by）
  • グループメンバーリスト
  • パッケージプラン詳細（該当する場合）
  • サブスクリプション詳細（slug, status, email）
  • Stripeメタデータ（session_id, price_id, subscription_item_id）
  • 使用制限（すべてのmax_*フィールド）
  • 日付情報（starts_at, ends_at, created_at, updated_at）
• 成功メッセージ: "カスタムプランの詳細取得に成功しました"

Database Related Tables & Fields

erDiagram
    custom_contracts {
        bigint id PK
        bigint subscription_id FK
        bigint package_plan_id FK
        bigint group_id FK
        bigint user_id FK
        string code
        string billing_interval
        string currency
        integer amount
        string status
        string provider_checkout_session_id
        string provider_price_id
        string provider_subscription_item_id
        timestamp starts_at
        timestamp ends_at
        integer max_member
        integer max_product_group
        integer max_product
        integer max_category
        integer max_search_query
        integer max_viewpoint
        string data_visible
        tinyint api_available
        timestamp created_at
        timestamp updated_at
    }
    groups {
        bigint id PK
        string name
        bigint created_by FK
        integer status
        timestamp created_at
        timestamp updated_at
    }
    group_members {
        bigint id PK
        bigint group_id FK
        bigint user_id FK
        string role
        timestamp created_at
    }
    subscriptions {
        bigint id PK
        string slug
        bigint package_plan_id FK
        bigint group_id FK
        string status
        string email
        string payment_provider_customer_id
        timestamp created_at
        timestamp updated_at
    }
    package_plans {
        bigint id PK
        bigint package_id FK
        string name
        string billing_interval
        integer amount
        timestamp created_at
        timestamp updated_at
    }
    users {
        bigint id PK
        string name
        string email
        timestamp created_at
    }
    
    custom_contracts ||--|| groups : belongs_to
    custom_contracts ||--o| package_plans : based_on
    custom_contracts ||--o| subscriptions : has
    custom_contracts ||--o| users : managed_by
    groups ||--o{ group_members : has
    group_members ||--|| users : belongs_to

Error Handling

• Log: Errors are logged via logThrow() method
• Error Detail:

Additional Notes

Response Structure

The response includes comprehensive contract information:

• Contract Details: code, status, amounts, intervals, dates
• Stripe Integration: session_id, price_id, subscription_item_id
• Usage Limits: All max_* fields (null means unlimited)
• Related Group: Full group details with member list
• Related Subscription: Complete subscription information
• Related Package Plan: Base plan used as template

Group Members Information

• Includes all members of the contract's group
• Shows member roles and permissions
• Useful for admin to understand who has access

Usage Limits Display

• null values indicate unlimited usage for that resource
• 0 values indicate feature is disabled
• Positive integers show the specific limit

Status Information

Contract status indicates lifecycle stage:

• draft: Created but not yet offered
• offered: Payment link sent, awaiting payment
• active: Payment successful, contract in effect
• expired: Contract end date has passed
• cancelled: Contract terminated before expiration

Stripe Metadata

• provider_checkout_session_id: Used to track payment session
• provider_price_id: Stripe price ID for subscription
• provider_subscription_item_id: Stripe subscription item for management

Performance Considerations

• Single query with eager loading prevents N+1 problem
• Indexed lookup on contract ID (primary key)
• Fast response time (typically < 100ms)
• Consider caching for frequently accessed contracts

Response Format Example

{
  "status": true,
  "message": "カスタムプランの詳細取得に成功しました",
  "data": {
    "id": 1,
    "subscription_id": 10,
    "package_plan_id": 3,
    "group_id": 5,
    "user_id": 15,
    "code": "CUSTOM-2026-001",
    "billing_interval": "month",
    "currency": "jpy",
    "amount": 150000,
    "status": "active",
    "provider_checkout_session_id": "cs_test_abc123",
    "provider_price_id": "price_abc123",
    "provider_subscription_item_id": "si_abc123",
    "starts_at": "2026-02-01T00:00:00Z",
    "ends_at": "2027-02-01T00:00:00Z",
    "max_member": 10,
    "max_product_group": 5,
    "max_product": 100,
    "max_category": 20,
    "max_search_query": 50,
    "max_viewpoint": 30,
    "data_visible": "private",
    "api_available": 1,
    "created_at": "2026-01-28T10:30:00Z",
    "updated_at": "2026-01-28T15:45:00Z",
    "group": {
      "id": 5,
      "name": "Test Corporation",
      "status": 1,
      "created_by": 12,
      "group_members": [
        {
          "id": 1,
          "user_id": 15,
          "role": "owner",
          "user": {
            "id": 15,
            "name": "John Doe",
            "email": "john@example.com"
          }
        }
      ]
    },
    "subscription": {
      "id": 10,
      "slug": "sub_abc123",
      "status": "active",
      "email": "billing@example.com",
      "payment_provider_customer_id": "cus_abc123"
    },
    "package_plan": {
      "id": 3,
      "name": "Enterprise Plan",
      "billing_interval": "month",
      "amount": 100000
    }
  }
}