# 機能設計書 25-起動時ダッシュボード表示

## 概要

本ドキュメントは、Doom Emacsにおける起動時ダッシュボード表示機能の設計を記述する。Doom Dashboardは、Emacs起動時に表示されるカスタムスプラッシュスクリーンであり、最近使用したファイル、プロジェクト切り替え、セッション復元などへのクイックアクセスを提供する。

### 本機能の処理概要

**業務上の目的・背景**：Emacs起動時に、ユーザーが頻繁に行う操作へのショートカットを提供し、作業開始までの時間を短縮する。また、DOOMロゴやパッケージロード時間の表示により、Doom Emacsのブランドアイデンティティを確立する。

**機能の利用シーン**：Emacs起動時の初期画面として自動表示、他のバッファがない状態でのフォールバック表示、`+doom-dashboard/open`コマンドによる明示的な表示。

**主要な処理内容**：
1. DOOMバナー（ASCIIアートまたは画像）の表示
2. ショートメニューウィジェット（最近開いたファイル、セッション復元、org-agenda等）
3. パッケージロード時間とロード数のベンチマーク表示
4. GitHubリンクを含むフッター表示
5. ワークスペース（persp-mode）との連携によるプロジェクトコンテキストの維持
6. テーマ変更時の自動リロード

**関連システム・外部連携**：persp-modeとの連携によるワークスペース管理、Projectileとの連携によるプロジェクト検出、Org-modeとの連携によるアジェンダ表示。

**権限による制御**：本機能は全ユーザーが利用可能であり、権限による制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Doom Dashboard | 主機能 | ダッシュボード画面の描画、ウィジェット表示、バナー表示処理 |

## 機能種別

UI表示 / ナビゲーション / スタートアップ画面

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +doom-dashboard-name | string | No | ダッシュボードバッファ名（デフォルト: "*doom*"） | 文字列 |
| +doom-dashboard-banner-file | string | No | バナー画像ファイル名（デフォルト: "default.png"） | 画像ファイル名 |
| +doom-dashboard-pwd-policy | symbol/string/function | No | default-directoryのポリシー（デフォルト: 'last-project） | シンボル、文字列、または関数 |

### 入力データソース

- +doom-dashboard-functions（ウィジェット関数リスト）
- +doom-dashboard-menu-sections（メニュー項目定義）
- +doom-dashboard-banner-dir（バナーディレクトリ）
- persp-mode（ワークスペース情報）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ダッシュボードバッファ | buffer | 表示用の特殊バッファ |
| ウィジェット表示 | text | バナー、メニュー、フッター等のテキスト |

### 出力先

- "*doom*"バッファ（フォールバックバッファ）

## 処理フロー

### 処理シーケンス

```
1. doom-init-ui-hookの実行
   └─ +doom-dashboard-init-h関数の呼び出し
2. ダッシュボード初期化
   └─ doom-fallback-buffer-nameの設定
   └─ initial-buffer-choiceの設定
3. ダッシュボードリロード
   └─ +doom-dashboard-mode有効化
   └─ +doom-dashboard-functions実行（各ウィジェット描画）
4. ウィジェット描画
   └─ doom-dashboard-widget-banner
   └─ doom-dashboard-widget-shortmenu
   └─ doom-dashboard-widget-loaded
   └─ doom-dashboard-widget-footer
5. リサイズ処理
   └─ センタリングとマージン調整
```

### フローチャート

```mermaid
flowchart TD
    A[Emacs起動] --> B[doom-init-ui-hook]
    B --> C[+doom-dashboard-init-h]
    C --> D[fallback-buffer設定]
    D --> E[ダッシュボードリロード]
    E --> F[+doom-dashboard-mode有効化]
    F --> G[バッファクリア]
    G --> H[doom-dashboard-widget-banner]
    H --> I[doom-dashboard-widget-shortmenu]
    I --> J[doom-dashboard-widget-loaded]
    J --> K[doom-dashboard-widget-footer]
    K --> L[リサイズ・センタリング]
    L --> M[表示完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-25-01 | PWDポリシー | +doom-dashboard-pwd-policyに従ってdefault-directoryを設定 | ダッシュボード表示時 |
| BR-25-02 | GUI画像表示 | GUIモードかつ画像ファイルが読み取り可能な場合のみ画像バナーを表示 | display-graphic-p |
| BR-25-03 | メニュー条件表示 | :when条件がnilでないメニュー項目のみ表示 | 各メニュー項目 |
| BR-25-04 | セッション復元条件 | persp-auto-save-fnameまたはdesktopファイルが存在する場合のみ表示 | セッション復元メニュー |

### 計算ロジック

- センタリング: `(max 0 (/ (- window-total-width +doom-dashboard--width) 2))`
- 垂直センタリング: `(/ (window-height) 2) - (/ (count-lines) 2)`

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ERR-25-01 | バナー画像読み取り不可 | 指定された画像ファイルが存在しないか読み取り不可 | ASCIIバナーにフォールバック |

### リトライ仕様

リトライ処理は実装されていない

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

該当なし

## パフォーマンス要件

- ダッシュボードリロードはタイマーで0.1秒遅延実行（フレーム初期化完了を待機）
- +doom-dashboard-inhibit-refreshによる不要なリロードの抑制

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

- 外部URLへのリンク（GitHubリンク）はユーザーの明示的なクリックでのみ開く
- バナー画像は信頼できるディレクトリからのみ読み込み

## 備考

- ダッシュボードは`*doom*`バッファ名で識別される
- Evilモードでの編集操作は無効化されている
- hl-line-modeは視覚的な問題を避けるため無効化

---

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

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

### 推奨読解順序

#### Step 1: 変数定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/doom-dashboard/config.el` | カスタマイズ変数、メニュー定義、フェイス定義 |

