# 画面設計書 10-Workspaces

## 概要

本ドキュメントは、Doom Emacsのワークスペース管理画面（Workspaces）の設計仕様を定義する。

### 本画面の処理概要

Workspacesは、persp-modeを基盤としたワークスペース（パースペクティブ）管理機能を提供し、プロジェクト単位でバッファを分離・管理できるタブ風のインターフェースを実現する。

**業務上の目的・背景**：
Workspacesは、複数のプロジェクトを同時に扱う開発者のために、プロジェクトごとにバッファ一覧を分離し、タブブラウザのタブのように切り替えられる機能を提供する。セッション永続化により、Emacsを再起動しても作業状態を復元できる。VSCodeやIDEのワークスペース機能に相当する体験をEmacsで実現する。

**画面へのアクセス方法**：
- `SPC TAB TAB`（+workspace/display）でワークスペース一覧表示
- `SPC TAB n`（+workspace/new）で新規ワークスペース作成
- `SPC TAB 1-9`で特定のワークスペースに切り替え
- プロジェクト切り替え時に自動的にワークスペース作成/切り替え

**主要な操作・処理内容**：
1. ワークスペースの作成・削除・リネーム
2. ワークスペース間のバッファ分離
3. ワークスペースの切り替え（番号/名前指定）
4. セッションの保存・復元
5. プロジェクト連携によるワークスペース自動作成
6. winner-mode履歴のワークスペース単位保存

**画面遷移**：
- 遷移元：任意のバッファから
- 遷移先：選択したワークスペース内のバッファ

**権限による表示制御**：
- 権限による表示制御は存在しない

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 41 | ワークスペース管理（タブ風） | 主機能 | ワークスペース作成、切り替え、削除、セッション管理 |
| 7 | プロジェクト管理 | 補助機能 | プロジェクト切り替え時のワークスペース自動作成 |
| 42 | セッション保存・復元 | 補助機能 | ワークスペース状態の永続化 |

## 画面種別

エコーエリア表示 / ウィンドウ状態管理

## URL/ルーティング

Emacsアプリケーションのため、URLルーティングは存在しない。persp-modeを通じてワークスペースを管理する。

## 入出力項目

| 項目名 | 種別 | 必須 | 説明 |
|--------|------|------|------|
| ワークスペース名 | 入力 | いいえ | 新規作成・リネーム時に指定（省略時は自動生成） |

## 表示項目

| 項目名 | 種別 | 説明 |
|--------|------|------|
| タブ一覧 | テキスト | エコーエリアに表示されるワークスペースタブ |
| 現在のワークスペース | ハイライト | +workspace-tab-selected-faceで強調 |
| ワークスペース番号 | テキスト | [1] [2] [3]... の形式で表示 |
| メッセージ | テキスト | 操作結果のフィードバック |

## イベント仕様

### 1-ワークスペース操作

| コマンド | 動作 |
|---------|------|
| +workspace/new | 新規ワークスペースを作成 |
| +workspace/new-named | 名前を指定して新規作成 |
| +workspace/kill | 現在のワークスペースを削除 |
| +workspace/rename | ワークスペースをリネーム |
| +workspace/display | ワークスペース一覧を表示 |

### 2-ワークスペース切り替え

| コマンド | 動作 |
|---------|------|
| +workspace/switch-to | 指定したワークスペースに切り替え |
| +workspace/switch-to-0〜9 | 番号指定で切り替え |
| +workspace/cycle | 次/前のワークスペースへ |
| +workspace/switch-left | 左のワークスペースへ |
| +workspace/switch-right | 右のワークスペースへ |
| +workspace/other | 最後に使用したワークスペースへ |

### 3-セッション管理

| コマンド | 動作 |
|---------|------|
| +workspace/save | ワークスペースをファイルに保存 |
| +workspace/load | 保存したワークスペースをロード |
| +workspace/restore-last-session | 最後のセッションを復元 |
| +workspace/kill-session | 全ワークスペースを削除 |

### 4-キーバインド

| キー | 動作 |
|------|------|
| SPC TAB TAB | ワークスペース一覧表示 |
| SPC TAB n | 新規ワークスペース |
| SPC TAB d | ワークスペース削除 |
| SPC TAB r | リネーム |
| SPC TAB 1-9 | 番号指定で切り替え |
| SPC TAB [ | 左のワークスペースへ |
| SPC TAB ] | 右のワークスペースへ |

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

