diff --git "a/docs/02_Guide/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" "b/docs/02_Guide/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" index 07dd34b..e4f637b 100644 --- "a/docs/02_Guide/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" +++ "b/docs/02_Guide/GUIDE_01_\343\203\211\343\202\255\343\203\245\343\203\241\343\203\263\343\203\210\344\275\234\346\210\220\343\202\254\343\202\244\343\203\211.txt" @@ -8,6 +8,7 @@ ・改行コード: LF (推奨) または CRLF ・インデント: 半角スペース4つ (4 spaces) - タブ文字は使用せず、スペースに展開して揃える． +・ファイル命名: `GUIDE_02_ファイル命名規則.txt` を参照する． ■ ファイルヘッダー (File Header) ・ファイルの先頭には必ずタイトルブロックを記述する． @@ -61,15 +62,19 @@ 3-4. レベル4：リスト項目 (List Item) ・記号: 「・」（全角中黒） ・書式: 「・項目名: 内容」または「・項目名」のみ． + ・使いどころ: セクション内の主要な列挙（親項目）に使用する． ・例: ・タイトル: Paint War 3-5. レベル5：詳細項目 (Detail Item) ・記号: 「- 」（半角ハイフン＋半角スペース） ・インデント: 親項目のテキスト開始位置に合わせる（基本はスペース8つ）． + ・使いどころ: 親が「・」のとき，その補足・条件・内訳を子項目として記述する． + ・ルール: 親が「・」なら子は必ず「- 」を使う． ・例: - ・親項目 (Level 4) - - 子項目: 詳細内容 (Level 5) + ・接続設定 + - host: localhost + - port: 3000 3-6. 特殊なナンバリング (Zero Indexing) ・目的定義: セクションの冒頭で目的や定義を述べる場合、「X-0. 目的」というナンバリング（ゼロ始まり）を使用してもよい． @@ -87,6 +92,26 @@ ・中見出し（X-X）の上: 1行空ける． ・小見出し（■や数字）の上: 1行空ける． ・セクション内のリスト: 原則として行間を詰め、まとまりごとに適宜空行を入れる． +・ミニサンプル: + 1. 基本設計 (Basic Design) + ------------------------------------------------------------------------ + + + 1-1. 製品概要 + + ■ 主要要件 + ・要件A: 説明 + ・要件B: 説明 + + ■ 補足 + ・注意点: 説明 + +・NG例（空行不足）: + 1. 基本設計 (Basic Design) + ------------------------------------------------------------------------ + 1-1. 製品概要 + ■ 主要要件 + ・要件A: 説明 5. 技術記述・コード表記 (Technical & Code) diff --git "a/docs/02_Guide/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" "b/docs/02_Guide/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" index c47a0e1..a8217e6 100644 --- "a/docs/02_Guide/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" +++ "b/docs/02_Guide/GUIDE_02_\343\203\225\343\202\241\343\202\244\343\203\253\345\221\275\345\220\215\350\246\217\345\211\207.txt" @@ -5,6 +5,7 @@ 1. 命名の基本方針 (Basic Policy) ------------------------------------------------------------------------ プロジェクトの規模拡大に伴うファイルの散乱を防ぎ，開発メンバーおよびAI（Gemini/Copilot）がファイルの内容・文脈を即座に特定できるようにするため，以下の規則を適用する． +※ 書式・記述スタイルの基準は `GUIDE_01_ドキュメント作成ガイド.txt` を参照する． ■ 基本フォーマット `[カテゴリ]_[連番]_[ファイル名].txt` @@ -50,4 +51,4 @@ これにより，AIへのコンテキスト入力精度が向上する． ・スタイルの継承: - 新規作成するファイルも，必ず `GUIDE_01_スタイルガイド.txt` に記載された書式（見出し，句読点「，．」等）に従うこと． \ No newline at end of file + 新規作成するファイルも，必ず `GUIDE_01_ドキュメント作成ガイド.txt` に記載された書式（見出し，句読点「，．」等）に従うこと． \ No newline at end of file diff --git "a/docs/02_Guide/GUIDE_05_\343\203\227\343\203\255\343\203\210\343\202\263\343\203\253\350\277\275\345\212\240\346\211\213\351\240\206.txt" "b/docs/02_Guide/GUIDE_05_\343\203\227\343\203\255\343\203\210\343\202\263\343\203\253\350\277\275\345\212\240\346\211\213\351\240\206.txt" new file mode 100644 index 0000000..30ab458 --- /dev/null +++ "b/docs/02_Guide/GUIDE_05_\343\203\227\343\203\255\343\203\210\343\202\263\343\203\253\350\277\275\345\212\240\346\211\213\351\240\206.txt" @@ -0,0 +1,109 @@ +======================================================================== +プロトコル追加手順 (Protocol Extension Guide) +======================================================================== + + +1. 目的 (Purpose) +------------------------------------------------------------------------ +本ドキュメントは，ソケットイベントの追加・変更時に，修正箇所の漏れを防ぐための標準手順を定義する． +`packages/shared/src/protocol` の責務分割方針に従い，イベント名，ペイロード型，方向別マップ，公開エントリを順に更新する． + + +2. 適用対象 (Scope) +------------------------------------------------------------------------ +・対象レイヤ: shared プロトコル定義（client/server 共通契約） +・対象ディレクトリ: `packages/shared/src/protocol` +・対象ユースケース: 新規イベント追加，既存イベントのペイロード変更，イベント廃止 + + +3. ディレクトリ構成 (Directory Layout) +------------------------------------------------------------------------ +・基準構成は以下とする． + + packages/shared/src/protocol/ + ├── socketEvents.ts + ├── eventPayloads.ts + ├── eventPayloadMaps.ts + ├── events.ts + ├── socketEventBridge.ts + ├── payloads/ + │ ├── commonPayloads.ts + │ ├── lobbyPayloads.ts + │ └── gamePayloads.ts + └── maps/ + ├── commonEventPayloadMap.ts + ├── lobbyEventPayloadMap.ts + └── gameEventPayloadMap.ts + + +4. 標準追加フロー (Standard Flow) +------------------------------------------------------------------------ +新規イベントを追加する場合は，必ず次の順で更新する． + +4-1. イベント名を追加する + ・ファイル: socketEvents.ts + ・作業: `SocketEvents` にイベント名を追加する + ・確認: 命名規則（kebab-case / snake_case）を既存方針に合わせる + +4-2. ペイロード型を追加する + ・ファイル: payloads/commonPayloads.ts または payloads/lobbyPayloads.ts または payloads/gamePayloads.ts + ・作業: イベントに対応する payload 型を追加する + ・確認: 既存型の再利用可否を確認し，重複定義を避ける + +4-3. 方向別マップへ対応を追加する + ・ファイル: maps/commonEventPayloadMap.ts / maps/lobbyEventPayloadMap.ts / maps/gameEventPayloadMap.ts + ・作業: 追加イベントを C→S または S→C の適切な map に追記する + ・確認: 方向が誤っていないかを必ず確認する + +4-4. 集約エントリの再公開を調整する + ・ファイル: eventPayloads.ts / eventPayloadMaps.ts / events.ts + ・作業: 外部利用が必要な型のみ再公開する + ・確認: 既存 import パス互換（`@repo/shared` 経由）を維持する + +4-5. 利用側を接続する + ・対象: client/server の handler / bridge / useCase + ・作業: on/off/emit と payload 型参照を更新する + + +5. 変更時のチェックポイント (Checklist) +------------------------------------------------------------------------ +・イベント名追加済みか +・payload 型追加済みか +・map への方向別登録済みか +・events.ts 再公開が過不足ないか +・client/server で型エラーがないか +・既存イベントの型互換を壊していないか + + +6. 典型ミスと対策 (Common Pitfalls) +------------------------------------------------------------------------ +■ イベント名だけ追加して map を更新しない +・症状: emit/on の型推論が崩れる，もしくは any 化する +・対策: 4-3 を必須工程として実施する + +■ payload 定義場所が不適切 +・症状: common/lobby/game の境界が曖昧になる +・対策: イベント責務に従って payloads 配下へ配置する + +■ 循環参照を作る +・症状: 型解決エラー，TS2307/TS2456 系が発生しやすくなる +・対策: `events.ts` は再公開専用とし，型本体は payload 側へ置く + + +7. 検証コマンド (Validation Commands) +------------------------------------------------------------------------ +・shared 型定義のビルド確認 + $ pnpm --filter @repo/shared build + +・サーバー互換確認 + $ pnpm --filter server build + +・クライアント互換確認 + $ pnpm --filter client build + + +8. 運用ルール (Operation Rules) +------------------------------------------------------------------------ +・プロトコル追加時は，本ガイドの 4-1 から 4-5 までを PR テンプレート上でチェックする +・events.ts に型本体を戻さない（再公開専用を維持する） +・新規型のコメントは `GUIDE_04_コードコメント規則` に従う