**読解のコツ**: `defvar`で定義された変数がダッシュボードの挙動を制御する。特に`+doom-dashboard-menu-sections`はメニュー項目のカスタマイズポイント。

**主要処理フロー**:
- **3-4行目**: ダッシュボード名とウィジェット関数リスト
- **15-20行目**: バナー設定変数
- **35-46行目**: PWDポリシー定義
- **48-91行目**: メニューセクション定義（アイコン、アクション、条件）
- **137-164行目**: フェイス定義

#### Step 2: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/doom-dashboard/config.el` | +doom-dashboard-init-h、各種フック登録 |

**主要処理フロー**:
- **104-131行目**: `+doom-dashboard-init-h` - 初期化関数
- **109-110行目**: fallback-bufferとinitial-buffer-choiceの設定
- **118-131行目**: 各種フックの登録（リサイズ、バッファ切替、persp連携）

#### Step 3: ウィジェット実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/doom-dashboard/config.el` | doom-dashboard-widget-* 関数群 |

**主要処理フロー**:
- **389-420行目**: `doom-dashboard-draw-ascii-banner-fn` - ASCIIバナー描画
- **422-441行目**: `doom-dashboard-widget-banner` - バナーウィジェット
- **443-452行目**: `doom-dashboard-widget-loaded` - ベンチマーク表示
- **454-506行目**: `doom-dashboard-widget-shortmenu` - メニューウィジェット
- **508-520行目**: `doom-dashboard-widget-footer` - フッターウィジェット

#### Step 4: 自動ロード関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload.el | `modules/ui/doom-dashboard/autoload.el` | インタラクティブコマンド |

**主要処理フロー**:
- **9-14行目**: `+doom-dashboard/open` - ダッシュボードを開く
- **17-21行目**: `+doom-dashboard/forward-button` - 次のボタンへ移動
- **24-28行目**: `+doom-dashboard/backward-button` - 前のボタンへ移動

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

```
doom-init-ui-hook
    │
    └─ +doom-dashboard-init-h
           │
           ├─ doom-fallback-buffer (バッファ設定)
           │
           ├─ +doom-dashboard-reload
           │      │
           │      ├─ +doom-dashboard-mode
           │      │
           │      └─ +doom-dashboard-functions
           │             ├─ doom-dashboard-widget-banner
           │             ├─ doom-dashboard-widget-shortmenu
           │             ├─ doom-dashboard-widget-loaded
           │             └─ doom-dashboard-widget-footer
           │
           └─ フック登録
                  ├─ window-configuration-change-hook
                  ├─ doom-switch-buffer-hook
                  ├─ persp-created-functions
                  └─ persp-activated-functions
```

### データフロー図

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

doom-init-ui-hook ───▶ +doom-dashboard-init-h ───▶ フック登録

+doom-dashboard-functions
       │
       ├─▶ widget-banner ───▶ バナー表示
       ├─▶ widget-shortmenu ───▶ メニュー表示
       ├─▶ widget-loaded ───▶ ベンチマーク表示
       └─▶ widget-footer ───▶ フッター表示

persp-mode ───▶ PWD更新 ───▶ default-directory設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/doom-dashboard/config.el` | ソース | メイン実装ファイル |
| autoload.el | `modules/ui/doom-dashboard/autoload.el` | ソース | インタラクティブコマンド |
| default.png | `modules/ui/doom-dashboard/banners/default.png` | リソース | デフォルトバナー画像 |
| test-doom-dashboard.el | `modules/ui/doom-dashboard/test/test-doom-dashboard.el` | テスト | テストファイル |
