reorg docs

docs/2_architecture/20251116_[Active]_system_architecture.md

@@ -0,0 +1,159 @@
+---
+status: 'Active'
+created: '2025-11-16'
+last_updated: '2025-11-16'
+owner: '@lv'
+---
+
+# 系统架构设计总览
+
+## 1. 引言
+
+### 1.1. 文档目的
+
+本文档旨在为“基本面选股系统”的事件驱动微服务架构，提供一份统一的、作为“单一事实源”的核心技术蓝图。它整合并取代了多个历史设计文档，旨在清晰、准确地描述当前系统的核心架构理念、服务职责、关键设计以及数据模型。
+
+### 1.2. 核心架构理念
+
+本系统采用纯 Rust 构建的现代化微服务架构，其核心理念根植于“Rustic”风格的健壮性与确定性，遵循以下原则：
+
+- **服务独立化**: 每个外部数据源、每个核心业务能力都被封装成独立的、可独立部署和运行的微服务。
+- **事件驱动**: 引入消息总线（Message Bus）作为服务间通信的主干，实现服务的高度解耦和异步协作。
+- **数据中心化**: 所有微服务将标准化的数据写入一个由 `data-persistence-service` 独占管理的中央数据库，实现“数据写入即共享”。
+- **契约先行**: 所有服务间的通信与数据模型，均通过 `common-contracts` 共享库进行强类型约束，确保系统的一致性与稳定性。
+
+## 2. 架构图与服务职责
+
+### 2.1. 目标架构图
+
+```
++-------------+      +------------------+      +---------------------------+
+|             | HTTP |                  |      |                           |
+|  前端        |----->|   API 网关        |----->|      消息总线             |
+|  (Next.js)  |      |     (Rust)       |      | (例如 RabbitMQ, NATS)    |
+|             |      |                  |      |                           |
++-------------+      +-------+----------+      +-------------+-------------+
+                             |                                |
+        (读操作)             |                                | (发布/订阅 命令与事件)
+                             |                                |
+           +-----------------v------------------+      +------v------+  +----------------+
+           |                                    |      | 数据提供商A |  | 数据提供商B |
+           |   数据持久化服务 (Rust)              |<---->| (Tushare)   |  | (Finnhub)      |
+           |                                    |      | 服务 (Rust) |  | 服务 (Rust)    |
+           +-----------------+------------------+      +-------------+  +----------------+
+                             |
+                             v
++-----------------------------------------------------+
+|                                                     |
+|                PostgreSQL 数据库                  |
+|                                                     |
++-----------------------------------------------------+
+```
+
+### 2.2. 服务职责划分
+
+- **API 网关 (api-gateway)**:
+    - 面向前端的唯一入口 (BFF)。
+    - 负责用户请求、认证鉴权。
+    - 将前端的查询请求，转化为对**数据持久化服务**的数据读取调用。
+    - 将前端的操作请求（如“生成新报告”），转化为命令（Command）并发布到**消息总线**。
+
+- **数据提供商服务 (`*_provider-service`)**:
+    - 一组独立的微服务，每个服务对应一个外部数据 API。
+    - 订阅消息总线上的相关命令（如 `FetchFinancialsRequest`）。
+    - 独立调用外部 API，对返回数据进行清洗、标准化。
+    - 调用**数据持久化服务**的接口，将标准化后的数据写入数据库。
+
+- **数据持久化服务 (data-persistence-service)**:
+    - 数据库的**唯一守门人**，是整个系统中唯一有权直接与数据库交互的服务。
+    - 为所有其他内部微服务提供稳定、统一的数据库读写 HTTP 接口。
+
+- **消息总线 (Message Bus)**:
+    - 整个系统的神经中枢，负责所有服务间的异步通信。
+
+## 3. `SystemModule` 核心规范
+
+为确保所有微服务行为一致、可观测、易于管理，我们定义了一套名为 `SystemModule` 的设计规范。它并非真实的 Rust Trait，而是一个所有服务都必须遵守的**行为契约**。
+
+**每个微服务都必须：**
+
+1.  **容器化**: 提供一个 `Dockerfile` 用于部署。
+2.  **配置驱动**: 从环境变量或配置服务中读取配置，缺少必要配置必须启动失败。
+3.  **消息契约**: 严格按照 `common-contracts` 中定义的契约进行消息的订阅和发布。
+4.  **暴露标准接口**: 实现一个内置的 HTTP 服务器，并暴露**两个强制性的 API 端点**：
+    -   `GET /health`: 返回服务的健康状态。
+    -   `GET /tasks`: 返回服务当前正在处理的所有任务列表及其进度。
+
+## 4. 关键服务设计：数据持久化服务
+
+- **核心定位**: 整个微服务架构中**唯一的数据持久化层**。
+- **职责边界**: 严格限定在管理跨多个业务领域共享的**核心数据实体**上（如公司信息、财务数据、市场数据、AI分析结果）。
+- **API 端点摘要**:
+    | Method | Endpoint | 描述 |
+    | :--- | :--- | :--- |
+    | `PUT` | `/api/v1/companies` | 创建或更新公司基本信息 |
+    | `GET` | `/api/v1/companies/{symbol}` | 获取公司基本信息 |
+    | `POST` | `/api/v1/market-data/financials/batch` | 批量写入时间序列财务指标 |
+    | `GET` | `/api/v1/market-data/financials/{symbol}` | 查询财务指标 |
+    | `POST` | `/api/v1/analysis-results` | 保存一条新的 AI 分析结果 |
+    | `GET` | `/api/v1/analysis-results` | 查询分析结果列表 |
+
+## 5. 数据库 Schema 设计
+
+### 5.1. 设计哲学
+
+采用**“为不同形态的数据建立专属的、高度优化的持久化方案”**的核心哲学，统一使用 **PostgreSQL** 及其扩展生态。
+
+- **时间序列数据**: 明确采用 **TimescaleDB** 扩展，通过 Hypertables 机制保障高性能的写入与查询。
+- **其他数据**: 使用标准的关系表进行存储。
+
+### 5.2. 核心表结构
+
+#### `time_series_financials` (财务指标表 - TimescaleDB)
+```sql
+CREATE TABLE time_series_financials (
+    symbol VARCHAR(32) NOT NULL,
+    metric_name VARCHAR(64) NOT NULL,
+    period_date DATE NOT NULL,
+    value NUMERIC NOT NULL,
+    source VARCHAR(64),
+    PRIMARY KEY (symbol, metric_name, period_date)
+);
+SELECT create_hypertable('time_series_financials', 'period_date');
+```
+
+#### `daily_market_data` (每日市场数据表 - TimescaleDB)
+```sql
+CREATE TABLE daily_market_data (
+    symbol VARCHAR(32) NOT NULL,
+    trade_date DATE NOT NULL,
+    open_price NUMERIC,
+    close_price NUMERIC,
+    volume BIGINT,
+    total_mv NUMERIC,
+    PRIMARY KEY (symbol, trade_date)
+);
+SELECT create_hypertable('daily_market_data', 'trade_date');
+```
+
+#### `analysis_results` (AI分析结果表)
+```sql
+CREATE TABLE analysis_results (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    symbol VARCHAR(32) NOT NULL,
+    module_id VARCHAR(64) NOT NULL,
+    generated_at TIMESTAMTz NOT NULL DEFAULT NOW(),
+    content TEXT NOT NULL,
+    meta_data JSONB
+);
+```
+
+#### `company_profiles` (公司基本信息表)
+```sql
+CREATE TABLE company_profiles (
+    symbol VARCHAR(32) PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    industry VARCHAR(255),
+    list_date DATE
+);
+```