# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 常用命令

### 开发环境
```bash
# 安装依赖
pip install -r requirements.txt

# 启动开发服务器
python run.py

# 初始化数据库（首次使用）
python init_database.py

# 数据迁移（从JSON文件迁移到数据库）
python migrate_to_database.py
```

### 生产环境部署
```bash
# Docker构建和运行
docker-compose up -d

# 查看运行状态
docker-compose ps

# 查看日志
docker-compose logs stock-monitor
```

### 测试和调试
```bash
# 查看API文档
# 访问 http://localhost:8000/docs

# 测试数据库连接
python -c "from app.dao import StockDAO; print('数据库连接成功')"

# 测试Tushare API
python -c "import tushare as ts; ts.set_token('your_token'); print(ts.pro_api().trade_cal(exchange='SSE', start_date='20240101', end_date='20240105'))"
```

## 核心架构

### 技术栈
- **后端**: FastAPI + SQLAlchemy + MySQL/SQLite
- **前端**: HTML5 + CSS3 + JavaScript + Bootstrap + ECharts
- **数据源**: Tushare API (股票数据) + 豆包大模型 (AI分析)
- **部署**: Docker + Uvicorn

### 项目结构
```
stock-monitor/
├── app/                     # 应用主目录
│   ├── api/                 # API路由层
│   │   ├── stock_routes.py     # 股票相关API
│   │   └── market_routes.py    # 市场数据API
│   ├── services/            # 业务逻辑层
│   │   ├── stock_service_db.py      # 股票数据服务
│   │   ├── ai_analysis_service_db.py # AI分析服务
│   │   ├── market_data_service.py    # 市场数据服务
│   │   └── kline_service.py          # K线数据服务
│   ├── dao/                 # 数据访问层 (DAO模式)
│   │   ├── base_dao.py           # 基础DAO类
│   │   ├── stock_dao.py          # 股票数据DAO
│   │   ├── watchlist_dao.py      # 自选股DAO
│   │   ├── ai_analysis_dao.py    # AI分析DAO
│   │   └── config_dao.py         # 配置DAO
│   ├── models/              # 数据模型
│   └── templates/           # HTML模板
├── config.template.py       # 配置文件模板
├── database_schema.sql     # MySQL数据库表结构
├── init_database.py        # 数据库初始化脚本
└── run.py                  # 应用启动脚本
```

### 数据架构
- **MySQL生产数据库**: 包含stocks、stock_data、watchlist、ai_analysis等核心表
- **SQLite开发数据库**: 用于本地开发和测试
- **JSON缓存**: 历史数据使用JSON文件缓存
- **DAO模式**: 统一的数据访问接口，便于数据库切换

### 核心功能模块

#### 1. 股票数据管理 (app/services/stock_service_db.py)
- 从Tushare API获取实时股票数据
- 数据缓存机制（优先从数据库读取）
- 支持强制刷新和增量更新

#### 2. AI智能分析 (app/services/ai_analysis_service_db.py)
- 集成豆包大模型进行股票分析
- 支持多维度分析：价值投资、道德经视角、投资大师分析
- 分析结果持久化存储

#### 3. 自选股管理 (app/services/watchlist_service.py)
- 添加/删除自选股票
- 设置市值预警范围
- 目标市值监控

#### 4. 市场数据服务 (app/services/market_data_service.py)
- 沪深指数实时行情
- K线图表数据
- 板块涨跌排行

### API设计
- RESTful API设计
- 自动生成API文档 (`/docs`)
- 统一错误处理和响应格式
- 支持CORS跨域请求

### 配置管理
- **Tushare Token**: 需要在config.py中配置
- **豆包大模型API**: 需要配置API Key和模型ID
- **数据库配置**: 支持MySQL和SQLite切换
- **环境变量**: 支持通过环境变量覆盖配置

## 重要说明

### 数据获取限制
- Tushare API有调用频率限制，建议适当控制请求频率
- 免费账户每分钟最多调用200次
- 生产环境建议使用付费套餐

### AI分析成本
- 豆包大模型按量计费，有免费额度
- 超出免费额度后按实际使用量收费
- 建议合理控制AI分析次数

### 数据免责声明
- 项目提供的股票数据仅供参考，不构成投资建议
- 股票投资有风险，入市需谨慎
- AI分析结果基于公开数据和模型计算

### 开发建议
- 首次使用需要先执行`python init_database.py`初始化数据库
- 开发时可使用SQLite数据库，生产环境推荐MySQL
- 建议监控股票数量不超过30只以保证性能
- 定时刷新间隔建议60秒以上

## 常见问题

### Q: Tushare Token如何获取？
A: 访问 https://tushare.pro 注册账号并获取API Token

### Q: 豆包大模型API如何配置？
A: 访问火山引擎控制台创建应用，获取API Key和模型接入点ID

### Q: 如何切换数据库？
A: 修改config.py中的数据库连接配置，重新执行init_database.py

### Q: Docker部署端口冲突？
A: 修改docker-compose.yml中的端口映射，如将"15348:8000"改为其他端口