# 设计文档 - 基本面选股系统

## 概览

基本面选股系统是一个全栈Web应用，采用前后端分离架构。前端使用Next.js和shadcn/ui构建响应式中文界面，后端使用Python FastAPI提供API服务。系统通过多个专业分析模块，结合财务数据API、AI大模型和实时数据，为用户提供全面的股票基本面分析报告。

## 架构

### 系统架构图

```mermaid
graph TB
    subgraph "前端层"
        A[Next.js应用] --> B[shadcn/ui UI组件]
        A --> C[TradingView图表组件]
    end
    
    subgraph "后端层"
        D[FastAPI服务器] --> E[报告生成引擎]
        D --> F[数据获取服务]
        D --> G[配置管理服务]
    end
    
    subgraph "外部服务"
        H[Tushare API]
        I[Gemini API]
        J[其他数据源APIs]
    end
    
    subgraph "数据层"
        K[PostgreSQL数据库]
    end
    
    A --> D
    F --> H
    F --> I
    F --> J
    E --> K
    G --> K
```

### 技术栈

**前端:**
- Next.js 14 (App Router)
- TypeScript
- shadcn/ui组件库 (https://ui.shadcn.com/)
- TradingView Charting Library
- Tailwind CSS
- Radix UI (shadcn/ui的底层组件)

**后端:**
- Python 3.11+
- FastAPI
- SQLAlchemy (ORM)
- Alembic (数据库迁移)
- Pydantic (数据验证)
- httpx (HTTP客户端)

**数据库:**
- PostgreSQL 15+

**外部服务:**
- Tushare API (中国股票数据)
- Google Gemini API (AI分析)
- 其他市场数据源APIs

## 组件和接口

### shadcn/ui组件使用规划

系统将使用shadcn/ui (https://ui.shadcn.com/) 的官方组件来构建一致的用户界面：

**核心组件使用：**
- `Button`: 主要操作按钮（生成报告、保存配置等）
- `Input`: 证券代码输入框
- `Select`: 交易市场选择器
- `Card`: 分析模块容器、报告卡片
- `Progress`: 报告生成进度条
- `Badge`: 状态标识（完成、进行中、失败）
- `Tabs`: 分析模块切换
- `Form`: 配置表单、搜索表单
- `Alert`: 错误提示、成功消息
- `Separator`: 内容分隔线
- `Skeleton`: 加载占位符
- `Toast`: 操作反馈通知
- `Table`: 财务数据展示表格（资产负债表、利润表、现金流量表等）

**主题配置：**
- 使用默认主题，支持深色/浅色模式切换
- 自定义中文字体配置
- 适配中文内容的间距和排版

### 前端组件结构

```
src/
├── app/
│   ├── page.tsx                 # 首页
│   ├── report/[symbol]/page.tsx # 报告页面
│   ├── config/page.tsx          # 配置页面
│   └── layout.tsx               # 根布局
├── components/
│   ├── ui/                      # shadcn/ui基础组件 (Button, Input, Card, etc.)
│   ├── StockSearchForm.tsx      # 股票搜索表单 (使用Form, Input, Select)
│   ├── ReportProgress.tsx       # 报告生成进度 (使用Progress, Badge, Card)
│   ├── TradingViewChart.tsx     # TradingView图表
│   ├── AnalysisModule.tsx       # 分析模块容器 (使用Card, Tabs, Separator)
│   ├── FinancialDataTable.tsx   # 财务数据表格 (使用Table, TableHeader, TableBody, TableRow, TableCell)
│   └── ConfigForm.tsx           # 配置表单 (使用Form, Input, Button, Alert)
├── lib/
│   ├── api.ts                   # API客户端
│   ├── types.ts                 # TypeScript类型定义
│   └── utils.ts                 # 工具函数
└── hooks/
    ├── useReport.ts             # 报告数据钩子
    └── useProgress.ts           # 进度追踪钩子
```

### 后端API结构

```
app/
├── main.py                      # FastAPI应用入口
├── models/
│   ├── __init__.py
│   ├── report.py                # 报告数据模型
│   ├── config.py                # 配置数据模型
│   └── progress.py              # 进度追踪模型
├── schemas/
│   ├── __init__.py
│   ├── report.py                # 报告Pydantic模式
│   ├── config.py                # 配置Pydantic模式
│   └── progress.py              # 进度Pydantic模式
├── services/
│   ├── __init__.py
│   ├── data_fetcher.py          # 数据获取服务
│   ├── ai_analyzer.py           # AI分析服务
│   ├── report_generator.py      # 报告生成服务
│   └── config_manager.py        # 配置管理服务
├── routers/
│   ├── __init__.py
│   ├── reports.py               # 报告相关API
│   ├── config.py                # 配置相关API
│   └── progress.py              # 进度相关API
└── core/
    ├── __init__.py
    ├── database.py              # 数据库连接
    ├── config.py                # 应用配置
    └── dependencies.py          # 依赖注入
```

### 核心API接口

#### 报告相关API

```python
# GET /api/reports/{symbol}?market={market}
# 获取或生成股票报告
class ReportResponse:
    symbol: str
    market: str
    report_id: str
    status: str  # "existing" | "generating" | "completed" | "failed"
    created_at: datetime
    updated_at: datetime
    modules: List[AnalysisModule]

# POST /api/reports/{symbol}/regenerate?market={market}
# 重新生成报告
class RegenerateRequest:
    force: bool = False

# GET /api/reports/{report_id}/progress
# 获取报告生成进度
class ProgressResponse:
    report_id: str
    current_step: int
    total_steps: int
    current_step_name: str
    status: str  # "running" | "completed" | "failed"
    step_timings: List[StepTiming]
    estimated_remaining: Optional[int]
```

#### 配置相关API

```python
# GET /api/config
# 获取系统配置
class ConfigResponse:
    database: DatabaseConfig
    gemini_api: GeminiConfig
    data_sources: Dict[str, DataSourceConfig]

# PUT /api/config
# 更新系统配置
class ConfigUpdateRequest:
    database: Optional[DatabaseConfig]
    gemini_api: Optional[GeminiConfig]
    data_sources: Optional[Dict[str, DataSourceConfig]]

# POST /api/config/test
# 测试配置连接
class ConfigTestRequest:
    config_type: str  # "database" | "gemini" | "data_source"
    config_data: Dict[str, Any]
```

## 数据模型

### 数据库表结构

```sql
-- 报告表
CREATE TABLE reports (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    symbol VARCHAR(20) NOT NULL,
    market VARCHAR(20) NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'generating',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(symbol, market)
);

-- 分析模块表
CREATE TABLE analysis_modules (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    report_id UUID REFERENCES reports(id) ON DELETE CASCADE,
    module_type VARCHAR(50) NOT NULL,
    module_order INTEGER NOT NULL,
    title VARCHAR(200) NOT NULL,
    content JSONB,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    started_at TIMESTAMP WITH TIME ZONE,
    completed_at TIMESTAMP WITH TIME ZONE,
    error_message TEXT
);

-- 进度追踪表
CREATE TABLE progress_tracking (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    report_id UUID REFERENCES reports(id) ON DELETE CASCADE,
    step_name VARCHAR(100) NOT NULL,
    step_order INTEGER NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    started_at TIMESTAMP WITH TIME ZONE,
    completed_at TIMESTAMP WITH TIME ZONE,
    duration_ms INTEGER,
    error_message TEXT
);

-- 系统配置表
CREATE TABLE system_config (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    config_key VARCHAR(100) UNIQUE NOT NULL,
    config_value JSONB NOT NULL,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
```

### 分析模块类型定义

```python
class AnalysisModuleType(Enum):
    TRADING_VIEW_CHART = "trading_view_chart"
    FINANCIAL_DATA = "financial_data"
    BUSINESS_INFO = "business_info"
    FUNDAMENTAL_ANALYSIS = "fundamental_analysis"
    BULLISH_ANALYSIS = "bullish_analysis"
    BEARISH_ANALYSIS = "bearish_analysis"
    MARKET_ANALYSIS = "market_analysis"
    NEWS_ANALYSIS = "news_analysis"
    TRADING_ANALYSIS = "trading_analysis"
    INSIDER_ANALYSIS = "insider_analysis"
    FINAL_CONCLUSION = "final_conclusion"

class AnalysisModule(BaseModel):
    id: UUID
    module_type: AnalysisModuleType
    title: str
    content: Dict[str, Any]
    status: str
    duration_ms: Optional[int]
    error_message: Optional[str]
```

## 错误处理

### 错误类型定义

```python
class StockAnalysisError(Exception):
    """基础异常类"""
    pass

class DataSourceError(StockAnalysisError):
    """数据源错误"""
    pass

class AIAnalysisError(StockAnalysisError):
    """AI分析错误"""
    pass

class ConfigurationError(StockAnalysisError):
    """配置错误"""
    pass

class DatabaseError(StockAnalysisError):
    """数据库错误"""
    pass
```

### 错误处理策略

1. **数据获取失败**: 重试机制，最多3次重试，指数退避
2. **AI分析失败**: 记录错误，继续其他模块，最后汇总失败信息
3. **数据库连接失败**: 使用连接池，自动重连
4. **配置错误**: 提供详细错误信息，阻止系统启动
5. **前端错误**: Toast通知，错误边界组件

## 测试策略

### 测试层级

1. **单元测试**
   - 后端服务函数测试
   - 前端组件测试
   - 数据模型验证测试

2. **集成测试**
   - API端点测试
   - 数据库操作测试
   - 外部服务集成测试

3. **端到端测试**
   - 完整报告生成流程测试
   - 用户界面交互测试

### 测试工具

- **后端**: pytest, pytest-asyncio, httpx
- **前端**: Jest, React Testing Library, Playwright
- **数据库**: pytest-postgresql
- **API测试**: FastAPI TestClient

### 测试数据

- 使用测试数据库和模拟数据
- 外部API使用mock响应
- 测试用例覆盖各种市场和股票类型