# 通知設計書 25-forge-list-notifications

## 概要

本ドキュメントは、Doom EmacsのForgeモジュールによるGitHub通知一覧表示機能（forge-list-notifications）の設計を定義する。

### 本通知の処理概要

forge-list-notifications機能は、GitHubリポジトリに関連する通知（プルリクエストのコメント、イシューの更新、レビュー依頼など）をEmacs内で一覧表示する機能である。ForgeパッケージがGitHub APIを通じて通知情報を取得し、専用のバッファにリスト形式で表示する。

**業務上の目的・背景**：ソフトウェア開発においてGitHubは中心的なコラボレーションプラットフォームであり、プルリクエストのレビュー依頼、イシューへのコメント、メンションなど様々な通知が日常的に発生する。これらの通知を確認するために毎回ブラウザを開く必要があると、開発作業のコンテキストスイッチが発生し効率が低下する。Emacs内で直接GitHub通知を確認できることで、開発フローを中断することなく通知管理が可能になる。

**通知の送信タイミング**：ユーザーが`forge-list-notifications`コマンドを実行した時点、またはForgeがバックグラウンドで通知を取得した時点で表示が更新される。自動同期が設定されている場合は定期的に更新される。

**通知の受信者**：GitHubアカウントと連携しているEmacs/Forgeユーザー本人。

**通知内容の概要**：GitHub通知の種別（プルリクエスト、イシュー、リリース等）、リポジトリ名、タイトル、最終更新日時、既読/未読状態などが表示される。

**期待されるアクション**：ユーザーは通知一覧を確認し、興味のある項目を選択して詳細を表示する。プルリクエストやイシューに直接移動してコメントやレビューを行うことができる。既読にする、削除するなどの通知管理操作も可能。

## 通知種別

アプリ内通知（Emacsバッファ表示） + 外部サービス連携（GitHub API）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（GitHub API経由） |
| 優先度 | 中 |
| リトライ | あり（ghub経由のHTTP再試行） |

### 送信先決定ロジック

現在のリポジトリまたは全リポジトリに関連する通知をGitHub APIから取得。表示は`forge-notifications`バッファで行われる。

## 通知テンプレート

### バッファ表示

| 項目 | 内容 |
|-----|------|
| バッファ名 | `*Notifications*`または`*forge-notifications*` |
| メジャーモード | forge-notifications-mode |
| 表示形式 | tabulated-list-mode派生 |

### リスト項目

| カラム | 説明 | 例 |
|-------|------|-----|
| State | 既読/未読状態 | unread/read |
| Type | 通知種別 | PullRequest/Issue/Release |
| Repository | リポジトリ名 | owner/repo |
| Title | 通知タイトル | Fix bug in feature X |
| Updated | 最終更新日時 | 2024-01-15 10:30 |

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| state | 既読状態 | GitHub API | Yes |
| type | 通知種別 | GitHub API | Yes |
| repository | リポジトリ名 | GitHub API | Yes |
| title | 通知タイトル | GitHub API | Yes |
| updated_at | 更新日時 | GitHub API | Yes |
| url | 通知URL | GitHub API | No |
| reason | 通知理由 | GitHub API | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ユーザー操作 | forge-list-notifications | 常時 | コマンド実行 |
| キーバインド | SPC g l n | Doomキーバインド | リーダーキーからのアクセス |
| 自動更新 | forge-pull | 定期実行時 | バックグラウンド同期 |
| Magitステータス | magit-status | forge有効時 | ステータス画面でのセクション表示 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| オフライン | ネットワーク接続なし |
| 認証エラー | GitHubトークン無効 |
| Forge無効 | +forgeフラグなし |
| API制限 | レート制限超過 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[forge-list-notifications呼び出し] --> B{Forge有効?}
    B -->|No| C[エラーメッセージ]
    B -->|Yes| D{認証トークン?}
    D -->|No| E[認証プロンプト]
    D -->|Yes| F[GitHub API呼び出し]
    E --> F
    F --> G{API応答}
    G -->|成功| H[通知データパース]
    G -->|エラー| I[エラー表示]
    H --> J[forge-notifications-mode有効化]
    J --> K[通知リスト表示]
    I --> L[終了]
    K --> L
    C --> L
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| forge-database | ローカルキャッシュ | SQLite |
| notification | 通知情報格納 | forge-database内 |

### テーブル別参照項目詳細

