# arena-frontend

**Repository Path**: quant-seminar/arena-frontend

## Basic Information

- **Project Name**: arena-frontend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# arena-frontend

`arena-frontend` 是 Arena 量化投研平台的 React 前端。首页展示可扩展的研究方向入口；工作台负责执行、保存和比较研究版本；成果库用于整理个人成果；广场展示公开研究并支持收藏。

## 技术栈

- Vite
- React
- TypeScript
- Tailwind CSS
- shadcn/ui
- lucide-react
- motion
- VChart
- Apache Arrow、parquet-wasm
- react-markdown、remark-gfm、remark-math、rehype-katex
- react-syntax-highlighter

## 启动

```bash
cd arena/frontend
npm install
npm run dev
```

默认开发地址：

```text
http://127.0.0.1:5173
```

后端地址：

```env
VITE_ARENA_API_URL=http://127.0.0.1:8003
```

## 常用命令

```bash
npm run lint
npm run build
```

## 主要页面

| 路径 | 说明 |
| --- | --- |
| `/` | 研究方向轮播和快捷入口 |
| `/square` | 公开成果广场首页 |
| `/square/:researchTypeSlug` | 某类研究的公开成果列表 |
| `/square/:researchTypeSlug/:publicationId` | 公开成果详情 |
| `/workbench/:researchTypeSlug` | 某类研究工作台列表 |
| `/workbench/:researchTypeSlug/new` | 新建研究 |
| `/workbench/:researchTypeSlug/:projectId?v=1` | 研究详情和指定版本 |
| `/achievements/:researchTypeSlug` | 个人成果列表 |
| `/achievements/:researchTypeSlug/:publicationId` | 个人成果详情 |
| `/profile` | 登录、注册和个人中心 |
| `/users/:userId` | 用户公开主页 |
| `/help` | 帮助中心首页 |
| `/help/:topic` | 分主题帮助文档 |
| `/api` | API 说明页 |

## 目录结构

```text
frontend
|-- public/
|   `-- images/
|-- src/
|   |-- app/             # 应用壳、路由和布局
|   |-- components/      # shadcn/ui 和通用组件
|   |-- domains/         # API、领域类型和请求 hooks
|   |-- features/        # 可复用业务功能模块
|   |-- hooks/           # 通用 hooks
|   |-- pages/           # 路由页面
|   |-- research-types/  # 研究类型前端插件
|   |-- shared/          # 常量、API path、工具和展示组件
|   `-- styles/
```

## 当前能力

- 首页以研究方向轮播承载入口，不把产品限定为因子研究。
- 工作台支持研究列表、分页记忆、刷新、新建、详情、版本切换、版本对比、执行状态和错误展示。
- 成果库支持发布、删除、筛选来源、收藏公开成果，以及成果详情。
- 广场展示公开成果，支持查看详情、进入作者主页和收藏。
- 单因子分析支持构造 JSON、研究助手、因子分析图表、单因子回测图表、版本保存和成果发布。
- 多因子策略支持从已发布或收藏的单因子成果中选择输入，并执行策略回测。
- 帮助中心支持顶部导航和右下角浮动帮助窗口；帮助内容按基础介绍、分析项目、工作流、参考和 FAQ 分级。
- API 页面按 OpenAPI 风格组织接口、请求示例、响应示例和类型说明，示例代码使用 Python `requests`。
- 个人中心支持主题切换、登录状态、研究助手提示词配置。

## 研究类型插件

研究类型相关的参数面板、报告展示、成果参数展示和指标列应优先放到：

```text
src/research-types/<research-type>/
```

当前插件：

| slug | 说明 |
| --- | --- |
| `single-factor-analysis` | 单因子分析 |
| `multi-factor-strategy` | 多因子策略 |

跨研究类型复用的报告图表、对比面板、成果详情骨架等放到 `features` 或 `research-types/shared`。
页面层只做路由组合，不直接拼研究类型专属逻辑。

## 关键交互约定

- 页面列表状态只在前端运行期间记忆，不持久写入 localStorage。
- 详情页切换版本时按需拉取并缓存版本数据，支持 `?v=1` 指定初始版本。
- 执行分析后，结果区域立即进入运行状态；失败时显示本次错误，不恢复上一次报告。
- 完整报告以 Parquet 二进制传输，并在 Web Worker 中解析，避免大型 JSON 阻塞主线程。
- 大型弹窗和助手窗口应禁止背景穿透滚动，避免页面宽度抖动。
- 下拉、卡片、可点击胶囊和行项目需要明确 `cursor-pointer`、hover 状态和动效。
- JSON 结构展示使用 `shared/components/JsonCodeBlock`，不要在页面内重复手写 `<pre>` 样式。

## 开发约定

- 页面只做路由级组合，复杂业务逻辑下沉到 `features`、`domains` 或研究类型插件。
- 协议字符串使用 `src/shared/constants`，不要散落硬编码。
- 图表由前端根据 Worker 从 Parquet 还原的业务表生成 VChart spec。
- 指标优先读取后端 `metrics` 字段，缺失时显示 `-`。
- 基础组件优先使用 `components/ui` 中的 shadcn/ui 组件；不要在业务组件里重新实现按钮、弹窗、下拉等基础控件。
- Markdown 展示统一使用帮助中心或成果详情已有 Markdown 渲染组件。
- 不提交 `node_modules`、`dist`、本地 `.env` 或日志文件。

## 构建注意

`npm run build` 可能提示 VChart、lottie 或语法高亮相关 chunk 偏大。这是当前可接受的构建警告；
如果图表或 API 文档继续膨胀，应优先考虑按页面懒加载或拆分 `src/pages/api/apiDocs.ts`。