# 画面設計書 15-IRC Client

## 概要

本ドキュメントは、Doom EmacsにおけるIRC Client（IRCクライアント）画面の設計仕様を定義するものである。circeパッケージを利用したIRCチャット機能について、その表示形式、メッセージフォーマット、および通知機能を記載する。

### 本画面の処理概要

IRC Client画面は、IRC（Internet Relay Chat）プロトコルを使用したリアルタイムチャット機能を提供する。

**業務上の目的・背景**：開発者コミュニティやオープンソースプロジェクトでは、IRCがコミュニケーション手段として広く使用されている。本機能により、Emacs内でIRCチャットに参加できるため、エディタを離れることなくコミュニティとの対話やサポートを受けることが可能。専用IRCクライアントと同等の機能を提供しつつ、Emacsのテキスト編集機能やキーバインドを活用できる。

**画面へのアクセス方法**：`circe`コマンドでIRCサーバーに接続。設定済みのサーバーに接続すると、サーバーバッファとチャンネルバッファが作成される。

**主要な操作・処理内容**：
1. IRCサーバーへの接続・切断
2. チャンネルへの参加（JOIN）・退出（PART）
3. メッセージの送受信
4. ニックネームの色分け表示
5. デスクトップ通知（circe-notifications）
6. メッセージログの保存

**画面遷移**：サーバーバッファからチャンネルに参加するとチャンネルバッファが開く。tracking-modeにより未読メッセージのあるバッファに素早く移動できる。

**権限による表示制御**：本機能に権限による表示制御はない。IRCサーバーとチャンネルの権限はIRCプロトコル側で管理される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 82 | IRCクライアント | 主機能 | circeによるIRCチャット機能 |

## 画面種別

チャット（リアルタイムメッセージング）

## URL/ルーティング

Emacsモード: `circe-mode`, `circe-server-mode`, `circe-channel-mode`
バッファ名: サーバー名、チャンネル名に応じて動的に生成

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| サーバー設定 | 入力 | alist | IRCサーバー接続情報 |
| ニックネーム | 入力 | 文字列 | ユーザーのニックネーム |
| メッセージ | 入力 | 文字列 | 送信するメッセージ |
| チャンネルログ | 出力 | バッファ | チャンネルのメッセージ履歴 |
| タイムスタンプ | 出力 | 文字列 | メッセージの受信時刻 |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|---------|------|
| ニックネーム | 左側（13文字幅） | 発言者のニックネーム（色分け） |
| 区切り線 | ニック後 | 「│」文字 |
| メッセージ本文 | 右側 | チャットメッセージ |
| タイムスタンプ | 右マージン | HH:MM形式の時刻 |
| サーバーメッセージ | 左側 | 「-Server-」プレフィックス |
| 参加/退出通知 | 全体 | JOIN/PART/QUITイベント |

## イベント仕様

### 1-サーバー接続

`circe`コマンドでサーバーを選択し接続。接続成功時にサーバーバッファが作成され、チャンネル自動参加が設定されている場合は各チャンネルに自動JOIN。

### 2-チャンネル参加

`circe-command-JOIN`（`/join #channel`または`SPC m j`）でチャンネルに参加。参加成功時にチャンネルバッファが作成される。

### 3-メッセージ送信

入力プロンプトでメッセージを入力しRETで送信。`+irc/send-message`コマンドでも送信可能。

### 4-チャンネル退出

`circe-command-PART`（`/part`または`SPC m p`）でチャンネルから退出。

### 5-通知設定

サーバー接続完了時に`circe-notifications`が有効化される。`+irc-defer-notifications`で通知開始を遅延可能（ZNCユーザー向け）。

### 6-ニックネーム変更

`circe-command-NICK`でニックネームを変更。変更イベントはフォーマット済みでバッファに表示。

### 7-切断・終了

`+irc/quit`（`SPC m Q`）で全サーバーから切断。`+irc-disconnect-hook`が実行される。

### 8-トラッキング

`tracking-next-buffer`（`SPC m a`）で未読メッセージのあるバッファに移動。

## データベース更新仕様

本機能はデータベースを直接使用しない。メッセージログは`lui-logging`により`~/.doom.d/state/lui/`ディレクトリにファイルとして保存される。

## メッセージ仕様

| メッセージ種別 | フォーマット | 表示条件 |
|--------------|-------------|---------|
| 通常発言 | `{nick:+13s} │ {body}` | チャンネルでの発言 |
| アクション | `{nick:+13s} * {body}` | /meコマンド |
| サーバー通知 | `   -Server- _ {body}` | サーバーからの通知 |
| JOIN | `*** Join │ {nick} ({userinfo}) joined {channel}` | チャンネル参加 |
| PART | `*** Part │ {nick} ({userhost}) left {channel}: {reason}` | チャンネル退出 |
| QUIT | `*** Quit │ {nick} ({userhost}) left IRC: {reason}` | IRC切断 |
| NICK変更 | `*** Nick │ {old-nick} is now known as {new-nick}` | ニックネーム変更 |
| 日付変更 | `***  Day │ Date changed [{day}]` | 日付が変わった時 |

## 例外処理

