# PC Express API — Python 接口测试

使用 **pytest + requests** 对 `doc/开发/PC后端接口文档.md` 中的 PC 端接口做集成测试（被测服务为 Node.js Express，测试用 Python 编写）。

## 前置

```powershell
cd backend
pnpm install
pnpm dev
```

另开终端：

```powershell
cd backend\tests_python
pip install -r requirements.txt
pytest
```

## 环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `PC_API_BASE_URL` | `http://localhost:3101/api` | PC 端 Base URL |
| `MOBILE_API_BASE_URL` | `http://localhost:3201/api` | Mobile 健康检查 |
| `RUN_INTEGRATION` | `1` | 设为 `0` 可跳过需后端的用例 |

## 用例结构

| 文件 | 对应文档章节 |
|------|----------------|
| `test_01_health.py` | §1 健康检查 |
| `test_02_qiwei.py` | §2 企微（webhook / room-docs） |
| `test_03_staff.py` | §3 人员 |
| `test_04_community.py` | §4 小区 |
| `test_05_room.py` | §5 群 |
| `test_06_compliance.py` | §6 合规 |
| `test_07_risk.py` | §7 风控 |
| `test_08_content.py` | §8 内容 |
| `test_09_koc.py` | §9 KOC |
| `test_10_dashboard.py` | §10 看板 |
| `test_11_sales.py` | §11 经营 |
| `test_12_workbench.py` | §12 工作台 |

## 报告（测试 UI，可发给领导/产品）

```powershell
# 先启动后端: cd backend && pnpm dev
pytest --html=report.html --self-contained-html
```

生成文件：`backend/tests_python/report.html`（单文件、内嵌样式，可直接双击用浏览器打开，或打印为 PDF）。

**真实 QiWe 联调**（需 `QIWEI_TOKEN` + `QIWEI_GUID`；`getRoomList` 为空时加 `QIWEI_ROOM_IDS=群id1,群id2`，从 `getSessionList` 里 `sessionType=1` 的 `sessionId` 复制）：

| 文件 | 覆盖 |
|------|------|
| `test_13_qiwei_live.py` | 在线状态、proxy 拉群、同步消息 |
| `test_14_room_live.py` | 群同步、群详情、健康度、进退群事件 |
| `test_15_koc_live.py` | 外部联系人同步 |
| `test_16_content_live.py` | 群发状态接口探测（不发真实消息） |
| `test_17_session_live.py` | 校验 QIWEI_ROOM_IDS 在 getSessionList 中 |
| `test_18_workbench_live.py` | 通知模板 + 真实 sendText（需 `QIWEI_LIVE_NOTIFY=1`） |
| `test_19_qiwei_docs_live.py` | webhook / messages / room-docs / 异常解决（真 roomId） |

**Swagger 模块 1～2 手测说明：** [doc_qiwei_swagger_live.md](./doc_qiwei_swagger_live.md)

**模块 3 人员真实联调：** `python run_section_3_live.py`（用 `.env` 的 `QIWEI_GUID` 回填并验在线）

**模块 4 小区真实联调：** `python run_section_4_live.py`（用 `.env` 的 `QIWEI_ROOM_IDS` 绑定真实群）

**模块 5～8 真实联调：** `python run_section_5_8_live.py`（群/合规/风控/内容，真实 roomId）

### 模块 2 覆盖一览

| 接口 | 联调 |
|------|------|
| staff/status、batch-status、sync、proxy/getRoomList | test_13 ✅ |
| webhook、messages、room-docs、anomalies、resolve | test_19 ✅ |
| proxy 其它 method | 手测或自行加 proxy 用例 |

`backend/.env` 示例：

```env
QIWEI_ROOM_IDS=10865515454476837,10941673770342441
```

联调时 `POST /api/rooms/sync` 可带 `roomIdList`（与上面相同 id），写入本方群库后再测 `GET /api/rooms/{roomId}`。

### 两种跑法（别混）

| 命令 | 含义 | 交付物 |
|------|------|--------|
| `python run_all.py` | 本地接口（内存假数据）+ 真实联调 | `report.html`（37 passed 里含 21 条本地） |
| **`python run_live_only.py`** | **只要真实 QiWe** | `report_live.html` + **`live_data_report.md`** + `live_data_snapshot.json` |
| `python export_live_data.py` | 只导出真实 API 返回，不跑 pytest | `live_data_report.md` |

**你要给上级看「真实联调数据」**：用 `run_live_only.py` 或 `export_live_data.py`，打开 **`live_data_report.md`**（里面有真实群名、roomId、消息条数等 JSON）。

## 交互测试 UI（领导要求「能点着测」）

启动后端后浏览器打开：**http://localhost:3101/api-docs**

在 Swagger UI 中展开接口 → **Try it out** → 填参数 → **Execute**。

自动化结果报告仍为 `report.html`（pytest-html），与 Swagger 互补。

## 说明

- 依赖**内存存储**，用例使用 `uid` 后缀避免冲突。
- 调用真实 QiWei（`/qiwei/proxy`、`/qiwei/sync`）需配置 `QIWEI_TOKEN`，本套件默认不测外网。
- `test_02_qiwei.py` 使用 `fixtures/qiwei_webhook_sample.json` 验证 docid 台账链路。