# 新旧版本发布包：接口同构验证计划

## 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`）。