# 画面設計書 36-認証設定画面

## 概要

Giselleアカウントに紐づけるサードパーティ認証（Google、GitHub）の連携を管理するための設定画面。

### 本画面の処理概要

**業務上の目的・背景**：ユーザーはメールアドレス/パスワード以外に、Google や GitHub アカウントを使用してGiselleにログインできる。本画面は、これらのサードパーティ認証プロバイダーとの連携状態を管理し、接続・切断を行うためのインターフェースを提供する。複数の認証方法を連携しておくことで、ログイン方法の選択肢が増え、アカウントへのアクセスが容易になる。

**画面へのアクセス方法**：設定画面 > アカウント設定 > 認証 からアクセスする。URLは `/settings/account/authentication`。

**主要な操作・処理内容**：
1. Google連携の管理：Googleアカウントの接続、再接続、切断
2. GitHub連携の管理：GitHubアカウントの接続、再接続、切断
3. 連携状態の確認：各プロバイダーの連携状態と連携済みアカウント情報を表示

**画面遷移**：
- 前画面：アカウント設定画面（/settings/account）または一般設定画面（/settings/account/general）
- 関連画面：接続完了画面（/connected）- OAuth認証後のコールバック

**権限による表示制御**：
- 全てのログイン済みユーザーがアクセス可能
- 連携中のプロバイダーが1つのみの場合、そのプロバイダーの切断ボタンは表示されない（unlinkable フラグ）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 96 | ユーザー認証 | 主機能 | Google, GitHub連携の管理（連携・解除） |

## 画面種別

設定

## URL/ルーティング

`/settings/account/authentication`

## 入出力項目

本画面にはフォーム入力はなく、ボタン操作のみ。

## 表示項目

### Google連携セクション

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| 連携状態 | enum | unauthorized/invalid-credential/authorized |
| Googleユーザー名 | string | 連携済みGoogleアカウントのユーザー名（連携時のみ） |
| Googleメールアドレス | string | 連携済みGoogleアカウントのメールアドレス（連携時のみ） |
| アバター | string | Googleアカウントのプロフィール画像（連携時のみ） |

### GitHub連携セクション

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| 連携状態 | enum | unauthorized/invalid-credential/error/authorized |
| GitHubユーザー名 | string | 連携済みGitHubアカウントのユーザー名（連携時のみ） |
| アバター | string | GitHubアカウントのプロフィール画像（連携時のみ） |
| エラーメッセージ | string | エラー発生時のエラー内容 |

## イベント仕様

### 1-Google連携ボタン押下（Connect）

未連携の場合、「Connect」ボタンを押下してGoogleアカウントを連携する。

1. `connectGoogleIdentity` Server Action を呼び出し
2. `connectIdentity("google", "/settings/account/authentication")` を実行
3. Google OAuth 認証ページにリダイレクト
4. 認証完了後、`/connected` 経由で元の画面に戻る
5. 連携情報がDBに保存され、画面が更新される

### 2-Google再接続ボタン押下（Reconnect）

トークンが無効な場合、「Reconnect」ボタンを押下して再連携する。

1. `reconnectGoogleIdentity` Server Action を呼び出し
2. `reconnectIdentity("google", "/settings/account/authentication")` を実行
3. Google OAuth 認証ページにリダイレクト
4. 認証完了後、トークンが更新される

### 3-Google切断ボタン押下（Disconnect）

連携済みで切断可能な場合、「Disconnect」ボタンを押下して連携を解除する。

1. `disconnectGoogleIdentity` Server Action を呼び出し
2. `disconnectIdentity("google", "/settings/account/authentication")` を実行
3. 連携情報がDBから削除される
4. 画面が更新される

### 4-GitHub連携ボタン押下（Connect）

未連携の場合、「Connect」ボタンを押下してGitHubアカウントを連携する。

1. `connectGitHubIdentity` Server Action を呼び出し
2. `connectIdentity("github", "/settings/account/authentication")` を実行
3. GitHub OAuth 認証ページにリダイレクト
4. 認証完了後、`/connected` 経由で元の画面に戻る
5. 連携情報がDBに保存され、画面が更新される
6. エラー発生時、`oauthError` クエリパラメータ付きでリダイレクト

### 5-GitHub再接続ボタン押下（Reconnect）

トークンが無効な場合、「Reconnect」ボタンを押下して再連携する。

1. `reconnectGitHubIdentity` Server Action を呼び出し
2. `reconnectIdentity("github", "/settings/account/authentication")` を実行
3. GitHub OAuth 認証ページにリダイレクト
4. 認証完了後、トークンが更新される

### 6-GitHub切断ボタン押下（Disconnect）

連携済みで切断可能な場合、「Disconnect」ボタンを押下して連携を解除する。

