# QA Agent — Sport Era 测试

后端 API 接口验证 + 前端页面验证。**消费 server/admin/uniapp/pc 四端产出，输出验证脚本和缺陷清单。**

## 技术栈

- **Python** 3.10+ + `requests` 用于后端接口验证
- **Playwright** 或浏览器预览用于前端页面验证
- **PowerShell** 用于本地命令、日志和静态检查

## 目录结构

```text
qa/
├── backend/              # 后端接口验证脚本
│   ├── test_<module>_<action>.py
│   └── ...
├── frontend/             # 前端页面验证脚本或记录
│   ├── test_<page>.py
│   └── snapshots/
├── bugs/                 # 缺陷记录
│   └── YYYY-MM-DD-<module>.md
└── AGENTS.md             # 本文件
```

## 后端验证规范

### 单接口脚本模板

```python
# qa/backend/test_<module>_<action>.py
"""
接口验证: <接口描述>
路径: <HTTP_METHOD> <URL>
"""
import requests

BASE_URL = "http://127.0.0.1:8000"


def test_normal():
    resp = requests.get(f"{BASE_URL}/api/xxx/lists", params={"page_no": 1})
    assert resp.status_code == 200
    data = resp.json()
    assert data["code"] == 1
    print("正常场景通过")


if __name__ == "__main__":
    test_normal()
    print("全部通过")
```

### 用例覆盖矩阵

| 用例类别 | 必测 | 备注 |
| --- | --- | --- |
| 正常流程 | 是 | 标准参数 + 标准账号 |
| 必填校验 | 是 | 缺字段、空字符串、null |
| 类型校验 | 是 | 字符串传整数、整数传字符串、超长输入 |
| 边界值 | 是 | 0 / -1 / 极大值 / 空列表 |
| 权限校验 | 是 | 未登录 / 普通用户访问管理员接口 |
| 业务冲突 | 视情况 | 重复提交、状态非法流转 |
| 并发 | 视情况 | 高频提交、重复请求 |

## 前端验证规范

### 校验流程

```text
1. 确认对应开发服务器已运行
2. 打开目标页面 URL
3. 检查页面是否白屏、错位或资源缺失
4. 检查控制台是否有 error 级别日志
5. 检查网络请求是否正常返回数据
6. 验证核心交互：点击、滑动、输入、提交、跳转
7. 如有异常，记录到 qa/bugs/YYYY-MM-DD-<module>.md
```

### 缺陷记录模板

```markdown
# YYYY-MM-DD <模块> 缺陷

## Bug #1 - <简短标题>

- **页面**：<URL 或路径>
- **复现步骤**：
  1. ...
  2. ...
- **期望**：...
- **实际**：...
- **截图/录屏**：`./snapshots/xxx.png`
- **关联接口**：`POST /api/xxx/submit`
- **优先级**：高/中/低
- **状态**：待修复 / 修复中 / 已验证
```

## 协作准则

1. 测试前先明确本轮改动文件、接口、页面和数据依赖。
2. 接口验证以实际 controller、validate、logic、model 为准。
3. 数据库结构优先参考项目内 `sbnews.sql` / `docs/sql/`，必要时再按用户要求核对线上库。
4. 发现 bug 后优先给出最小复现路径和关联文件，不直接扩大修改范围。
5. 验证结论需同步到 `业务进度管理.md` 或缺陷记录。