xucheng 91f701139f Initial commit: Fundamental stock analysis project setup

2025-10-20 15:20:32 +08:00

9.7 KiB

Raw Blame History

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

概览

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

架构

系统架构图

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

# 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

# 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]

数据模型

数据库表结构

-- 报告表
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()
);

分析模块类型定义

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]

错误处理

错误类型定义

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

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

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

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

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

错误处理策略

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

测试策略

测试层级

单元测试
- 后端服务函数测试
- 前端组件测试
- 数据模型验证测试
集成测试
- API端点测试
- 数据库操作测试
- 外部服务集成测试
端到端测试
- 完整报告生成流程测试
- 用户界面交互测试

测试工具

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

测试数据

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

9.7 KiB Raw Blame History Unescape Escape