# 機能設計書 82-IRCクライアント

## 概要

本ドキュメントは、Doom EmacsにおけるIRCクライアント機能（`modules/app/irc/`）の設計を記述する。この機能は、Circeパッケージを使用してEmacs内でフル機能のIRCクライアントを提供し、複数サーバー接続、通知、ロギング、補完フレームワーク連携などを実現する。

### 本機能の処理概要

**業務上の目的・背景**：開発者コミュニティやオープンソースプロジェクトでは、IRCがリアルタイムコミュニケーションの重要なチャネルとして使用されている。本機能は、コーディング作業中にEmacsから離れることなくIRCコミュニケーションを行える環境を提供する。ワークスペース分離により、チャット作業と開発作業のコンテキストを明確に分離できる。

**機能の利用シーン**：
- オープンソースプロジェクトのIRCチャンネルへの参加
- チームメンバーとのリアルタイムコミュニケーション
- 技術サポートチャンネルでの質問・回答
- ZNCバウンサー経由での常時接続IRC運用

**主要な処理内容**：
1. `=irc`コマンドによるIRC接続の開始と専用ワークスペースへの切り替え
2. 複数IRCネットワークへの同時接続管理
3. チャンネル/サーバーバッファ間のジャンプナビゲーション
4. デスクトップ通知の送信（circe-notifications）
5. チャットログの永続化（lui-logging）
6. ニックネームの色分け表示（circe-color-nicks）
7. 長いニックネームの切り詰め表示
8. ボットメッセージのフィルタリング

**関連システム・外部連携**：
- IRCサーバー: RFC 1459/2812準拠のIRCプロトコル
- ZNC: IRCバウンサーとの連携（接続遅延通知対応）
- デスクトップ通知: macOS (osx-notifier)、Linux (libnotify)
- 補完フレームワーク: Vertico (consult連携)、Ivy

**権限による制御**：IRCサーバー接続時の認証情報は`circe-network-options`で設定。NickServやSASL認証をサポート。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | IRC Client | 主画面 | circeによるIRCチャット機能 |

## 機能種別

リアルタイム通信 / テキスト入出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +irc-left-padding | integer | No | 左側のパディング幅（デフォルト: 13） | 12以上推奨 |
| +irc-truncate-nick-char | character | No | 長いニック切り詰め時の文字（デフォルト: ?...） | 単一文字 |
| +irc-scroll-to-bottom-on-commands | list | No | 自動スクロールするコマンドリスト | シンボルリスト |
| +irc-disconnect-hook | hook | No | 切断時に実行されるフック | フック関数 |
| +irc-bot-list | list | No | ボットとして扱うニックのリスト（デフォルト: "fsbot", "rudybot"） | 文字列リスト |
| +irc-defer-notifications | number/nil | No | 通知を遅延させる秒数（ZNC用） | 正の数値またはnil |

### 入力データソース

- ユーザー入力（チャットメッセージ）
- IRCサーバーからの受信メッセージ
- `circe-network-options`で設定されたサーバー情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| サーバーバッファ | buffer | IRCサーバー接続状態とシステムメッセージ |
| チャンネルバッファ | buffer | 各チャンネルのチャットログ |
| 詳細バッファ | buffer | ニック情報等の詳細表示 |
| 通知 | system-notification | デスクトップ通知（言及時等） |
| ログファイル | file | チャットログの永続化ファイル |

### 出力先

- IRCバッファ: circe-modeのバッファ群
- ログファイル: `doom-profile-state-dir/lui/`
- デスクトップ通知: OS通知システム

## 処理フロー

### 処理シーケンス

```
1. =irc コマンド実行
   └─ 引数でワークスペース作成を抑制可能
2. ワークスペース切り替え/作成（*IRC*）
   └─ +irc-setup-wconf 呼び出し
3. 既存接続の確認
   └─ circe-modeバッファが存在すれば再利用
4. circe-network-options からネットワーク一覧取得
   └─ 各ネットワークに対してcirce関数を呼び出し
5. サーバー接続開始
   └─ IRC NICK/USER コマンド送信
6. 認証処理（設定に応じて）
   └─ NickServ IDENTIFY または SASL認証
7. 自動JOIN処理
   └─ :channels オプションで指定されたチャンネルに参加
8. メッセージ受信/送信ループ
   └─ lui-mode による入出力処理
```

