React 前端

前端是纯静态的 React 应用，构建产物由 gui.py 本地托管。它没有服务端渲染，也不需要单独的 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	动效
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/        # 通用组件
├── api/               # 客户端、类型、生成契约
├── config/            # 配置表单模型与保存队列
├── scheduler/         # 调度画布的节点、端口、布局
├── mind/              # 心智计算器
├── fleet-tech/        # 舰队科技
├── resources/         # 资源管理
├── stock/             # 交易所
├── remote/            # 远程访问
├── i18n*.ts           # 国际化资源与开发工具
└── styles/            # 全局样式与变量

路由

路径	页面
`/`	首页（实例列表）
`/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`	舰队科技

旧路径（/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 生成，包含每个方法的名与参数类型。
frontend/src/api/contract.json 是完整 JSON Schema，用于校验与测试。
不要手改生成文件。后端改参数模型后重新导出。

api.request 负责：请求 ID 生成、超时、错误码到提示的映射、连接断开时的重连提示。

状态管理

没有引入 Redux 或 Zustand。状态分三类：

类型	载体	例子
服务器状态	订阅 + 请求结果	实例列表、总览、统计
编辑状态	`config/EditQueue.ts`	配置表单的待提交修改
界面偏好	localStorage + 顶栏偏好	主题、布局、上次路径

保存队列

配置编辑不是每次输入都发请求：

输入进入 EditQueue。
合并同一路径的连续修改。
带 revision 批量 config.patch。
冲突时提示刷新，不覆盖他人的修改。

页面卸载前会等待队列清空，避免「改完就切页」丢配置。

国际化

i18n.resources.ts 是运行时文案，zh-CN 为源。
i18n.dev.ts / i18n.test.ts 提供开发与测试用的缺失键提示。
配置项的中文文案不在这里，而在 Python 侧的 module/config/i18n/*.json，由 schema.get 下发。

新增界面文案时，至少补 zh-CN 与 en-US；缺失键在开发模式下会显式显示，不会静默回退。

调度画布

src/scheduler/ 是自定义调度编辑器的核心：

节点与端口由 module/scheduler/ 的模型驱动，前端只负责渲染与编辑。
方形端口控制执行顺序，圆形端口传数据；不兼容类型不能连线。
拖拽由 React Flow 管理，松手后提交一次文档变更。
保存前调用 scheduler.program.validate，运行前调用 apply。

样式

全局变量在 styles/，组件样式就近。
主题切换通过 CSS 变量，不在组件里写死颜色。
移动端断点会让侧边栏折叠、表单单列。

本地开发

bash

npm ci --prefix frontend
npm run dev --prefix frontend        # 需要后端在 25548
npm run dev:mock --prefix frontend   # 使用 mock 服务，不连真实后端

Vite 开发服务器监听 127.0.0.1，通过代理访问后端。dev:mock 适合只改界面的场景，不会触碰真实配置。

测试

类型	命令	覆盖
类型检查	`npm run typecheck --prefix frontend`	全部 TS/TSX
单元测试	`npm test --prefix frontend`	组件、hooks、工具函数
端到端	`npm run test:e2e --prefix frontend`	真实后端
端到端（mock）	`npm run test:e2e:mock --prefix frontend`	模拟服务
交易所专项	`npm run test:e2e:stock --prefix frontend`	交易所流程

先跑 mock

真实 e2e 需要模拟器与实例，跑一次成本高。改界面时优先 test:e2e:mock，确认交互无误后再跑真实链路。

构建

bash

npm run build --prefix frontend

先 tsc -b 再 vite build，类型错误会直接失败。
产物写入 frontend/dist，由后端静态托管。
gui.py 在 dist 缺失时会自动构建，但生产部署建议预构建，避免首次启动等待。

修改前须知

事项	约定
新增 API	先改 Python 契约并导出，再写前端
配置字段	不改前端表单代码，schema 驱动自动渲染
主题色	用 CSS 变量，不要新增硬编码色值
图标	统一用 `lucide-react`
文案	补 `zh-CN` 与 `en-US`
大组件	拆到 `components/`，页面只做编排

React 前端

技术栈 ​

目录 ​

路由 ​

API 契约 ​

状态管理 ​

保存队列 ​

国际化 ​

调度画布 ​

样式 ​

本地开发 ​

测试 ​

构建 ​

修改前须知 ​

技术栈

目录

路由