docs+test: 发布包对拍计划、pytest 双端 API 对拍与 run_elevator_parity 脚本

- docs/elevator-api-parity: 计划/报告模板/示例 - tools/elevator_api_parity: 端点目录、fixtures、对拍 client/compare、报告生成 - scripts/run_elevator_parity: JDK8 构建 + 单测/对拍（无服务时跳过对拍用例） Made-with: Cursor Former-commit-id: 3d54a40e1a7ae0b1724261d4f18910a6f415f853
2026-06-09 16:30:29 +08:00 · 2026-04-25 09:50:32 +08:00
parent 2cd9da61da
commit 038f846dad
24 changed files with 712 additions and 0 deletions
@@ -0,0 +1,44 @@
+# 新旧版本发布包：接口同构验证计划
+
+## 1. 目标
+
+- **新构建物**：`cw-elevator-application-starter` 经 `mvn package` 产出的 `cw-elevator-application-2.0.0.jar`。
+- **历史基线**（约定路径，若不存在需单独拷贝）：  
+  `.../cw-elevator-application-V1.0.0.20211103/cw-elevator-application-V1.0.0.20211103.jar`。
+- **成功标准**：在**相同运行配置与依赖环境**下，对同一批 HTTP 请求，两实例返回的 **HTTP 状态码、JSON 结构、业务 `code`（`CloudwalkResult`）** 一致；可约定忽略字段（时间戳、随机 `requestId` 等）在报告中注明。
+
+## 2. 约束与先决条件
+
+1. **双进程**：旧版默认端口 `18080`，新版 `18081`；均通过**同一套**外置或环境变量 `spring.config` 指向上游/库（与现网联调一致时才有可比性）。
+2. **无历史 JAR**：本仓库中若不存在上述 `*.jar`，仅完成构建与**框架/离线用例**；等效性验证需在拿到 JAR 后执行 `scripts/run_elevator_parity.sh`。
+3. **健康检查**：优先 `GET /actuator/health`；若基线为 Spring Boot 1.5 且 `management` 基路径不同，由脚本 `tools/elevator_api_parity/parity/health.py` 自动探测回退。
+
+## 3. 子任务分解
+
+| 序号 | 任务 | 产出 |
+|------|------|------|
+| T1 | Maven 发布包构建 | `target/cw-elevator-application-2.0.0.jar` |
+| T2 | 端点目录与用例体 | `tools/elevator_api_parity/api_catalog.json`、fixtures |
+| T3 | 双端 HTTP 对拍与比较 | `parity/*` + `pytest` |
+| T4 | 一键脚本与报告 | `scripts/run_elevator_parity.sh` → `report/parity-*.md` |
+| T5 | 在联调环境实跑、签字发布 | 人工/运维 |
+
+## 4. 接口范围（与源码 Controller 一致）
+
+- `/elevator/person/*`（含 `/add/visitor` 等）
+- `/elevator/passRule/*`
+- `/elevator/device/*`、`/elevator/restructure/*`
+- `/intelligent/acs/elevator/record/*`（`POST` 为主）
+- 设备通道 `/device/v2/*`（`39201` 等，按业务场景启用）
+
+具体路径与请求体以 `api_catalog.json` 为准，可按现网场景追加 `fixtures/*.json`。
+
+## 5. 非目标
+
+- 不替代集成环境全链路压测、安全扫描。
+- 不强制在一台空库机子上与线上一致（需**相同数据与上游**才可比）。
+
+## 6. 与本文档配套脚本
+
+- 见 `maven-cw-elevator-application/tools/elevator_api_parity/README.md`。
+- 报告模板：`docs/elevator-api-parity/REPORT-TEMPLATE.md`（实跑时由 `generate_report.py` 自动填充为 `tools/elevator_api_parity/report/parity-*.md`）。
@@ -0,0 +1,28 @@
+# 电梯应用 API 新旧版本对拍报告
+
+- **报告生成时间**：（由脚本自动写入）
+- **新版权益端 Base URL**：
+- **历史基线端 Base URL**：
+
+## 结论摘要
+
+| 项 | 值 |
+|----|-----|
+| 总用例 | |
+| 通过 | |
+| 失败/跳过 | |
+| 可上线建议 | **通过/不通过/条件通过**（人工确认） |
+
+## 逐条用例
+
+| 名称 | 方法+路径 | HTTP(旧) | HTTP(新) | JSON 等值 | 备注 |
+|------|-----------|----------|----------|------------|------|
+| （表格由 `generate_report.py` 从 pytest 结果填充） | | | | | |
+
+## 已忽略/归一化项
+
+- `timestamp`、各层 `message` 文案差异、UUID 等（如策略允许可在 `parity_config.yaml` 配置）。
+
+## 未启动实例时的说明
+
+- 若出现「基线/新版无法连接健康检查」，对拍不执行，需在本机或联调机启动两 JAR 后重跑。
@@ -0,0 +1,19 @@
+# 电梯应用 API 新旧对拍报告（示例）
+
+- **时间**: 2026-04-25T12:00:00
+- **基线(旧) URL**: `http://127.0.0.1:18080`
+- **新构建 URL**: `http://127.0.0.1:18081`
+
+## 用例
+
+| 用例 | 方法+路径 | HTTP(旧) | HTTP(新) | 等值 | 说明 |
+| ---- | -------- | -------- | -------- | ---- | ---- |
+| person_add_visitor_min | `POST /elevator/person/add/visitor` | 200 | 200 | Y | 双端 `code` 一致（联调同库同配置时） |
+| person_detail | `POST /elevator/person/detail` | 200 | 200 | Y | 同上 |
+| passrule_page | `POST /elevator/passRule/page` | 200 | 200 | Y | 同上 |
+| record_page | `POST /intelligent/acs/elevator/record/page` | 200 | 200 | Y | 同上 |
+
+## 汇总
+
+- 通过: 4，不一致: 0。
+- **上线前请人工与联调/业务确认**（本表为结构示例，实跑见 `tools/elevator_api_parity/report/parity-*.md`）。