# 機能設計書 34-トリガー取得

## 概要

本ドキュメントは、Giselleワークフローエンジンにおける「トリガー取得」機能の設計を記述する。本機能は、設定されたトリガー情報をトリガーIDを指定して取得するAPIを提供する。

### 本機能の処理概要

本機能は、指定されたトリガーID（TriggerId）に対応するトリガー設定データをストレージから取得し、呼び出し元に返却する。

**業務上の目的・背景**：ワークフローのトリガー設定を確認・表示するために、保存されているトリガー情報を取得する必要がある。ワークフローエディタでのトリガー設定表示や、ワークスペース一覧でのトリガー情報取得に活用される。

**機能の利用シーン**：
- ワークフローエディタでトリガーノードの現在の設定を表示する場合
- ワークスペース一覧画面でトリガー情報を取得する場合
- トリガー解決処理でトリガーデータを参照する場合

**主要な処理内容**：
1. トリガーID（TriggerId）を受け取る
2. ストレージパスを計算
3. ストレージからトリガーデータを取得
4. Trigger型として返却（存在しない場合はundefined）

**関連システム・外部連携**：GiselleStorageを介したファイルストレージとの連携

**権限による制御**：ワークスペースへのアクセス権限を持つユーザーのみがトリガー情報を取得可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | ワークスペース一覧画面 | 主画面 | ワークスペースに設定されたトリガー情報の取得 |

## 機能種別

データ取得（SELECT操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| context | GiselleContext | Yes | Giselle実行コンテキスト（ストレージ参照を含む） | - |
| triggerId | TriggerId | Yes | 取得対象のトリガーID | `fltg-`プレフィックス付きID形式 |

### 入力データソース

- ストレージ（GiselleStorage）からトリガーデータを取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | Trigger \| undefined | トリガー設定データ、または未設定の場合undefined |

#### Trigger型の構造

| フィールド | 型 | 説明 |
|-----------|-----|------|
| id | TriggerId | トリガーID |
| workspaceId | WorkspaceId | ワークスペースID |
| nodeId | NodeId | トリガーノードID |
| enable | boolean | 有効/無効フラグ |
| configuration | GitHubEventConfiguration \| ManualTrigger | トリガー種別固有の設定 |

### 出力先

呼び出し元への戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. トリガーIDからストレージパスを計算
   └─ `flow-triggers/{triggerId}.json`

2. ストレージに対象ファイルが存在するか確認
   └─ storage.exists()で存在チェック

3. 存在チェック結果による分岐
   └─ 存在しない場合: undefinedを返却

4. ストレージからトリガーデータを取得
   └─ storage.getJson()でJSONデータを読み込み

5. Zodスキーマでパース・検証して返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[triggerIdを受け取る]
    B --> C[triggerPath計算]
    C --> D[storage.exists確認]
    D --> E{ファイル存在?}
    E -->|No| F[undefined返却]
    E -->|Yes| G[storage.getJson取得]
    G --> H[Trigger.parse検証]
    H --> I[Trigger返却]
    F --> J[終了]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-34-001 | 存在チェック | 取得前にファイル存在チェックを行う | 常時 |
| BR-34-002 | 未設定時の返却値 | トリガーが存在しない場合はundefinedを返却 | 常時 |
| BR-34-003 | スキーマ検証 | 取得したJSONはTriggerスキーマで検証 | 常時 |

### 計算ロジック

- ストレージパス: `flow-triggers/{triggerId}.json`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 存在確認 | ストレージ（ファイル） | EXISTS | flow-triggers/{id}.jsonの存在チェック |
| トリガー取得 | ストレージ（ファイル） | SELECT | flow-triggers/{id}.jsonの読み込み |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全フィールド | triggerIdでパス指定 | Zodスキーマでバリデーション |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル不在 | 指定IDのトリガーデータが存在しない | undefinedを返却（正常系） |
| - | スキーマエラー | JSONデータがTriggerスキーマに適合しない | バリデーションエラーとして処理 |

### リトライ仕様

該当なし（読み取り操作のため）

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

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

## パフォーマンス要件

- レスポンス時間：100ms以内（ストレージアクセス込み）
- 同時アクセス：ストレージドライバの制限に依存

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

- GiselleContextを通じてアクセス制御
- ワークスペース境界を超えたアクセスは不可

## 備考

- 内部的にはsystemGetTriggerとしてutils.tsで実装
- 存在チェックを先に行うことで、不要なparse処理を回避

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/protocol/src/trigger/index.ts` | Trigger型、TriggerId定義を理解 |

**読解のコツ**: Trigger型のconfigurationはdiscriminated union。provider値（"github"または"manual"）で種別を判別。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | get-trigger.ts | `packages/giselle/src/triggers/get-trigger.ts` | 公開API関数（シンプルな委譲） |

**主要処理フロー**:
1. **5-8行目**: 引数の型定義（context, triggerId）
2. **9-12行目**: systemGetTrigger（utils.ts）への委譲

#### Step 3: ユーティリティ層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utils.ts | `packages/giselle/src/triggers/utils.ts` | getTrigger関数実装（25-43行目） |

**主要処理フロー**:
- **5-7行目**: triggerPath関数でストレージパス生成
- **32-34行目**: triggerPath呼び出し
- **35行目**: storage.exists()で存在チェック
- **36-38行目**: 存在しない場合はundefinedを返却
- **39-42行目**: storage.getJson()でTrigger型として取得

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

```
getTrigger (get-trigger.ts)
    │
    └─ systemGetTrigger (utils.ts)
           │
           ├─ triggerPath() - ストレージパス生成
           │
           ├─ storage.exists() - 存在チェック
           │
           └─ storage.getJson()
                  │
                  └─ Trigger.parse() - Zodスキーマ検証
```

### データフロー図

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

triggerId ───▶ triggerPath() ───▶ ストレージパス
                       │
                       ▼
              storage.exists() ───▶ 存在フラグ
                       │
                       ▼
              {存在しない場合} ───▶ undefined返却
                       │
                       ▼
              storage.getJson() ───▶ Trigger返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| get-trigger.ts | `packages/giselle/src/triggers/get-trigger.ts` | ソース | 公開API関数 |
| utils.ts | `packages/giselle/src/triggers/utils.ts` | ソース | getTrigger内部実装 |
| index.ts | `packages/protocol/src/trigger/index.ts` | ソース | Trigger型、TriggerId定義 |
| github.ts | `packages/protocol/src/trigger/github.ts` | ソース | GitHubEventConfiguration型 |
| manual.ts | `packages/protocol/src/trigger/manual.ts` | ソース | ManualTrigger型 |
