# 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 的暂停语义。 复现命令(不访问真实站点,不提交预约): ```bash .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` 等原有配置,没有新增香港硬编码或修改配置格式。 - 本次没有执行远端上传、上线或真实预约;本地热更新通过不等同于线上预约成功。 - 不在进行中的真实预约提交期间切换版本;沿用宿主的停止/清理后更新流程。