# 数据库设置指南

## 概述

本项目使用PostgreSQL作为主数据库，SQLAlchemy作为ORM，Alembic作为数据库迁移工具。

## 数据库架构

### 表结构

1. **reports** - 报告主表
   - 存储股票分析报告的基本信息
   - 包含证券代码、市场、状态等字段

2. **analysis_modules** - 分析模块表
   - 存储报告中各个分析模块的内容
   - 与reports表一对多关系

3. **progress_tracking** - 进度追踪表
   - 记录报告生成过程中各步骤的执行状态
   - 与reports表一对多关系

4. **system_config** - 系统配置表
   - 存储系统配置信息
   - 使用JSONB格式存储配置值

## 环境配置

### 1. 安装PostgreSQL

```bash
# macOS (使用Homebrew)
brew install postgresql
brew services start postgresql

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# CentOS/RHEL
sudo yum install postgresql-server postgresql-contrib
```

### 2. 创建数据库

```sql
-- 连接到PostgreSQL
psql -U postgres

-- 创建数据库
CREATE DATABASE stock_analysis;

-- 创建用户（可选）
CREATE USER stock_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE stock_analysis TO stock_user;
```

### 3. 配置环境变量

创建 `.env` 文件：

```bash
# 数据库配置
DATABASE_URL=postgresql+asyncpg://username:password@localhost:5432/stock_analysis
DATABASE_ECHO=false

# API配置
GEMINI_API_KEY=your_gemini_api_key
TUSHARE_TOKEN=your_tushare_token
```

## 数据库管理

### 使用管理脚本

```bash
# 检查数据库连接
python manage_db.py check

# 初始化数据库表
python manage_db.py init

# 查看数据库状态
python manage_db.py status
```

### 使用Alembic迁移

```bash
# 初始化Alembic（已完成）
alembic init alembic

# 创建迁移文件
alembic revision --autogenerate -m "描述信息"

# 应用迁移
alembic upgrade head

# 查看迁移历史
alembic history

# 回滚迁移
alembic downgrade -1
```

## 开发工具

### 1. 数据库连接检查

```bash
python check_db.py
```

### 2. 数据库初始化

```bash
python init_db.py
```

### 3. 综合管理工具

```bash
python manage_db.py [check|init|status]
```

## 模型使用示例

### 创建报告

```python
from app.models import Report, AnalysisModule
from app.core.database import get_db

async def create_report():
    async for db in get_db():
        # 创建报告
        report = Report(
            symbol="000001",
            market="中国",
            status="generating"
        )
        db.add(report)
        await db.commit()
        await db.refresh(report)
        
        # 创建分析模块
        module = AnalysisModule(
            report_id=report.id,
            module_type="financial_data",
            module_order=1,
            title="财务数据分析",
            status="pending"
        )
        db.add(module)
        await db.commit()
```

### 查询报告

```python
from sqlalchemy import select
from app.models import Report

async def get_report(symbol: str, market: str):
    async for db in get_db():
        stmt = select(Report).where(
            Report.symbol == symbol,
            Report.market == market
        )
        result = await db.execute(stmt)
        return result.scalar_one_or_none()
```

## 性能优化

### 索引

所有表都已配置适当的索引：

- reports: symbol+market, status, created_at
- analysis_modules: report_id, module_type, status, module_order
- progress_tracking: report_id, status, step_order
- system_config: config_key, updated_at

### 连接池

数据库连接使用异步连接池，配置参数：

- pool_size: 10
- max_overflow: 20
- pool_timeout: 30秒
- pool_recycle: 1小时

## 故障排除

### 常见问题

1. **连接失败**
   - 检查PostgreSQL服务是否运行
   - 验证数据库URL配置
   - 确认防火墙设置

2. **迁移失败**
   - 检查数据库权限
   - 验证表结构冲突
   - 查看Alembic日志

3. **性能问题**
   - 检查索引使用情况
   - 分析慢查询日志
   - 优化查询语句

### 日志配置

在 `config.py` 中设置 `DATABASE_ECHO=True` 可以查看SQL执行日志。

## 备份与恢复

### 备份

```bash
pg_dump -U username -h localhost stock_analysis > backup.sql
```

### 恢复

```bash
psql -U username -h localhost stock_analysis < backup.sql
```