# WR-3 数据契约与 API 集成

## 目标

把 `war-room` 从本地草稿和 mock 数据过渡到真实数据契约，完成前后端 API、页面状态和测试的基础闭环。

## 范围

1. 设计并实现模板、编排、群组三组接口。
2. 建立前端 `warRoom.ts` API 层。
3. 接入 Pinia 或 composable 的异步数据流。
4. 去除页面核心 mock 数据。

## API 规划

### 1. Agent Templates

优先对齐 spec：
- `GET /api/agents/templates`
- `GET /api/agents/templates/:id`

说明：
- 可以挂在现有 `agent.py`，但只承载模板读取，不混入运行态编辑逻辑。

### 2. Orchestrations

建议新增路由：
- `GET /api/orchestrations`
- `POST /api/orchestrations`
- `PUT /api/orchestrations/:id`
- `DELETE /api/orchestrations/:id`

### 3. Teams

建议新增路由：
- `GET /api/teams`
- `POST /api/teams`
- `PUT /api/teams/:id`
- `DELETE /api/teams/:id`

## 数据结构建议

### Frontend / Backend 共识

```ts
interface AgentTemplate {
  id: string
  name: string
  type: 'schedule' | 'knowledge' | 'bookkeeping' | 'dispatch'
  kicker: string
  icon: string
  tone: 'cyan' | 'amber' | 'green' | 'violet'
  summary: string
  stats: string[]
  flow: string[]
}
```

```ts
interface Orchestration {
  id: string
  name: string
  nodes: FlowNode[]
  edges: FlowEdge[]
  source_template_id?: string | null
  updated_at: string
}
```

```ts
interface TeamSummary {
  id: string
  name: string
  protocol: 'leader-led' | 'pipeline' | 'roundtable'
  member_count: number
  focus: string
}
```

## 建议文件变更

### Backend

- 新增 `backend/app/routers/orchestration.py`
- 新增 `backend/app/routers/team.py`
- 新增 `backend/app/schemas/war_room.py`
- 视情况新增 `backend/app/services/war_room/`
- 修改 `backend/app/main.py` 注册路由

### Frontend

- 新增 `frontend/src/api/warRoom.ts`
- 扩展 `useWarRoomPage.ts`
- 让 FIXED / STUDIO / TEAMS 从 API 读数据

## 验收标准

1. `/war-room` 首屏不再依赖硬编码模板与团队数据。
2. orchestration 草稿可以创建、读取、更新。
3. TEAMS 模式能读取真实列表。
4. 数据加载、空态、错误态都可见。

## 测试要求

### Backend

- router 单测
- schema 序列化校验
- create/update/delete 流程测试

### Frontend

- API mock 测试
- 页面加载状态测试
- 保存 orchestration 行为测试

## 前置决策

WR-3 结束前必须明确 `/chat` 接口需要的最小执行 payload，否则 WR-4 无法完成。