# 前端开发文档

## 1. 项目架构

### 1.1 技术栈

| 类别 | 技术/库 | 版本 | 用途 |
|------|---------|------|------|
| 框架 | React | 18.x | 前端UI框架 |
| 路由 | React Router | 6.x | 页面路由管理 |
| 状态管理 | Redux Toolkit | 2.x | 全局状态管理 |
| UI组件库 | Ant Design | 5.x | 界面组件 |
| 图表库 | Lightweight Charts | 4.x | K线图表展示 |
| HTTP客户端 | Fetch API | 浏览器内置 | API调用 |
| 构建工具 | Vite | 5.x | 项目构建和开发服务器 |

### 1.2 目录结构

```
src/
├── assets/           # 静态资源
├── components/       # 通用组件
│   └── layout/       # 布局组件
├── pages/            # 页面组件
│   ├── admin/        # 管理配置页面
│   ├── config/       # 配置管理页面
│   ├── dashboard/    # 市场概览页面
│   ├── detail/       # 合约详情页面
│   ├── risk-control/ # 风控管理页面
│   └── watchlist/    # 自选合约页面
├── store/            # Redux状态管理
│   ├── futuresSlice.js # 期货数据状态管理
│   └── index.js      # Store配置
├── utils/            # 工具函数
│   └── mockData.js   # 模拟数据
├── App.jsx           # 应用入口组件
├── main.jsx          # 应用启动文件
└── index.css         # 全局样式
```

## 2. 页面结构与路由

### 2.1 路由配置

| 路径 | 组件 | 功能 |
|------|------|------|
| `/` | Dashboard | 市场概览 |
| `/watchlist` | Watchlist | 自选合约 |
| `/detail/:code` | Detail | 合约详情分析 |
| `/risk-control` | RiskControl | 风控管理 |
| `/config` | Config | 配置管理 |
| `/admin` | AdminConfig | 管理配置 |

### 2.2 布局设计

- **顶部导航栏**：包含系统名称、深色模式切换、消息通知和用户头像
- **左侧菜单栏**：包含主要功能模块的导航链接
- **右侧内容区**：根据路由显示对应页面内容
- **响应式设计**：支持桌面端、平板和移动端

## 3. 组件设计

### 3.1 布局组件

#### MainLayout 组件

- **功能**：提供统一的页面布局，包括顶部导航栏和左侧菜单栏
- **交互**：
  - 支持菜单栏折叠/展开
  - 深色模式切换
  - 响应式布局适配

### 3.2 页面组件

#### Dashboard 页面

- **功能**：市场概览，展示所有合约的基本信息和热点合约
- **交互**：
  - 数据刷新
  - 合约筛选和排序
  - 添加/移除自选合约
  - 查看合约详情
  - 消息推送配置

#### Detail 页面

- **功能**：合约详情分析，包括K线图、技术指标和AI研判
- **交互**：
  - 周期切换（5分钟、30分钟、1小时、1天、1周）
  - 技术指标切换（MA、MACD、KDJ、RSI、布林带）
  - 图表缩放和拖拽

#### Watchlist 页面

- **功能**：展示用户添加的自选合约
- **交互**：
  - 查看合约详情
  - 从自选中移除合约
  - 消息推送配置

#### RiskControl 页面

- **功能**：风险管理和仓位计算
- **交互**：
  - 止损策略设置
  - 仓位大小计算
  - 风险偏好设置
  - 换月预警查看

#### Config 页面

- **功能**：系统配置管理
- **交互**：
  - 系统参数调整
  - 消息推送配置

#### AdminConfig 页面

- **功能**：管理配置，包括数据库、服务器、安全和数据源配置
- **交互**：
  - 数据库连接测试
  - 数据源连接测试
  - 配置保存和恢复默认

## 4. 状态管理

### 4.1 Redux Store 设计

```javascript
// store/index.js
import { configureStore } from '@reduxjs/toolkit';
import futuresReducer from './futuresSlice';

const store = configureStore({
  reducer: {
    futures: futuresReducer
  }
});

export default store;
```

### 4.2 状态切片

#### futuresSlice.js

- **状态结构**：
  - `overview`：市场概览数据
  - `selectedFuture`：当前选中的合约详情
  - `riskAlerts`：风险预警数据
  - `aiAnalysis`：AI市场分析数据
  - `loading`：加载状态
  - `error`：错误信息
  - `watchlist`：自选合约列表

- **异步操作**：
  - `fetchFuturesOverview`：获取市场概览数据
  - `fetchFutureDetail`：获取单个合约详情
  - `fetchRiskAlerts`：获取风险预警数据
  - `fetchAIMarketAnalysis`：获取AI市场分析数据

- **同步操作**：
  - `selectFuture`：选择合约
  - `clearSelectedFuture`：清除选中合约
  - `toggleWatchlist`：切换自选合约状态

## 5. API 调用

### 5.1 后端 API 接口

| API路径 | 方法 | 功能 |
|---------|------|------|
| `/api/market/overview` | GET | 获取市场概览数据 |
| `/api/market/detail/:code` | GET | 获取合约详情数据 |
| `/api/market/klines/:code` | GET | 获取合约K线数据 |
| `/api/market/alerts` | GET | 获取风险预警数据 |
| `/api/config/get` | GET | 获取系统配置 |
| `/api/config/save` | POST | 保存系统配置 |
| `/api/config/test-database` | POST | 测试数据库连接 |
| `/api/config/test-datasource` | POST | 测试数据源连接 |

### 5.2 前端 API 调用封装

