# 機能設計書 37-GitHubトリガー再設定

## 概要

本ドキュメントは、Giselleワークフローエンジンにおける「GitHubトリガー再設定」機能の設計を記述する。本機能は、既存のGitHubトリガーの設定（リポジトリ、インストレーションID、イベント設定）を更新するAPIを提供する。

### 本機能の処理概要

本機能は、既存のGitHubトリガーに対して、リポジトリノードID、インストレーションID、イベント設定を更新する。リポジトリが変更された場合は、旧リポジトリの連携インデックスを削除し、新リポジトリの連携インデックスを追加する。

**業務上の目的・背景**：ワークフローのトリガーを別のGitHubリポジトリに紐付け直したり、GitHub Appの再インストール時にインストレーションIDを更新する必要がある。イベント種別の変更は許可しないが、同一イベント種別内での設定更新は可能。

**機能の利用シーン**：
- トリガーを異なるリポジトリに切り替える場合
- GitHub Appの再インストール後にインストレーションIDを更新する場合
- イベント設定の詳細（コールサイン、ラベル等）を変更する場合

**主要な処理内容**：
1. トリガーID、リポジトリノードID、インストレーションID、（オプション）イベント設定を受け取る
2. 現在のトリガー設定を取得
3. GitHubトリガーであることを確認
4. イベント種別が変更されていないことを確認
5. リポジトリが変更された場合は連携インデックスを更新
6. 更新されたトリガーをストレージに保存
7. ワークスペースのノード状態を更新

**関連システム・外部連携**：
- GiselleStorageを介したファイルストレージ
- GitHub連携インデックスの更新

**権限による制御**：ワークスペースへの編集権限を持つユーザーのみが実行可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | GitHubトリガー設定の更新 |

## 機能種別

データ更新（UPDATE操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| context | GiselleContext | Yes | Giselle実行コンテキスト | - |
| triggerId | TriggerId | Yes | 更新対象のトリガーID | `fltg-`プレフィックス付き |
| repositoryNodeId | string | Yes | 新しいリポジトリノードID | - |
| installationId | number | Yes | 新しいインストレーションID | - |
| event | GitHubEventData | No | イベント設定（オプション） | 同一イベント種別のみ許可 |

### 入力データソース

- API呼び出しによるトリガー更新情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| triggerId | TriggerId | 更新されたトリガーID（入力と同一） |

### 出力先

- ストレージ: `flow-triggers/{triggerId}.json`（更新）
- ストレージ: ワークスペースファイル（ノード状態更新）
- GitHub連携インデックス（リポジトリ変更時）

## 処理フロー

### 処理シーケンス

