01-technical-design.md 13 KB

Italy 插件约 1000 行技术方案

版本:1.1;日期:2026-09-01;配套:入口、可行性、测试计划。

2026-09-01 用户确认的方案覆盖:Italy 调试阶段允许记录 OTP、Token 与敏感表单,后续再单独删除;最终提交失败、超时或结果未确认时按普通失败交回现有 Booker 重试。本文以下规范已按该决定更新;此前执行记录保留为历史证据,不再代表当前目标语义。

1. 总体决策

把 Italy 收敛为现有 Coordinate 框架中的薄网站适配器。采用现有 IVSPlg 接口、公共工具和少量网站专属函数;不新建插件内部调度框架、通用预约引擎或传输自动切换框架。

现有 Sentinel → 池子账号的 ItaPlugin.query → VSQueryResult → 现有 Redis 信号
现有 Booker   ← 信号 → 用户账号的 ItaPlugin.book → VSBookResult / 现有异常

Query 和 Book 使用独立的实例/会话;信号只携带公共查询结果。网站运行时 ID、Cookie、OTP、选中状态不跨账号传递。

2. 必须保留的技术决策

编号 决策 实现边界
T-01 单文件、约 1000 行 唯一 Italy 专属生产上传文件是 plugins/ita_plugin.py;不新增其运行时辅助模块
T-02 公共能力优先 先调用现有函数;确有通用缺口才向后兼容扩展公共模块
T-03 Query 只查询 逐月扫描,首个正向月份停止,返回其中最早日期;不能把“进入表单”报告为真实有号
T-04 Book 只预约 不调用公开 query() 伪装内部步骤;在用户会话重新检查库存、筛选日期、选择时段、提交和核验
T-05 多领区靠配置 apt_configs[routing_key] 决定服务及表单差异;香港仅作样本,不硬编码服务、邮箱或日期
T-06 按证据选传输方式 无浏览器依赖的接口用 HTTP;依赖会话环境的读取可用公共浏览器 fetch;必要交互用浏览器
T-07 自动 OTP 复用云端 使用现有邮件 API,绑定当前账号与发送时间;邮件只用于提取预期验证码
T-08 会话准备共用、状态隔离 Query/Book 可调用相同内部准备函数,但每个实例持有自己的账号、路由和会话状态
T-09 最终提交使用普通重试 每次 book() 调用在提交前复核选择且最多点击一次;失败、超时或结果未确认统一作为普通失败返回,由现有 Booker 在后续调度中重试,不保留 Italy 专属未知暂停状态机
T-10 诊断不支配生产结构 生产保留必要日志;当前调试阶段允许记录 OTP、Token 与敏感表单,不再保留专门的脱敏包装层。后续删除敏感日志是独立工作,不阻塞本轮精简
T-11 配置与公共接口兼容 保持 IVSPlg、公共返回类型和已部署配置含义;不再发布弱信号有号结果,旧探测入口需明确迁移
T-12 有行为证据才算完成 迁移业务测试,不通过删除失败测试、跳过测试或只测新辅助函数证明成功

3. 文件与函数放在哪里

3.1 plugins/ita_plugin.py

建议只保留以下结构,名称可微调但职责不能扩散:

  • 导入、网站常量、少量解析函数和网站 DOM 脚本。
  • ItaLoginFlow(BaseFlow):Italy 特有的首页、登录表单、验证等待及成功页判断。
  • ItaPlugin(IVSPlg):公开接口和实例会话状态。
  • 私有业务步骤:解析路由、进入服务、准备日历、读取月份、读取时段、选中并核对、提交并核验回执。

不为每个步骤建立一个类。配置可用项目现有 Pydantic 能力或简单结构集中校验;内部日历数据不再层层转换成多套“证明对象”。也不强制把所有逻辑塞进一个超长 book()。

3.2 公共模块和测试工具

  • 已有公共能力继续留在 utils/plugin_utils.py、utils/flow_engine.py、toolkit/vs_cloud_api.py、vs_types.py 等现有位置。
  • 不把 Italy 的服务字段、领区配置、页面选择器或回执模板放进公共模块。
  • 测试与诊断可分文件,但运行时禁止依赖 tools.*、test.* 或另一份 Italy 私有实现。
  • 旧调试入口必须改为调用新公开接口或明确给出替代命令,不能留下导入已删除类型的损坏入口。

