========================================================================
Pixel Paint War - 開発環境・技術スタック定義書
========================================================================

1. プロジェクト基本方針
------------------------------------------------------------------------

1-1. アーキテクチャ構成: Monorepo (モノレポ)
    ・目的: クライアント(Client)とサーバー(Server)で，言語(TypeScript)およびゲームロジック(移動演算・定数・型定義)を完全共有するため．
    ・パッケージ管理: pnpm workspaces を採用．

1-2. コア・コンセプト
    ・言語: TypeScript (Strict mode)
    ・通信: WebSocket + Hybrid Protocol
        - Core Game (移動・塗り): Custom Binary (DataView) による極小パケット通信
        - Meta Data (ロビー・チャット): JSON (開発効率とデバッグ容易性を優先)
    ・描画: WebGL 2D (Pixi.js)
    ・同期: サーバー権限 (Authoritative) + クライアント予測 (Prediction)

1-3. AI活用型開発 (AI-Assisted Development)
    ・採用ツール:
        - Gemini Pro (学校提供ライセンス)
        - GitHub Copilot Pro (GitHub Student Developer Pack)
    ・言語選定の優位性:
        TypeScriptを採用することで厳密な型定義(Type/Interface)を保持する．
        これによりAIがコードの文脈や意図を正確に解釈可能となり，
        型のないJavaScriptと比較して，コード生成・補完・リファクタリングの精度が著しく向上する．


2. ディレクトリ構造 (Directory Structure)
------------------------------------------------------------------------

