kra-new/scripts/README.md

商务验证工具

仅保留仍用于当前 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 查看必需参数。日报、预警及写入工具会改动测试数据；使用其备份/恢复流程，并核对最终表计数与任务状态。

读取对比示例

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 的隔离实例：

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

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