# バッチ設計書 11-duplicate-issues.yml

## 概要

本ドキュメントは、GitHub Issueの重複チェックおよびコンプライアンス確認を自動化するワークフローの設計書です。新規Issue作成時および編集時にAIエージェントを使用して品質管理を行います。

### 本バッチの処理概要

このバッチは、GitHub Actionsワークフローとして実装され、リポジトリに新しいIssueが作成または編集された際に自動的に実行されます。AIエージェント（opencode）を活用して、Issueの品質を2つの観点から検証します。

**業務上の目的・背景**：オープンソースプロジェクトでは、大量のIssueが作成されるため、手動での重複チェックやテンプレート準拠確認が困難です。このバッチにより、メンテナーの負担を軽減し、Issue管理の効率化と品質向上を実現します。また、不適切なIssue（AIで生成された長文、テンプレート未使用など）を早期に検出し、コミュニティのIssue品質を維持します。

**バッチの実行タイミング**：Issueが新規作成された時（opened）およびIssueが編集された時（edited）にイベントドリブンで実行されます。

**主要な処理内容**：
1. リポジトリのチェックアウトとBun環境のセットアップ
2. opencodeのインストール
3. 新規Issue作成時（check-duplicates）：コントリビューションガイドライン準拠チェック（テンプレート使用、必須フィールド、AI生成テキスト検出）、既存Issueとの重複チェック、キーバインド関連Issue参照の追加
4. Issue編集時（recheck-compliance）：needs:complianceラベル付きIssueの再チェック、準拠確認後のラベル削除とコメント削除

**前後の処理との関連**：本バッチは独立して動作しますが、triage.ymlワークフローと連携してIssue管理を行います。needs:complianceラベルが付与されたIssueは、90日後にstale-issues.ymlにより自動クローズ対象となります。

**影響範囲**：GitHub Issues（ラベル付与、コメント追加・削除）、コミュニティメンバーへの通知

## バッチ種別

イベントドリブン / コンプライアンスチェック / AI分析処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント発生時（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | GitHub Issues イベント（opened, edited） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| OPENCODE_API_KEY | OpenCode APIキーがSecretsに設定されていること |
| GITHUB_TOKEN | GitHub Actionsの自動生成トークンが利用可能であること |
| needs:complianceラベル | recheck-complianceジョブ実行時、Issueにこのラベルが付与されていること |

### 実行可否判定

- **check-duplicatesジョブ**: `github.event.action == 'opened'` の場合のみ実行
- **recheck-complianceジョブ**: `github.event.action == 'edited'` かつ `contains(github.event.issue.labels.*.name, 'needs:compliance')` の場合のみ実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| github.event.issue.number | number | Yes | - | 対象IssueのID |
| github.event.action | string | Yes | - | イベントアクション（opened/edited） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub Issue | GitHub API | 新規作成または編集されたIssue |
| 既存Issues | GitHub API | 重複チェック対象の既存Issue一覧 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Issue Comment | API | 準拠違反・重複検出時のコメント |
| GitHub Issue Labels | API | needs:complianceラベルの追加・削除 |

### 出力ファイル仕様

ファイル出力はありません。すべてGitHub API経由で出力されます。

## 処理フロー

### 処理シーケンス

```
1. イベント受信
   └─ Issue opened/edited イベントをトリガー
2. 実行条件判定
   └─ check-duplicates: openedイベントのみ実行
   └─ recheck-compliance: editedイベント + needs:complianceラベル
3. 環境セットアップ
   └─ リポジトリチェックアウト、Bunセットアップ、opencode インストール
4. AI分析実行
   └─ opencodeエージェントにIssue分析を依頼
5. 結果処理
   └─ コメント投稿、ラベル追加/削除
```

### フローチャート

```mermaid
flowchart TD
    A[Issue イベント] --> B{アクション種別}
    B -->|opened| C[check-duplicates]
    B -->|edited| D{needs:compliance?}
    D -->|Yes| E[recheck-compliance]
    D -->|No| F[スキップ]
    C --> G[opencode AI分析]
    E --> G
    G --> H{準拠状態}
    H -->|違反| I[コメント追加 + ラベル付与]
    H -->|重複| J[重複情報コメント]
    H -->|準拠| K[ラベル削除 + 感謝コメント]
    I --> L[終了]
    J --> L
    K --> L
    F --> L
```

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

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

本バッチはデータベースを直接操作しません。GitHub APIを経由してIssueメタデータを更新します。

| 処理 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| ラベル追加 | GitHub Issue | UPDATE | needs:complianceラベル付与 |
| ラベル削除 | GitHub Issue | UPDATE | needs:complianceラベル削除 |
| コメント追加 | GitHub Issue Comment | INSERT | 違反/重複通知コメント |
| コメント削除 | GitHub Issue Comment | DELETE | 準拠確認後の違反コメント削除 |

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

該当なし（GitHub API経由のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API認証エラー | OPENCODE_API_KEYが無効 | Secrets設定を確認 |
| - | GitHub APIエラー | レート制限超過 | 自動リトライ待機 |
| - | AI分析タイムアウト | opencode応答遅延 | ワークフロー再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | GitHub Actionsデフォルト設定に従う |
| リトライ間隔 | - |
| リトライ対象エラー | ネットワークエラー、一時的なAPI障害 |

### 障害時対応

1. ワークフロー実行ログを確認
2. 必要に応じて手動でIssueを確認・ラベル付与
3. 再実行が必要な場合はワークフローを手動トリガー

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 各API呼び出し単位 |
| コミットタイミング | 各操作完了時（即座） |
| ロールバック条件 | 自動ロールバックなし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1件/実行 |
| 目標処理時間 | 120秒以内 |
| メモリ使用量上限 | GitHub Actionsランナー標準 |

## 排他制御

同一Issueに対する複数ワークフローの同時実行は許可されます。GitHub APIの整合性により、競合は発生しません。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | ジョブ名、Issue番号 |
| 進捗ログ | 各ステップ完了時 | ステップ名、実行結果 |
| 終了ログ | ワークフロー終了時 | 成功/失敗ステータス |
| エラーログ | エラー発生時 | エラーメッセージ、スタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHub Actions通知 |
| 処理時間 | 120秒超過 | GitHub Actions通知 |

## 備考

- AIエージェントの権限は制限されており、`gh issue*`コマンドのみ許可、WebFetchは拒否
- キーバインド関連Issue（#4997）への誘導機能あり
- 準拠違反Issueは2時間以内の修正を要求
