Merge pull request #167 from m1sk9/docs/Update-v1-docsv1.0.0

docs: Update v1 Document

6 files changed, 483 insertions, 0 deletions

diff --git a/website/src/docs/features/admin.md b/website/src/docs/features/admin.md
new file mode 100644
index 0000000..57d38c0
--- /dev/null
+++ b/website/src/docs/features/admin.md
@@ -0,0 +1,74 @@
+---
+layout: doc
+---
+
+# 管理者向け機能
+
+サーバー管理者向けの機能をまとめて解説します．これらの機能は主に OP 権限を持つプレイヤーが利用できます．
+
+## プラグインステータス (`/lc status`)
+
+プラグインの動作状況を一覧で確認できます．
+
+```
+/lc status
+```
+
+表示される情報:
+
+- プラグインバージョン (Git コミットハッシュ付き)
+- ヘルスステータス (OK / Degraded)
+- 各機能の有効/無効状態
+- 設定値 (デバッグモード，アップデート確認，言語)
+- GitHub，Modrinth，ドキュメントへのリンク
+
+## スパイモード
+
+`lunaticchat.spy` パーミッション (デフォルト: op) を持つプレイヤーは，サーバー上で送受信されるすべてのダイレクトメッセージを閲覧できます．
+
+- スパイプレイヤーにはローマ字変換前の元のメッセージが表示されます
+- ホバーテキストでスパイメッセージであることが示されます
+- スパイプレイヤー自身は通常の送受信者リストには含まれません
+
+## チャンネルバイパス
+
+`lunaticchat.channelbypass` パーミッション (デフォルト: op) を持つプレイヤーは，チャンネルに関する以下の制限を無視できます．
+
+- キック・BAN の対象にならない
+- オーナーでなくてもチャンネルを削除できる
+
+## アップデート通知
+
+`checkForUpdates` が `true` (デフォルト) の場合，プラグインは起動時に新しいバージョンが利用可能か確認します．`lunaticchat.noticeupdate` パーミッション (デフォルト: op) を持つプレイヤーがサーバーに参加した際にアップデート通知が表示されます．
+
+```yaml
+# config.yml
+checkForUpdates: true
+```
+
+## デバッグモード
+
+`debug` を `true` にすると，プラグインの詳細なログが出力されます．問題の調査やバグ報告時に有用です．
+
+```yaml
+# config.yml
+debug: true
+```
+
+## 言語設定
+
+プレイヤーに表示されるメッセージの言語を切り替えられます．プラグインログやコンソール出力には影響せず，英語のみ出力となります．
+
+```yaml
+# config.yml
+language: "ja"   # "en" または "ja"
+```
+
+## 管理者パーミッション一覧
+
+| パーミッション | デフォルト | 説明 |
+|---------------|-----------|------|
+| `lunaticchat.spy` | op | 全ダイレクトメッセージの閲覧 |
+| `lunaticchat.channelbypass` | op | チャンネル制限のバイパス |
+| `lunaticchat.noticeupdate` | op | アップデート通知の受信 |
+| `lunaticchat.command.lcv.status` | op | `/lcv status` コマンドの使用 |
diff --git a/website/src/docs/features/channel-chat.md b/website/src/docs/features/channel-chat.md
new file mode 100644
index 0000000..b0caa43
--- /dev/null
+++ b/website/src/docs/features/channel-chat.md
@@ -0,0 +1,92 @@
+---
+layout: doc
+---
+
+# チャンネルチャット
+
+チャンネルを作成してグループごとに会話を分離できます．この機能を利用するには `config.yml` で `features.channelChat.enabled` を `true` に設定してください．
+
+## チャンネルの作成
+
+```
+/lc channel create <channelId> <name> [description] [isPrivate]
+```
+
+- `channelId`: チャンネルの一意な識別子 (英数字, `_`, `-` のみ, 3〜30文字)
+- `name`: チャンネルの表示名
+- `description`: チャンネルの説明 (省略可)
+- `isPrivate`: プライベートチャンネルにする場合は `true` (デフォルト: `false`)
+
+作成者は自動的にオーナーになります．
+
+## チャンネルへの参加・退出
+
+```
+/lc channel join <channelId>    # チャンネルに参加
+/lc channel leave               # アクティブチャンネルから退出
+/lc channel switch <channelId>  # アクティブチャンネルを切り替え
+```
+
+プライベートチャンネルに参加するには，オーナーまたはモデレーターからの招待が必要です．
+
+## アクティブチャンネル
+
+プレイヤーは複数のチャンネルに参加できますが，一度にアクティブにできるチャンネルは1つです．チャットメッセージはアクティブチャンネルに送信されます．`/lc channel switch` でアクティブチャンネルを切り替えられます．
+
+```
+/lc channel status    # 現在のアクティブチャンネルと参加チャンネル一覧を表示
+```
+
+## ロールと権限
+
+チャンネルには3つのロールがあります．
+
+| ロール | 権限 |
+|--------|------|
+| **OWNER** | チャンネルの削除，モデレーター管理，オーナー譲渡，メンバー管理 |
+| **MODERATOR** | メンバーの招待，キック，BAN/BAN解除 |
+| **MEMBER** | チャットへの参加，チャンネル情報の閲覧 |
+
+### モデレーター管理 (オーナーのみ)
+
+```
+/lc channel mod <playerName>         # モデレーター権限の付与/剥奪
+/lc channel ownership <playerName>   # オーナー権限の譲渡
+```
+
+### メンバー管理 (オーナー / モデレーター)
+
+```
+/lc channel invite <playerName>   # プレイヤーを招待
+/lc channel kick <playerName>     # プレイヤーをキック
+/lc channel ban <playerName>      # プレイヤーを BAN
+/lc channel unban <playerName>    # BAN を解除
+```
+
+## 制限設定
+
+`config.yml` でチャンネルの上限を設定できます (すべて `0` で無制限) ．
+
+| 設定キー | 説明 |
+|----------|------|
+| `maxChannelsPerServer` | サーバーあたりの最大チャンネル数 |
+| `maxMembersPerChannel` | チャンネルあたりの最大メンバー数 |
+| `maxMembershipPerPlayer` | プレイヤーあたりの最大参加チャンネル数 |
+
+## メッセージログ
+
+チャンネルメッセージは NDJSON 形式でログファイルに記録できます．ファイルは日次でローテーションされ，`maxFileSizeMB` を超えるとサフィックス付きの新しいファイルが作成されます．
+
+```json
+{"timestamp":"2026-04-05T14:23:45.123Z","playerId":"550e8400-...","playerName":"Steve","channelId":"general","message":"Hello!"}
+```
+
+ログ設定の詳細は[設定ページ](/docs/configuration)の `features.channelChat.messageLogging` を参照してください．
+
+## バイパス権限
+
+`lunaticchat.channelbypass` パーミッション (デフォルト: op) を持つプレイヤーは，キック・BAN の保護やチャンネルの強制削除が可能です．
+
+## メッセージフォーマット
+
+チャンネルメッセージの表示形式は `config.yml` の `messageFormat.channelMessageFormat` でカスタマイズできます．詳細は[メッセージフォーマット](/docs/reference/message-format)を参照してください．
diff --git a/website/src/docs/features/direct-message.md b/website/src/docs/features/direct-message.md
new file mode 100644
index 0000000..7b12aff
--- /dev/null
+++ b/website/src/docs/features/direct-message.md
@@ -0,0 +1,52 @@
+---
+layout: doc
+---
+
+# ダイレクトメッセージ
+
+プレイヤー間で 1対1 のプライベートメッセージを送受信できます．
+
+## 基本的な使い方
+
+### メッセージの送信
+
+```
+/tell <player> <message>
+```
+
+エイリアス: `/t`, `/msg`, `/m`, `/w`, `/whisper`
+
+指定したプレイヤーにダイレクトメッセージを送信します．受信したメッセージをクリックすると，送信者への返信コマンドが自動入力されます．
+
+### クイック返信
+
+```
+/reply <message>
+```
+
+エイリアス: `/r`
+
+最後にメッセージを送ってきたプレイヤーに返信します．該当するプレイヤーがいない場合は，最後にメッセージを送った相手に送信されます．
+
+クイック返信を利用するには `config.yml` で `features.quickReplies.enabled` が `true` (デフォルト) である必要があります．
+
+## 通知設定
+
+プレイヤーはダイレクトメッセージ受信時のサウンド通知を個別に制御できます．
+
+```
+/lc settings notice on     # 通知を有効化
+/lc settings notice off    # 通知を無効化
+```
+
+## ローマ字変換との連携
+
+[ローマ字変換](/docs/features/japanese-conversion)が有効な場合，ダイレクトメッセージの内容も自動的に日本語に変換されます．変換はプレイヤーの `japanese` 設定に従います．
+
+## スパイ機能
+
+`lunaticchat.spy` パーミッション (デフォルト: op) を持つプレイヤーは，サーバー上のすべてのダイレクトメッセージを閲覧できます．スパイプレイヤーには変換前のメッセージが表示されます．
+
+## メッセージフォーマット
+
+ダイレクトメッセージの表示形式は `config.yml` の `messageFormat.directMessageFormat` でカスタマイズできます．詳細は[メッセージフォーマット](/docs/reference/message-format)を参照してください．
diff --git a/website/src/docs/features/japanese-conversion.md b/website/src/docs/features/japanese-conversion.md
new file mode 100644
index 0000000..e5e751b
--- /dev/null
+++ b/website/src/docs/features/japanese-conversion.md
@@ -0,0 +1,62 @@
+---
+layout: doc
+---
+
+# ローマ字変換
+
+ローマ字で入力したチャットメッセージを自動的に日本語に変換します．この機能を利用するには `config.yml` で `features.japaneseConversion.enabled` を `true` に設定してください．
+
+## 変換の仕組み
+
+変換は2段階で行われます．
+
+1. **ローマ字 → ひらがな**: プラグイン内蔵の Trie ベースの変換エンジンでローマ字をひらがなに変換します
+2. **ひらがな → 漢字/カナ**: Google IME API を使用してひらがなを自然な日本語に変換します
+
+### 変換例
+
+```
+入力:  konnichiha sekai
+変換1: こんにちは せかい
+変換2: こんにちは 世界
+```
+
+## 変換対象
+
+- 通常チャット
+- ダイレクトメッセージ (`/tell`, `/reply`)
+- チャンネルチャット
+
+入力が有効なローマ字でない場合 (英単語などが含まれる場合)，変換は行われずそのまま送信されます．
+
+## プレイヤー設定
+
+プレイヤーは個別に変換のオン/オフを切り替えられます．
+
+```
+/lc settings japanese on     # 変換を有効化
+/lc settings japanese off    # 変換を無効化
+```
+
+## キャッシュ
+
+変換結果は単語単位でキャッシュされ，同じ単語の再変換時には API を呼び出さずにキャッシュから取得します．キャッシュは JSON ファイルとしてディスクに定期保存されます．
+
+| 設定キー | デフォルト | 説明 |
+|----------|-----------|------|
+| `cache.maxEntries` | `500` | キャッシュの最大エントリ数 |
+| `cache.saveIntervalSeconds` | `300` | ディスク保存の間隔 (秒) |
+| `cache.filePath` | `"conversion_cache.json"` | キャッシュファイルのパス |
+
+キャッシュが上限に達すると，古いエントリの10%が自動的に削除されます．
+
+## API 設定
+
+Google IME API への接続に関する設定です．
+
+| 設定キー | デフォルト | 説明 |
+|----------|-----------|------|
+| `api.timeout` | `3000` | リクエストタイムアウト (ミリ秒) |
+| `api.retryAttempts` | `2` | 失敗時のリトライ回数 |
+
+API がタイムアウトまたは失敗した場合，ひらがなのまま送信されます．
diff --git a/website/src/docs/features/message-logging.md b/website/src/docs/features/message-logging.md
new file mode 100644
index 0000000..944b9e9
--- /dev/null
+++ b/website/src/docs/features/message-logging.md
@@ -0,0 +1,94 @@
+---
+layout: doc
+---
+
+# メッセージログ
+
+チャンネルチャットのメッセージを NDJSON (Newline Delimited JSON) 形式でファイルに記録します．この機能はチャンネルチャットが有効な場合に利用でき，デフォルトで有効です．
+
+## 設定
+
+```yaml
+# config.yml
+features:
+  channelChat:
+    enabled: true
+    messageLogging:
+      enabled: true
+      retentionDays: 30
+      maxFileSizeMB: 100
+```
+
+| 設定キー | デフォルト | 説明 |
+|----------|-----------|------|
+| `enabled` | `true` | メッセージログを有効にする |
+| `retentionDays` | `30` | ログファイルの保持日数 (`0` で無期限保持) |
+| `maxFileSizeMB` | `100` | 単一ログファイルの最大サイズ (MB) |
+
+## ログファイルの形式
+
+ログファイルは `plugins/LunaticChat/logs/` ディレクトリに保存されます．各行が1つの JSON オブジェクトです．
+
+### ファイル名
+
+```
+channel-messages-YYYY-MM-dd.json
+```
+
+ファイルサイズが `maxFileSizeMB` を超えた場合，サフィックス付きの新しいファイルが作成されます．
+
+```
+channel-messages-2026-04-05.json       # 基本ファイル
+channel-messages-2026-04-05-1.json     # サイズ超過時
+channel-messages-2026-04-05-2.json     # さらに超過時
+```
+
+### エントリ形式
+
+各行は以下の JSON 構造を持ちます．
+
+```json
+{
+  "timestamp": "2026-04-05T14:23:45.123Z",
+  "playerId": "550e8400-e29b-41d4-a716-446655440000",
+  "playerName": "Steve",
+  "channelId": "general",
+  "message": "Hello everyone!"
+}
+```
+
+| フィールド | 型 | 説明 |
+|-----------|------|------|
+| `timestamp` | String | ISO 8601 形式のタイムスタンプ (UTC) |
+| `playerId` | String | プレイヤーの UUID |
+| `playerName` | String | プレイヤーの表示名 |
+| `channelId` | String | メッセージが送信されたチャンネルの ID |
+| `message` | String | メッセージの内容 |
+
+## ファイルローテーション
+
+- **日次ローテーション**: 日付が変わると新しいファイルが作成されます
+- **サイズローテーション**: `maxFileSizeMB` を超えるとサフィックス付きファイルに切り替わります
+- **自動クリーンアップ**: `retentionDays` で指定した日数を超えたログファイルは自動的に削除されます (`0` の場合は削除されません)
+
+## ログの活用例
+
+NDJSON 形式のため，`jq` などのツールで簡単にフィルタリング・集計が可能です．
+
+### 特定チャンネルのメッセージを抽出
+
+```bash
+jq 'select(.channelId == "general")' channel-messages-2026-04-05.json
+```
+
+### 特定プレイヤーのメッセージを抽出
+
+```bash
+jq 'select(.playerName == "Steve")' channel-messages-2026-04-05.json
+```
+
+### メッセージ数をチャンネルごとに集計
+
+```bash
+jq -s 'group_by(.channelId) | map({channel: .[0].channelId, count: length})' channel-messages-2026-04-05.json
+```
diff --git a/website/src/docs/features/velocity.md b/website/src/docs/features/velocity.md
new file mode 100644
index 0000000..d1394ec
--- /dev/null
+++ b/website/src/docs/features/velocity.md
@@ -0,0 +1,109 @@
+---
+layout: doc
+---
+
+# Velocity 連携
+
+Velocity プロキシを経由して複数の Paper / Folia サーバー間でグローバルチャットをリレーします．
+
+## セットアップ
+
+### 1. Velocity プラグインの導入
+
+`LunaticChat-<version>-velocity.jar` を Velocity の `plugins/` ディレクトリに配置し，プロキシを再起動します．
+
+### 2. Paper 側の設定
+
+各 Paper サーバーの `config.yml` で以下を設定します．
+
+```yaml
+features:
+  velocityIntegration:
+    enabled: true
+    crossServerGlobalChat: true
+    serverName: "survival"    # Velocity 設定のサーバー名に合わせる
+```
+
+### 3. 接続の確認
+
+```
+/lcv status
+```
+
+接続状態，プロトコルバージョン，Velocity プラグインのバージョンなどを確認できます (パーミッション: `lunaticchat.command.lcv.status`, デフォルト: op) ．
+
+## クロスサーバーグローバルチャット
+
+`crossServerGlobalChat` を `true` にすると，プレイヤーのチャットメッセージが Velocity を経由して他のすべての Paper サーバーに中継されます．
+
+### メッセージの流れ
+
+1. プレイヤーがチャットメッセージを送信
+2. Paper サーバーがメッセージを Velocity に送信
+3. Velocity が送信元以外の全サーバーにメッセージを中継
+4. 各サーバーのプレイヤーにメッセージが表示される
+
+### メッセージ重複排除
+
+各メッセージに一意な ID が付与され，キャッシュにより同じメッセージが重複して表示されることを防ぎます．キャッシュサイズは `messageDeduplicationCacheSize` (デフォルト: `100`) で設定できます．
+
+## プロトコルバージョン
+
+Paper と Velocity 間の互換性はプロトコルバージョンで管理されます．接続時にハンドシェイクが行われ，互換性のないバージョン同士では接続が拒否されます．
+
+### バージョンバンプルール
+
+| レベル | 変更例 | 互換性 | デプロイ順序 |
+|--------|--------|--------|-------------|
+| PATCH (1.0.0 → 1.0.1) | optional フィールド追加，新 sub-channel 追加 | 完全互換 (`ignoreUnknownKeys=true` で安全) | 順不同，いつでも |
+| MINOR (1.0.x → 1.1.0) | required フィールド追加，既存 sub-channel のセマンティクス変更 | `MIN_SUPPORTED_MINOR` の範囲内で後方互換 | **Velocity を先に更新** → 各 Paper を順次更新 |
+| MAJOR (1.x.x → 2.0.0) | ワイヤフォーマット変更，sub-channel 削除/リネーム | 非互換 | **全サーバー同時デプロイ** |
+
+### 互換性判定
+
+ハンドシェイク時に以下のルールで互換性が判定されます:
+
+- **MAJOR** が一致すること
+- リモートの **MINOR** が `MIN_SUPPORTED_MINOR` 以上かつ自身の MINOR 以下であること
+- **PATCH** は互換性判定に影響しない
+
+#### 例: Velocity がプロトコル 1.2.0 で `MIN_SUPPORTED_MINOR=1` の場合
+
+| Paper プロトコル | 結果 |
+|-----------------|------|
+| 1.1.x | 接続 OK |
+| 1.2.x | 接続 OK |
+| 1.0.x | 拒否 (`MIN_SUPPORTED_MINOR` より古い) |
+| 1.3.x | 拒否 (Velocity より新しい) |
+| 2.0.x | 拒否 (MAJOR 不一致) |
+
+### 運用サイクル
+
+1. **プロトコル変更なし** → Paper / Velocity を独立にデプロイ可能
+2. **PATCH 変更** → どちら側からでも自由にデプロイ
+3. **MINOR 変更** → Velocity を先行更新し，`MIN_SUPPORTED_MINOR` で旧 Paper の猶予期間を設定．全 Paper 更新後に `MIN_SUPPORTED_MINOR` を引き上げ
+4. **MAJOR 変更** → メンテナンスウィンドウで一括更新
+
+## 接続状態
+
+| 状態 | 説明 |
+|------|------|
+| `DISCONNECTED` | 未接続 |
+| `HANDSHAKING` | ハンドシェイク中 |
+| `CONNECTED` | 接続済み |
+| `FAILED` | 接続失敗 |
+
+ハンドシェイクのタイムアウトは5秒です．タイムアウトした場合，状態は `FAILED` になります．
+
+## 設定一覧
+
+| 設定キー | デフォルト | 説明 |
+|----------|-----------|------|
+| `enabled` | `false` | Velocity 連携を有効にする |
+| `crossServerGlobalChat` | `false` | クロスサーバーグローバルチャットを有効にする |
+| `serverName` | `"Unknown"` | クロスサーバーチャットで表示されるサーバー名 |
+| `messageDeduplicationCacheSize` | `100` | メッセージ重複排除キャッシュのサイズ |
+
+## メッセージフォーマット
+
+クロスサーバーチャットの表示形式は `config.yml` の `messageFormat.crossServerGlobalChatFormat` でカスタマイズできます．詳細は[メッセージフォーマット](/docs/reference/message-format)を参照してください．