# 画面設計書 28-インテグレーション設定画面

## 概要

本ドキュメントは、Giselle Studioのインテグレーション設定画面の設計仕様を記載したものです。

### 本画面の処理概要

この画面は、GitHubなどの外部サービスとの連携設定を管理するための画面です。GitHub App のインストール状況、連携アカウント、アクセス可能なリポジトリの一覧を表示し、新規連携やアクセス権限の管理が可能です。

**業務上の目的・背景**：AIワークフローでGitHub連携機能（Issue作成、PR作成、コード検索など）を使用するために、GitHub Appの連携が必要です。この画面では連携状態の確認と管理を一元化し、必要なリポジトリへのアクセス権限を設定できます。

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

**主要な操作・処理内容**：
1. GitHub連携状態の確認（連携済み/未連携）
2. GitHub Appのインストール/設定変更（GitHubへ遷移）
3. 連携アカウントの確認
4. アクセス可能リポジトリの一覧表示

**画面遷移**：この画面からはGitHub App インストールURL（外部）、認証設定画面（/settings/account/authentication）に遷移できます。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 39 | リポジトリ一覧取得 | 主機能 | 連携しているGitHubリポジトリの一覧取得と表示 |
| 38 | Webhookハンドリング | 補助機能 | GitHub連携設定の管理 |

## 画面種別

設定

## URL/ルーティング

`/settings/team/integrations`

## 入出力項目

なし（表示・操作のみ）

## 表示項目

| 項目名 | 説明 | データソース |
|--------|------|-------------|
| GitHubアイコン | GitHubサービスのアイコン | 静的アイコン |
| 連携状態 | 連携済み/未連携 | getGitHubIdentityState関数 |
| 連携アカウント | GitHubのユーザー名（@付き） | gitHubUser.login |
| インストールボタン | Install/Configure App | インストール状態による |
| インストール一覧 | GitHub App のインストール先（組織/ユーザー） | installations |
| リポジトリ一覧 | アクセス可能なリポジトリ | installation.repositories |
| リポジトリ公開設定 | Public/Private | repo.private |

## イベント仕様

### 1-Install/Configure App押下

GitHubAppInstallButtonコンポーネント押下時、GitHub App のインストールURLにリダイレクトされます。新規インストールまたは設定変更ができます。

### 2-Configure GitHub App押下（未連携時）

GitHubが未連携の場合、認証設定画面（/settings/account/authentication）へのリンクが表示されます。

### 3-リポジトリリンク押下

各リポジトリ名をクリックすると、GitHub上のリポジトリページが新しいタブで開きます。

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

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

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | - | - | 外部API（GitHub）からデータ取得 |

### 外部API連携

| API | 処理 | 備考 |
|-----|------|------|
| GitHub API | ユーザー情報取得 | gitHubUserClient経由 |
| GitHub API | インストール一覧取得 | getInstallations() |
| GitHub API | リポジトリ一覧取得 | getRepositories(installationId) |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 連携済み表示 | Logged in as (@{username}) | GitHub連携済みの場合 |
| 未連携表示 | Not connected | GitHub未連携の場合 |
| 認証エラー | Authentication Error: {message} | 認証状態がエラーの場合 |

## 例外処理

| 状態 | 処理 |
|------|------|
| GitHub認証エラー | エラーメッセージをAlertで表示 |
| GitHub App URL取得失敗 | エラーメッセージをAlertで表示 |
| GitHub未連携 | Configure GitHub Appボタンを表示 |
| 無効な認証情報 | GitHubIntegrationPresentationでインストールURLのみ表示 |

## 備考

- GitHub連携状態はgetGitHubIdentityState関数で取得され、複数の状態（unauthorized、invalid-credential、error、authorized）があります
- インストール先は複数（組織・個人）に対応し、それぞれのリポジトリ一覧を表示します
- リポジトリの公開/非公開はバッジで表示されます
- GitHub App インストールURLは外部で管理され、gitHubAppInstallURL関数で取得します

---

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

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

### 推奨読解順序

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

GitHub連携で使用されるデータ構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | github-integration.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/integrations/github-integration.tsx` | InstallationWithRepositories型定義（行70-74） |

**読解のコツ**: InstallationはGitHub APIのスキーマ型を拡張し、repositories配列を追加した型です。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/integrations/page.tsx` | シンプルなページ構造 |
| 2-2 | github-integration.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/integrations/github-integration.tsx` | メインのGitHub連携ロジック |

**主要処理フロー**:
1. **github-integration.tsx行13-49**: GitHubIntegration関数
2. **行14-16**: getGitHubIdentityStateで認証状態取得
3. **行19-22**: GitHub App インストールURL取得
4. **行23-28**: 未認証/無効認証時の処理
5. **行30-40**: インストール一覧とリポジトリ取得
6. **行43-48**: GitHubIntegrationPresentationへのデータ渡し

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

表示コンポーネントの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | github-integration.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/integrations/github-integration.tsx` | GitHubIntegrationPresentation, Header, Installation コンポーネント |

**主要処理フロー**:
- **行82-104**: GitHubIntegrationPresentation - メインレイアウト
- **行112-150**: Header - 連携状態とインストールボタン
- **行156-201**: Installation - インストール先とリポジトリ一覧

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

```
page.tsx (Server Component)
    │
    └─ GitHubIntegration (async)
           │
           ├─ getGitHubIdentityState() - 認証状態取得
           │      └─ 状態: unauthorized / invalid-credential / error / authorized
           │
           ├─ gitHubAppInstallURL() - インストールURL取得
           │
           ├─ gitHubUserClient.getInstallations() - インストール一覧取得
           │
           ├─ gitHubUserClient.getRepositories() - リポジトリ一覧取得
           │
           └─ GitHubIntegrationPresentation
                  ├─ Header
                  │      ├─ SiGithub (アイコン)
                  │      └─ GitHubAppInstallButton / Configure Link
                  │
                  └─ Installation (複数)
                         └─ Repository リスト
```

### データフロー図

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

GitHub OAuth Token ─────────────▶ getGitHubIdentityState() ────▶ identityState
         │                              │
         │                       status判定
         │                              │
         ├─ unauthorized ───────────────▶ Configure Linkを表示
         │
         ├─ invalid-credential ─────────▶ インストールURLのみ表示
         │
         ├─ error ──────────────────────▶ GitHubError表示
         │
         └─ authorized ─────────────────▶ gitHubUserClient
                                              │
                                              ├─ getInstallations()
                                              │
                                              └─ getRepositories()
                                                      │
                                                      ▼
                                              GitHubIntegrationPresentation
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/integrations/page.tsx` | ソース | サーバーコンポーネント、メインページ |
| github-integration.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/integrations/github-integration.tsx` | ソース | GitHub連携コンポーネント |
| github-app-install-button.tsx | `apps/studio.giselles.ai/packages/components/github-app-install-button.tsx` | ソース | インストールボタンUI |
| accounts/index.ts | `apps/studio.giselles.ai/services/accounts/index.ts` | ソース | getGitHubIdentityState関数 |
| github/index.ts | `apps/studio.giselles.ai/services/external/github/index.ts` | ソース | gitHubAppInstallURL関数 |
