# 后端服务拆分设计

版本号：v0.1.0
最后更新：2026-04-04

## 1. 目的

本文档用于定义第一阶段后端服务的拆分方式，明确各服务的职责、边界和协作关系。

## 2. 拆分原则

第一阶段的服务拆分应遵循以下原则：

- 按职责拆分，而不是按技术炫技拆分
- 先保证主链路清晰，再考虑进一步解耦
- 能单体时不强拆，能边界清晰时不混杂

## 3. 第一阶段服务建议

第一阶段建议逻辑上拆为四个核心部分：

1. API 服务
2. AI 编排服务
3. 实验执行服务
4. 模型服务

其中：

- API 服务与 AI 编排服务在第一阶段可以部署在同一 Python 进程或同一应用中
- 模型服务可以独立部署
- 实验执行服务建议独立出来

## 4. API 服务

### 4.1 职责

API 服务负责：

- 接收终端请求
- 鉴权与会话入口
- Observation 创建
- 分析任务创建
- 查询 Experiment 和 Conclusion
- 推送状态变更

### 4.2 不负责

API 服务不负责：

- 直接实现复杂 AI 决策
- 直接运行重型算法链

## 5. AI 编排服务

### 5.1 职责

AI 编排服务负责：

- 汇总当前上下文
- 调用模型
- 生成假设
- 生成实验计划
- 生成阶段性结论和最终结论

### 5.2 输入

- Observation 摘要
- Evidence 列表
- Experiment 历史摘要
- 可用链模板与模块摘要

### 5.3 输出

- `OrchestratorPlan`
- `InterimConclusion`
- `FinalConclusion`

## 6. 实验执行服务

### 6.1 职责

实验执行服务负责：

- 读取实验计划
- 用注册表校验计划
- 调用算法模块
- 收集中间输出
- 生成 `Evidence`
- 生成 `ScoreCard`
- 记录 `failureReasons`

### 6.2 不负责

实验执行服务不负责：

- 解释业务意义
- 直接面向用户输出最终结论

## 7. 模型服务

### 7.1 职责

模型服务负责：

- 托管 Gemma 4
- 提供稳定推理接口
- 统一模型版本和配置

### 7.2 与 AI 编排服务的关系

AI 编排服务是模型服务的调用方。

模型服务不理解实验业务，只负责模型推理。

## 8. 存储层职责

虽然存储层不是“服务”，但它在拆分设计中非常关键。

建议统一保存：

- Observation
- Evidence
- Experiment
- Conclusion
- Session 状态

这样所有服务都围绕同一批核心实体协作，而不是各自维护私有状态。

## 9. 推荐协作流程

推荐第一阶段流程如下：

1. Flutter 终端上传样本
2. API 服务创建 Observation 和分析任务
3. API 服务触发本地或远端初始 probe
4. AI 编排服务读取当前上下文，生成实验计划
5. 实验执行服务执行计划并写回 Experiment/Evidence
6. AI 编排服务继续判断是否进入下一轮
7. 形成 Conclusion
8. API 服务返回给终端

## 10. 第一阶段部署建议

第一阶段建议偏保守部署：

- API 服务 + AI 编排服务：一起部署
- 实验执行服务：独立部署
- 模型服务：独立部署
- PostgreSQL：独立实例

这样可以在保持边界清晰的同时，避免第一阶段服务过多导致运维复杂。

## 11. 后续可扩展方向

当系统成熟后，可进一步扩展：

- 独立任务队列
- 独立调度器
- 多执行 worker
- 多模型路由
- 多模态执行器拆分

但这些不应成为第一阶段前置条件。

## 12. 结论

第一阶段后端服务拆分建议为：

- API 服务
- AI 编排服务
- 实验执行服务
- 模型服务

其中 API 与 AI 编排可暂时合并部署，实验执行与模型服务保持独立，既保证边界清晰，也保持实现可控。