# 规范-性能基准

> **位置**: `docs/开发规范/规范-性能基准.md`
> **版本**: v1.0
> **日期**: 2026-07-08
> **关联**: AGENTS.md、TDD-01（服务端架构）、GDD-03（战斗系统）、GDD-21（数值平衡）

---

## 1. 性能红线

以下指标为 **不可突破的红线**，超过即视为事故：

| 指标 | 红线 | 监控方式 | 告警阈值 |
|------|------|----------|----------|
| 战斗结算（单场） | < 50ms | 服务端打点 | > 50ms 告警，> 100ms 事故 |
| API 响应（P95） | < 200ms | Nakama 内置监控 | > 200ms 告警，> 500ms 事故 |
| 登录流程（端到端） | < 3s | 客户端打点 | > 3s 告警，> 10s 事故 |
| 战报渲染 | 60fps | 客户端性能监控 | < 30fps 告警 |
| 数据库查询（单条） | < 100ms | PostgreSQL slow log | > 100ms 告警，> 500ms 事故 |
| 热更下载（百兆网络） | < 10s | CDN 监控 | > 10s 告警 |
| 内存泄漏 | 0 | 服务端内存监控 | 连续 24h 内存增长 > 10% 告警 |

### 1.1 事故定义

- **P0 事故**：性能红线被突破，影响玩家体验（如战斗卡顿、登录超时）
- **处理流程**：立即回滚/热修 → 事故复盘 → 预防措施

---

## 2. 性能监控

### 2.1 服务端监控

| 监控项 | 工具 | 频率 |
|--------|------|------|
| API 延迟分布 | Nakama 内置 + Prometheus | 实时 |
| 战斗结算耗时 | 自定义打点 | 实时 |
| DB 慢查询 | PostgreSQL pg_stat_statements | 每小时 |
| 内存/CPU/连接数 | Node exporter + Grafana | 实时 |
| 异常/error 日志 | ELK / Loki | 实时 |

### 2.2 客户端监控

| 监控项 | 方式 | 频率 |
|--------|------|------|
| FPS | Cocos 内置 stats | 实时 |
| 内存占用 | 系统 API | 每 5 秒 |
| 网络延迟 | Ping 服务端 | 每 30 秒 |
| 崩溃率 | 崩溃上报 | 实时 |
| 卡顿帧数 | 帧时间 > 33ms 计数 | 实时 |

### 2.3 性能报告

- **日报**：关键指标汇总（平均延迟、P95、错误率、崩溃率）
- **周报**：趋势分析，识别性能退化
- **月报**：容量规划，预测是否需要扩容

---

## 3. 性能优化原则

| 原则 | 说明 |
|------|------|
| 延迟优先于吞吐量 | 玩家体感延迟比 QPS 更重要 |
| 预计算 > 实时计算 | 能离线算的不在线算 |
| 缓存 > 查询 | 热点数据走 Redis/Valkey |
| 批量 > 单条 | 数据库操作尽量批量 |
| 异步 > 同步 | 非关键路径走消息队列 |

---

## 4. 性能测试要求

| 测试类型 | 频率 | 环境 |
|----------|------|------|
| 单元性能测试 | 每次 PR | CI |
| 战斗并发测试 | 每周 | Staging |
| 全链路压测 | 每月 | Staging |
| 客户端性能测试 | 每次发版 | 真机 |

---

## 5. 版本记录

- **v1.0**（2026-07-08）: 初始版本，覆盖性能红线、监控、优化原则、测试要求