ita_single_file_refactor.md 5.8 KB

Italy 单文件发布重构

结论与范围

Italy 专属运行时代码现统一放在 plugins/ita_plugin.py,版本为 1.0.1。 以后修改和上传这个文件即可,不需要先运行打包脚本,也不需要上传 Italy 辅助模块。

本次是代码搬迁和接线调整,不是重新实现 Query、Book、OTP 或预约结果核验。 未修改账号、领区配置、Sentinel、Booker、上传器、插件工厂,也未操作真实网站、邮箱或预约。

为什么必须这样改

现有 utils/plugin_updater.py::download_and_install_plugin 只写入一个 .py 文件; vs_plg_factory.py::VSPlgFactory.create 按文件加载插件; main.py::reload_wrappers_for_plugin 只移除该插件名称的模块缓存。 原来的 Italy 多文件运行时既无法随单次上传完整交付,也可能在更新入口后继续使用旧辅助模块。

这里沿用现有发布机制,没有扩展压缩包、依赖安装器或动态执行源码的机制。

搬迁与可核对性

源代码基线:62c23889992ca7ee9395efad47c707dbd7cd2cee。

原文件(均在 plugins 下) 现在的位置:ita_plugin.py 内部分区
ita_protocol.py PROTOCOL:配置、协议、日期和 OTP 解析
ita_calendar_query.py CALENDAR_QUERY:逐月查询
ita_calendar_book.py CALENDAR_BOOK:申请人会话中重新查号、选时段
ita_booking_final.py BOOKING_FINAL:一次提交与结果状态
ita_reservation.py RESERVATION:预约记录解析
ita_final_read_port.py FINAL_READ_PORT:独立标签页读取回执
ita_calendar_session.py CALENDAR_SESSION:表单准备、请求审计
ita_otp.py OTP:复用既有云端邮件读取接口
ita_turnstile.py TURNSTILE:既有准备流程
ita_workflow.py WORKFLOW:串起 Query / Book
ita_plugin.py PLUGIN:框架公开接口

tools/consolidate_ita_plugin.py 从固定 Git 基线读取原文,用 AST 定位后做文本搬迁, 不通过重新生成函数体的方式改写业务。docs/ita-single-file-migration.json 记录每个源文件、 搬迁分区以及最终文件的 SHA-256。

必要的接线改动:

  1. 移除 Italy 内部导入和模块限定名,保留宿主已有共享依赖。
  2. 区分 datetime.time 与 time 模块,以及两处不同含义的 _text、OTP 私有邮箱正则。
  3. 统一 future import,去掉原分模块的 __all__,清理 Python 行尾空白;保留字符串内容,包括页面 JavaScript。
  4. 版本从 1.0.0 升到 1.0.1,供现有更新器识别。
  5. 保留 OTP 锁的进程共享语义:现有工厂每次创建实例都会重新执行插件文件,因此仅将这把 原生锁保存在已存在的 vs_plg 宿主模块上。那里不保存插件函数、类或旧业务代码,也不需要修改宿主文件。
  6. 测试和调试工具改为引用单文件。本地 Query+Book 验收拦截跟随实际插件实例所属代码, 不通过可能已被下一次工厂加载替换的模块缓存寻找实现。跨加载版本的配置按完整数据比较, 不取消账号、路由、请求次数或提交保护。

原十个辅助运行时文件从当前树移除,完整内容仍可由上述 Git 提交恢复。 测试、调试工具和历史证据文档可以继续分文件,它们不属于上传产物。

验证及准出

2026-08-31 本地验证结果:完整 Italy 回归 838 项通过、0 跳过(10.863 秒), 其中包含单文件专项 8 项;既有 Query+Book CLI 离线验收 75 项通过(属于前述回归子集)。 机械搬迁复现检查、git diff --check 均以 exit code 0 结束。

test/test_ita_single_file.py 包含以下离线检查:

  • 对全部 11 个原分区做独立 AST 对比,只有上述白名单接线变化;函数控制流和字面量未重写。
  • 在临时目录只放一个插件文件,通过真实安装器和真实工厂加载;禁止插件导入任何 plugins.* / tools.*。
  • 公开 Query / Book 入口调用当前加载文件的实现。
  • 执行原样的宿主热重载函数,验证停止、加载、启动顺序,类、枚举和函数换新,进程共享 OTP 锁保持一致。
  • 多次动态加载后,本地提交保护仍绑定原申请人实例;只创建一次本地提交标记,不重试。
  • 不确定结果仍继承宿主的 BookingOutcomeUnknownError,不会丢失 Booker 的暂停语义。

复现命令(不访问真实站点,不提交预约):

.venv/bin/python -B tools/consolidate_ita_plugin.py
.venv/bin/python -B -m unittest -q test.test_ita_single_file
.venv/bin/python -B tools/debug_ita_query_book.py --offline
git diff --check

完整 Italy 回归覆盖 test/test_ita*.py、test/test_debug_ita*.py、 test/test_plugin_tester_ita_config.py。

注意:搬迁脚本是本次初始迁移的审计工具,不是今后的构建步骤。 正常开发直接编辑 ita_plugin.py;未来业务变化后,初始迁移逐字比对理应报告差异,需由对应变更更新验收基线。 审计测试需要上述源 Git 对象;插件运行、上传和热更新不需要 Git、脚本或清单文件。

发布边界

  • 上传产物只有 plugins/ita_plugin.py,但不是脱离宿主的独立应用。继续复用框架类型、云端 API、 浏览器和鼠标/键盘等已有工具,与其他插件一致。
  • 宿主至少需要当前 Italy 集成基线中的共享接口,尤其 vs_types.BookingOutcomeUnknownError 及 Booker 对该异常的处理。单文件插件不会替老宿主升级这些公共接口。
  • 领区差异仍来自 apt_configs 等原有配置,没有新增香港硬编码或修改配置格式。
  • 本次没有执行远端上传、上线或真实预约;本地热更新通过不等同于线上预约成功。
  • 不在进行中的真实预约提交期间切换版本;沿用宿主的停止/清理后更新流程。