2-1. 構成一覧
    root/
    ├── .devcontainer/
    │   └── devcontainer.json                               # 開発コンテナ設定
    ├── apps/
    │   ├── client/                                         # 【演出】フロントエンド (Browser)
    │   │   ├── .gitignore                                  # 除外設定
    │   │   ├── index.html                                  # HTMLエントリ
    │   │   ├── package.json                                # 依存・スクリプト
    │   │   ├── public/
    │   │   │   └── vite.svg                                # 公開アイコン
    │   │   ├── src/
    │   │   │   ├── app.tsx                                 # ルートUI
    │   │   │   ├── index.css                               # 全体スタイル
    │   │   │   ├── main.tsx                                # 起動エントリ
    │   │   │   ├── assets/
    │   │   │   │   └── preact.svg                          # ロゴ素材
    │   │   │   ├── hooks/
    │   │   │   │   └── useAppFlow.ts                        # 画面遷移フック
    │   │   │   ├── network/
    │   │   │   │   ├── SocketManager.ts                    # WSクライアント
    │   │   │   │   └── handlers/
    │   │   │   │       ├── CommonHandler.ts                # 共通WSハンドラ
    │   │   │   │       ├── GameHandler.ts                  # ゲームWSハンドラ
    │   │   │   │       ├── LobbyHandler.ts                 # ロビーWSハンドラ
    │   │   │   │       └── TitleHandler.ts                 # タイトルWSハンドラ
    │   │   │   └── scenes/
    │   │   │       ├── game/
    │   │   │       │   ├── GameInputManager.ts             # 入力管理
    │   │   │       │   ├── GameManager.ts                  # ゲーム制御
    │   │   │       │   ├── GameScene.tsx                   # ゲーム画面
    │   │   │       │   ├── GameView.tsx                    # ゲーム描画
    │   │   │       │   ├── entities/
    │   │   │       │   │   ├── map/
    │   │   │       │   │   │   ├── GameMapController.ts    # マップ制御
    │   │   │       │   │   │   ├── GameMapModel.ts         # マップモデル
    │   │   │       │   │   │   └── GameMapView.ts          # マップ描画
    │   │   │       │   │   └── player/
    │   │   │       │   │       ├── PlayerController.ts     # プレイヤー制御
    │   │   │       │   │       ├── PlayerModel.ts          # プレイヤーモデル
    │   │   │       │   │       └── PlayerView.ts           # プレイヤー描画
    │   │   │       │   └── input/
    │   │   │       │       ├── joystick/
    │   │   │       │       │   ├── JoystickInputPresenter.tsx # 仮想スティックUI
    │   │   │       │       │   ├── JoystickModel.ts        # スティックモデル
    │   │   │       │       │   ├── JoystickView.tsx        # スティック描画
    │   │   │       │       │   └── common/
    │   │   │       │       │       ├── index.ts            # スティック共通
    │   │   │       │       │       ├── joystick.constants.ts # スティック定数
    │   │   │       │       │       └── joystick.types.ts   # スティック型
    │   │   │       │       ├── useJoystickController.ts    # スティック制御フック
    │   │   │       │       └── useJoystickState.ts         # スティック状態
    │   │   │       ├── lobby/
    │   │   │       │   └── LobbyScene.tsx                  # ロビー画面
    │   │   │       └── title/
    │   │   │           └── TitleScene.tsx                  # タイトル画面
    │   │   ├── tsconfig.app.json                           # アプリTS設定
    │   │   ├── tsconfig.json                               # TS親設定
    │   │   ├── tsconfig.node.json                          # Node向けTS設定
    │   │   └── vite.config.ts                              # Vite設定
    │   └── server/                                         # 【権限】バックエンド (Node.js)
    │       ├── package.json                                # 依存・スクリプト
    │       ├── tsconfig.json                               # TS設定
    │       └── src/
    │           ├── index.ts                                # サーバー起点
    │           ├── logging/
    │           │   └── logEvent.ts                         # 共通ログ出力
    │           ├── domains/
    │           │   ├── game/
    │           │   │   ├── GameLoop.ts                     # 固定ループ
    │           │   │   ├── GameManager.ts                  # ゲーム状態管理
    │           │   │   ├── application/
    │           │   │   │   ├── ports/                      # ユースケース入出力境界
    │           │   │   │   ├── services/                   # ゲームアプリケーションサービス
    │           │   │   │   └── useCases/                   # ゲームユースケース
    │           │   │   ├── entities/
    │           │   │   │   └── Player.ts                   # サーバーPlayer
    │           │   │   └── states/
    │           │   │       └── MapStore.ts                 # マップ状態保持
    │           │   └── room/
    │           │       ├── application/
    │           │       │   ├── ports/                      # ユースケース入出力境界
    │           │       │   ├── services/                   # ルームアプリケーションサービス
    │           │       │   └── useCases/                   # ルームユースケース
    │           │       └── RoomManager.ts                  # ルーム管理
    │           └── network/
    │               ├── SocketManager.ts                    # WS接続管理
    │               ├── adapters/
    │               │   └── socketEmitters.ts              # 送信アダプタ
    │               ├── handlers/
    │               │   ├── CommonHandler.ts               # 共通WSハンドラ
    │               │   ├── GameHandler.ts                 # ゲームWSハンドラ(中間層)
    │               │   ├── RoomHandler.ts                 # ルームWSハンドラ(中間層)
    │               │   ├── game/
    │               │   │   ├── handleGameDisconnect.ts    # ゲーム切断処理配線
    │               │   │   └── registerGameHandlers.ts    # ゲーム受信イベント配線
    │               │   └── room/
    │               │       ├── handleRoomDisconnect.ts    # ルーム切断処理配線
    │               │       └── registerRoomHandlers.ts    # ルーム受信イベント配線
    │               ├── bootstrap/
    │               │   ├── createHttpServer.ts            # HTTP生成
    │               │   ├── createIo.ts                    # Socket.IO生成
    │               │   └── boot.ts                        # 起動配線
    ├── docs/
    │   ├── 01_Env/
    │   │   ├── ENV_01_環境構築・技術スタック.txt                # 環境・技術定義
    │   │   ├── ENV_02_環境構築手順書.txt                        # 初期構築手順
    │   │   ├── ENV_03_TypeScript概要.txt                     # TS基礎説明
    │   │   ├── ENV_04_スマホ実機デバッグ手順.txt                  # 実機デバッグ手順
    │   │   ├── ENV_05_Docker運用操作ガイド.txt                   # Docker運用手順
    │   │   ├── ENV_06_管理者用環境構築手順.txt                   # 管理者向け手順
    │   │   └── ENV_07_テスト操作手順.txt                        # テスト操作手順
    │   ├── 02_Guide/
    │   │   ├── GUIDE_01_ドキュメント作成ガイド.txt               # 文書作成ルール
    │   │   ├── GUIDE_02_ファイル命名規則.txt                     # 命名規則
    │   │   ├── GUIDE_03_Git運用ルール.txt                      # Git運用ルール
    │   │   └── GUIDE_04_コードコメント規則.txt                  # コメント運用ルール
    │   ├── 03_Plan/
    │   │   └── PLAN_01_移動テスト実装計画.txt                   # 実装計画
    │   └── 04_Spec/
    │       └── SPEC_03_プロトタイプ_移動テスト.txt               # 機能仕様
    ├── packages/
    │   └── shared/                                         # 【最重要】「真実」の定義場所（型、定数、純粋ロジック）
    │       ├── package.json                                # 依存・公開設定
    │       ├── tsconfig.json                               # TS設定
    │       └── src/
    │           ├── index.ts                                # 共有エクスポート
    │           ├── config/
    │           │   ├── index.ts                            # 設定エクスポート
    │           │   ├── gameConfig.ts                       # 共通定数
    │           │   └── networkConfig.ts                    # 通信設定
    │           ├── domains/
    │           │   ├── app/
    │           │   │   ├── app.const.ts                    # アプリ定数
    │           │   │   └── app.type.ts                     # アプリ型
    │           │   ├── gridMap/
    │           │   │   ├── gridMap.logic.ts                # マップ計算
    │           │   │   └── gridMap.type.ts                 # マップ型定義
    │           │   ├── player/
    │           │   │   └── player.type.ts                  # プレイヤー型
    │           │   └── room/
    │           │       ├── room.const.ts                   # ルーム定数
    │           │       └── room.type.ts                    # ルーム型
    │           └── protocol/
    │               └── events.ts                           # 通信イベント定義
    ├── test/                                                # テスト用スクリプト群
    │   ├── load-bot.constants.ts                            # 負荷テスト定数
    │   ├── load-bot.ts                                      # 負荷テスト実行
    │   ├── node_modules/                                    # テスト依存
    │   ├── package.json                                     # テスト依存・スクリプト
    │   └── tsconfig.json                                    # テストTS設定
    ├── .gitignore                                           # Git除外設定
    ├── .npmrc                                               # pnpm設定
    ├── docker-compose.prod.yml                              # 本番Compose定義
    ├── docker-compose.yml                                   # 開発Compose定義
    ├── Dockerfile                                           # 本番イメージ定義
    ├── package.json                                         # ワークスペース定義
    ├── pnpm-lock.yaml                                       # lockファイル
    ├── pnpm-workspace.yaml                                  # workspace設定
    └── README.md                                            # プロジェクト概要

    ※ 右側コメントは，役割が一行で分かる短文で記載する．

        ※ shared は client/server 両方から import して使用する．


