# 機能設計書 9-アクションノード

## 概要

本ドキュメントは、Giselleにおけるアクションノード機能の設計を定義する。GitHub APIを使用した操作（Issue作成、コメント投稿、PR更新等）を実行するためのオペレーションノードの型定義とデータ構造を規定する。

### 本機能の処理概要

アクションノードは、外部サービスへのAPI呼び出しを実行するオペレーションノードである。現在はGitHubアクションに対応しており、Issue作成、コメント投稿、PR更新などの操作を自動実行できる。

**業務上の目的・背景**：Giselleのワークフローにおいて、AI生成結果を外部サービスに反映する必要がある。本機能により、ワークフローの実行結果をGitHub Issue/PRにコメントとして投稿したり、新規Issueを自動作成したりできる。これにより、AIワークフローと開発プロセスのシームレスな統合が実現可能となる。

**機能の利用シーン**：ワークフローエディタ画面でアクションノードを追加・設定する時、GitHubリポジトリとの連携設定を行う時、自動コメント投稿やIssue作成を行う時などに利用される。

**主要な処理内容**：
1. アクションノードの型定義（ActionContent）
2. アクションプロバイダーの定義（GitHub）
3. アクション設定状態の管理（unconfigured/configured/reconfiguring）
4. GitHubアクション固有の設定（commandId、installationId、repositoryNodeId）

**関連システム・外部連携**：action-registryパッケージによるアクション定義と連携。GitHub App/APIを通じたGitHub操作。

**権限による制御**：アクション設定にはGitHub App連携とリポジトリへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 補助機能 | GitHub API操作などのアクションノードの追加・編集 |

## 機能種別

データ型定義 / ノード構造定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "action" | Yes | ノードコンテンツ種別 | リテラル型 |
| command | ActionData | Yes | アクションデータ（@deprecated: dataに変更予定） | discriminatedUnion |

### ActionData構造

| プロバイダー | 型 | 含まれるフィールド |
|------------|-----|------------------|
| github | GitHubActionData | provider, state |

### GitHubアクション設定状態

| 状態 | 型 | 含まれるフィールド |
|------|-----|------------------|
| unconfigured | GitHubActionUnconfiguredState | status |
| configured | GitHubActionConfiguredState | status, commandId, installationId, repositoryNodeId |
| reconfiguring | GitHubActionReconfiguringState | status, commandId |

## 出力仕様

### 出力データ

アクションノードはAPI呼び出しの結果を出力として提供する。

| 出力種別 | 説明 |
|---------|------|
| 実行結果 | API呼び出しの成否、レスポンスデータ |

### 出力先

- ワークフロー内の後続ノード（接続経由）

## 処理フロー

### データ構造定義フロー

```
1. GitHubアクション状態定義
   └─ GitHubActionUnconfiguredState（status: "unconfigured"）
   └─ GitHubActionConfiguredState（status: "configured" + commandId, installationId, repositoryNodeId）
   └─ GitHubActionReconfiguringState（status: "reconfiguring" + commandId）

2. GitHubActionData定義
   └─ provider: "github"
   └─ state: 上記3状態のdiscriminatedUnion

3. ActionData定義
   └─ GitHubActionDataのdiscriminatedUnion（現在はGitHubのみ）

4. ActionContent定義
   └─ type: "action"固定
   └─ command: ActionData（@deprecated）
```

### フローチャート