```javascript
// 后端API基础URL
const API_BASE_URL = 'http://localhost:3007/api';

// 异步获取期货概览数据
export const fetchFuturesOverview = createAsyncThunk(
  'futures/fetchOverview',
  async () => {
    const response = await fetch(`${API_BASE_URL}/market/overview`);
    if (!response.ok) {
      throw new Error('获取市场概览失败');
    }
    const data = await response.json();
    return data.data;
  }
);
```

## 6. 用户交互流程

### 6.1 市场概览流程

1. 用户进入系统，看到市场概览页面
2. 系统自动加载市场概览数据、风险预警和AI市场分析
3. 用户可以：
   - 刷新数据
   - 按类型筛选合约
   - 按胜率、涨跌幅或波动率排序
   - 点击合约查看详情
   - 添加合约到自选
   - 配置消息推送

### 6.2 合约详情流程

1. 用户从市场概览或自选列表点击合约进入详情页
2. 系统加载合约详情数据和K线数据
3. 用户可以：
   - 切换不同时间周期的K线图
   - 切换不同的技术指标
   - 查看技术指标数据
   - 查看多周期趋势
   - 查看AI研判结果
   - 查看交易建议和风险评估

### 6.3 自选合约流程

1. 用户进入自选合约页面
2. 系统显示用户添加的自选合约列表
3. 用户可以：
   - 刷新数据
   - 查看合约详情
   - 从自选中移除合约
   - 配置消息推送

### 6.4 风控管理流程

1. 用户进入风控管理页面
2. 用户可以：
   - 设置止损策略
   - 计算仓位大小
   - 设置风险偏好
   - 查看换月预警
   - 查看风险监控指标

### 6.5 配置管理流程

1. 用户进入配置管理页面
2. 用户可以：
   - 调整系统参数
   - 配置消息推送方式和内容

### 6.6 管理配置流程

1. 管理员进入管理配置页面
2. 管理员可以：
   - 配置数据库连接
   - 配置服务器参数
   - 配置安全设置
   - 配置数据源
   - 测试连接
   - 保存配置

## 7. 响应式设计

- **桌面端**：完整布局，左侧菜单展开
- **平板端**：左侧菜单可折叠，内容区域自适应
- **移动端**：底部导航栏，顶部状态栏，内容区域全屏

## 8. 深色模式

- **实现方式**：使用 Ant Design 的 ConfigProvider 和 CSS 变量
- **切换方式**：顶部导航栏的深色模式切换开关
- **效果**：全局界面元素的颜色和背景色随模式切换

## 9. 性能优化

### 9.1 代码分割

- 使用 React.lazy 和 Suspense 实现组件懒加载
- 按路由分割代码，减少初始加载时间

### 9.2 数据缓存

- 使用 Redux 缓存已获取的数据
- 避免重复请求相同数据

### 9.3 图表优化

- 使用 Lightweight Charts 高性能图表库
- 按需加载图表数据
- 优化图表渲染性能

## 10. 错误处理

- **API 错误处理**：捕获并显示 API 调用错误
- **图表错误处理**：当图表渲染失败时显示错误信息
- **数据加载状态**：使用 Spin 组件显示加载状态
- **边界情况**：处理空数据、无效参数等边界情况

## 11. 开发和部署

### 11.1 开发环境

- **启动命令**：`npm run dev`
- **开发服务器**：http://localhost:5173
- **API 代理**：配置代理到后端服务 http://localhost:3007

### 11.2 构建和部署

- **构建命令**：`npm run build`
- **构建产物**：`dist` 目录
- **部署方式**：可部署到任何静态文件服务器

## 12. 功能特性总结

| 功能 | 描述 | 实现方式 |
|------|------|----------|
| 市场概览 | 展示所有合约的基本信息和热点合约 | Redux + API调用 + 响应式布局 |
| 合约详情 | 展示合约的K线图、技术指标和AI研判 | Lightweight Charts + 技术指标计算 |
| 自选合约 | 管理用户关注的合约 | Redux状态管理 |
| 风控管理 | 风险管理和仓位计算 | 表单计算 + 数据展示 |
| 配置管理 | 系统配置和消息推送配置 | 表单 + 本地存储 |
| 管理配置 | 数据库、服务器和数据源配置 | 表单 + API调用 |
| 深色模式 | 支持深色和浅色主题切换 | Ant Design ConfigProvider |
| 响应式设计 | 适配不同屏幕尺寸 | CSS媒体查询 + Flexbox |
| 性能优化 | 代码分割和数据缓存 | React.lazy + Redux缓存 |
| 错误处理 | 完善的错误处理和边界情况 | 错误捕获 + 友好提示 |

## 13. 技术亮点

1. **模块化设计**：清晰的代码结构和组件划分
2. **高性能图表**：使用 Lightweight Charts 实现流畅的K线图表
3. **AI 集成**：集成AI市场分析和预测功能
4. **实时数据**：通过WebSocket获取实时市场数据
5. **响应式布局**：适配各种设备屏幕
6. **深色模式**：支持深色和浅色主题
7. **完善的风控**：提供全面的风险管理工具
8. **消息推送**：多渠道消息推送配置
9. **性能优化**：代码分割和数据缓存
10. **错误处理**：友好的错误提示和边界情况处理

## 14. 未来扩展

1. **用户系统**：添加用户登录、注册和权限管理
2. **交易系统**：集成交易功能，支持下单和撤单
3. **策略回测**：添加策略回测功能，评估交易策略
4. **更多数据源**：支持更多数据源，如Wind、新浪财经等
5. **更多技术指标**：添加更多技术指标和分析工具
6. **移动应用**：开发iOS和Android移动应用
7. **数据可视化**：增强数据可视化效果，添加更多图表类型
8. **智能投顾**：基于AI的智能投资顾问功能