# 商务验证工具

仅保留仍用于当前 sw8/sw9 验证的工具。旧 sw7、固定端口 18000、重复页面夹具脚本已归档；接口边界回归优先运行相应 Go 测试。

## 环境

- Python 3.10+；数据库工具需要 PyMySQL、PyYAML，Excel 对比需要 openpyxl。
- 页面检查使用 Node 和 Playwright；通过 `SW_PLAYWRIGHT_MODULE` 指定已有模块路径。
- `--runtime` 必须指向仓库外的私有目录。配置、令牌、实际响应、导出文件和 SQL 日志不得提交。
- 旧 Java 连接 sw8，新 Go 连接 sw9。运行命令时明确传入端口，避免误连日常服务。任务保持停用。

通用输入：`legacy-<identity>.token`、`new-<identity>.token`、`legacy-client.json`、`id-maps.json`；写入测试还需要专门创建的三级测试身份及对应凭据。不要把业务正常账号当作可随意清理的测试身份。

## 工具用途

| 工具 | 用途与写入范围 |
|---|---|
| start-sw-rehearsal.ps1 | 从私有配置启动本机 Go 服务，临时注入 SDK 兼容参数，日志留在 runtime |
| sw_database_rehearsal.py | 数据库盘点、备份、迁移及验证；同时提供其他脚本依赖的 connect/query |
| sw_api_compare.py | 新旧读取接口逐字段对比；输入 case JSON 明确路径、参数、允许的协议转换 |
| sw_write_verify.py | 规则与预警状态流程测试；提供其他写入工具的 Rehearsal 支持 |
| sw_account_create_verify.py | 创建临时下级、验证层级/角色并清理；不删除预先存在的同名账号 |
| sw_account_write_verify.py | 测试账号资料/状态并恢复原值 |
| sw_preference_compare.py | 四种包含下级/身份证去重组合，结束恢复偏好 |
| sw_export_compare.py | 新旧注册和充值 Excel 逐单元格对比 |
| sw_sdk_write_verify.py | 独立平台夹具上的绑定、重提、解绑与渠道创建；受控 OA 审核 |
| sw_report_rehearsal.py | 指定日报分区备份、比较和恢复 |
| sw_run_report_tasks.py | 要求已有日期匹配的备份；创建停用的临时计划、手工执行并清理计划 |
| sw_endpoint_benchmark.py | 接口耗时、完整响应摘要及 SQL 采集，只读 |
| sw_endpoint_parity.py | 优化前后接口及偏好矩阵对比；即使 HTTP 恢复失败也尝试还原数据库偏好 |
| sw_dashboard_layout_smoke.cjs | 激活分页、偏好和榜单布局检查，截图留在指定私有目录 |

先通过各 Python 工具的 `--help` 查看必需参数。日报、预警及写入工具会改动测试数据；使用其备份/恢复流程，并核对最终表计数与任务状态。

## 读取对比示例

```powershell
python scripts/sw_api_compare.py --runtime D:/private/sw-review --cases D:/private/sw-review/cases.json --old-url http://127.0.0.1:18080 --new-url http://127.0.0.1:19004 --output D:/private/sw-review/result.json
```

`--recompare` 只比较已保存响应；`--refresh-target` 使用已保存的同参数旧响应、重新请求新服务。报告会标记 `source_capture_reused`，不能把快照对比描述为双方重新实测。

本地 MySQL 回归只接受 `SW_TEST_MYSQL_DSN` 指向 `127.0.0.1` 的隔离实例：

```powershell
go test ./internal/data/business -run MySQL -count=1
```

这些测试创建并清理自己的随机数据库，不在 sw8/sw9 上运行测试建表和删除。