# 微服务架构重构计划

## 1. 引言

### 1.1. 文档目的

本文档旨在为“基本面选股系统”从单体架构向微服务架构的演进提供一个全面的设计蓝图和分阶段的实施路线图。它将详细阐述目标架构、服务划分、技术栈选型以及具体的迁移步骤，作为后续开发工作的核心指导文件。

### 1.2. 重构目标与收益

当前系统采用的是经典的前后端分离的单体架构。为了应对未来更复杂的需求、提升系统的可维护性、可扩展性并实现关键模块的独立部署与扩缩容，我们决定将其重构为微服务架构。

主要收益包括：
- **高内聚、低耦合**: 每个服务只关注单一业务职责，易于理解和维护。
- **独立部署与交付**: 可以对单个服务进行修改、测试和部署，而不影响整个系统，加快迭代速度。
- **技术异构性**: 未来可以为不同的服务选择最适合的技术栈。
- **弹性伸缩**: 可以根据负载情况，对高负荷的服务（如AI分析服务）进行独立扩容。
- **故障隔离**: 单个服务的故障不会导致整个系统崩溃。

## 2. 目标架构设计

我们将采用以 `API网关` 为核心的微服务架构模式。前端应用将通过网关与后端一系列独立的微服务进行通信。

![Microservices Architecture Diagram](https://i.imgur.com/gK98h83.png)

### 2.1. 服务划分 (Service Breakdown)

现有的后端应用将被拆分为以下几个核心微服务：

| 服务名称 | 容器名 (`docker-compose`) | 核心职责 |
| :--- | :--- | :--- |
| **前端应用** | `frontend-web` | **(保持不变)** Next.js UI，负责用户交互。 |
| **API网关** | `api-gateway` | **(新增)** 系统统一入口。负责请求路由、认证、限流、日志聚合。将前端请求转发到正确的内部服务。 |
| **报告编排器** | `report-orchestrator` | **(由原后端演变)** 负责报告生成的业务工作流。接收请求，调用数据、分析等服务，编排整个流程。 |
| **数据聚合服务**| `data-aggregator` | **(新增)** 封装所有对第三方数据源（Tushare, Finnhub等）的API调用，并提供统一的数据接口，内置缓存逻辑。 |
| **AI分析服务** | `analysis-service` | **(新增)** 专门负责与大语言模型（Gemini）交互。将其独立出来便于未来单独扩容或部署到GPU服务器。 |
| **配置服务** | `config-service` | **(新增)** 集中管理并提供所有动态配置（API密钥、Prompt模板等），实现配置的动态更新与统一管理。 |
| **数据库** | `postgres-db` | **(保持不变)** 独立的PostgreSQL数据库容器，为所有服务提供持久化存储。 |

### 2.2. 技术栈与开发环境

- **容器化**: `Docker`
- **服务编排**: `Docker Compose`
- **开发环境管理**: `Tilt`
- **服务间通信**: 同步通信采用轻量级的 `RESTful API (HTTP)`。对于长任务，未来可引入 `RabbitMQ` 或 `Redis Stream` 等消息队列实现异步通信。

### 2.3. 项目根目录清洁化 (Root Directory Cleanup)

根据约定，项目根目录应保持整洁，只存放与整个项目和微服务编排直接相关的顶级文件和目录。所有业务代码、独立应用的配置和脚本工具都应被归纳到合适的子目录中。

- **`services/` 目录**: 所有微服务（包括 `frontend` 和 `backend`）的代码都将迁移至此目录下。
- **`deployment/` 目录**: 用于存放与生产环境部署相关的配置文件（例如，`pm2.config.js`）。
- **`scripts/` 目录**: 用于存放各类开发、构建、工具类脚本（例如，`dev.py`, 根目录的 `package.json` 等）。
- **`.gitignore`**: 应添加规则以忽略开发者个人工具和二进制文件（例如，`portwardenc-amd64`）。

## 3. 分阶段实施计划

我们将采用增量、迭代的方式进行重构，确保每一步都是可验证、低风险的。

### 阶段 0: 容器化现有单体应用

**目标**: 在不修改任何业务代码的前提下，将现有的 `frontend` 和 `backend` 应用容器化，并使用 `docker-compose` 和 `Tilt` 运行起来。这是验证容器化环境和开发流程的第一步。

**任务**:
1.  在项目根目录创建 `docker-compose.yml` 文件，定义 `frontend`, `backend`, `postgres-db` 三个服务。
2.  分别为 `frontend` 和 `backend` 目录创建 `Dockerfile`。
3.  在项目根目录创建 `Tiltfile`，并配置其加载 `docker-compose.yml`。
4.  调整配置文件（如 `NEXT_PUBLIC_BACKEND_URL` 和 `DATABASE_URL` 环境变量），使其适应Docker内部网络。
5.  **验证**: 运行 `tilt up`，整个应用能够像在本地一样正常启动和访问。

---

### 阶段 1: 拆分配置服务 (`config-service`)

**目标**: 将配置管理逻辑从主后端中剥离，创建第一个真正的微服务。这是一个理想的起点，因为它依赖项少，风险低。

**任务**:
1.  创建新目录 `services/config-service`。
2.  在该目录中初始化一个新的、轻量级的FastAPI应用。
3.  将原 `backend` 中所有读取 `config/` 目录文件的逻辑（如 `ConfigManager`) 迁移至 `config-service`。
4.  在 `config-service` 中暴露API端点，例如 `GET /api/v1/system`, `GET /api/v1/analysis-modules`。
5.  在 `docker-compose.yml` 中新增 `config-service` 的定义。
6.  修改原 `backend` 应用，移除本地文件读取逻辑，改为通过HTTP请求从 `config-service` 获取配置。

