# 通知設計書 51-WINDOW_LUA_STATUS_TIP

## 概要

本ドキュメントは、Lua Language Serverにおけるステータスアイコン説明通知（WINDOW_LUA_STATUS_TIP）の設計仕様を定義するものである。

### 本通知の処理概要

本通知は、エディタのステータスバーに表示される猫アイコンについて、ユーザーに楽しい説明メッセージを提供する機能である。1%の確率でランダムに表示され、アイコンが猫であることをユーモラスに伝える。

**業務上の目的・背景**：Lua Language Serverはステータスバーに猫のアイコン（😺）を使用しているが、一部のユーザーは犬や狐と誤解する可能性がある。この通知は、アイコンが猫であることをユーザーにわかりやすく、かつ楽しく伝えることで、ユーザーエクスペリエンスを向上させることを目的としている。

**通知の送信タイミング**：サーバー起動時に1%の確率で選択され、その後ステータスバーのツールチップ更新時に表示される。この確率選択はサーバーのセッション開始時に一度だけ行われる。

**通知の受信者**：エディタ（VSCode等のLSPクライアント）を使用しているユーザー。ステータスバーにマウスホバーした際にツールチップとして表示される。

**通知内容の概要**：「このアイコンは猫です。犬でも狐でもありません！」という内容のメッセージをASCIIアートの矢印と共に表示する。

**期待されるアクション**：ユーザーへの情報提供が目的であり、特別なアクションは期待されない。ユーザーがアイコンの意味を理解し、開発体験を楽しむことを意図している。

## 通知種別

アプリ内通知（ステータスバーツールチップ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 低 |
| リトライ | 無 |

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

- 送信先はLSPクライアント（エディタ）
- 全てのユーザーが対象だが、表示確率は1%

## 通知テンプレート

### ツールチップ通知の場合

| 項目 | 内容 |
|-----|------|
| 表示場所 | ステータスバーツールチップ |
| 形式 | テキスト |

### 本文テンプレート

英語版:
```

This icon is a cat,
Not a dog nor a fox!
             ↓↓↓
```

日本語版:
```

このアイコンは猫です。
犬でも狐でもありません！
             ↓↓↓
```

### 添付ファイル

該当なし

## テンプレート変数

該当なし（固定メッセージ）

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| サーバー起動 | サービス初期化時 | `math.random(100) == 1` | 1%の確率で表示フラグがONになる |
| ステータス更新 | `m.reportStatus()` 呼び出し | `showStatusTip == true` | フラグがONの場合のみメッセージを追加 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `showStatusTip == false` | サーバー起動時の乱数判定で非表示が選択された場合 |
| `client.getOption('statusBar') == false` | クライアントがステータスバーをサポートしていない場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[サーバー起動] --> B[乱数判定 1%]
    B -->|当たり| C[showStatusTip = true]
    B -->|外れ| D[showStatusTip = false]
    C --> E[ステータス更新要求]
    D --> E
    E --> F{showStatusTipフラグ確認}
    F -->|true| G[TIPメッセージをツールチップに追加]
    F -->|false| H[通常のツールチップのみ]
    G --> I[$/status/report通知送信]
    H --> I
    I --> J[終了]
```

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

### 参照テーブル一覧

該当なし（データベースを使用しない）

### 更新テーブル一覧

該当なし（データベースを使用しない）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | - | - |

### リトライ仕様

該当なし（リトライ不要）

## 配信設定

### レート制限

該当なし

### 配信時間帯

制限なし（常時利用可能）

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

- 個人情報を含まない固定メッセージのため、特別な考慮は不要

## 備考

- この通知は純粋に装飾的な目的で使用され、機能的な影響はない
- 表示確率1%は開発者のユーモアとして実装されている
- 猫アイコン（😺）はLua Language Serverのマスコットキャラクターとして使用されている

---

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

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

### 推奨読解順序

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

まず、通知メッセージの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | script.lua | `locale/en-us/script.lua` | WINDOW_LUA_STATUS_TIPの英語メッセージ定義（570-576行目） |
| 1-2 | script.lua | `locale/ja-jp/script.lua` | WINDOW_LUA_STATUS_TIPの日本語メッセージ定義（570-576行目） |

**読解のコツ**: 複数行文字列は `[[` と `]]` で囲まれている。

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

処理の起点となるサービスモジュールを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | service.lua | `script/service/service.lua` | reportStatus関数でのTIP表示ロジック（209-245行目） |

**主要処理フロー**:
1. **209行目**: `showStatusTip = math.random(100) == 1` - 1%の確率でフラグ設定
2. **211行目**: `m.reportStatus()` 関数定義開始
3. **235-237行目**: `showStatusTip` が true の場合、WINDOW_LUA_STATUS_TIPをツールチップに追加
4. **244行目**: `proto.notify('$/status/report', info)` でクライアントに通知

#### Step 3: 言語処理を理解する

メッセージの国際化処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | language.lua | `script/language.lua` | `lang.script()` 関数の動作原理 |

**主要処理フロー**:
- **236行目**: `lang.script('WINDOW_LUA_STATUS_TIP')` で現在のロケールに応じたメッセージを取得

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

```
service.lua
    │
    ├─ m.start() [267行目]
    │      │
    │      └─ showStatusTip = math.random(100) == 1 [209行目]
    │
    ├─ m.reportStatus() [211行目]
    │      │
    │      ├─ lang.script('WINDOW_LUA_STATUS_WORKSPACE', ...) [231行目]
    │      ├─ lang.script('WINDOW_LUA_STATUS_CACHED_FILES', ...) [233行目]
    │      ├─ lang.script('WINDOW_LUA_STATUS_MEMORY_COUNT', ...) [234行目]
    │      ├─ lang.script('WINDOW_LUA_STATUS_TIP') [236行目] ← 本通知
    │      └─ proto.notify('$/status/report', info) [244行目]
    │
    └─ language.lua
           └─ lang.script() - メッセージ取得
```

### データフロー図

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

サーバー起動 ───▶ math.random(100) ───▶ showStatusTipフラグ設定
                                              │
                                              ▼
ステータス更新 ───▶ reportStatus() ───▶ ツールチップ文字列構築
                                              │
                                              ▼
                            proto.notify('$/status/report')
                                              │
                                              ▼
                                   [クライアント（エディタ）]
                                              │
                                              ▼
                                   ステータスバーツールチップ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| service.lua | `script/service/service.lua` | ソース | ステータス報告処理のメイン実装 |
| script.lua | `locale/en-us/script.lua` | 設定 | 英語メッセージ定義 |
| script.lua | `locale/ja-jp/script.lua` | 設定 | 日本語メッセージ定義 |
| script.lua | `locale/zh-cn/script.lua` | 設定 | 中国語（簡体字）メッセージ定義 |
| script.lua | `locale/zh-tw/script.lua` | 設定 | 中国語（繁体字）メッセージ定義 |
| language.lua | `script/language.lua` | ソース | 多言語対応処理 |
| proto.lua | `script/proto/proto.lua` | ソース | LSPプロトコル通信 |
