# 跨端 E2E 测试 — 司机接单到管理端核算打款

## 概述

`tests/cross_end/` 包含跨越管理端 Web + 司机安卓 APP 的端到端自动化测试，
验证从司机 APP 接单到管理端核算打款的**完整业务闭环**。

```
  [司机安卓 APP]                    [管理端 Web]
       │                                │
  ① 接单（货源→数量→协议）              │
  ② 装货（吨位→拍照→合同确认）          │
  ③ 卸货（吨位→拍照）                   │
  ④ 获取运输单号 ──────────────────────→│
                                     ⑤ 运费核算（无数据时 SQL 重试风控状态）
                                     ⑥ 运单审核
                                     ⑦ 垫资-财务打款（含验证码）
                                     ⑧ 垫资-货主打款
```

## 用例

| 用例ID | 名称 | 说明 |
|---|---|---|
| TC-D2S-001 | 司机APP接单到管理端核算打款完整流程 | 基础流程 |
| TC-D2S-002 | 司机APP接单到管理端核算打款-车队长全额收款流程 | 核算时选择车队长 + 全额收款模式 |

页面对象位于 `tests/pages/`（PO 层，与用例分离）：

| Page Object | 文件 | 用途 |
|---|---|---|
| `DriverFreightFlowPage` | `tests/pages/driver/freight_flow_page.py` | 司机 APP 接单/装货/卸货/取单号 |
| `FreightAccountingPage` | `tests/pages/admin/freight_accounting_page.py` | 核算/审核/财务打款/货主打款 |

元素定位依据: `resources/selectors/正常流程-web端.md`、`resources/selectors/正常流程-司机.md`。

## 前置条件

### 管理端

```bash
# 保存管理员登录态 (仅需一次，过期后重跑)
python tests/web/admin/save_auth.py --role super_admin --browser chromium
```

### 司机安卓 APP

| 条件 | 说明 |
|---|---|
| Appium Server | 启动: `appium` (默认 http://localhost:4723) |
| Android 模拟器/真机 | 已启动并通过 `adb devices` 确认 |
| 司机 APP | 已安装，包名 `com.arpa.ynchenggangdriver` |
| 登录态 | 在设备上**手动登录一次** (后续 `noReset=true` 自动复用) |

### Python 依赖

```bash
pip install -r requirements.txt
```

## 运行

```bash
# 运行跨端测试
pytest tests/cross_end/ -m cross_end -v -s

# 仅收集测试（不执行，验证 fixture 链正确）
pytest tests/cross_end/ --collect-only

# 排除跨端测试（常规运行不影响）
pytest tests/ -m "not cross_end"
```

## 查看报告 (Allure)

```bash
# 方式一: 直接起本地服务查看（推荐）
allure serve output/allure-results

# 方式二: 生成静态 HTML
allure generate output/allure-results -o output/allure-report --clean
```

报告中包含: 用例中文标题/用例ID、P0→BLOCKER 优先级、Phase 步骤树、
关键节点截图、失败时自动截图、完整日志。

## 配置

所有环境配置从 `tests/config/test_config.yaml` 读取，跨端测试使用的 section:

| Section | 用途 |
|---|---|
| `admin` | 管理端 base_url, viewport, timeout, 登录态路径 |
| `driver_android` | Appium host, device_name, app_package, no_reset |
| `accounts.super_admin` | 管理员手机号/密码 |
| `accounts.driver` | 司机手机号/密码 |
| `database` | MySQL 连接（运费核算无数据时更新风控状态） |

## 故障排查

| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| `pytest.skip: Playwright 未安装` | 环境缺少 playwright | `pip install playwright && playwright install chromium` |
| `pytest.skip: Appium-Python-Client 未安装` | 环境缺少 appium | `pip install Appium-Python-Client` |
| 登录态已过期 | storage_state 过期 | `python tests/web/admin/save_auth.py --role super_admin` |
| APP 在登录页 | noReset 未生效或首次运行 | 在设备上手动登录一次 |
| 无法连接到 Appium server | Appium 未启动 | 终端执行 `appium` |
| AdbError / 设备未找到 | 模拟器未启动 | `adb devices` 确认设备在线 |
| 运费核算查询无数据 | 风控状态未更新 | 用例已自动执行 SQL 重试；仍失败检查 `database` 配置 |

## 已知限制

- **仅 chromium**: 管理端不跑 browser matrix，固定使用 chromium
- **仅 Android**: APP 端目前固定为 `driver_android`，不跑 iOS
- **创建真实数据**: 测试会在环境中创建真实订单，需定期清理或使用测试环境
- **同时需要两个环境**: 管理端 + Appium + Android 设备必须同时可用