# 多 Agent 协同架构

本项目采用 4 个专业 Agent 协同工作,各司其职。

## Agent 职责

### 🗄️ 数据库 Agent (DBA)
**所有权:** `src/db/`, `alembic/`, 数据模型

职责:
- 数据库 schema 设计与迁移 (Alembic)
- ORM 模型定义与关系
- 查询性能优化与索引
- 数据完整性约束
- 数据源入库逻辑

边界:
- 不写业务路由
- 不写前端代码
- 对外暴露稳定的模型接口

---

### 🖥️ 前端 Agent (FE)
**所有权:** `frontend/`

职责:
- React 组件与页面
- 用户界面与交互
- 状态管理
- API 调用与数据展示
- 样式 (Tailwind)

边界:
- 不直接操作数据库
- 不写后端业务逻辑
- 通过 REST API 与后端通信

---

### ⚙️ 后端 Agent (BE)
**所有权:** `src/api/`, `src/core/`, `src/llm/`, `src/data/`

职责:
- API 路由与业务逻辑
- LLM 预测管线 (上下文构建 → 调用 → 存储)
- 数据采集与清洗
- 定时任务调度
- 多 Agent 编排 (LLM 专家系统)

边界:
- 不写前端展示
- 不直接配置部署环境
- 对外暴露 REST API

---

### 🚀 部署 Agent (Ops)
**所有权:** `Dockerfile`, `docker-compose.yml`, `.env.example`, 配置

职责:
- 容器化与编排
- 环境变量与配置管理
- 服务健康检查
- 日志与监控
- 备份策略

边界:
- 不写应用代码
- 不修改业务逻辑
- 通过配置文件影响行为

---

## 协作接口

### FE ↔ BE
```
REST API (OpenAPI 契约)
- GET  /api/v1/matches
- POST /api/v1/predict
- GET  /api/v1/predictions
- POST /api/v1/eval/settle
- GET  /api/v1/backtest
```

### BE ↔ DBA
```
SQLAlchemy 模型接口
- Match, Team, League, MatchStats, Prediction, Injury
- AsyncSession 依赖注入
```

### BE ↔ LLM
```
LLMProvider 抽象
- OpenAI / Deepseek / Ollama / 任意兼容网关
- JSON mode 结构化输出
```

### Ops ↔ 所有
```
环境变量 + docker-compose
- .env 配置注入
- 服务发现 (localhost:8000 / 5432)
```

---

## 工作流程

```
1. 用户/编排者 发起任务
2. 拆解任务分配给对应 Agent
3. Agent 在各自所有权范围内工作
4. 跨 Agent 变更通过接口契约协调
5. 集成测试验证协作
```

## 变更协调规则

| 变更类型 | 需要协调 |
|---|---|
| 新增 API 字段 | BE + FE |
| 修改数据模型 | DBA + BE + FE |
| 新增数据源 | DBA + BE |
| 修改部署配置 | Ops + 所有 |
| 修改 LLM Prompt | BE (独立) |