4. 复用清单

能力 现成参照 动作 必须处理的差异
浏览器/端口/代理/启动参数 plugin_utils.init_chromium_options;VFS/TLS create_session 直接复用,删除手写初始化 持久化目录由调用方提供,不能误删
登录调度 flow_engine.BaseFlow/on/guard/done;TlsLoginFlow 复用调度,只写 Italy 页面规则 关闭会导致重复登录提交的停滞刷新;当前调试期可保留 OAuth/Token 诊断,后续统一清理
鼠标/键盘及验证交互 现有 HumanMouse、HumanKeyboard、验证辅助代码 继续复用,去掉额外对象层 以页面真实就绪状态为准,不伪造验证成功、不无限重复尝试
浏览器内 HTTP plugin_utils.perform_browser_fetch 对经验证可用的读取接口复用 校验状态、返回结构、会话归属;提交超时不走通道切换重发
纯 HTTP BLS 使用的现有 HTTP 库和会话模式 仅在 H-04 通过后采用 不复制 BLS 的网站字段,不新建统一客户端框架
日期筛选 plugin_utils.filter_dates_in_range 使用 shuffle=False 缺少一端时先补默认边界;最早日期不能依赖随机排序
邮件读取 VFS/BLS 的 VSCloudApi.fetch_mail_content 直接复用 Italy 仍须使用自己的发件人/模板约束和当前账号绑定
返回值/异常 VSQueryResult、VSBookResult、现有异常 直接使用 无号、认证失效和限流仍明确区分;最终提交未确认按宿主可重试的普通失败处理
生命周期清理 cleanup_browser_workspace 复用主要能力 现有函数会忽略部分异常,持久化锁需保留失败处理
池子/退避/信号/订单 Sentinel、Booker、现有云端 SDK 不改调度,不在插件重写 不增加第二套账号选择、Redis 协议或订单状态机

公共清理函数是本轮唯一预先列出的公共扩展候选:提供可选严格模式或清理结果,默认调用行为不变。实际接口需先完成 H-02;若不需要扩展,优先零公共改动。

新增公共能力必须说明真实消费者。优先有两个以上插件可直接复用;属于现有公共函数的通用结果补全时,也须验证原 VFS/TLS 调用不退化。不得仅把函数改名、移到 utils 就认定公共化。

5. 6286 行如何减少

下表是分区预算,不是已实现结果。分区允许互相调整,但完整文件预算仍为 1000 行。

基线部分 基线行数 主要减法 目标行数
配置/协议/数据模型/校验 1146 一次入口校验,保留网站解析,删除重复类型和状态推导 140
Query/Book 日历 1348 一套月份读取与日期解析,两个明确的业务流程 180
最终提交/预约记录/回执 1189 复用宿主普通失败/重试;只保留身份、选择、单次点击和最小成功判定 140
表单/OTP/验证等待/工作流 1063 直接的准备函数;移除生产对验收报告的依赖 240
插件入口/登录/会话/清理 1530 公共初始化与调度、简洁状态、既有宿主生命周期 220
文件组织开销 10 统一导入与必要注释 20
合计 6286 1000

统计包含空行、注释和内嵌 JavaScript,文件保留末尾换行。不以分号拼行、巨型字符串外置、动态加载旧代码等手法达标。提交验收时同时报告新增公共生产代码、删除代码和全仓净变化;超过预算必须先记录原因并取得用户对调整的确认,不能自行放宽。

6. Query 合同

输入为现有 AppointmentType,输出为现有 VSQueryResult。

  1. 根据 routing key 解析服务配置,确认当前账号/服务会话。
  2. 首次进入日历可完成网站要求的表单和 OTP;有效会话内不重复准备。
  3. 从当前查询起点按月升序扫描,最多扫描配置的月份数,不无限翻页。
  4. 首个正向月份出现后停止;从该月真实正向日期中取最早日期。
  5. 日历日期信号可不携带时段;Book 自己在用户会话重新读取。
  6. 当前月为空不等于所有月份无号;扫描达到约定范围且无正向结果才报告该范围无号。
  7. 查询不会触发 InsertNewBooking,也不会把进入 Booking 表单或 HTTP 200 当作有号证据。

