# 機能設計書 54-Issueコメント作成

## 概要

本ドキュメントは、Giselleワークフローから GitHub のIssueにコメントを追加するアクション機能について記述する。

### 本機能の処理概要

Giselleワークフロー内のアクションノードを通じて、連携しているGitHubリポジトリの既存Issueにコメントを追加する機能である。Issue番号を指定してコメント本文を投稿することで、ワークフローの結果報告やAI生成レスポンスをIssueに直接フィードバックすることが可能となる。

**業務上の目的・背景**：GitHubのIssueはチームのコミュニケーションハブとして機能する。ワークフローの実行結果、AI分析結果、自動テスト結果などをIssueコメントとして自動投稿することで、関係者へのリアルタイムな情報共有と開発プロセスの透明性向上を実現する。

**機能の利用シーン**：
- Issueに関連するコードレビュー結果をAIが自動コメント
- Issue作成イベントをトリガーとした自動応答コメント
- 定期実行ワークフローの結果をIssueに報告
- Issueに関連するビルド/テスト結果を自動投稿

**主要な処理内容**：
1. アクションノードからの入力パラメータ（issueNumber、body）を受け取る
2. GitHub APIを使用して指定Issueにコメントを追加
3. 作成結果をワークフローに返却

**関連システム・外部連携**：GitHub API（REST API / GraphQL API）

**権限による制御**：GitHub Appのインストール権限と対象リポジトリへのIssueコメント作成権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | アクションノードの設定でIssueコメント作成アクションを選択・設定 |

## 機能種別

アクション実行 / 外部API連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| issueNumber | number | Yes | コメント追加先のIssue番号 | 正の整数（z.coerce.number()で変換） |
| body | string | Yes | コメントの本文 | 空文字不可 |

### 入力データソース

ワークフロー内のアクションノードからの入力（前段ノードの出力または定義済みパラメータ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| commentId | number | 作成されたコメントのID |
| commentUrl | string | 作成されたコメントのURL |

### 出力先

ワークフローの後続ノードへの入力として使用可能

## 処理フロー

### 処理シーケンス

```
1. アクションノードから入力パラメータを受け取る
   └─ issueNumber、bodyを抽出
2. 入力値のバリデーション
   └─ Zodスキーマによる検証（issueNumberは数値変換）
3. GitHub APIを呼び出し
   └─ 指定IssueにコメントをPOST
4. 作成結果を返却
   └─ コメントIDとURLを後続ノードに渡す
```

### フローチャート

