# バッチ設計書 5-org-capture

## 概要

本ドキュメントは、シェルからOrg-modeのキャプチャ機能を呼び出すためのスクリプトである`org-capture`の設計仕様を定義するものである。

### 本バッチの処理概要

`org-capture`は、コマンドラインからEmacs Org-modeのキャプチャ機能（メモ、タスク、アイデアを素早く記録する機能）を利用するためのシェルスクリプトである。Emacsデーモンが起動していない場合は自動的に起動し、ポップアップフレームでキャプチャインターフェースを表示する。

**業務上の目的・背景**：Org-modeはEmacsの強力な情報管理ツールであり、org-captureはアイデアやタスクを素早く記録するための機能である。しかし、通常はEmacsを起動してから操作する必要がある。このスクリプトを使用することで、ターミナルやスクリプトからワンコマンドでキャプチャを実行でき、作業の中断を最小限に抑えながらメモを取ることができる。

**バッチの実行タイミング**：ユーザーが手動でコマンドを実行する随時実行型。アイデアを素早くキャプチャしたい時に使用される。

**主要な処理内容**：
1. Emacsサーバー/デーモンの起動確認
2. 必要に応じて一時的なEmacsデーモンを起動
3. キャプチャキーとメッセージ引数の解析
4. emacsclient経由でorg-captureフレームを開く
5. スクリプト終了時の一時デーモンのクリーンアップ

**前後の処理との関連**：Emacsのorg-captureテンプレート設定に依存する。キャプチャされた内容は設定されたOrgファイルに保存される。

**影響範囲**：Orgファイル（通常は設定で指定されたキャプチャファイル）への書き込みが行われる。

## バッチ種別

ユーティリティスクリプト / Emacs連携

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | ユーザー任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動（ユーザーコマンド実行） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Emacs インストール | emacs および emacsclient が利用可能であること |
| Org-mode 設定 | org-capture のテンプレートが設定されていること |
| +org-capture/open-frame 関数 | Doom Emacs の org モジュールが有効であること |

### 実行可否判定

1. emacsclient コマンドが利用可能であること
2. Emacsサーバーが起動中、または起動可能であること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| -k KEY | 文字列 | No | nil | org-capture テンプレートのキー |
| MESSAGE | 文字列 | No | なし | キャプチャするメッセージ本文 |
| - (stdin) | テキスト | No | なし | 標準入力からメッセージを読み取る |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| コマンドライン引数 | テキスト | キャプチャキーとメッセージ |
| 標準入力 | テキスト | "-" 指定時にメッセージを読み取り |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Orgファイル | Org-mode形式 | キャプチャされたエントリ |
| 標準出力 | テキスト | 起動メッセージ（デーモン起動時） |
| Emacsフレーム | GUI | org-captureポップアップウィンドウ |

### 出力ファイル仕様

出力ファイルはOrg-modeのキャプチャ設定に依存する。

## 処理フロー

### 処理シーケンス

```
1. Emacsサーバー確認
   └─ emacsclient --eval nil で接続テスト
   └─ 接続失敗時は emacs --daemon で起動

2. クリーンアップ設定
   └─ 一時デーモン起動時は EXIT/INT/TERM トラップを設定
   └─ cleanup 関数で kill-emacs を実行

3. 引数解析
   └─ getopts で -k オプション（キャプチャキー）を解析
   └─ 残りの引数をメッセージとして取得
   └─ "-" の場合は標準入力から読み取り

4. ターミナル互換性対応
   └─ $TERM が "alacritty" の場合、xterm-256color に変更

5. org-capture フレームを開く
   └─ emacsclient -a "" -e "(+org-capture/open-frame ...)" を実行
```

### フローチャート

```mermaid
flowchart TD
    A[org-capture 開始] --> B{Emacsサーバー確認}
    B -->|接続成功| C[引数解析]
    B -->|接続失敗| D[Emacsデーモン起動]
    D --> E[クリーンアップトラップ設定]
    E --> C
    C --> F{-k オプションあり?}
    F -->|Yes| G[キャプチャキー設定]
    F -->|No| H[キー = nil]
    G --> I{メッセージ引数確認}
    H --> I
    I -->|"-"| J[標準入力から読み取り]
    I -->|文字列| K[引数をメッセージに設定]
    I -->|なし| L[メッセージ空]
    J --> M{$TERM確認}
    K --> M
    L --> M
    M -->|alacritty| N[TERM=xterm-256color]
    M -->|その他| O[emacsclient実行]
    N --> O
    O --> P[org-captureフレーム表示]
    P --> Q[終了]
```

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

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

本スクリプト自体はデータベースを使用しない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

### テーブル別操作詳細

データベース操作は行わない。Orgファイルへの書き込みはEmacs側で処理される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非ゼロ | Emacs起動失敗 | Emacsデーモンが起動できない | Emacsのインストールを確認 |
| 非ゼロ | 接続失敗 | emacsclientがサーバーに接続できない | サーバー設定を確認 |
| 非ゼロ | 関数未定義 | +org-capture/open-frame が存在しない | Doom orgモジュールを有効化 |

### リトライ仕様

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

### 障害時対応

1. `emacs --daemon` が正常に起動するか直接確認
2. `emacsclient -e "(+org-capture/open-frame)"` を直接実行してテスト
3. Doom Emacsの設定で`:editor org`モジュールが有効か確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | Orgファイル書き込み単位（Emacs側で管理） |
| コミットタイミング | ユーザーがキャプチャを確定時 |
| ロールバック条件 | ユーザーがキャプチャをキャンセル時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/実行 |
| 目標処理時間 | サーバー起動済み: 1秒以内、デーモン起動: 数秒 |
| メモリ使用量上限 | Emacsプロセス標準使用量 |

## 排他制御

- Emacsサーバーへの接続は単一クライアントに制限されない
- Orgファイルの編集はEmacs側のバッファロック機構に依存

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 起動ログ | デーモン起動時 | "No Emacs daemon/server is available! Starting one..." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | 監視対象外（インタラクティブツール） |

## 備考

- `set -e` により、コマンドエラー時は即座に終了
- cleanup関数は`(let (kill-emacs-hook) (kill-emacs))`でフックを無視してEmacsを終了
- `emacsclient -a ""` は接続失敗時に自動的にサーバーを起動する機能を持つ
- Alacrittyターミナルで「not a valid terminal」エラーが発生するため、$TERMを変更
- コメントアウトされたコード：`+org-capture-available-keys`でキー一覧を取得する機能（未実装）
