351 lines
9.7 KiB
Markdown
351 lines
9.7 KiB
Markdown
# 设计文档 - 基本面选股系统
|
||
|
||
## 概览
|
||
|
||
基本面选股系统是一个全栈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响应
|
||
- 测试用例覆盖各种市场和股票类型 |