---

### 阶段 2: 拆分数据聚合服务 (`data-aggregator`)

**目标**: 将所有与外部数据源的交互逻辑隔离出来。

**任务**:
1.  创建新目录 `services/data-aggregator`。
2.  将原 `backend/app/data_providers` 目录及相关的数据获取和处理逻辑整体迁移到新服务中。
3.  为新服务定义清晰的API，例如 `GET /api/v1/financials/{symbol}`。
4.  在 `docker-compose.yml` 中新增 `data-aggregator` 服务的定义。
5.  修改原 `backend` 应用，将调用本地数据模块改为通过HTTP请求调用 `data-aggregator` 服务。

---

### 阶段 3: 拆分AI分析服务 (`analysis-service`)

**目标**: 隔离计算密集型且可能需要特殊硬件资源的AI调用逻辑。

**任务**:
1.  创建新目录 `services/analysis-service`。
2.  将原 `backend/app/services/analysis_client.py` 及相关的Gemini API调用逻辑迁移到新服务中。
3.  定义API，例如 `POST /api/v1/analyze`，接收上下文数据和prompt，返回分析结果。
4.  在 `docker-compose.yml` 中新增 `analysis-service` 的定义。
5.  修改原 `backend` 应用，将直接调用SDK改为通过HTTP请求调用 `analysis-service`。

---

### 阶段 4: 引入API网关 (`api-gateway`) 并重塑编排器

**目标**: 建立统一的外部入口，并正式将原 `backend` 的角色明确为 `report-orchestrator`。

**任务**:
1.  创建新目录 `services/api-gateway`，并初始化一个FastAPI应用。
2.  在 `api-gateway` 中配置路由规则，将来自前端的请求（如 `/api/config/*`, `/api/financials/*`）代理到对应的内部微服务 (`config-service`, `report-orchestrator` 等)。
3.  更新 `docker-compose.yml`，将前端端口暴露给主机，而其他后端服务仅在内部网络可达。
4.  修改 `frontend` 的 `NEXT_PUBLIC_BACKEND_URL` 指向 `api-gateway`。
5.  此时，原 `backend` 的代码已经精简，主要剩下编排逻辑。我们可以考虑将其目录重命名为 `services/report-orchestrator`，以准确反映其职责。

## 4. 最终项目目录结构（设想）

重构完成后，项目目录结构将演变为：

```
/home/lv/nvm/works/Fundamental_Analysis/
├── docker-compose.yml
├── Tiltfile
├── README.md
├── .gitignore
├── services/
│   ├── frontend/
│   │   └── Dockerfile
│   ├── api-gateway/
│   │   ├── app/
│   │   └── Dockerfile
│   ├── config-service/
│   │   ├── app/
│   │   └── Dockerfile
│   ├── data-aggregator/
│   │   ├── app/
│   │   └── Dockerfile
│   ├── analysis-service/
│   │   ├── app/
│   │   └── Dockerfile
│   └── report-orchestrator/  # 由原 backend 演变而来
│       ├── app/
│       └── Dockerfile
├── deployment/
│   └── pm2.config.js
├── scripts/
│   ├── dev.py
│   └── package.json          # 原根目录的 package.json
├── config/                   # 静态配置文件，由 config-service 读取
└── docs/
    └── microservice_refactoring_plan.md
```

## 5. 结论

本计划提供了一个从单体到微服务的清晰、可行的演进路径。通过分阶段、增量式的重构，我们可以平稳地完成架构升级，同时确保在每个阶段结束后，系统都处于可工作、可验证的状态。

请您审阅此计划。如有任何疑问或建议，我们可以随时讨论和调整。