# Italy 插件精简重构:文档入口与执行约定 版本:1.1;建立日期:2026-09-01。 最新架构决定(CR-001,2026-09-01,用户已确认):Italy 调试期允许记录 OTP、Token 与敏感表单;最终提交失败、超时或结果未确认按普通失败交回 Booker 后续重试。单次 `book()` 仍最多点击一次,Query 仍不得产生最终写入。此决定覆盖旧文档中的脱敏准出和 `BookingOutcomeUnknownError` 暂停策略。 本目录记录用户要求的约 1000 行 Italy 插件技术方案,以及可行性、开发周期、测试和准出要求。后续相关开发必须以本目录为依据,不允许实现过程中另起一套架构。 当前状态:方案文档已建立;[W0 行为基线](records/W0-baseline.md)、[W1 公共能力](records/W1-shared-lifecycle.md) 与 [W2 登录/准备收敛](records/W2-login-preparation.md) 已留档。[W3 查询入口及共用日历](records/W3-query-entry.md)、[W4 Book 与提交职责收敛](records/W4-selection-readback.md) 仍只部分完成。[W5](records/W5-tools.md) 已把失效的旧文档账号池命令迁到现有 Query+Book CLI。R6/R7 及异步表单竞态修复后,Italy 生产运行时为 **1178 行**,SHA-256 `c6566021f997b5b9a1228229bd2f206b33c65a2c573c18acb78b89a960ccef7e`;同仓 VFS 为 1271 行、BLS 1107 行、TLS 852 行,已进入同一量级。当前协议、OTP、Query/Book、登录、公共生命周期与异步表单等待的 69 项精简合同测试及 15 项配置测试通过;旧的实现耦合诊断套件及工具仍在迁移,因此不能沿用旧版“全部测试通过”结论。生产只调用既有公共合同;VFS/TLS/BLS 与 `utils/plugin_utils.py` 均无差异。修复后的真实 Query、现场真实预约、全量消费者迁移与发布尚未完成。未提交、推送或部署。 ## 1. 目标不能被替换 - 最大化复用现有公共模块和 VFS/TLS/BLS 做法,将 `plugins/ita_plugin.py` 从 6286 行收敛到约 1000 行。 - Query 就是查询;Book 就是预约。保留账号池 Query 与用户账号 Book 的职责分离。 - 不依赖浏览器环境的已验证接口使用 HTTP;依赖浏览器环境的流程使用浏览器或浏览器内请求。不能靠猜测切换通道。 - 支持通用短期申根旅游签证、单人预约;香港只是现场验收样本,不得硬编码香港。 - 单文件上传、热更新继续可用;不能把几千行 Italy 私有代码搬到其他文件冒充精简。 - 不是从零重写协议:保留已验证的网站行为,替换重复能力、合并冗余层次。 质量对齐现有插件的工程方式,而不是照搬其他网站的字段和状态码;提交失败按用户确认的普通重试语义复用现有 Booker。 ## 2. 阅读与执行顺序 | 文档 | 回答的问题 | 何时必须查阅 | | --- | --- | --- | | [01 技术方案](01-technical-design.md) | 代码放哪里、复用谁、哪些删、哪些保留 | 开始任务、设计或代码审查时 | | [02 可行性与假设验证](02-feasibility.md) | 哪些已知、哪些待验证、失败后怎么办 | 开始工作包、变更传输方式或发现新事实时 | | [03 开发周期与工作包](03-development-plan.md) | 按什么顺序做、预计多久、每步交付什么 | 安排任务、报告进度时 | | [04 测试计划](04-test-plan.md) | 用什么证据证明行为没被压缩坏 | 写测试、修改实现、回归和现场验收时 | | [05 准出与发布条件](05-release-criteria.md) | 什么叫完成、什么情况不能发布 | 合并、发布、宣称完成前 | | [06 执行记录与变更模板](06-execution-records.md) | 如何留下可核对的过程和结果 | 每个工作包开始与结束时 | 当前 W5 工具迁移记录见 [现有工具与完整回归](records/W5-tools.md)。 技术决策使用 `T-xx`,假设使用 `H-xx`,工作包使用 `W0` 至 `W6`,测试使用 `UT/IT/LT-xx`,准出条目使用 `RC-xx`。执行记录必须引用这些编号,使需求、实现、测试能相互追溯。 实际开发时直接使用 [开发计划第 2.1 节的阶段执行对照表](03-development-plan.md):每一阶段都列明必须查阅的约束、需要验证的假设及完成证据。此要求也写入仓库根 [AGENTS.md](../../AGENTS.md),后续任务进入 Italy 工作时必须先读取。文档按技术方案约束实现;不能在实现之后悄悄改文档或测试来迁就代码。 ## 3. 当前事实基线 核对日期:2026-09-01;代码提交:`a22596f1fcdffb946960724ef299f249e7860891`。 | 文件 | 基线行数(`wc -l`) | 说明 | | --- | ---: | --- | | `plugins/ita_plugin.py` | 6286 | 11 个旧运行时文件机械合并后的单文件 | | `plugins/tls_plugin.py` | 852 | 已复用浏览器公共工具及 `BaseFlow` | | `plugins/vfs_plugin.py` | 1271 | 已复用浏览器公共工具、云端邮件 API 等 | | `plugins/bls_plugin.py` | 1107 | HTTP 为主,复用现有云端接口和类型 | 行数包含注释、空行和 JavaScript;其他插件也调用公共模块,因此入口行数不是项目的全部运行时代价。 现场约束:`config/test_conf.json` 有用户改动,多份旧 Italy 文档处于删除状态。本目录是新文档集,不恢复或覆盖这些改动。旧源码和历史提交是参考证据,不是新实现已经通过测试的证明。 ## 4. 每个工作包怎么执行 1. 读取对应技术决策、假设、测试及准出条目,检查实际代码是否仍符合记录。 2. 写明本次范围、文件、复用对象、预期行数变化和验证办法,再开始已获授权的修改。 3. 优先复用现成函数;需要增加抽象时写清现成实现为什么不能覆盖。 4. 结束时填写实际改动、精确命令、退出码、测试结果、行数及剩余问题。 5. 有未通过的前置条件,不把下一步或最终完成标成通过。可以做不依赖该条件的其他工作,但必须如实记录。 文档不是额外的形式主义:一个工作包只需一份简洁记录,不为每个函数生成一份报告。 ## 5. 方案变更规则 - 本目录技术约束不得被临时调试代码、旧注释或测试夹具悄悄覆盖。 - 一般实现细节可在已批准方案内决定,并在执行记录说明。 - 架构、功能范围、约 1000 行目标、公共 API、配置语义、账号隔离、预约提交与重试策略的改变,必须先给出证据和文档差异,取得用户确认后实施。 - 不得为已写出的代码倒改测试或准出标准,使其看起来完成。 - 修改文档时同步更新受影响的测试、工作包和准出引用;旧证据保留并标明失效原因。 - 实施、Git 提交/推送、部署、真实预约的授权分别核对,不由文档自动授予。 ## 6. 当前下一步 生产运行时已从 6286 行收敛到 1178 行,主要通过直接复用 `perform_browser_fetch`、`BaseFlow`、`init_chromium_options`、`cleanup_browser_workspace`、`filter_dates_in_range`、`VSCloudApi.fetch_mail_content` 和宿主公共类型,删除私有请求监听、诊断状态机、回执协调器与重复页面快照。Query 保持逐月扫描并在首个正向月份停止;Book 在申请人会话重新读取库存、选择日期/时段,最终写入每次调用至多一次,普通失败交回现有 Booker。2026-09-01 现场发现并修复 Booking/Purpose 异步选项晚于首次预检的竞态;表单未就绪现在有界轮询,且不会提前触碰 Turnstile 或发送 OTP。 Italy 专属测试与辅助模块现已统一归档到 `test/ita/`;新的 Italy 测试继续放在该包内,通用测试根目录不再散落 Italy 文件。无调用者的 `utils/ita_local_profile.py` 及两个只测试已删除本地调试工具的文件已经移除,混合测试中对应的持久 Profile 用例也已清理。当前公开薄合同 68 项通过;完整 discovery 仍如实暴露其他依赖已删除私有符号或历史工具的旧消费者。 下一步不是继续设计生产架构,而是迁移仍导入已删除私有符号的 Italy 调试工具和旧测试,使它们调用公开 Query/Book 合同;不能把旧私有实现重新塞回生产来换取测试通过。完成迁移后再跑完整 Italy/调试/热更新回归,并在另行授权下执行真实站点 Query、预提交和单次最终验收。实施授权仍不自动包含 Git、推送、部署或真实预约。