3. 技術スタック詳細 (Tech Stack)
------------------------------------------------------------------------

3-1. 共通・基盤 (Common / Shared)
    ・Runtime: Node.js (v20 LTS 以上)
    ・Package Manager: pnpm
    ・Build Tool: tsup (高速で軽量なTypeScriptバンドラ)
    ・Serialization: Custom Binary (Standard DataView API)
        - 採用理由: ライブラリ依存をなくし，仕様書要件（30KB/s以下）を満たす最適化を行うため．
        - 用途: 座標データ，入力情報の圧縮通信．

3-2. フロントエンド (Client)
    ・Build Tool: Vite
    ・Language: TypeScript
    ・Rendering Engine: Pixi.js (v8)
        - 採用理由: 50人同時対戦時の大量のスプライト描画と60fps維持のため．
    ・UI Library: Preact (または Vanilla HTML/CSS)
        - 採用理由: ゲームループへの負荷を避けつつ，軽量なHUDを構築するため．
    ・Network: socket.io-client

3-3. バックエンド (Server)
    ・Runtime: Node.js
    ・Execution: tsx (開発時の高速実行・ウォッチ用)
    ・WebSocket Library: Socket.IO
        - 採用理由: 接続管理・イベント配線を明確化しやすく，Client 側 (socket.io-client) と整合するため．
    ・Logic: 独自ループ (20Hz固定)
        - Physics Engine: 使用しない (shared/physics.ts による独自グリッド判定)