### フローチャート

```mermaid
flowchart TD
    A[=irc 実行] --> B{workspaces有効?}
    B -->|Yes| C[*IRC*ワークスペースに切り替え]
    B -->|No| D[現在のウィンドウで実行]
    C --> E{既存circeバッファ存在?}
    D --> E
    E -->|Yes| F[メッセージ表示して終了]
    E -->|No| G{circe-network-options設定済み?}
    G -->|Yes| H[全ネットワークに接続]
    G -->|No| I[circe対話的に呼び出し]
    H --> J[各サーバーに接続]
    I --> J
    J --> K[認証処理]
    K --> L[チャンネルJOIN]
    L --> M[メッセージ受信待機]
    M --> N{通知条件?}
    N -->|Yes| O[デスクトップ通知送信]
    N -->|No| M
    O --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ワークスペース分離 | IRCバッファは専用ワークスペース(*IRC*)で管理 | workspacesモジュール有効時 |
| BR-02 | ボットフィルタリング | +irc-bot-listに含まれるニックはcirce-fool-faceで表示し追跡しない | 常時 |
| BR-03 | ニック切り詰め | +irc-left-paddingを超える長さのニックは末尾を省略文字で置換 | 常時 |
| BR-04 | 通知遅延 | ZNC等使用時、+irc-defer-notifications秒後に通知を有効化 | 数値設定時 |
| BR-05 | 切断フック | IRC接続が切断されたら+irc-disconnect-hookを実行 | 常時 |
| BR-06 | バッファリアル化 | circeバッファはdoomのリアルバッファとして扱う | 常時 |

### 計算ロジック

ニックネーム表示幅の計算：
```elisp
(format "%%%ds | %%s" +irc-left-padding)
;; 例: +irc-left-padding=13 の場合 "%13s | %s"
```

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

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

本機能はデータベースを使用しない。ログはファイルシステムに永続化される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 接続エラー | IRCサーバーに接続できない | ネットワーク設定を確認、circe-reconnect実行 |
| N/A | 認証エラー | NickServ/SASL認証失敗 | パスワード設定を確認 |
| N/A | ニック衝突 | 使用したいニックが既に使用中 | 代替ニック設定または手動変更 |

### リトライ仕様

- Circeは自動再接続機能を内蔵
- `circe-reconnect`コマンドで手動再接続可能
- `circe-reconnect-all`で全サーバーに再接続

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

該当なし

## パフォーマンス要件

- メッセージ受信: リアルタイム表示
- ログ書き込み: 非同期（lui-logging）
- 通知送信: 即時

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

- IRC接続パスワードは`circe-network-options`で設定（:pass、:sasl-username、:sasl-password）
- TLS/SSL接続をサポート（:use-tls t）
- 認証情報はEmacs変数に保持されるため、設定ファイルの適切な保護が必要
- auth-source連携による安全な認証情報管理を推奨

## 備考

- lui-modeはチャットUI用の汎用フレームワークで、タイムスタンプ表示や入力履歴機能を提供
- circe-color-nicksによりニックネームごとに異なる色が自動割り当て
- visual-line-modeが自動有効化され、長いメッセージの折り返し表示に対応
- smartparens-modeは無効化される（チャット入力との相性問題回避）

---

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

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

### 推奨読解順序

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

設定変数を理解し、機能のカスタマイズポイントを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/app/irc/config.el` | defvar定義（1-28行目） |
| 1-2 | autoload/irc.el | `modules/app/irc/autoload/irc.el` | +irc--workspace-name変数（3行目） |

**読解のコツ**:
- `defvar`は設定可能なグローバル変数
- `defsubst`はインライン展開される関数（高速化用）
- `define-obsolete-variable-alias`は廃止予定の変数の互換性対応

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | autoload/irc.el | `modules/app/irc/autoload/irc.el` | =irc関数（19-30行目） |
| 2-2 | autoload/irc.el | `modules/app/irc/autoload/irc.el` | +irc-setup-wconf関数（5-16行目） |

