========================================================================
Pixel Paint War - 開発環境利用ガイド (Development Environment Guide)
========================================================================
1. 事前準備 (Prerequisites)
------------------------------------------------------------------------
1-1. 目的
本ドキュメントは，「Pixel Paint War」の開発に参加する全メンバー向けの
環境構築および利用ガイドである．
Monorepo構成とDocker(Dev Containers)を使用し，迅速に開発を開始する手順を記す．
1-2. 【全員必須】 共通ツールのインストール
開発メンバー全員（管理者・参加者問わず）が以下のツールをインストールする．
1. Docker Engine (Linux環境)
・開発環境の実体（コンテナ）を動かすために必須である．
・インストール手順 (Ubuntu/Debian系の例):
ターミナルで以下のコマンドを順に実行する．
# 1. 公式GPG鍵とリポジトリのセットアップ
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
"deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
"$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 2. パッケージのインストール
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# 3. ユーザー権限の設定 (重要: VS Codeからsudoなしで利用するために必須)
sudo usermod -aG docker $USER
newgrp docker
・確認コマンド:
$ docker -v
# Docker version 20.x.x 等と表示されること
2. VS Code (Visual Studio Code)
・メインのエディタとして使用する．最新版をインストールすること．
3. VS Code 拡張機能: "Dev Containers"
・ID: ms-vscode-remote.remote-containers
・拡張機能マーケットプレイスで検索し、インストールする．
・これを入れることで、Dockerコンテナ内でVS Codeを開くことが可能になる．
2. 環境セットアップ (Setup)
------------------------------------------------------------------------
■ リポジトリのクローン
1. ソースコードの取得
任意のディレクトリで以下のコマンドを実行する．
$ git clone <GitHubのリポジトリURL>
2. ディレクトリ移動
$ cd SkillSemiWebGame
3. 完了
これだけで準備は完了である．
パッケージのインストール等はDocker起動時に自動で行われるため、
手動での `pnpm install` 等は不要である．
3. 開発環境(Dev Container)の起動 (Launch)
------------------------------------------------------------------------
3-1. プロジェクトを開く
1. VS Codeを起動し，「ファイル > フォルダを開く」からプロジェクトルートを選択する．
3-2. コンテナでの再起動 (Reopen in Container)
以下のいずれかの方法で，開発環境をコンテナ内に移行する．
【方法A: ステータスバーから】
1. ウィンドウ左下の緑色(または青色)の「><」アイコンをクリックする．
2. 表示されるメニューから「Reopen in Container」を選択する．
【方法B: コマンドパレットから】
1. [F1] または [Ctrl+Shift+P] を押下する．
2. "Reopen" と入力し，「Dev Containers: Reopen in Container」を選択する．
※ トラブルシューティング:
もし起動後に node_modules が見つからない等のエラーが出た場合は，
「Reopen」ではなく「Dev Containers: Rebuild Container」を選択して
環境を完全に作り直してください．
3-3. 初回ビルドの待機
1. 初回起動時は Dockerイメージのビルドと npmパッケージのインストールが行われる．
(数分〜十数分かかる場合がある)
2. 右下に "Starting Dev Container" 等の通知が表示されている間は待機する．
3-4. 起動確認
1. 左下のアイコンが「Dev Container: Pixel Paint War Dev」と表示されていることを確認する．
2. VS Codeのターミナルを開き (`Ctrl + @`)，パスを確認する．
成功例: node@...:/workspace$
(Windowsのパス C:\Users... ではなく Linux形式になっていれば成功)
3. 動作確認コマンドを実行する．
$ pnpm --filter client dev
※ エラー時の対応:
「sh: vite: not found」等のエラーが出る場合は，自動インストールが完了していない可能性があります．
ターミナルで `pnpm install` を手動実行するか，上記 3-2 の「Rebuild Container」を試してください．
・ブラウザでの確認:
ターミナルに「➜ Local: http://localhost:5173/」と表示されたら，
Google Chrome等のブラウザを開き，アドレスバーに上記URLを貼り付けて実行する．
・正常動作の判断基準:
画面に「Vite + Preact」のロゴと「Vite + Preact + TypeScript」といった
テキストが表示されていれば，フロントエンドの環境構築は成功である．
4. 開発ツールの確認 (Tools Verification)
------------------------------------------------------------------------
Dockerコンテナ起動完了後、定義済みのツールが正しく自動導入されているか確認する．
※ 手動でのインストールは不要である．
4-1. VS Code 拡張機能
拡張機能サイドバーを開き、"Dev Container: Pixel Paint War Dev" セクションに
以下がインストール済みであることを確認する．
・ESLint
・Prettier - Code formatter
・EditorConfig for VS Code
・Hex Editor
・GitHub Copilot
4-2. AI アシスタント設定
GitHub Copilot Pro
- VS Code 右下のアイコンから、GitHubアカウントへのログイン状態を確認する．
5. 構成確認 (Project Structure)
------------------------------------------------------------------------
5-1. ディレクトリ構成
コンテナ内で以下のディレクトリ構造が見えていることを確認する．
SkillSemiWebGame/ <-- プロジェクトルート
├── .devcontainer/ <-- Docker設定
├── .git/
├── docker-compose.yml <-- Docker構成
├── package.json <-- ルート定義
├── pnpm-workspace.yaml <-- ワークスペース定義
├── node_modules/ <-- 依存ライブラリ
│
├── apps/ <-- アプリケーション格納用
│ ├── client/ <-- フロントエンド (Vite + Preact)
│ │ ├── src/
│ │ │ ├── main.tsx
│ │ │ └── ...
│ │ ├── package.json <-- pixi.js, @repo/shared 依存あり
│ │ └── vite.config.ts
│ │
│ └── server/ <-- バックエンド (Node.js)
│ ├── src/
│ │ └── index.ts <-- エントリーポイント
│ └── package.json <-- ws, @repo/shared 依存あり
│
└── packages/ <-- 共通パッケージ格納用
└── shared/ <-- 共通ロジック
├── dist/ <-- ビルド成果物
├── src/
│ └── index.ts
└── package.json
6. 動作確認 (Verification)
------------------------------------------------------------------------
6-1. ビルド確認
※ 注意: 以下のコマンドは全て「Dev Container内のターミナル」で実行すること．
$ pnpm --filter @repo/shared build
※ shared のビルドが成功することを確認する．
6-2. 開発サーバー起動
モノレポ構成のため，個別のディレクトリに移動せず，プロジェクトルートから
--filter オプションを使用して各アプリを起動する．
※ ターミナルを2つ開き，両方を同時に起動した状態で開発を進めることを推奨．
1．Client (フロントエンド) の動作確認
・ルートディレクトリにて以下のコマンドを実行する．
$ pnpm --filter client dev
・ブラウザでの確認:
ターミナルに「➜ Local: http://localhost:5173/」と表示されたら，
Google Chrome等のブラウザを開き，アドレスバーに上記URLを貼り付けて実行する．
・正常動作の判断基準:
画面に「Vite + Preact」のロゴと「Vite + Preact + TypeScript」といった
テキストが表示されていれば，フロントエンドの環境構築は成功である．
2. Server (バックエンド) の動作確認
・テスト用コードの作成:
動作確認用のエントリーポイントを作成する．
$ touch apps/server/src/index.ts
ファイルに以下の内容を記述する．
console.log("Server is running!");
・コマンド:
$ pnpm --filter server dev
・正常動作の判断基準:
ターミナルに「Server is running!」と出力されれば構築成功である．
3．終了方法 (重要)
・動作確認を終了し，開発サーバーを停止させる場合は，ターミナル上で
「Ctrl + C」を押下する．
7. (応用) 本番ビルドの動作確認 (Production Build Check)
------------------------------------------------------------------------
開発環境(Dev Container)ではなく，本番環境と同様のDockerイメージを作成し，
正しくビルド・起動できるかを確認する手順である．
「機能開発が終わった後」や「プルリクエストを出す前」に実施することを推奨する．
7-1. 準備
Dev Containerを閉じ，ホストOS（Windows/Mac）のターミナルを開く．
※ Dev Container内からはDockerコマンドが使用できない場合があるため．
7-2. ビルドと起動
プロジェクトルートで以下のコマンドを実行する．
$ docker compose -f docker-compose.prod.yml up -d --build
7-3. 動作確認
1. ログ確認
$ docker compose -f docker-compose.prod.yml logs -f
Serverが起動していることを確認する．
2. ブラウザ確認
http://localhost:3001
※ ポート番号が開発用(3000/5173)と異なり 3001 に設定されている点に注意．
7-4. 終了と削除
確認が終わったら必ず環境を停止・削除する．
$ docker compose -f docker-compose.prod.yml down