| 例外状態 | 処理内容 |
|---------|---------|
| 接続切断 | `+irc-disconnect-hook`を実行、自動再接続を試行 |
| 長いニックネーム | `+irc-truncate-nick-char`（…）で切り詰め |
| スパムユーザー | `circe-reduce-lurker-spam`で潜伏者スパムを軽減 |
| ボットユーザー | `+irc-bot-list`でfool-faceを適用、トラッキング除外 |

## 備考

- circeパッケージはIRCプロトコル処理とUI表示を担当
- luiパッケージは入力インターフェースとログを担当
- circe-notificationsはデスクトップ通知を担当（macOS: osx-notifier, Linux: libnotify）
- ニックネームの左パディングは13文字（`+irc-left-padding`）
- タイムスタンプは右マージンに表示（`lui-time-stamp-position`）
- smartparens-modeはcirceバッファで無効化
- visual-line-modeはチャンネルバッファで有効化
- vertico使用時はconsult-buffer-sourcesに追加される

---

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

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

### 推奨読解順序

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

IRCクライアントの設定変数とメッセージフォーマットを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/app/irc/config.el` | 3-28行目: カスタム変数定義 |

**読解のコツ**: `+irc-`プレフィックスの変数がDoom独自設定、`circe-`プレフィックスがcirceパッケージ設定。

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

circeパッケージの基本設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/app/irc/config.el` | 41-82行目: circe設定 |

**主要処理フロー**:
1. **44-47行目**: デフォルトQUIT/PARTメッセージを無効化
2. **49-82行目**: メッセージフォーマット定義
3. **84-87行目**: バッファとモードの設定

#### Step 3: メッセージフォーマットを理解する

チャットメッセージの表示形式を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/app/irc/config.el` | 49-82行目: circe-format-*変数 |
| 3-2 | config.el | `modules/app/irc/config.el` | 30-32行目: `+irc--pad`ヘルパー関数 |

**主要処理フロー**:
- **49行目**: 通常発言フォーマット（左パディング+区切り線+本文）
- **53-56行目**: サーバー通知フォーマット
- **57-82行目**: JOIN/PART/QUIT等のイベントフォーマット

#### Step 4: 通知機能を理解する

デスクトップ通知の設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/app/irc/config.el` | 144-159行目: circe-notifications設定 |

**主要処理フロー**:
- **147-153行目**: `+irc-init-circe-notifications-h`で通知を初期化
- **149-152行目**: `+irc-defer-notifications`で遅延有効化（ZNC対応）
- **155-159行目**: OS別通知スタイル設定

#### Step 5: lui（入力インターフェース）を理解する

メッセージ入力とログ機能を理解する。

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

**主要処理フロー**:
- **165-166行目**: キーバインド設定
- **169-170行目**: タイムスタンプ形式と位置
- **172-174行目**: 自動ペースト、トラッキング、IRC色サポート
- **176-186行目**: 長いニックネームの切り詰め処理

#### Step 6: ニックネーム色分けを理解する

ニックネームの自動色分け機能を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | config.el | `modules/app/irc/config.el` | 122-131行目: circe-color-nicks設定 |

**主要処理フロー**:
- **129行目**: 最小コントラスト比4.5
- **130行目**: 全メッセージで色分け有効
- **131行目**: モード有効化

#### Step 7: ログ保存を理解する

メッセージログの保存設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 7-1 | config.el | `modules/app/irc/config.el` | 232-235行目: lui-logging設定 |

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

```
circe (サーバー接続)
    │
    ├─ circe-server-mode-hook
    │      └─ circe-server-buffers (サーバーバッファ作成)
    │
    ├─ circe-server-connected-hook
    │      └─ +irc-init-circe-notifications-h
    │             ├─ [遅延なし] enable-circe-notifications
    │             └─ [遅延あり] run-at-time → enable-circe-notifications
    │
    ├─ circe-channel-mode-hook
    │      ├─ turn-on-visual-line-mode
    │      ├─ +irc--add-circe-buffer-to-persp-h
    │      └─ turn-off-smartparens-mode
    │
    └─ circe-mode-hook
           └─ lui-mode
                  ├─ lui-time-stamp
                  ├─ lui-track
                  └─ lui-logging

circe-command-JOIN
    └─ チャンネルバッファ作成

+irc/quit
    ├─ 全サーバー切断
    └─ +irc-disconnect-hook実行
```

### データフロー図

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

IRCサーバー接続     ───▶ circe-network-options  ───▶ サーバーバッファ

チャンネル参加      ───▶ circe-command-JOIN     ───▶ チャンネルバッファ

メッセージ入力      ───▶ lui-send-input         ───▶ IRCサーバーへ送信

IRCメッセージ受信   ───▶ circe-format-*         ───▶ フォーマット済み表示
                              │
                              ├─ circe-color-nicks ───▶ 色付きニック
                              │
                              └─ lui-time-stamp    ───▶ タイムスタンプ

メンション受信      ───▶ circe-notifications    ───▶ デスクトップ通知

全メッセージ        ───▶ lui-logging            ───▶ ログファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/app/irc/config.el` | ソース | メイン設定ファイル、circe/lui設定 |
| doctor.el | `modules/app/irc/doctor.el` | 診断 | 設定診断 |
| packages.el | `modules/app/irc/packages.el` | 設定 | パッケージ依存関係定義 |