**主要処理フロー**:
1. **19行目**: `=irc`関数定義、INHIBIT-WORKSPACE引数で制御
2. **25行目**: +irc-setup-wconfでワークスペース準備
3. **26-27行目**: 既存バッファ確認
4. **28-29行目**: circe-network-optionsから全ネットワークに接続
5. **30行目**: 設定なければ対話的にcirce呼び出し

#### Step 3: サーバー設定APIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload/settings.el | `modules/app/irc/autoload/settings.el` | set-irc-server!関数（4-18行目） |

**主要処理フロー**:
- **4-11行目**: サーバー登録マクロの定義
- **14-15行目**: :hostが未指定ならSERVER名をホストとして使用
- **16-17行目**: circe-network-optionsに設定を追加

#### Step 4: Circe設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/app/irc/config.el` | circe use-package設定（41-119行目） |
| 4-2 | config.el | `modules/app/irc/config.el` | circe-format-*変数（49-82行目） |

**主要処理フロー**:
- **44-47行目**: デフォルトのquit/partメッセージをnil（無し）に設定
- **49-82行目**: メッセージフォーマットを+irc-left-paddingに基づいて設定
- **84行目**: doom-real-buffer-functionsに+circe-buffer-pを追加
- **89-92行目**: 切断フックのadvice定義
- **94-98行目**: ボットメッセージのフィルタリング設定

#### Step 5: lui設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.el | `modules/app/irc/config.el` | lui use-package設定（162-229行目） |

**主要処理フロー**:
- **165行目**: C-uでlui-kill-to-beginning-of-lineにバインド
- **169-170行目**: タイムスタンプ表示設定（右マージン、HH:MM形式）
- **172-174行目**: autopaste、track、IRC colors有効化
- **176-186行目**: ニック切り詰め処理のフック定義
- **188-200行目**: Evil連携（インサート位置の自動調整）

#### Step 6: 補完フレームワーク連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | autoload/vertico.el | `modules/app/irc/autoload/vertico.el` | +irc/vertico-jump-to-channel（5-14行目） |
| 6-2 | autoload/ivy.el | `modules/app/irc/autoload/ivy.el` | +irc/ivy-jump-to-channel（5-26行目） |

**主要処理フロー**:
- Vertico: consult-multiを使用したバッファ選択
- Ivy: ivy-readを使用したバッファ選択（サーバーフィルタ対応）

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

```
=irc
    │
    ├─ +irc-setup-wconf
    │      ├─ +workspace-switch (ui/workspaces)
    │      └─ doom-buffers-in-mode
    │
    └─ circe (外部パッケージ)
           │
           ├─ circe-server-connect
           │      └─ make-network-process
           │
           ├─ circe-server-chat-buffers
           │
           └─ lui-mode
                  ├─ lui-input
                  └─ lui-logging

+irc/quit
    │
    ├─ disable-circe-notifications
    ├─ kill-buffer (各circeバッファ)
    └─ +workspace/kill
```

### データフロー図

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

ユーザー入力 ─────────────┐
                          │
IRCサーバー ──────────────┼──▶ circe-mode ──────────────▶ チャットバッファ
(メッセージ受信)          │       │
                          │       ├──▶ lui-logging ──────▶ ログファイル
circe-network-options ────┘       │
                                  └──▶ circe-notifications ▶ デスクトップ通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/app/irc/config.el` | ソース | パッケージ設定とキーバインド定義 |
| autoload/irc.el | `modules/app/irc/autoload/irc.el` | ソース | メインコマンドと接続管理 |
| autoload/settings.el | `modules/app/irc/autoload/settings.el` | ソース | サーバー設定API |
| autoload/vertico.el | `modules/app/irc/autoload/vertico.el` | ソース | Vertico連携 |
| autoload/ivy.el | `modules/app/irc/autoload/ivy.el` | ソース | Ivy連携 |
| doctor.el | `modules/app/irc/doctor.el` | ソース | 設定診断 |
| packages.el | `modules/app/irc/packages.el` | 設定 | 依存パッケージの宣言 |