services_probe/services_probe_only 是现有兼容项。实施前逐项登记其消费者:保留作为内部服务入口检查或显式诊断,不再让生产 Query 把弱信号发布成真实档期。不支持的旧路由必须明确报配置能力不足,不能静默变成“无号”。

7. Book 合同

输入为 Query 信号和现有订单用户字段,输出为 VSBookResult 或现有框架异常。

  1. 验证申请人账号与当前 Book 会话一致;不能直接使用池子账号的 Cookie、验证码或时段 ID。
  2. 在申请人会话进入目标服务、完成必要准备,重新读取真实库存。
  3. 使用现有期望起止日期字段筛选;默认按日期、时段升序选择,不引入新的随机策略。
  4. 日期有号但时段已耗尽时,继续检查允许范围内的下一候选,不把旧 Query 信号当库存承诺。
  5. 提交前检查当前服务、日期、时段、容量与选中 DOM 一致;所有运行时 ID 来自当前 Book 会话。
  6. final_submit_enabled=false 时只走到选中并核对,不产生最终请求,返回 success=false 和明确的预提交标签。
  7. 开启提交且具备当前任务授权时,自动提交,不要求终端输入冗长确认句;一次 book() 调用最多点击一次最终按钮。
  8. 网站明确返回成功且能读到与当前申请人、服务、日期及时段相符的结果时返回成功;明确拒绝、超时、断线或证据不足均返回普通失败。
  9. 普通失败交回现有 Booker;后续信号/调度再次调用 book() 时必须重新进入服务、准备日历、重查库存并取得新的运行时 ID。仍健康的申请人登录会话可以复用,不强制重复登录;Italy 不维护跨调用的未知暂停状态或持久提交 fence。
  10. 禁止在同一次 book() 调用内自旋重提、切换通道重发,或复用上一次调用的运行时 ID;每次重试都从当前申请人会话和当前库存重新开始。

网站回执可能提供分配到的具体时间,而不是选择时段的完整区间;须按已验证语义比较,不能为了简化错误要求两者字符串完全相同。

8. OTP、配置和会话

  • 继续支持配置邮箱与按当前账号邮箱派生两种已存在的授权来源;不能固定某个测试邮箱。
  • 使用网站已观察的 noreply-prenotami@esteri.it、OTP 模板及发送时间窗口。后端 From/To 过滤不是发件人身份认证,不夸大其保证。
  • 邮件正文是数据,只提取预期 ASCII 验证码,不执行内容、不交给大模型。保留前导零;多个冲突验证码应拒绝。
  • 不以 fetch-top 作为自动回退读取旧验证码;超时不自动重发 OTP。
  • 保留自动 OTP,手动模式仅作为显式调试能力;不得为精简恢复成强制人工接码。
  • 当前调试阶段允许日志、测试输出和诊断快照包含 OTP、Token 与敏感表单;不再以脱敏包装和“不落日志”测试作为本轮准出条件。账号密码、配置文件和真实秘密仍不得因此写入 Git。
  • 会话状态合并为少量字段,但保留账号、路由、浏览器实例、有效期和准备状态绑定。
  • 生命周期仍由宿主驱动;持久化目录复用、清理失败、跨实例恢复的既有行为必须有迁移清单,不能无声删除。
  • set_config、query_mode、otp_mode、apt_configs、提交开关等现有使用方式需做兼容测试;新增必填项须先获得确认。

9. 传输方式与禁止事项

优先采用已验证路径。浏览器流程已具备历史证据;日历 API 经 H-04 对照证明等价后,才用公共浏览器 fetch 或纯 HTTP 替换对应步骤。网络错误不代表应在同一次调用中切换账号、IP 或传输方式;最终写操作的普通重试由后续 Booker 调度重新进入完整 Book 准备流程,健康的已认证会话可继续使用。

本轮禁止:新调度器、新 OTP 服务、新通用协议校验框架、新的 Italy 私有辅助运行时、新打包/动态执行方案、为凑行数删除结果核验或必要测试。

10. 代码证据导航

以下为基线符号位置,未来行号可变化,以符号名和 Git 提交为准: