# 通知設計書 13-circe-new-day-notifier

## 概要

本ドキュメントは、Doom EmacsのIRCモジュールにおけるcirce-new-day-notifier機能の設計仕様を記述する。この機能は、日付が変わった際にIRCバッファに視覚的な区切りを挿入し、会話ログの日付を明確にする。

### 本通知の処理概要

circe-new-day-notifierは、日付変更を検知してIRCチャットバッファに日付変更通知メッセージを挿入する機能である。これにより、長時間のIRC接続中に日付の境界が明確になり、会話の時系列を把握しやすくなる。

**業務上の目的・背景**：IRCクライアントを長時間起動し続ける場合、日付が変わっても視覚的な区切りがないとログの時系列が把握しにくくなる。特に、過去の会話を遡って確認する際に、どの発言がいつ行われたかを特定するのが困難である。本機能により、日付変更時点が明確に記録され、会話ログの可読性と検索性が向上する。

**通知の送信タイミング**：システム時刻が日付変更（00:00:00）を検知した際に、アクティブなすべてのIRCチャットバッファに通知メッセージが挿入される。これはcirce-new-day-notifierの内部タイマーによって監視・実行される。

**通知の受信者**：通知はIRCバッファ内に表示されるため、そのバッファを閲覧しているすべてのユーザーが視認できる。ローカル表示のみでIRCサーバーには送信されない。

**通知内容の概要**：通知メッセージには日付変更を示す固定テキストと曜日名が含まれる。フォーマットは`*** Day | Date changed [{day}]`の形式で、Doom Emacsのカスタムパディングスタイルに従う。

**期待されるアクション**：ユーザーは日付の区切りを認識し、必要に応じて特定の日付の会話を検索・参照することができる。アクションは必須ではなく、情報提供が主目的。

## 通知種別

バッファ内テキスト挿入（IRCバッファ内通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（バッファ挿入） |
| 優先度 | 低 |
| リトライ | なし |

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

アクティブなすべてのcirce-mode派生バッファ（チャンネルバッファ、プライベートメッセージバッファ）に通知が挿入される。

## 通知テンプレート

### バッファ内通知の場合

| 項目 | 内容 |
|-----|------|
| フォーマット | *** Day \| Date changed [{day}] |
| パディング | +irc-left-padding（デフォルト13文字） |
| フェイス | circe標準フェイス |

### 本文テンプレート

```
       *** Day | Date changed [Monday]
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | - | - | テキスト挿入のため添付なし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| day | 曜日名（Monday, Tuesday等） | システム日時 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| スケジュール | 日付変更（00:00:00） | circe-modeバッファが存在 | 深夜0時に自動実行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| circe-modeバッファなし | IRCバッファが存在しない場合は何も挿入されない |
| enable-circe-new-day-notifier未実行 | 機能が有効化されていない場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[circe読み込み] --> B[require 'circe-new-day-notifier]
    B --> C[enable-circe-new-day-notifier実行]
    C --> D[内部タイマー設定]
    D --> E{日付変更検知?}
    E -->|No| F[タイマー待機]
    F --> E
    E -->|Yes| G[すべてのcirceバッファを取得]
    G --> H{バッファあり?}
    H -->|No| I[次の日付変更まで待機]
    H -->|Yes| J[各バッファにメッセージ挿入]
    J --> K{全バッファ処理完了?}
    K -->|No| J
    K -->|Yes| I
    I --> E
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | - | データベースは使用しない |

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

本機能はデータベースを使用しない。

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | - | データベースは使用しない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| バッファ不在 | circeバッファが削除された | エラーなく処理をスキップ |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 1回（日付変更は1日1回） |
| 1日あたり上限 | 1回 |

### 配信時間帯

00:00:00に実行（日付変更時）

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

- ローカル表示のみでセキュリティリスクは低い
- システム時刻の改ざんにより不正なメッセージが挿入される可能性があるが、実害は軽微

## 備考

- Doom Emacsでは+irc--padヘルパー関数でカスタムフォーマットを適用
- lui-time-stamp-formatとは独立した日付表示機能
- ログファイルにも日付区切りが記録される

---

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

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

### 推奨読解順序

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

パディングヘルパー関数とフォーマット設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/app/irc/config.el` | +irc--pad関数の定義（行30-32） |
| 1-2 | config.el | `modules/app/irc/config.el` | +irc-left-padding変数（行3-6） |

**読解のコツ**: +irc--padはformat関数を2回ネストし、左パディングを適用した整形文字列を生成する。

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

circe-new-day-notifierの初期化と設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/app/irc/config.el` | use-package! circe-new-day-notifierブロック（行134-141） |

**主要処理フロー**:
1. **行134**: use-package!でcirce-new-day-notifierを設定
2. **行137**: after! circeでcirce読み込み後にrequire
3. **行139**: enable-circe-new-day-notifierで機能を有効化
4. **行140-141**: circe-new-day-notifier-format-messageをカスタムフォーマットに設定

#### Step 3: フォーマット設定を理解する

メッセージフォーマットのカスタマイズを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/app/irc/config.el` | circe-new-day-notifier-format-message設定（行140-141） |

**主要処理フロー**:
- **行140-141**: `(+irc--pad "Day" "Date changed [{day}]")`でDoom Emacs独自のフォーマットを適用

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

```
after! circe
    │
    └─ require 'circe-new-day-notifier
           │
           └─ enable-circe-new-day-notifier
                  │
                  └─ 内部タイマー設定
                         │
                         └─ [日付変更時]
                                │
                                └─ 各circeバッファに+irc--pad形式でメッセージ挿入
```

### データフロー図

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

システム時刻 ───▶ circe-new-day-notifier ───▶ IRCバッファ
                      │                            │
                      ├─ 日付変更検知              └─ "*** Day | Date changed [{day}]"
                      └─ +irc--padでフォーマット
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/app/irc/config.el` | ソース | circe-new-day-notifierの設定、フォーマットカスタマイズ |
