# 機能設計書 59-Discussionコメント作成

## 概要

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

### 本機能の処理概要

Giselleワークフロー内のアクションノードを通じて、連携しているGitHubリポジトリのDiscussionにコメントを追加する機能である。Discussion番号を指定してコメント本文を投稿することで、AI生成の回答やワークフローの処理結果をDiscussionに自動でフィードバックすることが可能となる。また、既存コメントへの返信もサポートしている。

**業務上の目的・背景**：GitHub Discussionsは、Issue/PRとは異なるオープンなコミュニティコミュニケーションの場として活用される。Q&Aへの自動回答、アナウンスへのフォローアップ、アイデア共有への自動フィードバックなどを実現し、コミュニティマネジメントの効率化を図る。

**機能の利用シーン**：
- Discussion作成イベントをトリガーとしたAI自動回答
- Q&AカテゴリのDiscussionに対する関連ドキュメントリンクの自動投稿
- Discussionコメントへの自動返信
- 定期実行ワークフローの結果をDiscussionにサマリー投稿

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

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| discussionNumber | number | Yes | コメント追加先のDiscussion番号 | 正の整数（z.coerce.number()で変換） |
| body | string | Yes | コメントの本文 | 空文字不可 |
| commentId | number | No | 返信先コメントのID（指定時はスレッド返信） | 正の整数（z.coerce.number().optional()） |

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. アクションノードから入力パラメータを受け取る
   └─ discussionNumber、body、commentId（オプション）を抽出
2. 入力値のバリデーション
   └─ Zodスキーマによる検証
3. コメント種別を判定
   └─ commentIdの有無でトップレベル/返信を判定
4. GitHub GraphQL APIを呼び出し
   └─ Discussionにコメントを追加
5. 作成結果を返却
   └─ コメントIDとURLを後続ノードに渡す
```

### フローチャート

```mermaid
flowchart TD
    A[アクションノード実行] --> B[パラメータ抽出]
    B --> C{バリデーション}
    C -->|成功| D{commentIdあり?}
    C -->|失敗| E[エラー返却]
    D -->|あり| F[返信コメント作成]
    D -->|なし| G[トップレベルコメント作成]
    F --> H[GitHub GraphQL API呼び出し]
    G --> H
    H --> I{API成功?}
    I -->|成功| J[コメント情報返却]
    I -->|失敗| K[APIエラーハンドリング]
    J --> L[後続ノード実行]
    K --> M[エラーログ・通知]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-01 | アクション識別子 | アクションIDは`github.create.discussionComment`固定 | 常時 |
| BR-59-02 | 必須フィールド | discussionNumberとbodyは必須 | 常時 |
| BR-59-03 | オプションフィールド | commentIdはオプション（返信時のみ指定） | 常時 |
| BR-59-04 | 数値変換 | discussionNumberとcommentIdは文字列入力も数値に変換される | 常時 |
| BR-59-05 | リポジトリ指定 | トリガーのリポジトリ設定に基づいて対象リポジトリが決定 | 常時 |
| BR-59-06 | 返信動作 | commentId指定時は既存コメントへの返信として投稿 | commentId指定時 |

### 計算ロジック

特になし

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

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VALIDATION_ERROR | バリデーションエラー | 必須パラメータが不足 | エラーメッセージを出力 |
| DISCUSSION_NOT_FOUND | Discussionが見つからない | 指定された番号が存在しない | エラーメッセージに番号を含めて出力 |
| COMMENT_NOT_FOUND | コメントが見つからない | 指定されたcommentIdが存在しない | エラーメッセージにIDを含めて出力 |
| 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.discussionComment`として一意に識別される
- UIでの表示ラベルは「Create Discussion Comment」
- discussionNumberは`z.coerce.number()`により文字列からの自動変換をサポート
- commentIdを指定すると、既存コメントへのスレッド返信として投稿される
- Discussionトリガーイベント（No.47, 48）と組み合わせて使用することが多い

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: commentIdがオプション（`.optional()`）であることに注目。これにより、トップレベルコメントと返信コメントの両方に対応している。

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

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

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

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

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

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

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

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

**主要処理フロー**:
- **106-119行目**: `githubActionToInputFields`関数
- `safeParse(undefined).success`でオプショナル判定

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

```
アクションノード実行
    │
    ├─ executeAction (packages/giselle/src/operations)
    │      │
    │      ├─ アクションタイプ判定
    │      │     └─ github.create.discussionComment の場合
    │      │
    │      ├─ commentIdの有無を判定
    │      │     ├─ なし: トップレベルコメント作成
    │      │     └─ あり: 返信コメント作成
    │      │
    │      └─ GitHub GraphQL API呼び出し
    │
    └─ 結果をワークフローに返却
           └─ コメントID・URL
```

### データフロー図

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

アクションノード    ───▶ executeAction              ───▶ ワークフロー
パラメータ                │                              後続ノード
                         ├─ アクションタイプ判定
                         ├─ パラメータバリデーション
                         │   ├─ discussionNumber数値変換
                         │   └─ commentId数値変換（オプション）
                         ├─ コメント種別判定
                         └─ GitHub GraphQL API呼び出し

パラメータ:                    Zodスキーマ検証:               結果:
- discussionNumber: number    - 必須、coerce.number()      - commentId
- body: string                - 必須、文字列               - commentUrl
- commentId?: number          - オプション、coerce.number()
```

### 関連ファイル一覧

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