#### notification テーブル

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | 通知識別子 | PRIMARY KEY |
| repository | リポジトリ関連 | FOREIGN KEY |
| type | 通知種別 | - |
| title | タイトル | - |
| state | 既読状態 | - |
| updated | 更新日時 | - |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| notification | INSERT/UPDATE | GitHub API取得データの保存 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 認証エラー | トークン無効/期限切れ | 再認証プロンプト表示 |
| ネットワークエラー | 接続失敗 | リトライ後エラーメッセージ |
| API制限 | レート制限超過 | 待機時間を表示 |
| パースエラー | 不正なレスポンス | エラーログ記録 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | ghubのデフォルト設定に依存 |
| リトライ間隔 | 指数バックオフ |
| リトライ対象エラー | 5xx系エラー、タイムアウト |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1時間あたり上限 | GitHub API制限（5000リクエスト/時） |
| バースト | 制限なし |

### 配信時間帯

制限なし

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

- GitHub Personal Access Tokenは`auth-source`で安全に管理される
- トークンには必要最小限のスコープ（notifications, repo）を付与
- ネットワーク通信はHTTPS経由で暗号化
- 画面共有時はリポジトリ名やイシュータイトルに機密情報が含まれる可能性に注意

## 備考

- Forgeは`+forge`フラグで有効化する必要がある
- `forge-database-file`でデータベース保存先をカスタマイズ可能
- キーバインド `SPC g l n` でリーダーキーから通知一覧にアクセス可能
- 通知バッファで`q`キーを押すとバッファを閉じる
- `forge-list-issues`、`forge-list-pullreqs`と併用してGitHub連携を活用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/tools/magit/config.el` | Forgeパッケージの設定とポップアップルール |
| 1-2 | packages.el | `modules/tools/magit/packages.el` | forgeパッケージの依存関係 |

**読解のコツ**: `(use-package! forge ...)`ブロックを中心に読む。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | +evil-bindings.el | `modules/config/default/+evil-bindings.el` | forge-list-notificationsのキーバインド |

**主要処理フロー**:
1. **571行目**: `("l" . "list")`プレフィックス定義
2. **571行目**: `"n"   #'forge-list-notifications` - 通知一覧コマンド

#### Step 3: Forge設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/tools/magit/config.el` | Forgeの初期化と設定 |

**主要処理フロー**:
- **177-199行目**: `(use-package! forge ...)`でForgeを設定
- **184行目**: `forge-database-file`でデータベース保存先設定
- **192-193行目**: `forge-topic-list-mode-map`でキーマップ設定
- **198-199行目**: ポップアップルールの設定

#### Step 4: ポップアップルールを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/tools/magit/config.el` | Forgeバッファのポップアップルール |

**主要処理フロー**:
- **198行目**: `set-popup-rule! "^\\*?[0-9]+:..."` - イシュー/PR表示用
- **199行目**: `set-popup-rule! "^\\*\\(?:[^/]+/[^ ]+ #[0-9]+\\*$\\|Issues\\|Pull-Requests\\|forge\\)" :ignore t` - Forge専用ウィンドウ管理

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

```
forge-list-notifications (Forgeパッケージ)
    │
    ├─ ghub-graphql / ghub-get
    │      └─ GitHub Notifications API
    │
    ├─ forge-database
    │      └─ emacsql (SQLite)
    │
    └─ forge-notifications-mode
           │
           └─ tabulated-list-mode
                  │
                  └─ *Notifications* バッファ表示
```

### データフロー図

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

SPC g l n ─────────▶ forge-list-notifications ───▶ *Notifications*バッファ
                            │
                            ▼
                    GitHub API呼び出し
                            │
                   ┌────────┴────────┐
                   ▼                 ▼
              成功応答            エラー
                   │                 │
                   ▼                 ▼
          通知データパース      エラーメッセージ
                   │
                   ▼
        forge-database更新
                   │
                   ▼
     forge-notifications-mode
                   │
                   ▼
           通知リスト表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/tools/magit/config.el` | ソース | Forge設定、ポップアップルール |
| packages.el | `modules/tools/magit/packages.el` | ソース | forgeパッケージ依存関係 |
| +evil-bindings.el | `modules/config/default/+evil-bindings.el` | ソース | キーバインド定義 |
| +emacs-bindings.el | `modules/config/default/+emacs-bindings.el` | ソース | 非Evilキーバインド |
| autoload.el | `modules/tools/magit/autoload.el` | ソース | 自動ロード関数 |
