React フロントエンド

フロントエンドは純粋な静的 React アプリケーションとして構成されており、ビルド成果物は gui.py によってローカルホストされます。SSR（サーバーサイドレンダリング）は使用しておらず、独立した Node サーバーの常駐も不要です。

技術スタック

ライブラリ / ツール	バージョン	主な用途
React	19.3	UI 描画
React Router	7.18	クライアントサイドルーティング
Vite	6.x	ビルドおよび開発サーバー
TypeScript	5.x	型安全性の担保
ECharts	6.1	統計グラフの描画
@xyflow/react	12.x	ビジュアルスケジューラーキャンバス
motion	13.x	UI アニメーション
CodeMirror	6.x	YAML / JSON エディタ
lucide-react	1.45	アイコンセット

Node.js の動作要件は >=22.12.0 です（frontend/package.json の engines 参照）。

ディレクトリ構成

frontend/src/
├── main.tsx           # ルーティング設定とアプリケーションエントリ
├── app/               # レイアウトフレーム、トップバー、検索、ユーザー設定
├── pages/             # 各画面のルートコンポーネント
├── components/        # 再利用可能な共通 UI コンポーネント
├── api/               # API クライアント、型定義、自動生成規約
├── config/            # 設定フォームのモデルおよび保存キュー
├── scheduler/         # ビジュアルスケジューラーのノード、ポート、レイアウト
├── mind/              # メンタル計算機
├── fleet-tech/        # 艦隊技術
├── resources/         # リソース管理ビュー
├── stock/             # 取引所
├── remote/            # リモートアクセス設定
├── i18n*.ts           # 多言語テキストリソースおよび開発支援ツール
└── styles/            # グローバルスタイルシートおよび CSS 変数定義

ルーティング定義

パス	画面コンポーネント
/	ホーム画面（インスタンス一覧）
/announcement	お知らせ
/interface	外観・インターフェース設定
/remote	リモートアクセス
/settings	システム全体設定
/updater	アップデータ画面
/configs	インスタンス設定ファイル管理
/dev	開発者用テストコントロール
/i/:instance/overview	インスタンスダッシュボード
/i/:instance/task/:task	タスク設定フォーム
/i/:instance/statistics	統計レポート
/i/:instance/stock-exchange	取引所
/i/:instance/task/SchedulerProgram	ビジュアルスケジューラー
/i/:instance/task/MindCalculator	メンタル計算機
/i/:instance/task/FleetTechnology	艦隊技術

古い URL パス（/logs、/resources、/scheduler、/mind-calculator）は新パスへ自動リダイレクトされ、ブックマークの破損を防ぎます。

API 規約と通信クライアント

import { api } from '../api/client'

const list = await api.request('instances.list', {})

• frontend/src/api/generated.ts は dev_tools.export_api_schema により自動生成され、全メソッド名とパラメータの TypeScript 型定義を含みます。
• frontend/src/api/contract.json は完全な JSON Schema であり、自動検証テストで使用されます。
• 自動生成ファイルを直接手編集しないでください。バックエンド側のモデルを修正した後にスクリプトで再出力してください。

api.request はリクエスト ID の採番、タイムアウト制御、エラーコードからユーザー向け通知へのマッピング、切断時の自動再接続処理を透過的に担います。

状態管理アーキテクチャ

Redux や Zustand などの外部状態管理ライブラリは導入していません。状態は3系統に分類されて管理されます：

状態種別	格納・管理レイヤー	具体例
サーバー状態	WebSocket イベント購読 ＋ リクエスト結果	インスタンス一覧、現在タスク、統計データ
フォーム編集状態	config/EditQueue.ts	設定フォーム上の未送信変更キュー
UI 設定・好み	localStorage ＋ コンテキスト	テーマ、レイアウト密度、直前に開いていたパス

設定保存キュー（EditQueue）

文字入力のたびに即座に API リクエストを送信するのではなく、バッファリング制御が行われます：

1. ユーザーの入力変更はまず EditQueue に格納されます。
2. 同一設定パスへの連続した入力変更はマージ集約されます。
3. revision 番号を添えて config.patch をバッチ送信します。
4. バージョン競合が発生した場合はユーザーに通知し、他者の編集結果を勝手に上書きしません。

画面を離脱する際はキューのフラッシュ完了を待機するため、「入力直後に別ページへ移動して設定が消える」現象を防止します。

国際化（i18n）

• i18n.resources.ts にフロントエンドの UI テキストが定義されており、zh-CN をマスターとします。
• タスク名や設定項目の詳細な説明文はフロントエンド内には持たず、Python 側の module/config/i18n/*.json から schema.get を経由して動的に受給します。

新規 UI 文言を追加する際は、少なくとも zh-CN と en-US を定義してください。

ビジュアルスケジューラーキャンバス

src/scheduler/ はノードベースのカスタムスケジューラーの中心部です：

• ノードと接続ポートのデータモデルはバックエンドの module/scheduler/ に準拠し、フロントエンドはレンダリングと操作を担当します。
• 四角いポートは実行シーケンス、丸いポートはデータフローを制御し、型の異なるポート同士の結線はブロックされます。
• 保存前に scheduler.program.validate を呼び出して整合性を事前検証します。

スタイリングとデザイン規約

• グローバル変数や共通クラスは styles/ に集約し、コンポーネント固有のスタイルは同一ディレクトリ内に近接配置します。
• カラー値は CSS 変数（カスタムプロパティ）を使用し、ハードコードされた HEX カラーを記述しないでください。
• レスポンシブ設計により、モバイル幅ではサイドバーが自動収納されます。

ローカル開発環境の起動

npm ci --prefix frontend
npm run dev --prefix frontend        # バックエンドがポート 25548 で起動している必要があります
npm run dev:mock --prefix frontend   # モックサーバーを使用し、バックエンドなしで単体起動

Vite 開発サーバーは 127.0.0.1 で待機し、API 呼び出しをバックエンドへプロキシします。純粋な UI 修正であれば dev:mock を活用することで手軽に作業できます。

テストコマンド

テスト種別	実行コマンド	検証範囲
型検査	npm run typecheck --prefix frontend	全 TS/TSX コード
単体テスト	npm test --prefix frontend	コンポーネント、カスタムフック、ユーティリティ
E2E テスト（実機）	npm run test:e2e --prefix frontend	実バックエンドを介した統合検証
E2E テスト（モック）	npm run test:e2e:mock --prefix frontend	モックサーバー環境での主要 UI 動作
取引所テスト	npm run test:e2e:stock --prefix frontend	取引所機能の専用フロー検証

静的ビルド

npm run build --prefix frontend

• tsc -b による型検査を通過した後、vite build が実行されます。
• 生成物は frontend/dist に出力され、バックエンドにより静的ホスティングされます。

開発時の留意事項

開発項目	遵守すべき規約
新規 API の追加	必ず Python 側のモデルを先に改変してスキーマを出力してからフロントエンドを記述
設定項目の追加	フロントエンド側のフォームコードは触らない（スキーマ駆動で自動生成）
配色変更	CSS 変数を使用し、直接のカラーコード記述を避ける
アイコン	lucide-react で統一
コンポーネント設計	巨大化したロジックは components/ 配下に切り出し、ページ側は構成のみを担当