3-4. 開発ツール (Dev Tools)
    ・Linter: ESLint
    ・Formatter: Prettier
    ・Test: Vitest (共通ロジックの単体テスト用)
    ・AI Assistant: GitHub Copilot Pro, Gemini Pro

3-5. インフラ・コンテナ技術 (Infrastructure)
    ・Containerization: Docker
        - 採用理由: 開発環境(Dev Containers)と本番環境の差異を排除するため．
    ・Orchestration: 
        - Dev: Docker Compose (ボリュームマウントによるホットリロード)
        - Prod: Docker Compose (再起動ポリシーとポート開放のみの最小構成)
    ・Deployment Image: Multi-stage Build (Node.js Slim)
        - ビルド戦略: 
            1. Builderステージ: 全依存をインストールし，TypeScript (Shared -> Server) をコンパイル．
            2. Prune: `pnpm prune --prod` により開発依存を削除．
            3. Copy: pnpmの仕様(シンボリックリンク)に対応するため，`node_modules` を明示的にコピーする．
            4. Runnerステージ: 必要な `dist` と `node_modules` のみをコピーし，イメージサイズを最小化する．


4. 開発マシンの前提条件 (Prerequisites)
------------------------------------------------------------------------
本プロジェクトは Docker (Dev Containers) による開発環境統一を推奨する．
これにより、ホストOS（Windows/Mac）の環境を汚さずに構築が可能となる。

4-1. 【必須】ホストマシンにインストールするもの
    以下のツールのみ，開発者のPC（ホストOS）にインストールが必要である．

    1. Docker実行環境
       - Docker Desktop (最新版)
       - WSL2 (Windowsの場合必須)

    2. エディタ
       - VS Code (Visual Studio Code)

    3. VS Code 拡張機能
       - Dev Containers (ID: ms-vscode-remote.remote-containers)
       ※ これが「必須」である．これさえあれば，以下の開発ツール群は自動セットアップされる．

    4. アカウント・AI
       - GitHub Copilot Pro (Student)
       - Gemini Pro (学校提供ライセンス)

4-2. 【自動】コンテナ内に構築されるもの (インストール不要)
    以下のツールは `devcontainer.json` に定義済みであり，コンテナ起動時に
    自動的にインストール・設定されるため，手動導入は不要である．

    1. Runtime & Package Manager
       - Node.js (v20.x LTS)
       - pnpm (Latest)

    2. VS Code 拡張機能 (コンテナ内)
       - ESLint
       - Prettier
       - EditorConfig
       - Hex Editor
       
    ※ ホスト側で `node -v` や `pnpm -v` を実行する必要はなく，
       全て VS Code の「ターミナル (コンテナ接続済)」で行う．


5. 実装上の重要ルール (Implementation Rules)
------------------------------------------------------------------------

5-1. ロジックの一元管理
   - 「移動速度」「ヒット判定」「マップ更新」の計算式は必ず `packages/shared` に記述する．
   - Client と Server で別の計算式を書くことを禁止する（同期ズレ防止）．

5-2. 座標系
   - 内部計算: Float (浮動小数点)
   - 通信データ: Integer (整数 / 100倍して送信など圧縮を考慮)
   - 描画: Float (補間処理あり)

5-3. 依存方向
   - OK: Client -> Shared
   - OK: Server -> Shared
   - NG: Client -> Server / Server -> Client (直接参照禁止)

5-4. 通信境界の責務分離
    - SocketEvents の解決（イベント名の参照）は `apps/server/src/network` 配下に集約する．
    - `apps/server/src/domains` 配下では `protocol` を直接 import せず，意味名の Publisher 関数を受け取って利用する．
    - Socket の接続制御・受信イベント登録・切断順序制御は network 層が担当し，業務ロジック判断は domain 層が担当する．