前端开发指南

技术栈

技术	版本	用途
React	18.3.1	UI 框架
TypeScript	~5.7.2	类型安全
Vite	6.0.3	构建工具和开发服务器
TanStack React Query	5.62.0	数据获取和缓存
Zustand	5.0.2	客户端状态管理
react-router-dom	7.18.1	路由
Bootstrap	5.3.8	CSS 框架
Chart.js	4.4.7	数据可视化
xterm.js	6.0.0	终端模拟
react-markdown	10.1.0	Markdown 渲染

项目结构

frontend/
├── public/                     # 静态资源
├── src/
│   ├── main.tsx                # 入口文件
│   ├── App.tsx                 # 根组件（含路由）
│   ├── api/                    # API 客户端层（30+ 个带类型模块）
│   │   ├── client.ts           # ApiClient（重试、超时、错误处理）
│   │   ├── request.ts          # 共享请求辅助
│   │   ├── index.ts            # 统一导出
│   │   └── ...                 # 按后端领域一域一模块：
│   │                           # auth、dashboard、messages、sessions、admin、
│   │                           # analysis、remote、governance、tenant、sso、
│   │                           # prompts、projects、toolAccounts、autonomous、
│   │                           # compliance、encryptionKeys、featureFlags、
│   │                           # feishuConfig、fs、insights、mappingRules、
│   │                           # modelGateway、notificationChannels、policy、
│   │                           # projectCategories、report、roi、smtpConfig、
│   │                           # system、users、workspace、alerts、
│   │                           # aiAgentSettings（含同目录 *.test.ts）
│   ├── components/
│   │   ├── common/             # 49 个共享 UI 组件
│   │   ├── layout/             # 布局容器（WorkLayout、ManageLayout）
│   │   ├── features/           # 页面级组件
│   │   │   ├── analysis/       # TrendAnalysis、AnomalyDetection、ROIAnalysis、UsageForecast、EnterpriseReport
│   │   │   ├── management/     # 管理页面及其弹窗/编辑器（UserManagement、TenantManagement、SecurityCenter 等）
│   │   │   ├── settings/       # SSOSettings、BrandingSettings、AiAgentSettings、NotificationIntegration、FeishuConfig
│   │   │   └── compliance/     # DataRetention、ComplianceReport
│   │   └── work/               # 工作模式专用组件
│   ├── hooks/                  # React Query hooks
│   ├── store/                  # Zustand 全局状态
│   ├── i18n/                   # 国际化翻译（en/zh/ja/ko）
│   ├── types/                  # TypeScript 接口
│   ├── utils/                  # 格式化器、辅助工具
│   └── styles/                 # CSS（Bootstrap 覆盖）
├── vite.config.ts              # 构建配置
├── tsconfig.json
└── package.json

开发工作流

# 安装依赖
npm install

# 启动开发服务器（端口 3000，API 代理到 localhost:19888）
npm run dev

# 生产构建（输出到 ../static/js/dist/）
npm run build

# 运行测试
npm run test

# 代码检查
npm run lint

开发服务器运行在 3000 端口，/api 和 /auth 请求代理到 19888 端口的 Flask 后端。

路由

