docs/ARCHITECTURE.md

系统架构文档

本文档详细描述了智能股票分析系统的架构设计，旨在为开发人员提供清晰的指导，以便进行后续的维护和功能扩展。

1. 概览

系统采用模块化的分层架构，主要由表现层 (Presentation Layer)、应用层 (Application Layer)、核心逻辑层 (Core Logic Layer) 和 数据层 (Data Layer) 构成。这种设计旨在实现高内聚、低耦合，使系统更易于扩展和维护。

2. 目录结构

/
|-- app/                    # 核心应用代码
|   |-- analysis/           # 分析模块
|   |   |-- stock_analyzer.py
|   |   |-- fundamental_analyzer.py
|   |   |-- ...
|   |-- core/               # 核心组件 (如数据库)
|   |   |-- database.py
|   |-- web/                # Web服务 (Flask)
|   |   |-- web_server.py
|   |   |-- templates/
|   |   |-- static/
|-- configs/                # 配置文件
|-- data/                   # 数据文件 (日志、缓存、数据库)
|-- docs/                   # 项目文档
|-- scripts/                # 脚本 (启动、部署)
|-- tradingagents/          # 智能体交易模块
|-- run.py                  # 应用入口
|-- requirements.txt        # Python依赖
|-- .env                    # 环境变量

3. 分层架构

3.1. 表现层 (Presentation Layer)

• 组件: app/web/templates/ 和 app/web/static/
• 职责: 负责用户界面的渲染和交互。使用 Flask 的模板引擎（Jinja2）动态生成HTML页面，并通过JavaScript、CSS和图像等静态资源提供丰富的用户体验。

3.2. 应用层 (Application Layer)

• 组件: app/web/web_server.py, run.py
• 职责: 作为系统的入口，处理HTTP请求和响应。
  • web_server.py: 定义了所有API端点和Web路由。它负责解析用户请求，调用核心逻辑层的服务，并将结果返回给表现层。
  • run.py: 应用的启动脚本，负责初始化和运行Flask服务。

3.3. 核心逻辑层 (Core Logic Layer)

• 组件: app/analysis/, app/core/, tradingagents/
• 职责: 实现系统的核心业务逻辑，包括数据分析、模型计算和第三方服务集成。
  • app/analysis/: 包含多个独立的分析模块，每个模块负责一个特定的分析领域（如技术分析、基本面分析、资金流分析等）。这种设计使得每个分析功能都可以独立开发和测试。
  • app/core/: 提供核心共享组件，例如数据库连接和会话管理 (database.py)。
  • tradingagents/: 一个独立的模块，用于实现更复杂的智能体分析功能。

3.4. 数据层 (Data Layer)

• 组件: data/, akshare (第三方库)
• 职责: 负责数据的持久化存储和访问。
  • data/: 存储应用的持久化数据，包括：
    • stock_analyzer.db: SQLite数据库文件。
    • logs/: 应用日志。
    • news/: 缓存的新闻数据。
  • akshare: 作为主要的数据源，提供股票市场数据。

4. 关键流程

4.1. 应用启动流程

1. 用户执行 scripts/start.sh 脚本。
2. 脚本运行 run.py。
3. run.py 导入并启动 app/web/web_server.py 中的Flask应用。
4. Flask应用初始化所有路由和核心服务。

4.2. 用户请求处理流程 (以股票分析为例)

1. 用户在前端页面提交股票分析请求。
2. JavaScript将请求发送到 web_server.py 中定义的API端点 (例如 /api/start_stock_analysis)。
3. web_server.py 接收请求，并调用 app/analysis/stock_analyzer.py 中的分析方法。
4. stock_analyzer.py 通过 akshare 获取数据，进行计算和分析。
5. 分析结果返回给 web_server.py。
6. web_server.py 将结果格式化为JSON，并返回给前端。
7. 前端JavaScript接收到JSON数据，并动态更新页面内容。

5. 设计原则

• 模块化: 将系统划分为多个独立的模块，每个模块都有明确的职责。
• 分层: 通过分层架构，将UI、业务逻辑和数据访问分离。
• 可扩展性: 易于添加新的分析模块或更换数据源，而无需修改系统的核心结构。
• 可维护性: 清晰的代码结构和文档，便于开发者理解和维护。