```mermaid
flowchart TD
    A[アクションノード実行] --> B[パラメータ抽出]
    B --> C{バリデーション}
    C -->|成功| D[GitHub API呼び出し]
    C -->|失敗| E[エラー返却]
    D --> F{API成功?}
    F -->|成功| G[コメントID・URL返却]
    F -->|失敗| H[APIエラーハンドリング]
    G --> I[後続ノード実行]
    H --> J[エラーログ・通知]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-54-01 | アクション識別子 | アクションIDは`github.create.issueComment`固定 | 常時 |
| BR-54-02 | 必須フィールド | issueNumberとbodyは両方必須 | 常時 |
| BR-54-03 | 数値変換 | issueNumberは文字列入力も数値に変換される | 常時 |
| BR-54-04 | リポジトリ指定 | トリガーのリポジトリ設定に基づいて対象リポジトリが決定 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| アクション定義 | - | 参照（メモリ） | アクション定義はコード内で静的に定義 |

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

本機能はGiselle内部のデータベース操作を直接行わない。コメントデータはGitHub側で管理される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VALIDATION_ERROR | バリデーションエラー | 必須パラメータが不足 | エラーメッセージを出力 |
| ISSUE_NOT_FOUND | Issueが見つからない | 指定されたIssue番号が存在しない | エラーメッセージに番号を含めて出力 |
| GITHUB_API_ERROR | API呼び出しエラー | GitHub APIからエラー応答 | エラーログ出力、リトライ検討 |
| PERMISSION_ERROR | 権限エラー | リポジトリへの書き込み権限なし | 権限設定の確認を促す |
| RATE_LIMIT_ERROR | レート制限エラー | GitHub APIレート制限超過 | 待機後リトライ |

### リトライ仕様

- GitHub APIエラー時は最大3回までリトライ
- レート制限エラー時はReset-Afterヘッダーに従って待機

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

GitHub APIへのリクエストは単一操作であり、Giselle側でのトランザクション管理は不要

## パフォーマンス要件

- アクション実行から完了まで: 5秒以内（GitHub API応答時間に依存）
- パラメータバリデーション: 10ms以内

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

- GitHub App認証トークンを使用したセキュアなAPI呼び出し
- リポジトリ単位での権限管理
- コメント本文に機密情報を含めないようワークフロー設計者が注意

## 備考

- アクションIDは`github.create.issueComment`として一意に識別される
- UIでの表示ラベルは「Create Issue Comment」
- issueNumberは`z.coerce.number()`により文字列からの自動変換をサポート

---

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

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

### 推奨読解順序

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

まず、アクションのペイロード構造を定義するZodスキーマを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | github.ts | `packages/action-registry/src/github.ts` | githubCreateIssueCommentActionオブジェクトの構造を理解 |

**読解のコツ**: `z.coerce.number()`は文字列を数値に自動変換するZodメソッド。これによりUI入力やトリガーペイロードからの柔軟な入力に対応。

**主要処理フロー**:
- **19-26行目**: `githubCreateIssueCommentAction`オブジェクト定義
  - `id`: アクション識別子（`github.create.issueComment`）
  - `label`: UI表示用ラベル（`Create Issue Comment`）
  - `payload`: Zodスキーマによるペイロード定義
    - `issueNumber`: `z.coerce.number()`で数値変換
    - `body`: 必須文字列

#### Step 2: アクションレジストリの構造を理解する

全GitHubアクションがどのように管理されているかを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | github.ts | `packages/action-registry/src/github.ts` | githubActionsオブジェクトとヘルパー関数 |

**主要処理フロー**:
- **75-90行目**: `githubActions`オブジェクト - 全アクションの集約
- **78行目**: `githubCreateIssueCommentAction`の登録

#### Step 3: 入力フィールド変換を理解する

アクション定義からUIの入力フィールドを生成する処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | github.ts | `packages/action-registry/src/github.ts` | githubActionToInputFields関数 |

**主要処理フロー**:
- **106-119行目**: `githubActionToInputFields`関数
  - Zodスキーマからキーを抽出
  - ラベルとオプショナル属性を取得

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

```
アクションノード実行
    │
    ├─ executeAction (packages/giselle/src/operations)
    │      │
    │      ├─ アクションタイプ判定
    │      │     └─ github.create.issueComment の場合
    │      │
    │      └─ GitHub API呼び出し
    │             └─ Issue Commentリクエスト
    │
    └─ 結果をワークフローに返却
           └─ コメントID・URL
```

### データフロー図

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

アクションノード    ───▶ executeAction              ───▶ ワークフロー
パラメータ                │                              後続ノード
                         ├─ アクションタイプ判定
                         ├─ パラメータバリデーション
                         │   └─ issueNumber数値変換
                         └─ GitHub API呼び出し

パラメータ:              Zodスキーマ検証:                 結果:
- issueNumber: number    - issueNumber: coerce.number()  - commentId
- body: string           - body: 必須文字列              - commentUrl
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| github.ts | `packages/action-registry/src/github.ts` | ソース | GitHubアクション定義（Issueコメント作成含む） |
| execute-action.ts | `packages/giselle/src/operations/execute-action.ts` | ソース | アクション実行処理 |
| giselle.ts | `packages/giselle/src/giselle.ts` | ソース | Giselleメインクラス（executeAction公開） |
