# elevator_api_parity — V1/V2 接口冒烟与对拍

## 功能概览

| 能力 | 说明 |
|------|------|
| **单机冒烟** | 对单个 Base URL 遍历 `api_catalog.json` 中的接口（`include_in_smoke=true`），记录 HTTP 状态、耗时、业务 `code`、响应摘要 → `report/smoke-{label}-*.md` |
| **横向对拍** | 旧 JAR（`--base-old`）与新 JAR（`--base-new`）并行调用；仅 **`include_in_parity=true`** 的条目参与 **HTTP 状态 + 业务 code** 一致性断言 → `report/parity-*.md` |
| **套件总览** | 合并本次产生的冒烟×2 + 对拍 → `report/SUITE-*.md` |

接口清单与请求体见 **`api_catalog.json`**（支持 `fixture` 文件或内联 `body`）。

## 环境

- Python 3.8+，`pip install -r requirements.txt`
- 若遇全局 pytest 插件冲突：`export PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`

## 启动两实例（示例）

同一套 `application.properties`（或外部配置），仅端口不同：

```bash
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
CFG="file:/path/to/application.properties"
java -jar cw-elevator-application-V1.0.0.20211103.jar --server.port=18080 --spring.config.location=$CFG
java -jar cw-elevator-application-2.0.0.jar --server.port=18081 --spring.config.location=$CFG
```

## 一键完整套件（推荐）

在 **`maven-cw-elevator-application`** 目录：

```bash
./scripts/run_full_elevator_api_suite.sh
```

环境变量（可选）：

- `ELEVATOR_BASE_OLD` — 默认 `http://127.0.0.1:18080`（V1）
- `ELEVATOR_BASE_NEW` — 默认 `http://127.0.0.1:18081`（V2）
- `ELEVATOR_HEADER_BUSINESSID`、`ELEVATOR_HEADER_LOGINID`、`ELEVATOR_HEADER_AUTHORIZATION` 等 — 与现网一致时业务码更有可比性

## 分步执行

```bash
cd tools/elevator_api_parity
export PYTEST_DISABLE_PLUGIN_AUTOLOAD=1

# 仅逻辑单测
python3 -m pytest tests/test_unit_compare.py -q

# V1 单机冒烟
python3 -m pytest tests/test_smoke_catalog.py -m smoke \
  --smoke-base=http://127.0.0.1:18080 --smoke-label=v1_legacy -q

# V2 单机冒烟
python3 -m pytest tests/test_smoke_catalog.py -m smoke \
  --smoke-base=http://127.0.0.1:18081 --smoke-label=v2_build -q

# 双端对拍（双端 /actuator/health 等可达时执行，否则跳过）
python3 -m pytest tests/test_parity_endpoints.py -m live -q \
  --base-old=http://127.0.0.1:18080 --base-new=http://127.0.0.1:18081
```

### 强制要求联调（失败即中断）

```bash
export ELEVATOR_PARITY_REQUIRE_LIVE=1   # 对拍
export ELEVATOR_SMOKE_REQUIRE=1         # 冒烟
```

## 仅对拍（不含冒烟）

```bash
./scripts/run_elevator_parity.sh
```

（脚本内会先 `mvn package`，再跑单测 + 对拍。）

## 报告位置

- `report/smoke-v1_legacy-*.md` + **同名 `.json`**（结构化结果，供套件矩阵消费）
- `report/smoke-v2_build-*.md` + **同名 `.json`**
- `report/parity-*.md` + **同名 `.json`**
- **`report/SUITE-*.md`**：始终包含 **第二节「全量接口清单」**（来源于 `api_catalog.json`）；**第三节「测试结果矩阵」** 在有上述 JSON 时填入 V1/V2 HTTP、业务 code、对拍 Y/N；若本次因未起服务而 **skip**，矩阵中为 **—**（参见第三节说明）。

## 扩展接口

编辑 **`api_catalog.json`**：

- `include_in_parity: false` — 只做冒烟，不参与 V1/V2 等值断言（避免依赖不一致导致误报）。
- `include_in_parity: true` — 纳入横向对拍（当前默认对 **访客/人员/规则分页/记录分页** 四个核心场景开启）。