stock/README.md

# A股行情分析与量化交易系统

## 项目概述

本项目是一个完整的A股行情分析与量化交易系统，提供可靠的数据采集、存储、分析和交易功能。系统采用模块化架构设计，支持多数据源采集、自动化数据更新和实时监控。

## 系统架构

### 核心模块

- **数据采集模块**: 基于AKshare和Baostock的多源数据采集，支持股票基础信息、日K线数据和财务报告
- **数据处理模块**: 数据清洗、格式统一、校验和标准化处理
- **数据存储模块**: 基于SQLAlchemy的高效数据存储和查询，支持SQLite和MySQL
- **定时任务模块**: 基于APScheduler的自动化数据更新和同步
- **系统管理模块**: 统一的配置管理、日志记录和异常处理
- **测试模块**: 完整的单元测试、集成测试和性能测试

## 快速开始

### 环境要求

- Python 3.8+
- 推荐使用虚拟环境

### 一键部署

```bash
# 使用部署脚本自动完成环境设置
python deploy.py

# 生产环境部署
python deploy.py --production

# 跳过测试的快速部署
python deploy.py --skip-tests
```

### 手动安装

1. 创建虚拟环境
```bash
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate
```

2. 安装依赖
```bash
pip install -r requirements.txt
```

3. 配置环境
```bash
# 复制环境配置文件（可选）
cp .env.example .env

# 编辑.env文件配置数据库连接（可选）
# 默认使用SQLite数据库，无需额外配置
```

### 运行系统

```bash
# 查看帮助
python run.py --help

# 初始化系统数据（首次使用）
python run.py init

# 启动定时任务调度器
python run.py scheduler

# 查看系统状态
python run.py status

# 手动更新数据
python run.py update

# 运行测试
python run.py test

# 运行性能测试
python run.py performance
```

### 使用启动脚本（推荐）

```bash
# Windows
start.bat init
start.bat scheduler

# Linux/Mac
./start.sh init
./start.sh scheduler
```

## 功能特性

### ✅ 已完成功能

- **多源数据采集**: 集成AKshare和Baostock数据源，支持数据去重和合并
- **全量数据初始化**: 一键初始化所有股票基础数据、历史K线数据和财务报告
- **定时增量更新**: 自动化的每日K线更新、每周财务数据更新、每月基础信息更新
- **数据处理和清洗**: 数据验证、格式标准化、缺失值处理和异常检测
- **模块化架构**: 清晰的模块划分，便于维护和扩展
- **完善的日志系统**: 多级别日志记录，支持文件和控制台输出
- **异常处理机制**: 统一的异常分类和处理，支持错误恢复
- **数据库管理**: 支持SQLite和MySQL，包含连接池和事务管理
- **配置管理**: 统一的配置系统，支持环境变量覆盖
- **完整测试覆盖**: 单元测试、集成测试、性能测试

### 🔄 开发中功能

- 量化分析功能（技术指标计算）
- 交易接口实现（模拟交易）
- Web管理界面
- 数据可视化

## 项目结构

```
stock/
├── config/                 # 配置文件
│   ├── config.py          # 系统配置
│   └── settings.py         # 项目设置
├── src/                   # 源代码
│   ├── data/              # 数据采集和处理
│   ├── storage/           # 数据存储
│   ├── scheduler/         # 定时任务
│   ├── utils/            # 工具模块
│   └── main.py           # 主程序
├── tests/                 # 测试代码
│   ├── test_*.py         # 各类测试
│   └── conftest.py       # 测试配置
├── logs/                  # 日志文件（自动创建）
├── data/                  # 数据文件（自动创建）
├── run.py                # 启动脚本
├── deploy.py             # 部署脚本
├── requirements.txt      # 依赖包
└── README.md             # 项目文档
```

## 配置说明

### 数据库配置

系统默认使用SQLite数据库，无需额外配置。如需使用MySQL，可修改配置文件：

```python
# 在config/config.py中修改
DATABASE_CONFIG = {
    "database_url": "mysql+mysqlconnector://username:password@localhost:3306/stock_analysis",
    "echo": False,
    "pool_size": 10,
    "max_overflow": 20
}
```

### 定时任务配置

系统包含以下定时任务：

- **每日K线更新**: 交易日收盘后18:00执行
- **每周财务更新**: 周六09:00执行  
- **每月基础信息更新**: 每月1号10:00执行
- **每日健康检查**: 每天08:00执行

### 日志配置

系统支持多级别日志记录：

- DEBUG: 开发调试信息
- INFO: 常规运行信息
- WARNING: 警告信息
- ERROR: 错误信息

## 开发指南

### 添加新的数据源

1. 在`src/data/`目录下创建新的采集器类
2. 继承`BaseCollector`基类
3. 实现必要的数据采集方法
4. 在`DataManager`中注册新的数据源

### 添加新的定时任务

1. 在`src/scheduler/task_scheduler.py`中添加任务方法
2. 配置任务执行时间和参数
3. 在调度器中注册新任务

### 运行测试

```bash
# 运行所有测试
python -m pytest tests/ -v

# 运行特定测试
python -m pytest tests/test_data_collectors.py -v

# 运行性能测试
python -m pytest tests/test_performance.py -v

# 生成测试覆盖率报告
python -m pytest --cov=src tests/
```

### 测试环境配置

系统使用独立的测试数据库来确保测试隔离性：

#### 测试数据库配置
- **测试数据库文件**: `tests/test_stock.db` (SQLite)
- **测试模型定义**: 在`tests/conftest.py`中定义独立的测试模型类
- **数据隔离**: 测试使用独立的数据库，不影响生产数据

#### 测试模型兼容性
系统已解决测试环境与生产环境的模型兼容性问题：
- **模型类动态获取**: `StockRepository`使用`_setup_models`方法动态获取模型类
- **测试模型优先**: 优先使用测试数据库管理器中的模型定义
- **回退机制**: 如果无法获取测试模型，回退到默认导入的模型类

#### 测试数据管理
- **测试数据清理**: 每个测试结束后自动清理测试数据
- **事务回滚**: 支持事务级别的测试隔离
- **性能测试**: 包含批量插入和查询性能测试

#### 测试运行示例

```bash
# 运行存储模块测试
python -m pytest tests/test_storage.py -v

# 运行特定测试方法
python -m pytest tests/test_storage.py::TestStockRepository::test_save_stock_basic_info_success -v

# 运行事务回滚测试
python -m pytest tests/test_storage.py::TestStockRepository::test_transaction_rollback_on_error -v

# 运行性能测试
python -m pytest tests/test_performance.py -v
```

#### 测试注意事项
- 测试使用独立的SQLite数据库文件，不会影响主数据库
- 测试数据在测试结束后自动清理
- 支持事务回滚测试，确保数据一致性
- 性能测试包含基准性能指标验证

## 故障排除

### 常见问题

1. **数据库连接失败**
   - 检查数据库服务是否启动
   - 验证连接字符串是否正确
   - 检查网络连接

2. **数据采集失败**
   - 检查网络连接
   - 验证数据源API是否可用
   - 查看详细错误日志

3. **内存使用过高**
   - 减少批量处理大小
   - 增加垃圾回收频率
   - 优化数据处理逻辑

### 获取帮助

- 查看详细日志：`logs/stock_system.log`
- 使用调试模式：`python run.py --debug status`
- 查看系统状态：`python run.py status`

## 许可证

MIT License

## 贡献指南

欢迎提交Issue和Pull Request来改进本项目。