本画面はEmacs UI機能であり、データベースとの連携は存在しない。ワークスペース状態はファイルシステムに永続化される。

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| なし | - | - | データベース操作なし |

## メッセージ仕様

| メッセージ種別 | 表示条件 | メッセージ内容 |
|---------------|---------|---------------|
| 成功 | ワークスペース作成/削除/リネーム成功 | "'name' workspace saved/deleted/renamed" |
| 警告 | ワークスペースが存在しない | "'name' workspace doesn't exist" |
| エラー | 削除できない | "Can't delete 'name' workspace" |
| エラー | 他のフレームで表示中 | "Can't close workspace, it's visible in another frame" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 最後のワークスペース削除 | mainワークスペースに切り替え |
| 保護されたワークスペース（nil）の操作 | エラーメッセージを表示 |
| 他のフレームで表示中のワークスペース削除 | エラーメッセージを表示 |

## 備考

- `+workspaces-main`変数でメインワークスペース名を定義（デフォルト: "main"）
- プロジェクト切り替え時の動作は`+workspaces-on-switch-project-behavior`で制御
- セッションは`persp-save-dir`に自動保存される
- tab-bar-modeとの連携でタブバーにもワークスペースを表示可能

---

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

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

### 推奨読解順序

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

ワークスペース管理の変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/workspaces/config.el` | 行10-32: 変数定義（+workspaces-main, +workspaces-switch-project-function等） |

**読解のコツ**: `+workspaces-main`（メインワークスペース名）、`+workspaces-on-switch-project-behavior`（プロジェクト切替動作）が重要。

#### Step 2: persp-mode設定を理解する

persp-modeの基本設定を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/workspaces/config.el` | 行39-54: persp-mode設定 |

**主要処理フロー**:
1. **行42**: doom-init-ui-hookでpersp-mode有効化
2. **行44-54**: persp-mode設定変数（autokill, save-dir, auto-save等）

#### Step 3: ワークスペース初期化を理解する

ワークスペースの初期化処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/workspaces/config.el` | 行61-104: 初期化フック |

**主要処理フロー**:
- **行62-69**: nilワークスペースの回避
- **行72-86**: mainワークスペースの確保
- **行87-104**: uniquify無効化、doom-buffer-listオーバーライド

#### Step 4: インタラクティブコマンドを理解する

ユーザーが利用するコマンドを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload/workspaces.el | `modules/ui/workspaces/autoload/workspaces.el` | 行98-201: アクション関数群 |
| 4-2 | autoload/workspaces.el | `modules/ui/workspaces/autoload/workspaces.el` | 行206-468: コマンド関数群 |
| 4-3 | autoload/workspaces.el | `modules/ui/workspaces/autoload/workspaces.el` | 行473-513: タブ表示関数群 |

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

```
doom-init-ui-hook
    │
    └─ persp-mode有効化
           │
           ├─ +workspaces-init-first-workspace-h
           │      └─ mainワークスペース作成
           │
           └─ +workspaces-init-persp-mode-h
                  └─ uniquify無効化、doom-buffer-listオーバーライド

projectile-switch-project
    │
    └─ +workspaces-switch-to-project-h
           ├─ ワークスペース存在確認
           │      └─ 存在 → +workspace-switch
           │
           └─ 不存在 → +workspace-new → +workspace-switch

+workspace/display
    │
    └─ +workspace--tabline
           └─ エコーエリアにタブ表示
```

### データフロー図

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

SPC TAB n ──────────▶ +workspace/new ─────────▶ 新規ワークスペース + 表示更新

SPC TAB 1 ──────────▶ +workspace/switch-to ───▶ ワークスペース切り替え

プロジェクト選択 ────▶ +workspaces-switch-to-project-h ▶ ワークスペース自動作成/切替

セッション保存 ──────▶ persp-save-state-to-file ─▶ ファイル永続化
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/workspaces/config.el` | ソース | メイン設定、persp-mode設定 |
| autoload/workspaces.el | `modules/ui/workspaces/autoload/workspaces.el` | ソース | ワークスペース操作コマンド |
| autoload/evil.el | `modules/ui/workspaces/autoload/evil.el` | ソース | Evil連携 |
| test/test-workspaces.el | `modules/ui/workspaces/test/test-workspaces.el` | テスト | ユニットテスト |
| persp-mode | 外部パッケージ | 依存 | ワークスペース機能本体 |