工作模式 (/work/*) — 所有已认证用户

3 面板布局（WorkLayout）：会话列表 | 工作区（iframe）| 辅助面板

路由	组件	说明
/work	Workspace	主 AI 编码环境
/work/sessions	SessionList	会话历史
/work/prompts	Prompts	提示词模板
/work/usage	UsageOverview	个人使用统计
/work/insights	InsightsReport	AI 生成的洞察
/work/files	PersonalFiles	个人文件浏览
/work/alerts	UserAlerts	个人告警中心
/work/autonomous	AutonomousDev	自主开发工作流（受功能开关控制）
/work/workspace	—	工作区 iframe 锚点

管理模式 (/manage/*) — 仅管理员

侧边栏导航布局（ManageLayout）

路由	组件	说明
/manage/dashboard	Dashboard	管理概览
/manage/analysis	—	重定向到 /manage/analysis/trend
/manage/analysis/trend	TrendAnalysis	Token 趋势
/manage/analysis/request-dashboard	RequestDashboard	请求级用量仪表板
/manage/analysis/anomaly	AnomalyDetection	使用异常
/manage/analysis/roi	ROIAnalysis	ROI 指标
/manage/analysis/forecast	UsageForecast	用量预测
/manage/analysis/enterprise-report	EnterpriseReport	企业用量报告
/manage/analysis/conversation-history	ConversationHistory	对话历史浏览
/manage/messages	Messages	消息浏览器
/manage/audit	AuditCenter	审计日志查看
/manage/quota	QuotaAlerts	配额与告警
/manage/compliance	Compliance	数据保留
/manage/security	SecurityCenter	安全设置
/manage/policy/rules	PolicyRouteGuard	策略规则管理
/manage/users	UserManagement	用户 CRUD
/manage/tenants	TenantManagement	多租户
/manage/tenants/:id	TenantDetail	租户详情
/manage/projects	ProjectManagement	项目 CRUD
/manage/remote/machines	RemoteMachineManagement	机器管理
/manage/settings/sso	SSOSettings	SSO 配置
/manage/settings/branding	BrandingSettings	品牌与外观
/manage/settings/api-keys	APIKeyManagement	API Key 代理管理
/manage/settings/encryption-keys	EncryptionKeyManagement	加密密钥管理
/manage/settings/ai-agent	AiAgentSettings	AI Agent 设置
/manage/settings/notification-integration	NotificationIntegration	通知集成
/manage/settings/smtp	SmtpConfig	SMTP 配置
/manage/settings/model-gateway	ModelGatewayConfig	模型网关（LiteLLM 兼容）
/manage/settings/feishu	FeishuConfig	飞书集成

旧版路由（/dashboard、/messages 等）会将管理员重定向到 /manage/...，普通用户重定向到 /work/...。

数据流

API Client (src/api/client.ts)
  → React Query hooks (src/hooks/)
    → 页面组件 (src/components/features/)

ApiClient 类封装了 fetch，提供：

• 自动重试（最多 3 次，指数退避）
• 30 秒超时
• 自动包含凭证（credentials: 'include'）
• 按 HTTP 状态码返回友好的错误消息

React Query 配置了 1 分钟的 stale time 和单次重试。

状态管理

Zustand 状态仓库（src/store/index.ts），支持 localStorage 持久化（key: open-ace-store）：

持久化数据：

• theme（light/dark）、language（en/zh/ja/ko）
• appMode（work/manage）、sidebarCollapsed
• workspaceTabs — 多标签工作区状态（type、sessionId、machineId 等）

非持久化数据：

• user、isAuthenticated、authLoading
• workspaceFullscreen

导出了细粒度订阅的选择器（useUser、useTheme、useAppMode）。

国际化

src/i18n/index.ts 中的轻量级自定义 i18n：

import { t } from '@/i18n'

// 使用方法
t('common.save', language)

支持 4 种语言：en（默认）、zh、ja、ko。每种语言约 800+ 个键。

帮助文档也按语言存放在 src/components/work/docs/ 中。

构建配置

vite.config.ts 关键设置：

设置	值
Base 路径	/static/js/dist/
输出目录	../static/js/dist
开发服务器端口	3000
API 代理	/api、/auth → http://localhost:19888
编译目标	ES2020
压缩器	esbuild（生产环境移除 console.log）

路径别名： @ → src/、@api → src/api/、@components → src/components/ 等。

代码分割： react-vendor、router、query、zustand、charts、date-fns、api、components、hooks、store、utils、i18n，以及每个懒加载页面的自动分块。

通用组件

全部位于 src/components/common/：

组件	说明
Button	可配置按钮，支持变体、尺寸、加载状态
Card, StatCard	内容卡片和统计展示
Modal, ConfirmModal	对话框弹窗，支持多种尺寸
Select, SearchableSelect	下拉选择
Tabs, TabList, Tab, TabPanels	标签页导航
Loading, Skeleton, SkeletonCard	加载指示器
Error, EmptyState	错误和空状态
Badge, StatusBadge, CountBadge	状态指示器
Progress, CircularProgress	进度指示器
TextInput, Textarea, Checkbox	表单输入
Dropdown, SplitButton	下拉菜单
Avatar, AvatarUploader	用户头像
Tooltip	工具提示
ToastContainer, useToast	Toast 通知
ModeSwitcher	工作/管理模式切换
SessionDetailContent	会话详情查看器
LazyCharts	懒加载图表组件

添加新功能

1. API 层 — 创建 src/api/myFeature.ts，包含带类型的 API 调用
2. Hooks — 创建 src/hooks/useMyFeature.ts，包含 React Query hooks
3. 组件 — 创建 src/components/features/MyFeature.tsx（懒加载）
4. 路由 — 在 App.tsx 的 WorkRoutes 或 ManageRoutes 中添加路由
5. 国际化 — 在 src/i18n/index.ts 中为所有 4 种语言添加键
6. 类型 — 在 src/types/index.ts 中添加接口