# 機能設計書 57-PRレビューコメント返信

## 概要

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

### 本機能の処理概要

Giselleワークフロー内のアクションノードを通じて、連携しているGitHubリポジトリのPull Requestにおける既存のレビューコメントに対して返信を追加する機能である。PR番号とコメントIDを指定して返信本文を投稿することで、AIによるコードレビューの対話的なやり取りや自動応答を実現する。

**業務上の目的・背景**：Pull Requestのレビュープロセスでは、レビュアーが特定のコード行に対してコメントを残し、開発者がそれに返信するという対話が行われる。AIがレビューコメントに自動返信したり、開発者の質問に対して関連情報を提供したりすることで、レビュープロセスの効率化と品質向上を実現する。

**機能の利用シーン**：
- レビューコメントに対するAI自動応答
- レビューコメントの内容に基づいて関連ドキュメントやコード例を自動返信
- レビューコメントのトリガーイベントに対する確認応答
- コードスニペットの説明を自動生成して返信

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

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pullNumber | number | Yes | 返信対象のPR番号 | 正の整数（z.coerce.number()で変換） |
| commentId | number | Yes | 返信対象のレビューコメントID | 正の整数（z.coerce.number()で変換） |
| body | string | Yes | 返信の本文 | 空文字不可 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| replyCommentId | number | 作成された返信コメントのID |
| replyCommentUrl | string | 作成された返信コメントのURL |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-57-01 | アクション識別子 | アクションIDは`github.reply.pullRequestReviewComment`固定 | 常時 |
| BR-57-02 | 必須フィールド | pullNumber、commentId、bodyはすべて必須 | 常時 |
| BR-57-03 | 数値変換 | pullNumberとcommentIdは文字列入力も数値に変換される | 常時 |
| BR-57-04 | リポジトリ指定 | トリガーのリポジトリ設定に基づいて対象リポジトリが決定 | 常時 |
| BR-57-05 | スレッド返信 | 返信は既存のレビューコメントスレッドに追加される | 常時 |

### 計算ロジック

特になし

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

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VALIDATION_ERROR | バリデーションエラー | 必須パラメータが不足 | エラーメッセージを出力 |
| PR_NOT_FOUND | PRが見つからない | 指定されたPR番号が存在しない | エラーメッセージに番号を含めて出力 |
| 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.reply.pullRequestReviewComment`として一意に識別される
- UIでの表示ラベルは「Reply Pull Request Review Comment」
- pullNumberとcommentIdは`z.coerce.number()`により文字列からの自動変換をサポート
- レビューコメントトリガー（No.46）と組み合わせて使用することが多い

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: 3つのパラメータすべてが必須であり、そのうち2つ（pullNumber、commentId）が数値型でcoerce.number()を使用していることに注目。

**主要処理フロー**:
- **47-55行目**: `githubReplyPullRequestReviewCommentAction`オブジェクト定義
  - `id`: アクション識別子（`github.reply.pullRequestReviewComment`）
  - `label`: UI表示用ラベル（`Reply Pull Request Review Comment`）
  - `payload`: Zodスキーマによるペイロード定義
    - `pullNumber`: `z.coerce.number()`で数値変換
    - `commentId`: `z.coerce.number()`で数値変換
    - `body`: 必須文字列

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

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

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

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

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

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

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

**主要処理フロー**:
- **106-119行目**: `githubActionToInputFields`関数

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

```
アクションノード実行
    │
    ├─ executeAction (packages/giselle/src/operations)
    │      │
    │      ├─ アクションタイプ判定
    │      │     └─ github.reply.pullRequestReviewComment の場合
    │      │
    │      └─ GitHub API呼び出し
    │             └─ POST /pulls/{pull_number}/comments/{comment_id}/replies
    │
    └─ 結果をワークフローに返却
           └─ 返信コメントID・URL
```

### データフロー図

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

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

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

### 関連ファイル一覧

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