```
1. 現在のトリガー設定を取得
   └─ getTrigger()で既存設定を取得

2. 存在・種別チェック
   ├─ トリガーが存在しない場合: エラー
   └─ GitHubトリガーでない場合: エラー

3. イベント種別チェック
   └─ イベント種別（event.id）が異なる場合: エラー

4. リポジトリ変更時の連携インデックス更新
   ├─ 旧リポジトリのインデックス削除
   └─ 新リポジトリのインデックス追加

5. 更新されたトリガーを生成・保存
   └─ setTrigger()で保存

6. ワークスペースを取得

7. トリガーノードの状態を更新
   └─ status: "configured", flowTriggerId維持

8. ワークスペースを保存

9. TriggerIdを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[getTrigger呼び出し]
    B --> C{トリガー存在?}
    C -->|No| D[エラー: Trigger not found]
    C -->|Yes| E{GitHubトリガー?}
    E -->|No| F[エラー: Only GitHub triggers supported]
    E -->|Yes| G{イベント種別変更?}
    G -->|Yes| H[エラー: Changing event type not supported]
    G -->|No| I{リポジトリ変更?}
    I -->|Yes| J[連携インデックス更新]
    I -->|No| K[スキップ]
    J --> L[updatedTrigger生成]
    K --> L
    L --> M[setTrigger保存]
    M --> N[getWorkspace]
    N --> O[ノード状態更新]
    O --> P[setWorkspace保存]
    P --> Q[TriggerId返却]
    Q --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-37-001 | GitHubトリガー限定 | GitHubトリガー以外はエラー | 常時 |
| BR-37-002 | イベント種別不変 | イベント種別（event.id）の変更は不可 | 常時 |
| BR-37-003 | 連携インデックス同期 | リポジトリ変更時は連携インデックスも更新 | リポジトリ変更時 |
| BR-37-004 | 設定項目の引き継ぎ | shouldPostInProgressCommentは元の設定を維持 | 常時 |

### 計算ロジック

該当なし

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トリガー取得 | ストレージ | SELECT | 現在の設定読み込み |
| 連携インデックス削除 | ストレージ | UPDATE | 旧リポジトリのインデックス更新 |
| 連携インデックス追加 | ストレージ | UPDATE | 新リポジトリのインデックス更新 |
| トリガー更新 | ストレージ | UPDATE | トリガー設定の更新 |
| ワークスペース取得 | ストレージ | SELECT | ワークスペース読み込み |
| ワークスペース更新 | ストレージ | UPDATE | ノード状態の更新 |

### テーブル別操作詳細

#### ストレージ（flow-triggers/{triggerId}.json）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | configuration.repositoryNodeId | 新しいリポジトリノードID | |
| UPDATE | configuration.installationId | 新しいインストレーションID | |
| UPDATE | configuration.event | 更新後のイベント設定 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Trigger not found | 指定IDのトリガーが存在しない | エラーをスロー |
| - | Only GitHub triggers supported | ManualトリガーなどGitHub以外 | エラーをスロー |
| - | Changing event type not supported | イベント種別（event.id）の変更 | エラーをスロー |

### リトライ仕様

該当なし

## トランザクション仕様

- 連携インデックス更新とトリガー更新は個別の操作
- エラー発生時は部分的に更新される可能性あり

## パフォーマンス要件

- レスポンス時間：300ms以内

## セキュリティ考慮事項

- GiselleContextを通じてアクセス制御
- installationIdの適切な管理

## 備考

- イベント種別の変更が必要な場合は、削除→再作成が必要

---

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

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

### 推奨読解順序

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

まず、Trigger型とGitHubEventConfiguration型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/protocol/src/trigger/index.ts` | Trigger型の構造 |
| 1-2 | github.ts | `packages/protocol/src/trigger/github.ts` | GitHubEventConfiguration型 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | reconfigure-github-trigger.ts | `packages/giselle/src/triggers/reconfigure-github-trigger.ts` | メイン処理ロジック（全101行） |

**主要処理フロー**:
1. **16-22行目**: 引数定義
2. **23-26行目**: getTriggerで現在の設定取得
3. **27-29行目**: 存在チェック
4. **30-32行目**: GitHubトリガーチェック
5. **34-40行目**: イベント種別変更チェック
6. **42-57行目**: リポジトリ変更時の連携インデックス更新
7. **59-73行目**: updatedTrigger生成・保存
8. **75-99行目**: ワークスペースのノード状態更新
9. **100行目**: TriggerId返却

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

```
reconfigureGitHubTrigger (reconfigure-github-trigger.ts)
    │
    ├─ getTrigger() - 現在の設定取得
    │
    ├─ [リポジトリ変更時]
    │      │
    │      ├─ removeGitHubRepositoryIntegrationIndex()
    │      │
    │      └─ addGitHubRepositoryIntegrationIndex()
    │
    ├─ setTrigger() - 更新トリガー保存
    │
    ├─ getWorkspace()
    │
    └─ setWorkspace() - ノード状態更新
```

### データフロー図

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

triggerId ───────▶ getTrigger() ───▶ 現在のTrigger
repositoryNodeId
installationId
event（オプション）
        │
        ▼
検証チェック ───────▶ 存在/種別/イベント種別チェック
        │
        ▼
{リポジトリ変更?} ───▶ 連携インデックス更新
        │
        ▼
updatedTrigger ───────▶ setTrigger() ───▶ ストレージ保存
        │
        ▼
ノード状態更新 ───────▶ setWorkspace() ───▶ ワークスペース保存
        │
        ▼
TriggerId返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| reconfigure-github-trigger.ts | `packages/giselle/src/triggers/reconfigure-github-trigger.ts` | ソース | メイン処理 |
| utils.ts | `packages/giselle/src/triggers/utils.ts` | ソース | getTrigger、setTrigger |
| utils.ts | `packages/giselle/src/integrations/utils.ts` | ソース | add/removeGitHubRepositoryIntegrationIndex |
| utils.ts | `packages/giselle/src/workspaces/utils.ts` | ソース | getWorkspace、setWorkspace |
| index.ts | `packages/protocol/src/trigger/index.ts` | ソース | Trigger型 |
| github.ts | `packages/protocol/src/trigger/github.ts` | ソース | GitHubEventConfiguration型 |
