# Spec: Cross 模式统计报告

**创建时间:** 2026-03-09 14:38
**状态:** approved
**分支:** feature/cross-stats
**来源:** Cross-Debate

---

## 概述

给 dev-workflow 添加统计报告功能，显示 Cross 模式（Cross-Debate + Cross-Review）的使用情况。

---

## 背景

Cross 模式是 dev-workflow 的核心功能，需要了解其使用情况：
- 调用频率
- 成功率
- 常见场景
- 问题分布

---

## Cross-Debate 统一方案

### 共识

三个 Agent（保守派、全面派、快速派）经过交叉审查后达成共识：

> **"快速不等于简陋，结构化 + 缓存 + 权限是底线"**

### 渐进式架构

#### 短期（MVP）
```
日志埋点 → 结构化 JSON 存储 → Redis 缓存（TTL 5分钟）
```

#### 中期（加固）
```
Grafana 可视化 + 权限隔离（API 层最小校验）
```

#### 长期（完善）
```
数据脱敏 + 告警通知 + 定期归档
```

---

## 需求

### 功能需求

- [ ] **REQ-01**: 记录 Cross-Debate 调用事件（时间、场景、Agent 参与情况）
- [ ] **REQ-02**: 记录 Cross-Review 调用事件（时间、轮次、问题数量）
- [ ] **REQ-03**: 统计报告命令：`python3 dev_workflow.py stats`
- [ ] **REQ-04**: 输出格式：JSON + Markdown
- [ ] **REQ-05**: 统计维度：日/周/月、按场景、按成功率

### 非功能需求

- 性能：查询响应 < 100ms（通过 Redis 缓存）
- 安全：API 层最小权限校验
- 兼容：不破坏现有 dev_workflow.py 接口

---

## 技术设计

### 数据结构

```json
{
  "cross_events": [
    {
      "timestamp": "2026-03-09T14:38:00Z",
      "type": "debate" | "review",
      "scenario": "功能设计" | "Bug修复" | "重构",
      "agents": ["claude-code", "codex", "gemini"],
      "duration_ms": 45000,
      "status": "success" | "failed",
      "issues_found": 3,
      "rounds": 2
    }
  ]
}
```

### 文件结构

```
dev-workflow/
├── dev_workflow.py      # 添加 stats 命令
├── stats.py             # 新增：统计逻辑
└── .data/
    └── cross_events.json  # 事件存储
```

### 实现步骤

1. 添加 `record_event()` 函数记录事件
2. 在 Cross-Debate 和 Cross-Review 流程中埋点
3. 实现 `stats` 命令输出报告
4. 添加 Redis 缓存（可选）

### 依赖

- 无新增外部依赖
- 可选：Redis（用于缓存）

---

## 测试计划

### 单元测试

- [ ] `record_event()` 正常记录
- [ ] `record_event()` 异常处理
- [ ] `get_stats()` 空数据返回
- [ ] `get_stats()` 正常统计

### 集成测试

- [ ] 完整 Cross-Debate 流程后查看统计
- [ ] 完整 Cross-Review 流程后查看统计

---

## 验收标准

1. 执行 `python3 dev_workflow.py stats` 输出统计报告
2. 报告包含：总调用次数、成功率、Top 5 场景
3. 数据持久化到 JSON 文件
4. 不影响现有功能

---

## 风险与缓解

| 风险 | 缓解措施 |
|------|----------|
| 并发写入冲突 | 使用文件锁或队列 |
| 存储增长 | 定期归档旧数据 |
| 敏感信息泄露 | 不记录用户输入内容 |

---

## 变更日志

| 日期 | 变更 |
|------|------|
| 2026-03-09 14:38 | 初始创建（来自 Cross-Debate 共识） |