# 后端服务压测工具

为部署在阿里云单机（4G/2C）的 TopFans 后端微服务设计。

## 目录

```
backend/scripts/loadgen/
├── seed/                       # 数据准备工具(CLI)
│   ├── main.go                 # seed CLI 入口
│   ├── stars.go users.go profiles.go assets.go
│   ├── slots_and_exhibits.go friendships.go
│   ├── tokens.go sequences.go cleanup.go
│   ├── seed_test.go            # 单元测试
│   └── README.md
├── loadgen/                    # 压测主程序
│   ├── main.go                 # loadgen CLI 入口
│   ├── preflight.go verify.go  # 7 项开压前检查 + 压后验证
│   ├── lib/                    # 核心库(16 个测试全过)
│   │   ├── csv.go client.go hdr.go log.go ramp.go
│   │   ├── circuit.go ssh_metrics.go config.go
│   │   └── *_test.go
│   ├── scenarios/              # 7 个场景(已注册)
│   │   ├── s1_login.go s2_read.go s3_like.go s4_mint.go
│   │   ├── s5_dashboard.go s6_ranking.go s7_place.go
│   │   ├── common.go scenarios.go
│   │   └── scenarios_test.go
│   └── reporter/               # 报告生成
│       ├── json.go csv.go plot.go markdown.go
├── monitor/                    # 监控栈
│   ├── sample.sh               # 后台采样(写到 metrics-feed.jsonl)
│   ├── docker-compose.monitor.yml
│   ├── prometheus.yml
│   └── grafana-dashboards/     # 4 个预置面板
├── recover/                    # 一键灭火 + 备份还原
│   ├── emergency-stop.sh
│   └── restore-from-backup.sh
├── scripts/                    # 部署到 prod
│   └── mint_reset.sh
└── reports/                    # 跑测产出(gitignore)
```

## 编译

```bash
cd backend
GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o bin/seed ./scripts/loadgen/seed/
GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o bin/loadgen ./scripts/loadgen/loadgen/
```

## 测试

```bash
cd backend
go test ./scripts/loadgen/...
```

**当前测试状态** (截至 Phase 7 完结):
- `seed` 包: 5/5 PASS
- `loadgen/lib` 包: 16/16 PASS
- `loadgen/scenarios` 包: 2/2 PASS
- 共 23 个测试全过

## 关键特性

### 1. 6 维红线判停(自动熔断)

| # | 红线 | 阈值 | 数据源 |
|---|------|------|--------|
| R1 | 客户端错误率 | > 5% 持续 30s | loadgen HDR |
| R2 | 客户端 P99 | > 3000ms 持续 30s | loadgen HDR |
| R3 | 5xx 比例 | > 10% 持续 10s | loadgen status |
| R4 | PG 连接数 | > 42 持续 30s | metrics-feed |
| R5 | 磁盘空闲 | < 5GB 持续 30s | metrics-feed |
| R6 | OOM 事件 | 瞬时触发 | metrics-feed |

### 2. CLAUDE.md 序列重置

seed 工具自动同步所有相关表的 PG 序列(避免后续 GORM 插入报 duplicate key)。

### 3. 数据隔离

所有测试数据用 `star_id = 999900` 物理隔离,不影响真实业务 star_id (87, 88, 91, 93, 94, 95)。

### 4. 凌晨窗口

执行窗口:凌晨 02:00-06:00 业务低峰。emergency-stop 一键回滚,restore-from-backup.sh 5-8min 还原。

## 详细文档

- **设计文档**: `docs/superpowers/specs/2026-06-12-load-testing-design.md`
- **实施计划**: `docs/superpowers/plans/2026-06-12-load-testing.md`
- **seed 工具说明**: `seed/README.md`