zhangweijp df478e42e0 代码优化,无用文件删除 před 2 měsíci
..
records 835fa2fbd5 refactor(italy): simplify plugin and consolidate tests před 2 měsíci
01-technical-design.md df478e42e0 代码优化,无用文件删除 před 2 měsíci
02-feasibility.md 835fa2fbd5 refactor(italy): simplify plugin and consolidate tests před 2 měsíci
03-development-plan.md 835fa2fbd5 refactor(italy): simplify plugin and consolidate tests před 2 měsíci
04-test-plan.md df478e42e0 代码优化,无用文件删除 před 2 měsíci
05-release-criteria.md 835fa2fbd5 refactor(italy): simplify plugin and consolidate tests před 2 měsíci
06-execution-records.md df478e42e0 代码优化,无用文件删除 před 2 měsíci
07-reduction-inventory.md 835fa2fbd5 refactor(italy): simplify plugin and consolidate tests před 2 měsíci
README.md df478e42e0 代码优化,无用文件删除 před 2 měsíci

README.md

Italy 插件精简重构:文档入口与执行约定

版本:1.1;建立日期:2026-09-01。

最新状态(2026-09-02,覆盖下方历史状态): 按用户明确授权删除 20 个导入失败的旧测试模块,当前 test/ita 完整发现 131 项通过,0 错误、0 跳过。这不代表所有历史场景均已迁移或真实预约已成功。Italy 仍为 1.0.3、1202 行;本轮未改生产代码、原账号配置或其他插件。删除清单和恢复依据见 旧测试清理记录。第 2 批 和 第 1 批 保留历史过程。

最新架构决定(CR-001,2026-09-01,用户已确认):Italy 调试期允许记录 OTP、Token 与敏感表单;最终提交失败、超时或结果未确认按普通失败交回 Booker 后续重试。单次 book() 仍最多点击一次,Query 仍不得产生最终写入。此决定覆盖旧文档中的脱敏准出和 BookingOutcomeUnknownError 暂停策略。

本目录记录用户要求的约 1000 行 Italy 插件技术方案,以及可行性、开发周期、测试和准出要求。后续相关开发必须以本目录为依据,不允许实现过程中另起一套架构。

当前状态:方案文档已建立;W0 行为基线、W1 公共能力 与 W2 登录/准备收敛 已留档。W3 查询入口及共用日历、W4 Book 与提交职责收敛 仍只部分完成。W5 已把失效的旧文档账号池命令迁到现有 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 技术方案 代码放哪里、复用谁、哪些删、哪些保留 开始任务、设计或代码审查时
02 可行性与假设验证 哪些已知、哪些待验证、失败后怎么办 开始工作包、变更传输方式或发现新事实时
03 开发周期与工作包 按什么顺序做、预计多久、每步交付什么 安排任务、报告进度时
04 测试计划 用什么证据证明行为没被压缩坏 写测试、修改实现、回归和现场验收时
05 准出与发布条件 什么叫完成、什么情况不能发布 合并、发布、宣称完成前
06 执行记录与变更模板 如何留下可核对的过程和结果 每个工作包开始与结束时

当前 W5 工具迁移记录见 现有工具与完整回归。

技术决策使用 T-xx,假设使用 H-xx,工作包使用 W0 至 W6,测试使用 UT/IT/LT-xx,准出条目使用 RC-xx。执行记录必须引用这些编号,使需求、实现、测试能相互追溯。

实际开发时直接使用 开发计划第 2.1 节的阶段执行对照表:每一阶段都列明必须查阅的约束、需要验证的假设及完成证据。此要求也写入仓库根 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、推送、部署或真实预约。