JARVIS/development-doc/plan/war-room-update/phase-wr-3-data-contract-and-api.md

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 共识

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[]
}

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

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 无法完成。