# stock-simulator

**Repository Path**: narc/stock-simulator

## Basic Information

- **Project Name**: stock-simulator
- **Description**: 炒股模拟器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-29
- **Last Updated**: 2025-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 股票模拟交易系统 (Stock Simulator)

一个基于React + TypeScript构建的全功能股票模拟交易系统，提供可控制时间的股票交易模拟环境，让用户能够在真实的历史股价数据上练习交易策略。

## 📚 文档资源

详细的文档请访问我们的 [WIKI](https://gitee.com/narc/stock-simulator/wikis)。

WIKI包含以下主题：
- [快速开始指南](https://gitee.com/narc/stock-simulator/wikis/quick-start)
- [系统架构](https://gitee.com/narc/stock-simulator/wikis/architecture)
- [API文档](https://gitee.com/narc/stock-simulator/wikis/api)
- [常见问题](https://gitee.com/narc/stock-simulator/wikis/faq)
- [贡献指南](https://gitee.com/narc/stock-simulator/wikis/contributing)

## 🚀 项目特色

- **可控制时间系统** - 可以任意调整模拟交易的日期，体验历史行情
- **真实股价数据** - 基于真实的历史股价CSV数据进行模拟交易
- **完整交易功能** - 支持买入、卖出、持仓管理、盈亏统计
- **多种图表展示** - 提供K线图、移动平均线、成交量等多种技术分析工具
- **移动端适配** - 支持桌面端和移动端两种显示模式
- **数据持久化** - 所有交易数据保存在本地，支持页面刷新后恢复

## 📱 功能模块

### 1. 时间控制系统
- 灵活的时间控制，可快进、快退到任意交易日
- 自动跳过非交易日（周末、节假日）
- 支持按天、周、月进行时间跳转

### 2. 股票市场
- 显示所有可交易股票列表
- 实时显示当前模拟时间的股价信息
- 支持股票搜索和筛选功能

### 3. 交易中心
- 直观的买入/卖出交易界面
- 实时计算手续费和交易成本
- 支持市价单交易
- 交易前资金和持仓验证

### 4. 投资组合管理
- 账户总览：总资产、可用资金、持仓市值
- 持仓明细：显示每只股票的成本价、现价、盈亏
- 交易记录：完整的历史交易记录
- 交易统计：按股票分组的盈亏分析

### 5. K线图表系统
- **标准K线图**: 基于recharts的高性能K线图
- **ECharts增强版**: 支持更丰富的交互功能，包括:
  - 点击K线查看详情
  - 图表内直接交易
  - 交易标记显示
  - 智能时间控制
- **移动端版本**: 专为移动设备优化的全屏K线图

## 🛠 技术栈

- **前端框架**: React 18.3.1 + TypeScript
- **UI组件库**: Ant Design 5.27.1
- **图表库**: 
  - Recharts 3.1.2 (主要图表库)
  - ECharts 5.6.0 + echarts-for-react (增强图表)
- **样式方案**: CSS + Ant Design
- **数据处理**: PapaParse (CSV解析)
- **时间处理**: Day.js + Moment.js
- **图标**: Ant Design Icons + Lucide React
- **构建工具**: Create React App
- **HTTP客户端**: Axios

## 📦 项目结构

```
src/
├── components/          # UI组件
│   ├── EChartsKLineChart.tsx    # ECharts K线图组件
│   ├── KLineChart.tsx          # 标准K线图组件  
│   ├── MobileKLineChart.tsx    # 移动端K线图组件
│   ├── Portfolio.tsx           # 投资组合组件
│   ├── StockList.tsx          # 股票列表组件
│   ├── TimeControl.tsx        # 时间控制组件
│   └── TradingPanel.tsx       # 交易面板组件
├── services/           # 业务逻辑服务
│   ├── ApiService.ts           # API服务，用于与后端通信
│   ├── DataService.ts         # 数据服务
│   ├── TimeService.ts         # 时间服务  
│   └── TradingService.ts      # 交易服务
├── types/              # 类型定义
│   └── index.ts              # 全局类型定义
├── App.tsx            # 主应用组件
└── index.tsx          # 应用入口
```

## 🏗 系统架构

系统采用分层架构设计：

```
graph TB
    subgraph "UI组件层"
        A[时间控制] 
        B[股票列表]
        C[交易面板]
        D[投资组合]
        E[K线图表]
    end
    
    subgraph "服务层"
        F[TimeService<br/>时间服务]
        G[DataService<br/>数据服务] 
        H[TradingService<br/>交易服务]
    end
    
    subgraph "数据层"
        I[CSV股价数据]
        J[LocalStorage<br/>交易数据]
        K[外部API服务]
    end
    
    A --> F
    B --> G
    C --> H
    D --> H
    E --> G
    
    F --> G
    H --> G
    
    G --> I
    G --> K
    H --> J
```

## 🚀 快速开始

### 环境要求
- Node.js 16.x 或更高版本
- npm 或 yarn 包管理器

### 安装步骤

1. **克隆项目**
   ```bash
   git clone [repository-url]
   cd stock-simulator
   ```

2. **安装依赖**
   ```bash
   npm install
   # 或
   yarn install
   ```

3. **配置数据源**
   
   系统支持两种数据源：
   - **CSV文件** (默认): 从本地CSV文件加载数据
   - **API**: 从外部后端API服务加载数据
   
   要切换数据源，请修改项目根目录下的 `.env` 文件：
   ```env
   # 设置为 'api' 使用后端API
   REACT_APP_DATA_SOURCE=api
   
   # API基础URL (使用API数据源时需要)
   # 默认: http://127.0.0.1:5000
   REACT_APP_API_BASE_URL=http://127.0.0.1:5000
   ```
   
   要使用本地CSV文件：
   ```env
   REACT_APP_DATA_SOURCE=csv
   ```

4. **启动开发服务器**
   ```bash
   npm start
   ```
   
   应用将在 [http://localhost:4000](http://localhost:4000) 启动

5. **构建生产版本**
   ```bash
   npm run build
   ```

### 可用脚本

- `npm start` - 启动开发服务器 (端口: 4000)
- `npm test` - 运行测试
- `npm run build` - 构建生产版本
- `npm run eject` - 弹出CRA配置 (不可逆操作)

## 🎯 使用指南

### 基本操作流程

1. **设置模拟时间**
   - 进入"时间控制"页面
   - 选择想要开始模拟交易的日期
   
2. **浏览股票市场**
   - 进入"股票市场"页面
   - 查看当前时间点的股价信息
   - 点击"查看详情"可跳转到K线图
   
3. **执行交易**
   - 进入"交易中心"页面
   - 选择要交易的股票
   - 输入交易数量，点击买入/卖出
   
4. **查看投资组合**
   - 进入"我的账户"页面
   - 查看总资产、持仓情况
   - 分析交易记录和盈亏统计
   
5. **技术分析**
   - 进入"K线图表"页面
   - 使用多种图表工具进行技术分析
   - 可切换移动端/桌面端显示模式

### 高级功能

## 🔧 数据源配置

系统支持通过环境变量配置两种数据源：

### CSV数据源 (默认)
- 数据从 `public/data/csv/` 目录下的本地CSV文件加载
- 无需额外的后端服务
- 适用于本地开发和测试

### API数据源
- 数据从外部后端API服务获取
- 需要运行外部API服务
- 更适合生产环境

切换数据源的方法：
1. 打开项目根目录下的 `.env` 文件
2. 将 `REACT_APP_DATA_SOURCE` 设置为 `csv` 或 `api`
3. 如果使用API数据源，还需设置 `REACT_APP_API_BASE_URL` 为您的API端点

API数据源的 `.env` 配置示例：
```env
REACT_APP_DATA_SOURCE=api
REACT_APP_API_BASE_URL=http://127.0.0.1:5000
```

CSV数据源的 `.env` 配置示例：
```env
REACT_APP_DATA_SOURCE=csv
```