1. `disconnectGitHubIdentity` Server Action を呼び出し
2. `disconnectIdentity("github", "/settings/account/authentication")` を実行
3. 連携情報がDBから削除される
4. 画面が更新される

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 連携（Connect） | user_identities | INSERT | 認証プロバイダー情報の追加 |
| 再連携（Reconnect） | user_identities | UPDATE | トークンの更新 |
| 切断（Disconnect） | user_identities | DELETE | 認証プロバイダー情報の削除 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|---------|
| エラー | OAuth Error: {error} | OAuth認証エラー発生時（クエリパラメータ経由） |
| 警告 | Your GitHub access token has expired or become invalid. Please reconnect to continue using the service. | GitHubトークン無効時 |
| 警告 | GitHub integration error: {errorMessage} | GitHub連携でエラー発生時 |
| 情報 | Connect your Giselle Account with a third-party service to use it for login. | 画面の説明文 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| OAuth認証エラー | エラーメッセージをクエリパラメータに含めてリダイレクト、画面上部にエラー表示 |
| トークン無効 | 「Reconnect」ボタンを表示し、再連携を促す |
| GitHub API エラー | エラーメッセージを表示 |
| リダイレクトエラー | isRedirectErrorLike でチェックし、リダイレクトを継続 |

## 備考

- 最後の認証方法は切断できない（unlinkable フラグで制御）
- GitHub連携は GitHub App のインストールとは別の概念
- OAuth認証エラーは `oauthError` クエリパラメータで画面に渡される
- Suspense を使用してローディング状態を表示

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | page.tsx | `apps/studio.giselles.ai/app/(main)/settings/account/authentication/page.tsx` | Server Component としてのページレンダリング |

**主要処理フロー**:
1. **行11-13**: searchParams から oauthError を取得
2. **行14-18**: 説明文の表示
3. **行19-24**: oauthError がある場合にエラーバナーを表示
4. **行25-40**: Suspense でラップした GoogleAuthentication と GitHubAuthentication のレンダリング

#### Step 2: 認証コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | google-authentication.tsx | `apps/studio.giselles.ai/app/(main)/settings/account/google-authentication.tsx` | Google連携コンポーネント |
| 2-2 | github-authentication.tsx | `apps/studio.giselles.ai/app/(main)/settings/account/github-authentication.tsx` | GitHub連携コンポーネント |

**主要処理フロー**:
- **行14**: getGoogleIdentityState() / getGitHubIdentityState() で連携状態を取得
- **行16-29**: 連携状態に応じた表示の分岐

#### Step 3: Server Actions を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | actions.ts | `apps/studio.giselles.ai/app/(main)/settings/account/actions.ts` | 連携・切断のServer Actions |

**主要処理フロー**:
- **行28-30**: connectGoogleIdentity
- **行46-56**: connectGitHubIdentity（エラーハンドリング付き）
- **行58-60**: reconnectGoogleIdentity
- **行62-75**: reconnectGitHubIdentity（エラーハンドリング付き）
- **行77-79**: disconnectGoogleIdentity
- **行81-83**: disconnectGitHubIdentity

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

```
AccountAuthenticationPage (page.tsx)
    │
    ├─ searchParams.oauthError ──────────────────────────▶ エラーバナー表示判定
    │
    ├─ GoogleAuthentication
    │      ├─ getGoogleIdentityState() ──────────────────▶ Google連携状態取得
    │      └─ 状態に応じたボタン
    │             ├─ connectGoogleIdentity()
    │             │      └─ connectIdentity("google", ...)
    │             ├─ reconnectGoogleIdentity()
    │             │      └─ reconnectIdentity("google", ...)
    │             └─ disconnectGoogleIdentity()
    │                    └─ disconnectIdentity("google", ...)
    │
    └─ GitHubAuthentication
           ├─ getGitHubIdentityState() ──────────────────▶ GitHub連携状態取得
           └─ 状態に応じたボタン
                  ├─ connectGitHubIdentity()
                  │      └─ connectIdentity("github", ...)
                  ├─ reconnectGitHubIdentity()
                  │      └─ reconnectIdentity("github", ...)
                  └─ disconnectGitHubIdentity()
                         └─ disconnectIdentity("github", ...)
```

### データフロー図

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

URL oauthError ─────────────▶   エラーバナー表示 ──────────────▶ エラー表示

User Session ───────────────▶   getGoogleIdentityState() ──────▶ {status, googleUser, unlinkable}
                                        │
                                        ▼
                                ┌─────────────────────┐
                                │ GoogleAuthentication│
                                │ Presentation        │ ─────────▶ 画面表示
                                └─────────────────────┘

User Session ───────────────▶   getGitHubIdentityState() ──────▶ {status, gitHubUser, unlinkable, errorMessage}
                                        │
                                        ▼
                                ┌─────────────────────┐
                                │ GitHubAuthentication│
                                │ Presentation        │ ─────────▶ 画面表示
                                └─────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `apps/studio.giselles.ai/app/(main)/settings/account/authentication/page.tsx` | ソース | ページのエントリーポイント |
| actions.ts | `apps/studio.giselles.ai/app/(main)/settings/account/actions.ts` | ソース | Server Actions |
| google-authentication.tsx | `apps/studio.giselles.ai/app/(main)/settings/account/google-authentication.tsx` | ソース | Google連携コンポーネント |
| github-authentication.tsx | `apps/studio.giselles.ai/app/(main)/settings/account/github-authentication.tsx` | ソース | GitHub連携コンポーネント |
| google-authentication-presentation.tsx | `apps/studio.giselles.ai/app/(main)/settings/account/components/google-authentication-presentation.tsx` | ソース | Google連携表示コンポーネント |
| github-authentication-presentation.tsx | `apps/studio.giselles.ai/app/(main)/settings/account/components/github-authentication-presentation.tsx` | ソース | GitHub連携表示コンポーネント |
