# Agent 角色与职责

> 描述 AI agent 在本项目里的角色定位与职责边界。协作进度由人把控，本文不立工作流规矩。
> 本文由原 05（协作准则，已砍掉技术栈/铁律/CI/工作流）与原 06（subagent 角色分工）合并而来。

| 项 | 内容 |
|----|------|
| 文档版本 | v1.0 |
| 文档状态 | 待评审 |
| 更新日期 | 2026-06-21 |

## 修订记录

| 版本 | 日期 | 修订内容 |
|------|------|----------|
| v1.0 | 2026-06-21 | 初版：合并原 05 与 06 |

---

## 1. 项目背景

内部数据平台,MVP 先交付拼团漏斗一个可用模块,其余能力域占位"待开发"。完整需求见 `docs/01-产品需求`。

## 2. 角色模型

- **主会话（orchestrator，人主导）**：拆任务、定契约、做集成与评审，是协作的把控者。
- **AI agent（实现执行者）**：接受需求与方案，产出代码、文档、SQL 等具体产物。

具体实现按目录边界委派给两个 **subagent**：**前端 agent**（在 `apps/web/`）、**后端 agent**（在 `apps/api/`）。按目录分两个 subagent，各自上下文干净、互不越界，主会话只在契约与集成处介入。

## 3. Agent 总体职责范围

- 按既定的产品需求（`docs/01`）、技术架构（`docs/02`）、数据契约（`docs/03`）、设计规范（`docs/04`）做实现。
- **导航信息架构(模块与层级,L1/L2/L3)以 `docs/01` §2 为准**;视觉/交互定稿以 `docs/04` 为准。
- 跟随既定技术栈，不擅自更换；新增依赖前先与人确认。
- 不清楚的事实以代码与 `docs/` 为准，查不到先问，不臆测。
- 严格的"做"与"不做"边界以 `docs/01` §7"明确不做"为准。

## 4. Agent 不负责

- **不负责协作进度安排、需求决策、架构定型** —— 由人（主会话）把控。
- 不擅自扩大需求范围、不"顺手优化"周边、不替假想场景写防御性代码。
- 不替用户拍板未决议事项（鉴权方案、事件清单等），见 `docs/01` §10。

## 5. 前端 agent

- **目录**：只在 `apps/web/`。
- **技术**：React 19 + Vite + TypeScript + **shadcn/ui + Tailwind v4** + ECharts(漏斗图)+ TanStack Query。
- **职责**：
  - 平台导航/布局壳,五个 L1 能力域进导航(见 `docs/01` §2)。
  - 拼团漏斗模块:时间控件(单日 / 近 7 天 / 近 30 天,单日带历史日历)、ECharts 漏斗图、结果表格、空/错误状态。
  - 其余域:"待开发"占位页(复用同一占位组件)。
  - 前端校验:单日上限昨日、今天/未来不可选(T+1)。
  - 调用后端 `POST /api/funnels/query`,消费 UV/转化率/流失率/`data_status`。
- **不碰**：后端代码、数据契约的服务端实现。
- **产出**：可运行前端 + 组件；契约未就绪时用 **mock 响应** 对齐字段并行开发。
- **测试**：周期选择、单日历史/今天不可选、图表渲染、表格渲染、`missing`/错误状态。

## 6. 后端 agent

- **目录**：只在 `apps/api/`。
- **技术**：FastAPI + Pydantic v2 + SQLAlchemy(async)。
- **职责**：
  - 提供 `POST /api/funnels/query`。
  - 校验 `period`(枚举)与 `snapshot_dt`(仅单日有效、上限昨日、今天/未来拒绝)。
  - 从 PostgreSQL 读**预聚合两表**(`ads_trd_group_funnel_daily` / `_rolling`,见 `docs/03` §11):单日取 daily 行、近 7/30 天取 rolling 行的对应列;**不读 bitmap、不做 OR、不跨天聚合**。
  - 返回每层 UV、相邻转化率/流失率、`data_status`(`ready`/`missing`)。
- **不碰**：前端代码、埋点明细存储、数仓侧产出逻辑（只消费 `docs/03` 约定的表）。
- **产出**：可运行 API + 单测；真数据未就绪时基于 **seed 假数据** 开发(`USE_FAKE_DATA` 兜底)。
- **测试**：`period` 校验、单日(最新/指定/不存在/今天拒绝)、近 7/30 天取列、转化率(第 1 层 null)、`data_status` 两态。

## 7. 契约交接点

两角色唯一耦合在接口契约：

- **唯一来源**：`docs/02-技术架构` §5 的请求/响应字段。
- **并行机制**：前端按契约 mock、后端按契约 + seed 实现，各自先跑通，再联调。
- **改契约协议**：任一侧需要改字段，先改 `docs/02` 并同步对端，不在代码里单方面偏离。
- **数据状态**：`ready` / `missing` 由后端判定并返回，前端按状态渲染，**两侧都不静默补零**。

## 8. 主会话职责（不下放给 agent）

- 任务拆分与排期、契约定义与变更裁决。
- 跨端集成与联调、端到端验收（对照 `docs/01` §8）。
- 代码评审、依赖增减裁决（新依赖按 `docs/02` §1 技术栈把关）。

## 9. 委派纪律

- 一个 subagent 只在自己的目录内改动；跨目录需求回主会话重新拆分。
- 委派任务时带齐：目标、相关契约/文档、验证点。
- subagent 返回后，主会话核对产出是否落在边界内、是否满足验证点，再决定集成。