```mermaid
flowchart TD
    A[ActionContent] --> B[type: "action"]
    A --> C[command: ActionData]

    C --> D{provider}
    D -->|github| E[GitHubActionData]

    E --> F{state}
    F -->|unconfigured| G[未設定状態]
    F -->|configured| H[設定完了]
    F -->|reconfiguring| I[再設定中]

    H --> J[commandId, installationId, repositoryNodeId]
    I --> K[commandId]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 状態遷移 | unconfigured → configured → reconfiguring → configured の遷移パターン | 常に適用 |
| BR-002 | 設定完了要件 | configuredではcommandId, installationId, repositoryNodeIdが必須 | 設定完了時 |
| BR-003 | commandId非推奨 | commandIdはActionIdに名称変更予定 | 将来のマイグレーション対象 |

### 計算ロジック

特になし（型定義のため）

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

本機能は型定義のため、直接のデータベース操作は発生しない。アクション実行時はGitHub APIを呼び出す。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VALIDATION_ERROR | バリデーションエラー | Zodスキーマ検証失敗 | 入力データの確認 |
| INVALID_PROVIDER | プロバイダー不正 | 未対応のプロバイダー指定 | 対応プロバイダーを使用 |
| INVALID_STATE | 状態不正 | 不正な状態遷移 | 状態遷移ルールを確認 |

### リトライ仕様

型定義のため該当なし

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

型定義のため該当なし

## パフォーマンス要件

型定義のため該当なし

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

- installationIdはGitHub App連携のIDであり、適切な権限管理が必要
- repositoryNodeIdはGitHub GraphQL APIのノードIDであり、リポジトリスコープのアクセス制御に使用

## 備考

- commandフィールドは@deprecatedであり、将来dataに名称変更予定
- commandIdは@deprecatedであり、ActionIdに名称変更予定
- ActionContentReferenceはノード参照時の軽量版として使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | action.ts | `packages/protocol/src/node/operations/action.ts` | ActionContent全体構造 |

**読解のコツ**: GitHubアクションの3つの状態と、@deprecatedコメントに注意する。

#### Step 2: GitHubアクション状態を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | action.ts | `packages/protocol/src/node/operations/action.ts` | 各状態の定義（4-29行目） |

**主要処理フロー**:
- **4-9行目**: GitHubActionUnconfiguredState（status: "unconfigured"のみ）
- **11-18行目**: GitHubActionConfiguredState（status, commandId, installationId, repositoryNodeId）
- **20-27行目**: GitHubActionReconfiguringState（status, commandId）
- **31-38行目**: GitHubActionData（provider: "github" + state）

#### Step 3: ActionContentを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | action.ts | `packages/protocol/src/node/operations/action.ts` | ActionContent定義（44-49行目） |

**主要処理フロー**:
- **40-42行目**: ActionData（現在はGitHubActionDataのみのdiscriminatedUnion）
- **44行目**: type: "action"固定
- **46-48行目**: command: ActionData（@deprecated）

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

```
ActionContent (action.ts)
    │
    ├─ type: z.literal("action")
    │
    └─ command: ActionData (@deprecated)
           └─ z.discriminatedUnion("provider", [...])
                  └─ GitHubActionData
                         ├─ provider: z.literal("github")
                         └─ state: z.discriminatedUnion("status", [...])
                                ├─ GitHubActionUnconfiguredState
                                ├─ GitHubActionConfiguredState
                                │      ├─ commandId: GitHubActionId (@deprecated)
                                │      ├─ installationId: number
                                │      └─ repositoryNodeId: string
                                └─ GitHubActionReconfiguringState
                                       └─ commandId: GitHubActionId (@deprecated)
```

### データフロー図

```
[ワークフローエディタ]              [プロトコル層]              [アクション実行]

アクション設定UI ───▶ ActionContent
    │                     │
    │                     └─ command ───▶ GitHubActionData
    │                            │
    │                            ├─ installationId ───▶ GitHub App認証
    │                            │
    │                            ├─ repositoryNodeId ───▶ リポジトリ特定
    │                            │
    │                            └─ commandId ───▶ アクション種別
    │
    ▼
Workspace.nodes[] ───▶ ストレージ保存
                              │
                              ▼
                       タスク実行時 ───▶ GitHub API呼び出し
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| action.ts | `packages/protocol/src/node/operations/action.ts` | ソース | ActionContent定義 |
| operation-node.ts | `packages/protocol/src/node/operations/operation-node.ts` | ソース | ActionNode型、isActionNode関数 |
| github.ts | `packages/action-registry/src/github.ts` | ソース | GitHubアクション定義 |
