版本:1.1;日期:2026-09-01;配套:入口、可行性、测试计划。
2026-09-01 用户确认的方案覆盖:Italy 调试阶段允许记录 OTP、Token 与敏感表单,后续再单独删除;最终提交失败、超时或结果未确认时按普通失败交回现有 Booker 重试。本文以下规范已按该决定更新;此前执行记录保留为历史证据,不再代表当前目标语义。
2026-09-02 测试范围更新:用户明确授权删除剩余 20 个导入失败的旧测试模块,具体范围见 清理记录。对这 20 个文件不再要求逐个迁移后才能删除;其他有效测试保留。该决定不改变业务需求、公共复用和真实预约成功的准出要求,也不把未覆盖的历史场景记为已验证。
2026-09-02 错误处理补充:按用户最新 CR 使用框架默认异常,公开入口不得将 Session、限流、权限或 NotFound 包装成统一普通失败。最终明确业务拒绝返回 success=False;网络/格式异常和标准状态码抛相应框架异常。它们仍交给既有 Booker 处理,不增加 Italy 重试状态机。当前提交响应与合成回执路径的证据边界见 修复记录。
把 Italy 收敛为现有 Coordinate 框架中的薄网站适配器。采用现有 IVSPlg 接口、公共工具和少量网站专属函数;不新建插件内部调度框架、通用预约引擎或传输自动切换框架。
现有 Sentinel → 池子账号的 ItaPlugin.query → VSQueryResult → 现有 Redis 信号
现有 Booker ← 信号 → 用户账号的 ItaPlugin.book → VSBookResult / 现有异常
Query 和 Book 使用独立的实例/会话;信号只携带公共查询结果。网站运行时 ID、Cookie、OTP、选中状态不跨账号传递。
| 编号 | 决策 | 实现边界 |
|---|---|---|
| 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 | 有行为证据才算完成 | 迁移业务测试,不通过删除失败测试、跳过测试或只测新辅助函数证明成功 |
plugins/ita_plugin.py建议只保留以下结构,名称可微调但职责不能扩散:
ItaLoginFlow(BaseFlow):Italy 特有的首页、登录表单、验证等待及成功页判断。ItaPlugin(IVSPlg):公开接口和实例会话状态。不为每个步骤建立一个类。配置可用项目现有 Pydantic 能力或简单结构集中校验;内部日历数据不再层层转换成多套“证明对象”。也不强制把所有逻辑塞进一个超长 book()。
utils/plugin_utils.py、utils/flow_engine.py、toolkit/vs_cloud_api.py、vs_types.py 等现有位置。tools.*、test.* 或另一份 Italy 私有实现。| 能力 | 现成参照 | 动作 | 必须处理的差异 |
|---|---|---|---|
| 浏览器/端口/代理/启动参数 | 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 就认定公共化。
下表是分区预算,不是已实现结果。分区允许互相调整,但完整文件预算仍为 1000 行。
| 基线部分 | 基线行数 | 主要减法 | 目标行数 |
|---|---|---|---|
| 配置/协议/数据模型/校验 | 1146 | 一次入口校验,保留网站解析,删除重复类型和状态推导 | 140 |
| Query/Book 日历 | 1348 | 一套月份读取与日期解析,两个明确的业务流程 | 180 |
| 最终提交/预约记录/回执 | 1189 | 复用宿主普通失败/重试;只保留身份、选择、单次点击和最小成功判定 | 140 |
| 表单/OTP/验证等待/工作流 | 1063 | 直接的准备函数;移除生产对验收报告的依赖 | 240 |
| 插件入口/登录/会话/清理 | 1530 | 公共初始化与调度、简洁状态、既有宿主生命周期 | 220 |
| 文件组织开销 | 10 | 统一导入与必要注释 | 20 |
| 合计 | 6286 | 1000 |
统计包含空行、注释和内嵌 JavaScript,文件保留末尾换行。不以分号拼行、巨型字符串外置、动态加载旧代码等手法达标。提交验收时同时报告新增公共生产代码、删除代码和全仓净变化;超过预算必须先记录原因并取得用户对调整的确认,不能自行放宽。
输入为现有 AppointmentType,输出为现有 VSQueryResult。
InsertNewBooking,也不会把进入 Booking 表单或 HTTP 200 当作有号证据。services_probe/services_probe_only 是现有兼容项。实施前逐项登记其消费者:保留作为内部服务入口检查或显式诊断,不再让生产 Query 把弱信号发布成真实档期。不支持的旧路由必须明确报配置能力不足,不能静默变成“无号”。
输入为 Query 信号和现有订单用户字段,输出为 VSBookResult 或现有框架异常。
final_submit_enabled=false 时只走到选中并核对,不产生最终请求,返回 success=false 和明确的预提交标签。book() 调用最多点击一次最终按钮。book() 时必须重新进入服务、准备日历、重查库存并取得新的运行时 ID。仍健康的申请人登录会话可以复用,不强制重复登录;Italy 不维护跨调用的未知暂停状态或持久提交 fence。book() 调用内自旋重提、切换通道重发,或复用上一次调用的运行时 ID;每次重试都从当前申请人会话和当前库存重新开始。网站回执可能提供分配到的具体时间,而不是选择时段的完整区间;须按已验证语义比较,不能为了简化错误要求两者字符串完全相同。
noreply-prenotami@esteri.it、OTP 模板及发送时间窗口。后端 From/To 过滤不是发件人身份认证,不夸大其保证。fetch-top 作为自动回退读取旧验证码;超时不自动重发 OTP。set_config、query_mode、otp_mode、apt_configs、提交开关等现有使用方式需做兼容测试;新增必填项须先获得确认。优先采用已验证路径。浏览器流程已具备历史证据;日历 API 经 H-04 对照证明等价后,才用公共浏览器 fetch 或纯 HTTP 替换对应步骤。网络错误不代表应在同一次调用中切换账号、IP 或传输方式;最终写操作的普通重试由后续 Booker 调度重新进入完整 Book 准备流程,健康的已认证会话可继续使用。
本轮禁止:新调度器、新 OTP 服务、新通用协议校验框架、新的 Italy 私有辅助运行时、新打包/动态执行方案、为凑行数删除结果核验或必要测试。
以下为基线符号位置,未来行号可变化,以符号名和 Git 提交为准: