# 画面設計書 26-チーム設定画面

## 概要

本ドキュメントは、Giselle Studioのチーム設定画面の設計仕様を記載したものです。

### 本画面の処理概要

この画面は、チームのプロフィール情報、プラン情報、請求情報を管理するための画面です。チーム名やアバターの編集、プランのアップグレード、サブスクリプション管理、チームの削除が可能です。

**業務上の目的・背景**：チームの基本情報を一元管理し、プランのアップグレードやサブスクリプションの管理をスムーズに行えるようにします。Danger Zoneとしてチーム削除機能も提供し、不要になったチームを安全に削除できます。

**画面へのアクセス方法**：設定画面のサイドバーから「Team Settings」、または「/settings/team」パスに直接アクセスします。

**主要な操作・処理内容**：
1. チームプロフィールの表示と編集（名前、アバター）
2. 現在のプラン情報の表示
3. プランのアップグレード（FreeプランからProプランへ）
4. サブスクリプションの管理（Proプラン時）
5. サブスクリプションのキャンセル
6. チームの削除

**画面遷移**：この画面からは外部決済画面（Stripe）、プラン・料金ページ（giselles.ai/pricing）に遷移できます。

**権限による表示制御**：ログイン済みユーザーで、チームに所属しているユーザーのみアクセス可能です。プランによって表示内容が異なります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 97 | チーム管理 | 主機能 | チームプロフィール、プラン情報の取得と表示 |
| 98 | サブスクリプション管理 | 補助機能 | プラン情報、請求情報の管理画面への遷移 |

## 画面種別

詳細・編集

## URL/ルーティング

`/settings/team`

## 入出力項目

| 項目名 | 型 | 入出力 | 必須 | 説明 |
|--------|-----|--------|------|------|
| teamName | string | 入力 | 必須 | チーム名（編集時） |
| teamAvatar | File | 入力 | - | チームアバター画像（編集時） |

## 表示項目

| 項目名 | 説明 | データソース |
|--------|------|-------------|
| チーム名 | チームの表示名 | teams.name |
| チームアバター | チームのアバター画像 | teams.avatarUrl |
| プラン名 | 現在のプラン | team.plan |
| キャンセル予定日 | サブスクリプションのキャンセル予定日 | subscription.willCancelAt |
| ドキュメントリンク | チーム設定に関するドキュメントへのリンク | 固定URL |

## イベント仕様

### 1-チームプロフィール編集

TeamProfileCardコンポーネントでチーム名やアバターを編集できます（詳細はTeamProfileCardの実装による）。

### 2-Upgrade to Pro押下（Freeプラン時）

Upgrade to Proボタン押下時、upgradeCurrentTeamアクションが呼び出され、Stripeの決済画面にリダイレクトされます。

### 3-Manage Subscription押下（Proプラン時）

Manage Subscriptionボタン押下時、manageBillingアクションが呼び出され、Stripeのカスタマーポータルにリダイレクトされます。

### 4-Cancel Subscription押下（Proプラン時）

CancelSubscriptionButtonコンポーネントでサブスクリプションのキャンセルを行います。キャンセル後はキャンセル予定日が表示されます。

### 5-Delete Team押下

Delete Teamボタン押下時、確認ダイアログが表示されます。確認後、deleteTeamアクションが呼び出され、チームが削除されます。

### 6-ドキュメントリンク押下

About Team Settingsリンク押下時、外部ドキュメント（docs.giselles.ai）が新しいタブで開きます。

### 7-料金ページリンク押下

Learn about plans and pricingリンク押下時、料金ページ（giselles.ai/pricing）が新しいタブで開きます。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | teams, subscriptions | SELECT | チーム情報とサブスクリプション情報を取得 |
| プロフィール編集 | teams | UPDATE | チーム名、アバターURLを更新 |
| チーム削除 | teams, 関連テーブル | DELETE | チームと関連データを削除 |

### テーブル別更新項目詳細

#### teams

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, avatarUrl, plan | 現在のチームID | fetchCurrentTeam関数で取得 |
| UPDATE | name | ユーザー入力値 | プロフィール編集時 |
| UPDATE | avatarUrl | アップロードされた画像URL | プロフィール編集時 |
| DELETE | 全項目 | チームID | チーム削除時 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| プランアップグレード案内 | Have questions about your plan? Learn about plans and pricing | 常時表示 |
| キャンセル予定 | Cancels {日付} | サブスクリプションがキャンセル予定の場合 |
| Danger Zone | Delete Team | 常時表示 |
| 削除説明 | Permanently remove your Team Account and all of its contents... | チーム削除セクション |
| 削除エラー | {エラーメッセージ} | 削除処理失敗時 |

## 例外処理

| 状態 | 処理 |
|------|------|
| チーム情報取得エラー | エラーメッセージを表示 |
| サブスクリプション取得エラー | デフォルト状態（Freeプラン）で表示 |
| 削除処理エラー | アラートでエラーメッセージを表示 |

## 備考

- BillingInfoコンポーネントはプランに応じてFreeプラン用とProプラン用のUIを切り替えます
- activeSubscriptionIdが"bpps_"で始まる場合はv2サブスクリプションとして処理されます
- キャンセル予定がある場合、Cancelボタンは非表示になります
- チーム削除は確認ダイアログを経由して実行されます

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

チーム設定で使用されるデータ構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `apps/studio.giselles.ai/services/teams/types.ts` | CurrentTeam、TeamId型の定義 |

**読解のコツ**: CurrentTeamはplan、activeSubscriptionIdなどのサブスクリプション関連情報を含みます。

#### Step 2: エントリーポイントを理解する

ページコンポーネントの構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/page.tsx` | TeamPage関数、BillingInfo非同期コンポーネント |

**主要処理フロー**:
1. **行17-56**: TeamPage関数 - ページ全体のレイアウト
2. **行33-41**: TeamProfileのSuspense表示
3. **行44**: BillingInfoの表示
4. **行47-52**: Danger Zone（チーム削除セクション）
5. **行58-72**: BillingInfo非同期コンポーネント - プラン情報取得と表示切り替え
6. **行78-109**: BillingInfoForFreePlan - Freeプラン用UI
7. **行110-169**: BillingInfoForProPlan - Proプラン用UI

#### Step 3: 関連コンポーネントを理解する

各機能を提供するコンポーネントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | team-profile.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/team-profile.tsx` | チームプロフィール表示 |
| 3-2 | delete-team.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/delete-team.tsx` | チーム削除ダイアログ |
| 3-3 | cancel-subscription-button.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/cancel-subscription-button.tsx` | キャンセルボタン |

**主要処理フロー**:
- **delete-team.tsx行21-99**: ダイアログUIとdeleteTeamアクション呼び出し
- **team-profile.tsx行4-16**: TeamProfileCardへのデータ渡し

### プログラム呼び出し階層図

```
page.tsx (Server Component)
    │
    ├─ PageHeading - タイトル表示
    │
    ├─ DocsLink - ドキュメントリンク
    │
    ├─ Suspense
    │      └─ TeamProfile
    │             └─ fetchCurrentTeam() - チーム情報取得
    │                    └─ TeamProfileCard
    │
    ├─ BillingInfo (async)
    │      ├─ fetchCurrentTeam() - チーム情報取得
    │      ├─ isProPlan() - プラン判定
    │      ├─ BillingInfoForFreePlan
    │      │      └─ UpgradeButton
    │      │             └─ upgradeCurrentTeam - Server Action
    │      │
    │      └─ BillingInfoForProPlan
    │             ├─ getLatestSubscriptionV2() - サブスクリプション取得
    │             ├─ UpdateButton
    │             │      └─ manageBilling - Server Action
    │             └─ CancelSubscriptionButton
    │
    └─ DeleteTeam (Client Component)
           ├─ Dialog - 確認ダイアログ
           └─ deleteTeam - Server Action
```

### データフロー図

```
[入力]                         [処理]                          [出力]

teams テーブル ───────────────▶ fetchCurrentTeam() ───────────▶ CurrentTeam
         │                           │                              │
subscriptions テーブル ────────▶ getLatestSubscriptionV2() ────▶ willCancelAt
         │                           │                              │
         ▼                           ▼                              ▼
                              isProPlan() ─────────────────────▶ UI切り替え
                                    │                              │
                                    ├─ BillingInfoForFreePlan ────▶ UpgradeButton
                                    │
                                    └─ BillingInfoForProPlan ─────▶ ManageButton
                                                                   CancelButton
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/page.tsx` | ソース | サーバーコンポーネント、メインページ |
| team-profile.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/team-profile.tsx` | ソース | プロフィール表示 |
| team-profile-card.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/team-profile-card.tsx` | ソース | プロフィールカードUI |
| delete-team.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/delete-team.tsx` | ソース | チーム削除ダイアログ |
| cancel-subscription-button.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/cancel-subscription-button.tsx` | ソース | キャンセルボタン |
| actions.ts | `apps/studio.giselles.ai/app/(main)/settings/team/actions.ts` | ソース | Server Actions（削除など） |
| upgrade-current-team.ts | `apps/studio.giselles.ai/services/teams/actions/upgrade-current-team.ts` | ソース | アップグレードアクション |
| manage-billing.ts | `apps/studio.giselles.ai/services/teams/actions/manage-billing.ts` | ソース | 請求管理アクション |
