# Italy 插件:通用短期申根旅游签证单人预约交付方案 > 状态:CS3A VERIFIED(一次负责人现场回传);CS3B / OTP-AUTO 邮箱接入列为待办,暂缓 > > 修订:2026-08-30 / R5(保留 R3/R4 的设计与历史验证记录) > > 当前 Query 恢复合同:[CS3R:掉线恢复与持续盯号](./ita_query_recovery.md)。本地实现、387 项 Italy 回归及零网络预检已验证;E51 的 15 分钟实测已通过(909 秒、3 次查询、1 次受控恢复、exit 0,版本指纹一致)。真实认证过期及 2/24 小时现场证据待补。自动处理重新需要 OTP 仍是必须完成的 ITA-OTP-01,不以人工停止点代替完成。CS3R 不授权上线或 Book 最终提交。 > > 唯一事实源:[Italy Discovery](./ita_plugin_discovery.md) > > 历史实现记录:[Italy Recovery Design](./ita_plugin_recovery_design.md) > > 约束:香港是第一条正向协议样本,不是代码分支;Dublin 是无号回归样本,不是默认产品目标。CS3A 的人工准备加两次生产 Query 已通过一次现场验收;负责人确认 Query 邮箱尚未接入并授权云邮箱 API,要求记为待办。当前不执行邮箱接入、新的 OTP、真实取信、共享框架修改或最终预约。 ## 0. D0 设计审查什么算完成 D0 只完成设计审查。以下条件必须同时满足,缺一项都不能说“方案完成”: 1. 当前代码、VFS/BLS、Sentinel/OrderBooker 和 E1–E44 证据之间没有未解释的矛盾; 2. “如何发现真实号源”“如何把信号交给用户账号”“如何只提交一次最终预约”各有机械判定合同; 3. 所有 P0/P1 都有唯一状态:已关闭、由某个 Change Set 关闭,或由明确的外部 Gate 关闭;不得存在无负责人、无验证方法的“以后再看”; 4. 配置、文件边界、状态机、重试、恢复、测试、准出、回滚全部可执行; 5. 生产方案不依赖香港/Dublin 条件分支,不复制 Query 账号的 Cookie、页面对象或临时 Slot ID; 6. E43/E44 正向 Slot 只用于解析、页面选择与 precommit 取证;没有最终授权时 InsertNewBooking 必须为 0; 7. 文档结构检查、陈旧结论反向扫描、敏感信息扫描和 whitespace 检查全部 exit 0; 8. D0 阶段对 plugins、tools、test 和 config 的新增修改数为 0。 2026-08-29 负责人随后明确批准 R3、CS1 和 CS2。该批准不改写 D0 的历史完成标准;CS1/CS2 的实际文件、测试和边界记录在 §17、§23.2 与 §23.3。 ## 1. 结论先说人话 旧方案只有一半正确。 正确的一半是: ~~~text 团队账号负责发现 → Sentinel 发布短 TTL 信号 → 用户账号自己的热 Session 收到信号 → 用户账号重新检查 → 只使用当前 Session 的日期、时间和动态状态完成预约 ~~~ 不正确的一半是:把“能进入 bookingForm”当成足够好的生产信号。 香港已经真实证明两件必须同时记住的事: ~~~text GET /Services/Booking/4937 → 200 + bookingForm → OTP + AVANTI → Calendar ├─ 默认 2026-08 窗口:日期/时段均为负向 └─ 向后到 2026-10:出现真实正向日期与时段 Availability:SlotLiberi=1 / SlotRimanenti=0 TimeSlot:普通 fascia、无红点、显示 (1) ~~~ 所以,bookingForm 只表示“门开着”,不携带日期、扫描范围和容量;它既不能单独证明有号,也不能单独证明无号。若 Sentinel 每 60–300 秒都把这个弱事实发给用户 Book,用户账号会反复发送 OTP,却仍不知道目标日期范围内是否有 Slot。这既不能可靠回答“什么时候有号”,也不珍惜真实机会。 R3 的推荐方案是: ~~~text 团队 Query 账号 ├─ 每个认证/业务 Session 至多一次: │ 原生选择单人 + 旅游 → Privacy → OTP → AVANTI │ 进入自己的 Calendar Session │ └─ 后续每个 Query probe: 在配置日期范围内逐月读取 Availability → 不能因默认月份无号提前结束 → 至少一个正向日期才返回 Available → times 保持空;不把动态 Slot 状态跨账号传递 Sentinel → 原样发布 VSQueryResult Available 强信号 用户 Book 账号 → 独立登录、独立 OTP、独立 Calendar → 重查同一服务、日期和时段 → 满足全部提交前不变量后 → 原生点击一次 btnPrenotaNoOtp → 只读核对预约结果 ~~~ 这叫“准备型 Calendar Query”。它复用 VFS/BLS 已有的最小强信号:Query 发布真实日期,`DateAvailability.times=[]`,Book 在自己的 Session 重新查具体时段;也复用现有账号池和信号链路。Query 不主动为每个日期扇出 TimeSlots 请求,页面原生自动产生的 TimeSlots 只作为诊断,不作为信号前提。它比旧弱信号多一次团队账号的 OTP + AVANTI 副作用,因此必须经过单独授权和无预约副作用 Gate。E43 已用同日 TimeSlots 交叉证明 Availability 的正向 `1/0` 确实对应一个真实时段,但没有替这些安全 Gate 背书。 旧弱信号仍有价值,但只用于 Discovery、告警或手工唤醒,默认不得触发生产 Book。 ## 2. “100% 信心”如何工程化 外部网站、自然放号和网络永远不受本项目 100% 控制。把这种不确定性口头改成“有信心”是不诚实的。 本方案把 100% 定义成分阶段准入: | 阶段 | 达到 100/100 的机械条件 | 当前状态 | |---|---|---| | 设计一致性 | 本文无内部矛盾;P0/P1 全部有关闭路径;检查 exit 0 | 已验证 D0 | | CS1 配置与纯解析器 | 只实现已观察 schema;全部离线 fixture 通过;网站写请求 0 | 已验证:28 个协议测试 + 30 个现有 Italy 回归测试 | | CS2 通用路线接线 | Plugin、配置和本地工具只从 routing key 解析 route;HK/Dublin 同路径;网站请求 0 | 已验证:137 个相关离线测试 + 静态扫描 | | 强 Query | 团队账号准备 Calendar 被单独授权;预约列表前后不变;重复只读 probe 无 OTP/AVANTI/最终 POST | 外部 Gate | | Book 到最终按钮前 | 用户 Session 的 OTP、AVANTI、Calendar、正向 Slot 合同全部真实验证;最终 POST=0 | 外部 Gate | | 一次最终 Canary | 用户明确需要该真实预约;preflight 全绿;InsertNewBooking 次数=1;结果可权威核对 | 外部 Gate | | 生产准出 | 端到端 Canary 成功;异常响应和重启恢复不重复提交;第二 Sede 同协议验证 | 外部 Gate | 纪律是:某阶段没有达到 100/100,就不进入该阶段的有副作用动作;不是把总置信度四舍五入成 100。 ## 3. 产品目标、范围和成功定义 ### 3.1 产品目标 使用已明确授权的团队成员真实账号检测任意已配置 Prenot@Mi Sede 的单人短期申根旅游签证真实号源,并使用申请人自己的真实账号完成预约。 香港用于跑通第一条完整成功链;通用性由配置和第二 Sede 回归证明。 ### 3.2 首版范围 - 一位申请人; - 短期申根; - 目的为旅游; - 团队账号 Query,用户账号 Book; - 用户日期范围过滤; - 当前页面原生 Turnstile 状态; - 邮件 OTP; - 一个 OrderBooker 实例处理一份订单; - 最终返回预约编号、日期、时间和账号; - 未知页面、未知字段、未知 Slot 状态一律 fail-closed。 ### 3.3 明确不做 - 家庭、多人、同行人; - 商务、探亲、学习、工作、国家 D 类签证; - 自动切换 Sede; - 自动取消、改期或候补; - 绕过 CAPTCHA、Turnstile、限流或网站公平机制; - 从传闻预测放号时间; - Query 与 Book 共享 Cookie、Profile、DOM 或 CSRF; - 为香港复制一个 ita_hk_plugin.py; - 在本项目中重做 Sentinel、OrderBooker、Redis、邮箱服务或工作流引擎; - 未经用户授权执行真实最终预约。 ### 3.4 什么才叫 Book 成功 以下五项必须同时成立: 1. POST /BookingCalendar/InsertNewBooking 在本次机会中恰好执行一次; 2. 服务端结果或随后只读的 /Reservation 显示一条新预约; 3. 预约编号、日期和时间来自同一条记录; 4. 日期、时间、Sede 和目标 route 与本次选择一致; 5. VSBookResult.success=True 且 urn/book_date/book_time/account 全部填充。 OTP 发送成功、AVANTI 302、进入 Calendar、看到正向日期、点击 PRENOTA、HTTP 200 都不能单独算成功。 ## 4. 当前事实与代码现状 ### 4.1 已真实验证的网站链 ~~~text Public / IAM → callback_1 + callback_2 → /UserArea → /Services → /Services/Booking/{service_id} ├─ Dublin 1321:302 → /Services + 明确无号 marker └─ Hong Kong 4937:200 + bookingForm → single=1 → tourism=42 → PrivacyCheck → GET GenerateOTP:200 / SENT / 邮件送达 → OTP 输入 → 原生 AVANTI → POST /Services/Booking/4937:302 → GET /BookingCalendar?...:200 → Availability / TimeSlots → btnPrenotaNoOtp → POST InsertNewBooking [从未执行] ~~~ 关键纠正: - OTP 在 AVANTI 之前,不在 Calendar 之后; - Calendar 上的 btnPrenotaNoOtp 是最终预约按钮,不会再发送第二次 OTP; - bookingForm 本身不能表达号源;同一流程既观察到默认月份无号,也观察到后续月份有号; - selected、active、enabled 按钮都不等于有号; - 配置中的 Services service_id 与 Calendar DOM 的 #idServizio 不是同一来源,禁止混用; - 最终 handler 从 active Slot 的后代 input 取 daily calendar ID,而不是全局按重复 HTML id 查找。 ### 4.2 Calendar 已观察协议 | 能力 | Method / Path | 已观察输入 | 已观察输出 | |---|---|---|---| | 日期 | POST /BookingCalendar/RetrieveCalendarAvailability | JSON:_Servizio、selectedDay | 外层 JSON 字符串,内层数组:DateLibere、SlotLiberi、SlotRimanenti | | 时段 | POST /BookingCalendar/RetrieveTimeSlots | JSON:selectedDay、idService | 外层 JSON 字符串,内层数组;含两个 Slot 数量、时间和 daily ID | | 最终预约 | POST /BookingCalendar/InsertNewBooking | form:idCalendarioGiornaliero、selectedDay、selectedHour | 静态观察含 errorMessage、url;真实结果未知 | 网站当前前端判定: - 日期 `SlotLiberi>0 AND SlotRimanenti>=0` 是 E43 已观察的正向组合;`SlotRimanenti=0` 不能判无号; - Slot SlotRimanenti < 0 会得到 notAvailableFascia + dotRed; - SlotLiberi 用于显示括号中的数量;E43 正向 `1/0` 显示 `(1)`,负向 `0/-1` 显示 `(0)`; - 唯一非负 Slot 会自动带 act; - delegated click 甚至能给负向 Slot 加 act,所以 act 不是安全证据; - Calendar 初始化找不到目标日期时会静默回退到第一天并程序化点击; - 当前稳定 DOM 有一个 timeline selected 和一个 content selected,日期值相同。 - 默认 8 月窗口没有正向 Slot,但 10 月存在;任何 Query 都必须扫描完整配置日期范围。 ### 4.3 当前代码已经做到哪里 plugins/ita_plugin.py 当前只实现: 1. IAM 登录并以 /UserArea + .app-menu + /Services 作为成功条件; 2. 从顶层 free_config.service_id 查一个服务; 3. Dublin 已知无号分类; 4. bookingForm 返回 success=True + NoneAvailable 弱信号; 5. Book 使用用户 Session 再调用一次 Query; 6. 到达 bookingForm 后只采集 allowlist 结构,停在 AVANTI 前; 7. keep_alive() 仍为空。 尚未实现: - routing_key → apt_configs; - 香港和多 Sede 调试目标; - 表单选择、Turnstile preflight、OTP、AVANTI; - Calendar/TimeSlots 解析; - 正向 Slot 选择; - 最终一次性提交; - /Reservation 对账; - 模糊结果写屏障。 当前调试工具和大部分 fixture 仍硬编码 Dublin 1321。这属于待通用化的实现债务,不是通用设计。 ## 5. 从大到小复用 VFS/BLS ### 5.1 复用矩阵 | 层级 | 现有参照 | Italy 决策 | 复用程度 | |---|---|---|---:| | 插件接口 | IVSPlg | 原样实现生命周期 | 100% | | Query 调度 | SentinelGCO | 原样使用账号池、节奏和 Redis 发布 | 100% | | 用户 Book | OrderBookerGCO | 原样使用 order 账号和热 Session | 100% | | 账号边界 | VFS/BLS 集成方式 | Query built-in;Book order;状态不共享 | 100% | | route 配置 | VFS/BLS apt_configs[routing_key] | Italy 从顶层单一 service_id 迁移到相同模式 | 100% | | 强信号 | VFS/BLS Available + dates | 生产 Query 发布真实 Calendar 正向日期,`times=[]`;Book 重查时段 | 100% | | 弱信号 | BLS success=True + NoneAvailable + [] | 仅 Discovery/降级诊断,不作为生产精确检测 | 有条件复用 | | Book 重查 | VFS Book 自己查 Calendar/TimeSlot | Italy 用户 Session 独立重查 | 100% | | 日期范围 | VFS 的 Book 内过滤纪律 | 复用边界;改为确定性排序,不复制随机选择 | 规则复用 | | OTP 邮箱 | VFS/BLS VSCloudApi.fetch_mail_content() | 复用 API;Italy 自己配置 sender/subject/regex | 100% 基建复用 | | 结果 | VSBookResult | 原样填充现有字段 | 100% | | 错误类型 | 现有 Biz/Session/RateLimit 类型 | 原样映射;Italy 增加站点内局部分类 | 100% | | 浏览器 Network | USA/TLS 的 page.listen 一次监听 | 用于监听原生动作结果,不手写敏感 POST | 复用现有能力 | | 最终恢复 | VFS/BLS 没有足够的模糊结果合同 | 先用 Prenot@Mi /Reservation 作为权威对账;失败才提框架扩展 | 需 Gate | ### 5.2 复用的本质 复用的是稳定控制结构: ~~~text 账号池 → Session → Query 事实 → 标准结果 → Redis 信号 → 用户 Session 重查 → 标准 Book 结果 ~~~ 不复制: - VFS/BLS 私有 endpoint、payload、hidden field; - 另一个插件的重试次数; - 随机 Slot 选择; - 调试日志里的响应正文、OTP 或动态 Token; - 在 Book 中依赖 Query 插件实例内临时字段的做法; - 另一个网站的 CAPTCHA 处理。 “最大化复用”不等于把别的网站偶然实现也当成规范。 ## 6. 目标架构与文件边界 ### 6.1 模式:Functional Core + Imperative Shell 旧方案建议所有逻辑继续塞进 ita_plugin.py。E22–E44 之后,这个选择不再成立:当前文件已经接近 1,000 行,新增协议又包含双层 JSON、两个 Slot 数量、跨月扫描、异步日期回退、重复 id、selected 一致性和一次性提交屏障。 推荐只新增一个小模块,不新增框架: ~~~text plugins/ita_plugin.py Imperative Shell / Site Adapter - IVSPlg 生命周期 - 浏览器和原生 DOM 交互 - page.listen - OTP/AVANTI/最终点击 - 阶段编排和写屏障 plugins/ita_protocol.py Functional Core - route 配置校验 - 双层 JSON 解码 - CalendarDay / SlotCandidate 纯数据 - 日期范围过滤 - 候选排序 - precommit 不变量 - response 分类 - 不导入 DrissionPage,不访问网络 ~~~ 这样做的长期价值: - 网站输入可以用 E15–E44 脱敏 fixture 机械复现; - 最危险的“能不能提交”判断不依赖浏览器 timing; - 地区差异留在配置,不进入条件分支; - 浏览器层只负责执行已经由纯逻辑批准的动作; - 没有创建新的 scheduler、provider、signal 或 workflow engine。 ### 6.2 计划涉及的文件 | 文件 | 职责 | |---|---| | plugins/ita_plugin.py | 站点适配、原生交互、一次性副作用和 IVSPlg | | plugins/ita_protocol.py | 新增;纯配置/解析/选择/不变量 | | config/config_sentinel.json | 每 Sede 的 apt_configs、Query 模式和安全开关 | | config/config_booker.json | 与 Sentinel 同一 route 合同、Book 模式和安全开关 | | test/test_ita_protocol.py | 新增;E15–E44 纯协议/选择态 fixture | | test/test_ita_plugin.py | 浏览器适配、写次数、错误和结果测试 | | 现有 test/test_debug_ita_*.py | 通用目标和安全停点回归 | | 现有 tools/debug_ita_*.py | 参数化 route;不复制香港工具 | | docs/ita_plugin_discovery.md | 只记录事实,不承载未来设计 | | 本文 | 唯一目标设计、Gate 和发布合同 | 首版禁止修改: - sentinel.py - booker.py - vs_types.py - vs_plg.py - VFS/BLS 插件 - Redis payload - 云端任务接口 若实现被迫修改这些文件,当前 Change Set 立即停止,先提交最小失败测试和扩大范围理由。 唯一已知的潜在例外是最终提交的跨进程持久写屏障。当前 OrderBooker 的 tracker 是 心跳租约,云端 grabbed 状态又发生在成功结果之后;两者都不是“提交前已持久化”的 证据。Gate FENCE-1 会先验证现有任务 API 能否原样承载这个屏障。不能承载时,必须 另开一个最小框架 Change Set 并单独批准;在此之前 final 永久保持 disabled。 ## 7. 通用 route 配置 ### 7.1 配置形状 示意,不是本轮对生产配置的修改: ~~~json { "query_mode": "calendar", "final_submit_enabled": false, "apt_configs": { "slot.hkg.it.tourist": { "service_id": 4937, "capability": "single_schengen_tourism", "calendar_scan": { "lookahead_months": 3 }, "form": { "booking_type_control_id": "typeofbookingddl", "booking_type_value": "1", "booking_type_labels": ["Prenotazione Singola", "Single booking"], "purpose_control_id": "ddls_0", "purpose_value": "42", "purpose_labels": ["Turismo", "Tourism"] }, "mail": { "authorization_email": "", "sender": "", "subject_keywords": "", "body_keywords": "", "otp_pattern": "" } }, "slot.dub.it.tourist": { "service_id": 1321, "capability": "services_probe_only" } } } ~~~ ### 7.2 为什么字段必须放 route 下 - service id 随 Sede/服务变化; - 附加下拉位置和值可能变化; - OTP 邮件模板可能变化; - 一个运行组未来可能包含同一 Sede 的多个目标; - AppointmentType.routing_key 已经是 VFS/BLS 使用的稳定查找键。 ### 7.3 配置机械合同 1. Query 和 Booker 对同一 routing key 的非秘密 route 配置完全一致; 2. service_id 为正整数; 3. capability 必须明确,不能默认猜成 live; 4. live route 必须声明 single + short-stay Schengen + tourism; 5. 表单 value 必须同时通过 DOM label allowlist 交叉确认; 6. 任何新增 required 控件没有映射时,OTP=0、AVANTI=0; 7. 顶层 free_config.service_id 在迁移完成后禁止继续作为运行时真相; 8. 代码中不得出现 if city == ...、if service_id == 4937 一类业务分支。 9. `calendar_scan.lookahead_months` 必须是正整数,并由产品日期窗口和 Q-CAL 实测校准;示例值 `3` 只用于表达“默认月份 + 后续月份”,不是全局常量。 控件结构和值是主合同;本地化 label 只是第二重交叉检查。label allowlist 由 route 配置扩展,不把实现限制为中文、意大利语或英语,也不允许仅凭翻译文案继续提交。 ### 7.4 Sede 隔离 首版每个运行组只服务一个 Sede。一个账号池只放属于该 Sede 的账号;扩容用于容错,不用于提高单位时间请求频率。 同一个 ItaPlugin 能处理多个 Sede,含义是“同一协议 + 不同配置”,不是“一个浏览器同时切换多个 Sede”。 ## 8. Query 设计:真正回答“什么时候有号” ### 8.1 两种模式 | 模式 | 行为 | 信号 | 用途 | |---|---|---|---| | services_probe | 只进入服务入口;不发 OTP | bookingForm 只记录诊断 | Dublin 回归、Discovery | | calendar | 团队账号每 Session 准备一次 Calendar;后续扫描只读 Availability | 至少一个正向日期才发 Available,times 为空 | 生产候选 | services_probe 不得把 bookingForm 弱信号交给生产 OrderBooker。 ### 8.2 Calendar Session 准备 每个 Query 插件实例、每个 route、每个认证 Session 至多执行一次: ~~~text Q0 AUTHENTICATED_USER_AREA → Q1 ROUTE_RESOLVED → Q2 SERVICE_ENTRY → Q3 BOOKING_FORM_VALIDATED → Q4 SINGLE_AND_TOURISM_SELECTED → Q5 PRIVACY_AND_TURNSTILE_READY → Q6 OTP_SENT_ONCE → Q7 OTP_RECEIVED_AND_ENTERED → Q8 AVANTI_SUBMITTED_ONCE → Q9 CALENDAR_READY ~~~ 它不会选择最终日期/时段,也不会点击 btnPrenotaNoOtp。 这一步是团队账号的业务 Session 准备,不是普通只读 Query。必须由配置开关显式启用,且满足: - 账号所有者已授权; - 邮箱读取已授权; - 准备前后 /Reservation 没有新增预约; - 每次 Session OTP=1、AVANTI=1、最终 POST=0; - 结果不明时不重复 OTP/AVANTI; - 账号池增加不提高总 probe 频率。 ### 8.3 日常只读 probe Calendar ready 后,每轮: 1. 校验仍是同一 host、route 和 Calendar; 2. 从当前月份开始,按 `calendar_scan.lookahead_months` 逐月驱动网站原生 Calendar;默认月份无号不能提前结束,但首个正向月份必须立即停止; 3. 每次动作前开启 `page.listen`,捕获当月 Availability response,并在 `finally` 停止监听; 4. 双层解码日期数组,把 `DD/MM/YYYY 00:00:00` 严格归一化为内部日期;重复日期或冲突记录 fail-closed; 5. 只保留 `SlotLiberi>0 AND SlotRimanenti>=0` 的日期,并应用扫描范围; 6. 当前月份出现正向日期时,只在该月份内升序取最早一天并立即停止,不再请求更远月份;如果完整范围都没有正向日期,才返回 `success=False/NoneAvailable`; 7. 首个正向月份返回 `Available`,`earliest_date` 与唯一一项 `DateAvailability(date=earliest, times=[])` 指向同一天;不传播该月其他日期; 8. 不主动点击每个日期、不主动为每个日期查询 TimeSlots。网站初始化自动产生的 TimeSlots 可以用于诊断/一致性监控,但不能把其中的 daily ID 或时段放进跨账号快照; 9. 未知 schema、超时、月份未完整扫描、challenge 或限流抛明确异常,不伪装无号。 为什么这里不要求 Query 先拿到具体时段:VFS/BLS 的稳定合同本来就是“Query 给日期,Book 重查时间”;E43 又证明 Availability 的正向容量与同日 TimeSlots 一致。这样少一次主动交互、少一批请求,也避免把转瞬即逝的动态时段误当成用户账号事实。 ### 8.4 Query 输出 | 当前事实 | success | status | payload | |---|---:|---|---| | 服务明确无号 | false | NoneAvailable | 空 | | bookingForm 但未准备 Calendar | false | NoneAvailable | 只记录 stage,不发生产信号 | | 完整配置范围内没有正向日期 | false | NoneAvailable | 空 | | 首个正向月份至少一个 E43 合同的正向日期 | true | Available | 该月最早日期,`times=[]`;不含 runtime/daily ID 或 token | | Waiting List | 只有真实验证后 | Waitlist | 首版默认不支持 | | 未知状态 | 异常 | 不伪造 | signal=0 | VSQueryResult 快照只传播可公开的日期线索。daily calendar ID、Calendar runtime service ID、Cookie、OTP、DOM 对象和 Query 账号时段不进入 Redis。 ### 8.5 现有信号协议的一个细节 Sentinel 只在 query_result.success=True 时写 Redis;to_snapshot_payload() 本身不保存 success,Booker 反序列化后该字段会回到默认 false,但 Booker 以“Redis 信号存在”触发,不再次检查 success。 首版不修改这个既有合同,但必须加回归测试固定它,避免以后误以为反序列化后的 success 仍为 true。 ## 9. Book 设计:如何珍惜一次真实机会 ### 9.1 原则 - Query 快照只告诉“团队账号刚看到什么”; - 用户账号必须重新查; - 用户账号只能使用自己当前 Session 的动态状态; - 所有写动作至多一次; - 最终结果不明时只读对账; - 选择策略确定性,不随机。 ### 9.2 状态机 ~~~text B0 TRIGGER_VALIDATED → B1 USER_SESSION_RECONCILED → B2 SERVICE_RECHECKED → B3 BOOKING_FORM_VALIDATED → B4 FORM_SELECTIONS_VALIDATED → B5 PRIVACY_AND_TURNSTILE_READY → B6 OTP_SENT_ONCE → B7 OTP_RECEIVED_AND_ENTERED → B8 AVANTI_SUBMITTED_ONCE → B9 CALENDAR_READY → B10 CURRENT_AVAILABILITY_RECHECKED → B11 CURRENT_SLOT_SELECTED → B12 PRECOMMIT_VALIDATED → B13 FINAL_CLICK_ONCE → B14 OUTCOME_RECONCILED → B15 VSBookResult ~~~ 状态只存在于同一个插件实例的内存中,不创建新工作流服务。关键防重复标志: - otp_sent - avanti_submitted - final_submitted - outcome_unknown - 当前 routing_key 这些标志只能防住同一进程内的重复动作,不能防住进程在最终点击附近崩溃后重启。 在 B13 前还必须有一个以 task/order + route 为键的持久 final-attempt fence。fence 必须 在点击前成功写入;重启看到 fence 后只能对账或人工处理,不能再次 final。 这保证的是 at-most-once:正常成功路径 final=1;任何 crash/timeout 路径 final<=1。 如果进程恰好在 fence 已写入、网站尚未收到请求时崩溃,宁可丢失这次机会,也不能 自动制造第二次不可逆提交。网站没有已观察到的 idempotency key,因此不能诚实承诺 同时做到“绝不重复”和“崩溃后绝不丢机会”。 Session 变化会清除页面临时状态,但在任何新的最终写动作前仍必须先做 /Reservation 对账。 ### 9.3 启动时对账 每次 book() 开头先检查: 1. 当前订单是否已经存在目标预约; 2. 上一次本地状态是否为 outcome_unknown; 3. 当前页面是否仍在同一 route 的 Calendar; 4. 是否处于 OTP 前端/服务端冷却。 若已经存在预约,直接解析并返回成功;若存在持久 final-attempt fence 或结果未知, 只做对账,不重新提交。 这个步骤是发布 P0。当前 Booker 对 success=False 会在下一信号重试,单靠异常无法阻止进程重启后的重复写。 当前插件 book() 也没有显式 task_id 上下文,现有云任务更新只在成功后异步执行;因此 不能用插件内存、tracker TTL 或 grabbed 通知冒充持久 fence。 ### 9.4 用户表单 Book 操作可见控件并触发网站原生事件: 1. 选择配置的 single; 2. 触发 change; 3. 断言 visible/hidden booking type 一致; 4. 断言 companion hidden 为 0; 5. 选择配置的 tourism; 6. 断言可见值正确; 7. 允许旅游 hidden 在 AVANTI 前仍为 0; 8. 检查全部 required 控件;未知 required=1 即停止; 9. Hong Kong 当前 Notes 可选、文件控件为 0;其他 Sede 按各自 Gate; 10. 勾 Privacy; 11. 等待当前页面自己的 Turnstile 状态可用,不复制或日志输出 token。 禁止直接给 hiddenTipoPrenotazione、numAccSelected、hiddenSelezionato_0 赋值。网页原生同步链本身就是协议的一部分。 ### 9.5 OTP 顺序: ~~~text 记录 UTC sent_at → 监听 GenerateOTP → 原生点击 otp-send 一次 → 只接受 HTTP 200 + SENT → VSCloudApi.fetch_mail_content() → 只搜索 sent_at 之后的新邮件 → 正则只返回验证码,不输出正文 → 输入 otp-input ~~~ 约束: - HTTP GET 也按有副作用命令处理; - 一次 Session 准备最多一次; - response 超时/不明不自动重发; - UI 120 秒只是前端冷却,不冒充服务端规则; - sender、subject、body keyword、验证码格式必须由真实邮件 Gate 配置; - recipient 默认取当前 Italy 账号的 username,但必须先验证该 username 确实是收件 邮箱;不得读取不存在的 VSAccount.email 属性; - authorization_email 对应现有 VSCloudApi.fetch_mail_content() 的第一个参数,必须从 私密配置取得且不得写入日志或 fixture; - 旧邮件、旧验证码、错误 recipient 必须命中 0 次; - 日志中 OTP、邮件正文和 sender 以外的个人信息命中 0。 首个 Canary 可以人工输入 OTP;无人值守生产必须关闭邮件自动读取 Gate。 ### 9.6 AVANTI 提交前: - form action/method/enctype 与 route 合同一致; - single visible/hidden=1/1; - companions hidden=0; - tourism visible 为配置值; - tourism hidden 允许为 0; - OTP 非空但不读取到日志; - Privacy checked; - Turnstile 字段存在且非空布尔为 true; - btnAvanti.disabled=false; - 未知 required=0; - OTP 发送次数=1; - AVANTI 提交次数=0。 执行: 1. 在监听 POST /Services/Booking/{service_id} 后原生点击 AVANTI; 2. 接受网站原生摘要确认框; 3. 不手工构造 multipart; 4. 期望一次 POST、302 和 /BookingCalendar; 5. 任何模糊结果不重复 AVANTI。 ### 9.7 Calendar 重查 Book 与 Query 使用同一纯解析器,但使用完全不同的浏览器 Session。 Book 忽略 Query 的 daily ID 和临时 DOM,只用 Query 的日期作为优先线索: 1. 先重查 Query 提示日期; 2. 若它已失效,再扫描用户日期范围内当前返回的日期; 3. 每次 date click 后等待 TimeSlots 完成; 4. 检查实际 selected 日期,拒绝网站静默回退; 5. 再执行候选选择。 ### 9.8 候选排序 首版确定性策略: 1. 过滤 expected_start_date <= date <= expected_end_date; 2. 日期升序; 3. 在同一天按明确的正向剩余量降序; 4. 再按开始时间升序; 5. 取第一个。 不复制 VFS 当前的随机 shuffle/random choice。确定性选择更容易审计,也不会在同一输入下随机偏离用户意图。 ## 10. Side-effect Budget 和重试 | 操作 | 类别 | 同一阶段上限 | 结果不明 | |---|---|---:|---| | /UserArea、/Services | 只读 | 同一错误最多 2 次 | 重建 Session | | 服务入口 GET | 探测 | 每 probe 1 次 | 当前轮停止 | | Calendar document/已证明只读 XHR | 只读 | 同一错误最多 2 次 | 当前轮停止 | | DOM/纯解析 | 本地 | 可重算 | fail-closed | | GenerateOTP | 外部命令 | 每 Session/attempt 1 次 | 禁止重发 | | AVANTI form POST | 外部命令 | 每 Session/attempt 1 次 | 对账/停写 | | date/slot 原生选择 | 页面状态 | 每候选 1 次 | 重新读 DOM | | InsertNewBooking | 最终不可逆 | 每机会 1 次 | 只读对账 | “同一错误最多两次”只适用于可证明幂等的只读操作。OTP、AVANTI、最终 POST 不因为报错而获得第二次机会。 ## 11. 正向日期和 Slot 的提交前不变量 E43 已关闭当前页面版本的零值语义,E44 已关闭安全点击后的唯一选择态;但二者仍不等于“可以最终提交”。解析器和 precommit 必须同时满足: ### 11.1 日期 - 日期能严格解析为 YYYY-MM-DD; - 在用户范围内; - Availability item 唯一对应; - `SlotLiberi > 0`; - `SlotRimanenti >= 0`; - 不带 disabled; - 不带 notAvailableDay; - 带已验证的正向状态; - timeline selected 恰好 1; - content selected 恰好 1; - 两者 data-date 完全相等; - 等于计划选择日期; - 没有发生静默回退。 ### 11.2 Slot - TimeSlots item schema 完整; - 起止时间合法且开始早于结束; - IDCalendarioServizioGiornaliero 存在,只保留在内存; - SlotRimanenti、SlotLiberi 都能解析成有限整数; - `SlotLiberi > 0` 且 `SlotRimanenti >= 0`;E43 的 `1/0` 必须判正向; - DOM 不带 notAvailableFascia; - DOM 不带 dotRed; - 点击后 .fascia.act 恰好 1; - active Slot 就是候选; - active Slot 内符合合同的 hidden input 恰好 1; - active Slot 日期/时间仍与选择一致。 仅以下任一项单独出现都不够: - SlotRimanenti >= 0 - SlotLiberi > 0 - .act - enabled PRENOTA - 数组非空 - 有时间文字 - 日期带 selected/active/availableDay ### 11.3 最终 handler 不手写 InsertNewBooking 请求。先用纯逻辑批准 DOM 快照,再触发网站原生 btnPrenotaNoOtp: - 复用页面当前 token/serializer; - 避免猜 selectedHour 中空白和数量格式; - 避免错误使用重复的 idHiddenFasciaServizio; - 用 Network listener 验证 method/path/调用次数和响应 schema; - 请求体只检查字段名/形状,不打印值。 ## 12. 最终结果与模糊恢复 ### 12.1 已知响应 当前静态合同: ~~~text response.errorMessage response.url ~~~ 真实成功 response、失败 response 和成功 URL 仍是外部 Gate。 ### 12.2 明确成功 listener 取得响应后: 1. 允许页面按原生 handler 跳转; 2. 读取成功摘要或 /Reservation; 3. 唯一匹配 route + date + time; 4. 读取预约编号; 5. 返回 VSBookResult。 ### 12.3 明确失败 只有服务器明确表示 Slot 已失效/请求失败,且 /Reservation 明确没有新记录,才返回可重试失败。不会在同一调用中重提。 ### 12.4 结果未知 包括: - 点击后 listener 超时; - 连接断开; - response 无法解析; - 页面卡住; - response.errorMessage 与页面状态冲突。 处理: ~~~text final_submitted = true outcome_unknown = true durable_final_attempt_fence = present → 永久关闭当前实例的最终写入口 → 只读 /Reservation → 找到唯一记录:成功 → 明确无记录且协议允许:失败 → 仍不确定:manual-reconciliation-required ~~~ 下一次信号只允许再次对账。进程重启后每次 Book 开始仍先查 /Reservation。 重启后若 durable fence 存在,即使 /Reservation 暂时没有记录,也不得自动 final; 应在有界窗口内继续只读对账,超时后转人工。fence 何时归档、绝不能被普通失败路径 清除,必须由 FENCE-1 的状态迁移测试固定。 如果网站不能提供权威对账,现有 VSBookResult + Booker retry 无法安全表达未知结果;届时必须停止发布,再提出最小框架级 OutcomeUnknown/任务冻结扩展。不能在 Italy 内假装解决。 ## 13. Session、冷却和并发 ### 13.1 账号隔离 | 角色 | 账号 | Profile | 可以做什么 | |---|---|---|---| | Query | 已授权团队成员 | 每账号独占 | 准备自己的 Calendar;只读发现;不最终预约 | | Book | 申请人自己 | 与 Query 完全独立 | 为自己的订单完成预约 | 一个 Profile 同时只能有一个浏览器实例;现有文件锁继续复用。 ### 13.2 信号与 cooldown 生产强信号沿用: ~~~text signal_ttl = 30s booking_cooldown > signal_ttl target_instances = 1 有效 Italy OrderBooker 部署数 = 1 ~~~ 强信号来自真实 Slot,不再每轮发送 bookingForm 弱信号。 OTP 的 120 秒冷却不能只靠 booking_cooldown=45 保护。插件自己的 attempt guard 必须阻止同一 Session 重发;如果仍在同一路由 Calendar,下一次 book() 直接重查 Calendar,不重新走 OTP。 ### 13.3 Session 生命周期 当前 Italy 配置的 session_max_life=900 会主动每 15 分钟淘汰 Session。准备型 Query 若照搬,会每 15 分钟重新发 OTP。 不能猜一个更长值。Gate 必须测量: - 登录 Session 实际寿命; - Calendar Session 实际寿命; - 只读 probe 是否保持有效; - OTP/AVANTI 的实际频率; - 429/challenge。 生产配置使用已验证寿命的保守下界。账号数量不能被用来掩盖 Session 设计错误。 ### 13.4 keep_alive - Sentinel 正在定期 Query,按 IVSPlg 合同通常不需要额外 keep_alive; - OrderBooker 在 /UserArea 时可以使用已证明只读的认证页; - OrderBooker 在 /BookingCalendar 时不得导航离开,只做 DOM 健康检查或已证明安全的 Calendar 只读动作; - keep_alive 永不进入服务、发送 OTP、提交表单或最终预约。 ## 14. 错误、日志和隐私 ### 14.1 错误分类 | 状态 | 结果 | |---|---| | 已验证无号/无正向 Slot | 正常 success=False | | IAM 登录页或认证回跳 | SessionExpiredOrInvalidError | | 429 | RateLimiteddError,当前实例停止 | | 403/挑战 | 明确挑战/权限错误,不自动绕过 | | 目标 route 缺失 | 配置或结构错误 | | 未知弹窗/字段/schema | BizLogicError,signal=0 | | OTP timeout | OTP 专用业务错误,不重发 | | AVANTI 结果未知 | attempt 停写并对账 | | 最终结果未知 | manual reconciliation,禁止重提 | ### 14.2 允许日志 - stage; - routing key、service id; - path、method、status; - schema keys; - field/button/count; - 日期和展示时间; - elapsed time; - 写请求计数; - 脱敏错误类别。 ### 14.3 禁止日志 - username、password; - Cookie、Authorization; - CSRF/OAuth/Turnstile 值; - OTP、邮件正文; - daily calendar ID; - 护照、生日、电话、地址; - 完整 HTML、HAR、POST body; - 任何可复用的动态 Session 值。 ## 15. 假设验证账本 ### 15.1 P0:不关闭就不能发布对应阶段 | ID | 假设 | 当前状态 | 机械关闭标准 | 失败动作 | |---|---|---|---|---| | P0-01 | IAM 自动登录可达 /UserArea | 已关闭 E9 | 真实 exit 0 + DOM 双标志 | Session 不可用 | | P0-02 | Dublin 1321 无号分类安全 | 已关闭 E7/E12 | GET/302/marker;业务 POST=0 | 保留回归 | | P0-03 | Hong Kong 4937 是单人申根旅游样本 | 已关闭 E14–E20 | service/form/single/tourism 唯一 | 不配 live route | | P0-04 | bookingForm 能代表真实 Slot | 已否决 E15/E43 | 表单自身无日期、范围、容量;不能从某次后续有号外推恒真 | 禁止生产弱信号 | | P0-05 | 团队账号准备 Calendar 不创建预约/候补 | 外部 Q-CAL-1 | OTP=1、AVANTI=1、final=0;Reservation 前后相同 | 否决准备型 Query | | P0-06 | Calendar 重复 probe 是只读且稳定 | 外部 Q-CAL-2 | 连续 N 次;OTP/AVANTI/final=0;记录不变;无 429 | 不自动 probe | | P0-07 | Query 正向日期对用户账号可传播 | 外部 Q-XACC | 3 个自然窗口 3/3;Book 在 TTL 内重查到可用时段 | 调整模型/不发布 | | P0-08 | 用户 OTP + AVANTI 能进 Calendar | 已关闭 E21/E22 | OTP 1、POST 1、302、Calendar 200 | 不实现后段 | | P0-09 | Cloud API 能唯一读取 Italy 新 OTP | 外部 OTP-AUTO | sent_at 后唯一命中;旧码=0;日志泄漏=0 | Canary 手工,生产禁用 | | P0-10 | 正向 Slot 的两个数量和 DOM truth table 已知 | 已关闭 E43/E44 | response/DOM 一致;安全点击后唯一 active、后代、时间和日期一致 | 保留 final=0 回归 | | P0-11 | precommit 能拒绝负向/冲突状态 | CS1 纯核心已关闭;CS4 接线时复验 | E23–E44 mutation fixtures 全通过 | 不进入 final | | P0-12 | InsertNewBooking 真实 response 可分类 | 外部 FINAL-1 | 一次真实 Canary 收集脱敏 schema | 不发布 final | | P0-13 | /Reservation 可权威对账 | 外部 FINAL-2 | 成功/失败/响应丢失均唯一判断 | 提框架 Unknown 状态 | | P0-14 | 跨进程 durable fence 保证最终 at-most-once | FENCE-1 + CS5A + FINAL-2 | 正常 final=1;timeout/crash/restart final<=1;fence 后只对账 | 不发布 | | P0-15 | 通用实现无 Sede 分支 | CS1–CS5 | HK 正向 + Dublin 负向同一路径;源码扫描=0 | 拒绝合并 | | P0-16 | kill switch 真能阻止最终动作 | CS5 | final_submit_enabled=false 下 final=0 | 不进 Canary | ### 15.2 P1:生产前关闭 | ID | 条件 | 关闭位置 | |---|---|---| | P1-01 | 任一启用 locale/配置 label 不改变核心结构判断 | locale fixtures | | P1-02 | 新 required 字段必然停在 OTP/AVANTI 前 | mutation fixture | | P1-03 | Query/Book route 配置完全一致 | JSON contract | | P1-04 | snapshot 不含临时 ID/secret | serialization scan | | P1-05 | date fallback 被检测 | E30/E41/E42 fixtures | | P1-06 | duplicate hidden id 不会取错 | active-descendant fixture | | P1-07 | `1/0` 正向、`0/-1` 负向,其他零/负数/冲突组合按 allowlist fail-closed | E43 truth-table fixtures | | P1-08 | 一个 retained signal 最多触发一次 Book | Booker offline integration | | P1-09 | 订单 pause/cancel 不触发 Book | OrderBooker regression | | P1-10 | Query 账号数增加不放大总频率 | cadence test + soak | | P1-11 | Session/Calendar 寿命已校准 | Q-CAL-2 | | P1-12 | Book p95 小于自然 Slot 可用窗口 | Q-XACC telemetry | | P1-13 | 日志/异常/产物敏感命中 0 | security scan | | P1-14 | 真实正向链外的未知页面 signal/final 都为 0 | mutation suite | | P1-15 | 第二 Sede 按配置工作 | GEN-1 | 所有内部设计问题都已分配给 Change Set;所有网站未知都已分配给外部 Gate。不存在无验证路径的内部 P0/P1。 ## 16. 真实网站 Gate 每个 Gate 的授权只覆盖该 Gate,不能继承到下一个副作用。 ### Gate D0:批准本文 只评审设计。网站请求=0,代码修改=0。 ### Gate Q-CAL-1:团队 Query Calendar 准备 前提:一个属于目标 Sede、已授权且邮箱可访问的团队账号。 动作: 1. 记录 /Reservation 非敏感计数; 2. 进入 4937; 3. single + tourism + privacy; 4. OTP 一次; 5. AVANTI 一次; 6. 到 Calendar 停止; 7. 再读 Reservation 计数。 通过: ~~~text GenerateOTP = 1 Booking form POST = 1 InsertNewBooking = 0 预约/候补新增 = 0 Calendar ready = true ~~~ 2026-08-29 的 Q-CAL-1 受控执行尚未关闭本 Gate: - 第一次执行在读取 `/Reservation` 基线时发现空候补表不会初始化 DataTables;工具在进入 服务、OTP 和 AVANTI 之前停止。该读取假设已离线修正并通过回归。 - 第二次执行成功取得基线 `reservations=0, waitlist=0`,但当前认证账号的 Services 页面 没有目标 `/Services/Booking/4937`。页面结构为 8 个数据行、7 个预约链接,目标链接数为 0;工具在 OTP、AVANTI 和 Calendar 之前 fail-closed。 - 两次执行的 `GenerateOTP`、Booking Form POST 和 `InsertNewBooking` 均为 0;没有新增预约 或候补。第二次输出只能证明“当前账号所在 Sede 与 Hong Kong 4937 路由不匹配”,不能仅凭 行数把当前 Sede 名称事实化为 Dublin。 - Gate 状态仍为 **OPEN**。再次执行前必须先显式确认一个已授权团队 Query 账号当前属于 Hong Kong Sede,或经单独授权把该账号的 Sede 切换为 Hong Kong;不得原样重跑。 - 账号 Sede 随后由负责人完成调整。一次零副作用 Query 预检已精确进入 `/Services/Booking/4937`,确认 form action 仍为同一路径,Booking Type、Purpose、OTP、 Privacy、Turnstile 与 AVANTI 结构仍存在;工具按“Booking Form 弱信号”合同返回 exit 4。 该 exit code 是安全停止,不是路由失败。预检没有发送 OTP、提交 AVANTI 或进入 Calendar, 因而只关闭“账号与 Hong Kong 4937 已对齐”,没有关闭 Q-CAL-1。 - 对齐后的下一次受控执行取得 `reservations=0, waitlist=0` 基线并成功观察到一次 `GenerateOTP`,随后由负责人在隐藏终端提示中人工输入验证码。执行在 AVANTI 前因 `Booking preflight rejected otpDisabled` 停止;Booking Form POST 和 `InsertNewBooking` 仍为 0。独立只读审计随后再次得到 `reservations=0, waitlist=0`,证明 本次 OTP 没有新增预约或候补。 - 网站在发送 OTP 后会让发送按钮进入冷却禁用态。当前工作树已有显式的 `BEFORE_OTP_SEND/AFTER_OTP_SEND` 阶段校验,且 4 个聚焦测试验证发送后 `otpDisabled=true` 可接受;真实输出却仍命中旧判据。由于该次进程没有输出非敏感工具版本 标识,不能证明它加载了哪一版合同,也不能排除运行时值形状差异。再次授权前必须先增加 可审计版本标识与脱敏 stage/type 诊断,再做零网站副作用回归;不得直接重发 OTP。 - 上述本地前置工作已经完成:工具在读取 route、账号或启动浏览器前输出语义合同版本和 当前源码 SHA-256 短指纹;每次 preflight ready/rejected 只输出 allowlist 中的 stage、 snapshot 类型,以及 `otpDisabled`、`avantiDisabled`、`turnstileReady` 的类型与布尔值。 未知值只记录类型并把 value 置为 null,额外表单字段不会被序列化。19 个 Q-CAL 聚焦测试、 168 个 Italy 相关离线测试、语法编译、diff/尾随空格检查均 exit 0;真实网站请求为 0。 Q-CAL-1 仍为 OPEN,新的 OTP 仍需新的明确授权。 - 另用本地 `data:` 页面和真实 Chromium/DrissionPage 桥接验证:JavaScript `true/false` 均返回 Python `bool`,命令 exit 0,外部网站请求为 0。由此排除“浏览器桥把 true 转为整数 1”的假设;上次输出来自旧合同进程成为当前最强解释,但仍须由下一次 source fingerprint 实证,不能写成已最终证明。 - 新授权的真实执行随后输出了预期合同版本与源码指纹;pre-OTP 为 `otpDisabled=false`,post-OTP 为 `otpDisabled=true`,两个阶段都以 bool/ready 通过,从而 实证 stage-aware 修复已加载。执行发送 OTP 1 次并提交 AVANTI 1 次,但旧 validator 因 `packet.response.status != 302` 停止;Calendar probe 和 final 请求均为 0。独立只读审计仍为 `reservations=0, waitlist=0`,证明本次没有新增预约或候补。 - 本地临时 HTTP 服务与真实 Chromium/DrissionPage 进一步机械复现:服务端执行 `POST /booking → 302 Location:/calendar → GET /calendar 200`,listener 返回的 packet 却是 `request_method=POST, request_path=/booking, response_status=200, response_path=/calendar`,浏览器 final path 也是 `/calendar`;命令 exit 0,外部请求为 0。 DrissionPage 复用 redirect requestId 并用最终 response 覆盖原始 302,因此“packet 必须 直接暴露 302”是错误的适配器假设,不是 Italy 协议变化。 - 最小修复不能接受任意 200:必须同时验证原始 request 仍是同源目标 POST、packet response 最终 URL 是同源 `/BookingCalendar`、浏览器最终 pathname 也是 `/BookingCalendar`;若底层 仍能直接提供 302,则继续验证 Location。修复和离线回归未获得本轮授权前不实施;新的 OTP 仍需再次单独授权。 2026-08-29 最终状态:**Q-CAL-1 CLOSED**。 - v5 真实运行已验证 OTP=1、Booking Form POST=1、Calendar ready=true、 InsertNewBooking=0;事后 Reservation/Waitlist 为 0/0;v6 只修改 Calendar selector,未改 OTP/AVANTI 合同; - 同一持久化认证状态随后无需 OTP/AVANTI 即可恢复 Calendar; - 真实只读翻月验证得到 candidate=4、actionable=1、clicked=true,并观察到两个不同月份的 availability request; - 只读验证前后 Reservation/Waitlist 均为 0/0,OTP=0、AVANTI=0、final=0; - 因此一次性 Calendar 准备与后续只读恢复均满足本 Gate;Q-CAL-2 的 cadence/寿命/限流仍需 独立 soak,不能由 Q-CAL-1 代替。 ### Gate Q-CAL-2:Calendar 只读 soak 在同一团队账号 Calendar Session 里按计划 cadence 重查。 通过: - Availability 逐月只读次数符合配置;没有主动按日期扇出 TimeSlots;页面原生自动 TimeSlots 单独计数; - OTP、AVANTI、final 增量均为 0; - Reservation 无变化; - Session/Calendar 寿命已量化; - 429/challenge=0; - 发生 schema 变化时 signal=0。 ### Gate SLOT-POS:自然正向 Slot,停在最终按钮前 不制造 Slot,不点击 unavailable。 阶段 A:response/DOM 正向语义,已由 E43 关闭: - Availability 的 `SlotLiberi>0 / SlotRimanenti>=0`; - TimeSlot 的 `1/0`、普通 `fascia`、无红点、显示 `(1)`; - timeline/content selected 日期一致; - 正向 Slot 有唯一 hidden daily ID 形状; - 正向 Slot 尚未点击、`act=false`; - `InsertNewBooking=0`。 阶段 B:安全选择,已由 E44 关闭: 1. 只点击一次已由阶段 A 批准的正向 Slot; 2. 断言 `.fascia.act` 恰好 1; 3. active Slot 仍无负向 class,后代 ID、时间和 selected 日期与候选一致; 4. 运行纯 precommit,结果必须为 true; 5. 不点击 `btnPrenotaNoOtp`,Network 中 `InsertNewBooking` 仍为 0。 E44 实际结果: - 授权探针源码对 E43 批准的 `10:05 - 11:05` 候选只调用一次 `.click()`;原 Promise fulfilled 后没有重跑; - 独立只读 readback 得到唯一 `.fascia.act`,且 active 就是同一时间、同一 selected 日期的候选; - active 不带 `notAvailableFascia`/`dotRed`,仍显示 `(1)`; - active 后代 hidden input 恰好 1,动态值只验证“存在、全数字、长度 8”,没有读取或保存具体值; - `btnPrenotaNoOtp` 仍存在但点击数为 0;当前页面 Resource Timing 中 `InsertNewBooking` 为 0;机械总判定 `done=true`; - Resource Timing 只关闭本次选择态的“未观察到 final XHR”,不替代 FINAL Gate 的 Network listener、服务端 response 和 `/Reservation` 对账。 禁止:InsertNewBooking。 通过:阶段 A 和 B 都关闭,唯一正向候选满足 §11 全部不变量,最终 POST=0。 ### Gate Q-XACC:团队信号 → 用户账号 团队 Query 观察正向日期后发布本地/Redis 信号;用户热 Session 独立重查具体时段。 通过: - 3 个独立自然窗口 3/3; - 用户看到同一日期的可用时段,或在其允许范围内看到另一正向日期/时段; - 信号到 Book precommit 的 p95 有安全余量; - Query 与 Book 账号/Profile/Cookie 完全不同。 ### Gate OTP-AUTO:自动邮件读取 通过: - sender/subject/body/regex 有真实证据; - sent_at 之后唯一命中; - 旧 OTP 0 命中; - recipient 错误 0 命中; - 日志/异常/产物不含 OTP/正文。 ### Gate FENCE-1:最终提交持久写屏障 先只调查现有云任务 API 和 OrderBooker,不访问预约网站、不执行 final。 通过必须同时满足: - 有稳定 task/order 标识可作为 fence key; - fence 写入发生在原生最终点击之前,并能被另一个进程读到; - 写入具备 compare-and-set 或等价的单写者保证; - 进程在 fence 前、fence 后点击前、请求发出后、response 前四个 crash point 都有测试; - fence 存在时 Booker 不会因新 Redis 信号再次 final; - 只有权威成功归档或人工处置能结束 fence,普通 false/exception 不能清除; - 不把 Cookie、OTP、daily ID 或 PII 写入 fence。 若现有任务 API 不具备这些能力,结论不是“插件里写个文件”,而是提出最小框架/ 后端扩展并重新评审文件范围。该 Gate 未通过时 CS5 和 FINAL-1 均禁止。 ### Gate FINAL-1:一次真实 Canary 前提: - 用户确实需要当前日期/时间的预约; - SLOT-POS、Q-XACC、OTP-AUTO、FENCE-1 已关闭; - final kill switch 的离线测试已通过; - 用户再次明确授权。 动作: - 原生点击一次 btnPrenotaNoOtp; - InsertNewBooking 恰好 1; - 不人工重试; - 读取成功页和 Reservation。 ### Gate FINAL-2:结果对账 用已取得的真实 response/成功页设计离线响应丢失测试,并在不制造第二个预约的前提下验证 Reservation。 通过:成功、明确失败、网络结果未知三种路径都不会导致第二次 final。 ### Gate GEN-1:第二 Sede 通用性 香港正向 fixture 与 Dublin 无号 fixture 必须走同一协议代码。随后选择一个合法的第二 Sede 做只读/前置 Gate。 源码中的城市、领馆、1321、4937 控制分支命中必须为 0。 ### Gate PROD-1:受控上线 - 单 Sentinel; - 单 Italy OrderBooker; - target_instances=1; - 强信号模式; - kill switch 已演练; - 可观察 stage/write counts; - 回滚命令和负责人明确; - 前 1 个生产订单人工旁路监控。 ## 17. 开发计划 每个 Change Set 都需要单独批准。前一个完成不自动授权下一个。 ### CS0:设计与证据收敛 本轮。 完成:本文、历史文档状态、机械检查。 ### CS1:route 配置与纯协议核心(已验证) 文件: - 新增 plugins/ita_protocol.py - 新增 test/test_ita_protocol.py - 只读运行现有 test/test_ita_plugin.py 作为回归;本 Change Set 不修改该用户已有文件 内容: - 使用 VFS/BLS 同类的 `apt_configs[routing_key]` 配置入口,严格校验 capability、 service_id、扫描范围与表单控件配置; - 严格双层 JSON parser,只接受“外层 JSON 字符串包内层对象数组”; - 不可变 Calendar/Slot value objects,动态日历 ID 不进入 `repr`; - 日期范围过滤、跨年月份生成与确定性排序; - 按 E43 建立唯一的容量 allowlist:`SlotLiberi>0 && SlotRimanenti>=0` 为正向, `0/-1` 为负向,矛盾组合 fail-closed; - 按 E44 校验日期与时段唯一选中、动态 ID、日期、时间、容量和负向标志均一致后, 才生成纯内存 `PrecommitApproval`; - 不导入浏览器或网络库,不登录、不发 OTP、不提交表单、不接触网站。 完成结果:28 个聚焦协议测试 exit 0;30 个现有 Italy 回归测试 exit 0;编译、 纯模块导入、地区硬编码/网络副作用、敏感信息与 whitespace 检查 exit 0;生产网站 请求=0;`ita_plugin.py` 和生产 Query/Book 均未接入,现有 Italy 行为不变。 ### CS2:配置与调试工具通用化(已验证) 内容: - Italy 插件按 apt_type.routing_key 解析; - Sentinel/Booker route parity; - debug query/book/monitor/soak/handoff 接受显式 route; - Dublin 默认仅作为兼容参数,不再锁死; - 未配置 capability fail-closed。 完成:HK/Dublin fixture 同一实现;硬编码控制分支扫描=0。 实际结果: - `ItaPlugin.query()` 与 `book()` 都通过 `apt_type.routing_key → free_config.apt_configs[routing_key]` 解析 route;顶层 `service_id` 不再是运行时 fallback; - Sentinel/Booker 的 Italy 配置拥有相同 `apt_configs`,并显式保持 `query_mode=services_probe`、`final_submit_enabled=false`; - query/book/monitor/soak 调试入口共用一个 route resolver;Dublin/1321 只在完全没有 route 环境变量时作为兼容默认值;自定义 route 的 key、service id、city、visa type 必须一次性全部提供,部分覆盖会 fail-closed; - `ita_local_handoff.py` 继续只接收显式 routing key/service id,没有新增地区分支; - `services_probe_only` 仍只允许弱入口探测与用户 Session 重查,Book 到达表单后停在 AVANTI 之前;没有接入 CS1 的 Calendar parser,也没有发送 OTP 或最终请求; - 137 个相关离线测试、编译、配置 parity、控制分支与 whitespace 检查均 exit 0; 真实 Italy 网站请求数为 0。 ### CS3A:生产 Calendar 扫描合同(离线及一次现场验收已验证) 前提:Q-CAL-1 已关闭;实现仍需保持 final disabled,并由 Q-CAL-2 校准 cadence。 内容: - 新增 `plugins/ita_calendar_query.py`,作为生产 Query 与 Q-CAL 工具唯一共享的浏览器适配层; - page.listen 一次性安全 wrapper、同源 method/path/body shape 校验; - 原生 Calendar refresh; - 唯一可操作 `#datetimepicker th.dtpicker-next` 与严格单月递增; - 首个正向月份立即停止,只发布该月最早日期; - 复用 VFS 风格 `Available + earliest_date + DateAvailability(times=[])`; - Calendar 最终按钮在每次 probe 后被 guard,`InsertNewBooking` 观察数必须为 0; - services weak signal 默认不发布。 当前安全边界:`query_mode=calendar` 只接受同一插件实例中已经过 route 确认的 `/BookingCalendar`;未完成准备时明确失败,不把 bookingForm 弱信号降级发布。默认生产配置 仍是 `query_mode=services_probe`,因此本 Change Set 不会自动发送 OTP、点击 AVANTI 或启用强 信号。 ### CS3B:Calendar Session 准备(未实现) 内容:Query Calendar Session stage、OTP/AVANTI 一次性 guard,以及经过 OTP-AUTO Gate 的邮件 读取适配。它必须先证明同一实例内 route 身份连续,不能把旧持久化 Calendar 或页面标题猜成 当前 routing key。CS3A 完成不会自动授权 CS3B,也不会修改生产配置。 ### CS4:用户 Book 到最终按钮前 内容: - 用户 Session 重查; - 原生 form selection; - OTP/AVANTI; - Calendar parser; - Slot 选择; - precommit; - 默认 final_submit_enabled=false 并在按钮前停止。 ### CS5A:跨进程持久写屏障 前提:FENCE-1 已证明可复用路径,并单独批准可能扩大的文件范围。 内容:只实现已批准的 task/order fence、状态读取和 crash-point 离线测试;不访问 Prenot@Mi,不执行 final。若需要修改 booker.py、toolkit/vs_cloud_api.py 或后端合同, 必须作为独立 Change Set,不夹带进 Italy 插件提交。 ### CS5:最终一次提交与对账 前提:SLOT-POS、Q-XACC、OTP-AUTO、FENCE-1、CS5A 已关闭,且 FINAL-1 已授权。 内容: - final listener; - 原生 click once; - response parser; - Reservation reconcile; - outcome_unknown 写屏障; - VSBookResult。 ### CS6:生产接入 内容: - 启用真实 route; - cadence/session/cooldown 使用 Gate 数据; - kill switch; - canary rollout; - 观察与回滚。 ## 18. 测试计划 ### 18.1 纯协议单元测试 - route 缺失/类型错误; - 双层 JSON 正常、空、单层、三层、坏 JSON、超大数组; - Availability 的 `DD/MM/YYYY 00:00:00` 日期格式、非法日期和重复日期; - 默认月份全负向、后续月份有正向时不得提前返回无号; - `lookahead_months` 边界、翻月顺序和完整范围为空; - TimeSlot 缺字段、非法时间、非整数数量; - E43 `SlotLiberi=1 / SlotRimanenti=0` 必须判正向; - E43 `SlotLiberi=0 / SlotRimanenti=-1` 必须判负向; - 其余 SlotRimanenti/SlotLiberi 组合按 allowlist 或冲突 fail-closed; - negative class + act 冲突; - selected 两层日期不一致; - 网站 fallback 到错误日期; - 多 active/零 active; - active Slot 多 input/零 input; - 重复 HTML id 但 active 后代唯一; - 日期边界; - 确定性排序。 ### 18.2 插件合同测试 每个测试断言调用次数: | 场景 | OTP | AVANTI | final | |---|---:|---:|---:| | Dublin 无号 | 0 | 0 | 0 | | bookingForm / services_probe | 0 | 0 | 0 | | 未知 required | 0 | 0 | 0 | | Turnstile 未就绪 | 0 | 0 | 0 | | OTP response unknown | 1 | 0 | 0 | | AVANTI response unknown | 1 | 1 | 0 | | 配置扫描范围全部无正向日期 | 1 | 1 | 0 | | 默认月份无号、后续月份有 E43 正向日期 | 1 | 1 | 0 | | Availability 正向、TimeSlots 无正向(冲突) | 1 | 1 | 0 | | 负向 Slot 被手工加 act | 1 | 1 | 0 | | final disabled | 1 | 1 | 0 | | final listener timeout | 1 | 1 | 1 | | timeout 后再触发 | 不增加 | 不增加 | 仍为 1 | | reconcile 找到预约 | 不增加 | 不增加 | 仍为 1 | “默认月份无号、后续月份正向”还必须断言 Query 发布一次 `Available`,快照含正向日期且所有 `times=[]`;其他 final=0 场景不得发布错误强信号。 另加 crash-point 矩阵:fence 前崩溃允许重新预检;fence 后点击前、请求发出后和 response 前崩溃均不得产生第二次 final。正常成功 final=1,其余路径 final<=1。 ### 18.3 框架离线集成 - Sentinel 只为强 Available 写生产信号; - snapshot 不含临时 ID/secret; - 反序列化 success 默认值的既有行为被固定; - retained signal 只触发一次 Book; - pause/cancelled task 不 Book; - Query/Book 是两个插件实例; - Book 不使用 Query 临时状态; - final kill switch; - Session 重建后先 reconcile。 - durable fence 在进程重启和新信号后仍阻止 final; ### 18.4 Mutation 测试 主动修改 fixture: - 文案语言; - 控件 id; - 新 required; - 选项 value; - response 外层编码; - schema key; - selected 顺序; - class 冲突; - response errorMessage/url; - path/redirect。 期望:未知变化 signal=0、final=0,而不是“尽量继续”。 ### 18.5 安全测试 扫描: - password - Cookie/Authorization - OAuth/CSRF/Turnstile value - OTP 与邮件正文 - daily calendar ID - 完整 POST body - 用户 PII 测试日志、异常、snapshot、status file 命中必须为 0。 ### 18.6 计划验证命令 ~~~bash PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m unittest -v \ test.test_ita_protocol \ test.test_ita_plugin \ test.test_debug_ita_session \ test.test_debug_ita_query \ test.test_debug_ita_book \ test.test_debug_ita_monitor \ test.test_debug_ita_soak \ test.test_ita_local_handoff \ test.test_add_ita_query_account PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -m compileall -q \ plugins/ita_plugin.py plugins/ita_protocol.py tools test jq empty config/config_sentinel.json config/config_booker.json git diff --check ~~~ 真实测试命令必须单独带显式 Gate/arm 开关;默认 CLI 仍是零网络 preflight。 ## 19. 准入、准出、回滚 ### 19.1 进入研发 必须: - D0 明确批准; - 只做获批 Change Set; - Done 标准前置; - 工作树用户改动已盘点; - 外部 Gate 和内部实现不混在同一提交; - 默认 final disabled。 ### 19.2 进入最终 Canary 必须: - 所有相关 P0 关闭; - 自然正向 Slot; - 用户确实需要该预约; - precommit 全绿; - /Reservation 可读; - final request counter 初始为 0; - kill switch 已验证; - 用户当次明确授权。 ### 19.3 生产准出 必须: - 聚焦与回归测试 exit 0; - Q-CAL soak 通过; - Q-XACC 3/3; - FINAL-1/2 通过; - FENCE-1 和 CS5A 通过; - GEN-1 通过; - 敏感扫描 0; - 未知状态 fail-closed; - 一次性 final 在正常成功路径为 1,在 timeout/restart 路径为 <=1; - 真实成功返回完整 VSBookResult; - 运行配置默认不是 debug; - Runbook 和 kill switch 可执行。 ### 19.4 回滚 按最小影响顺序: 1. final_submit_enabled=false:保留观察,禁止最终写; 2. query_mode=services_probe:停止团队账号 OTP/AVANTI; 3. 禁用 Italy Booker group; 4. 禁用 Italy Sentinel group; 5. 回退对应 Change Set; 6. 已发 OTP 不补发;结果未知只对账; 7. 已成功预约不自动取消。 回滚不删除用户数据、不清理不属于本 Change Set 的工作树修改。 ## 20. 可行性分析 | 能力 | 可行性 | 当前确信度 | 原因 | |---|---|---:|---| | 登录 | 高 | 高 | 真实自动登录 exit 0 | | Dublin 无号 | 高 | 高 | DOM/Network/自动 Query 三重证据 | | route 通用化 | 高 | 高 | VFS/BLS 已有 apt_configs | | bookingForm 弱信号 | 技术可行但产品价值低 | 高 | 自身不含日期/范围/容量;不能回答“何时有号” | | 准备型 Calendar Query | 高,需副作用 Gate | 中高 | 完整进入链和 Calendar 协议已知 | | 日期/时段解析 | 高 | 高 | E43 已取得正负 response/DOM truth table;CS1 的解析与变异测试已验证 | | 正向 Slot 原生选择到 precommit | 高 | 高 | E44 已验证唯一 active、日期、时间、容量、动态 ID 形状一致且 final 请求为 0;CS1 纯 precommit 已验证 | | Query 日期→Book 时段传播 | 可行,需实测 | 中 | 与 VFS/BLS 契约一致;同站点库存共享仍需 Q-XACC 证明 | | 用户 Book 到 Calendar | 高 | 高 | E22 已真实通过 | | 自动邮件 OTP | 高,需邮件参数 | 中 | 基建存在;Italy filter 未关闭 | | 最终一次提交 | 技术路径清晰 | 中 | serializer 静态已知;真实 response 未执行 | | 模糊结果恢复 | 待 Gate | 低 | /Reservation 权威性与 durable fence 均未知 | | 跨 Sede 通用 | 架构可行 | 中高 | 配置化成立;需第二正向/前置样本 | 当前对“设计结构和安全推进路径”的信心可以达到 100/100;对“现在就无人值守上线”的信心不是 100,因此方案明确不允许现在上线。 ## 21. 被否决的方案 | 方案 | 否决原因 | |---|---| | Services 有 Prenota 就报有号 | Dublin 已证伪 | | bookingForm 就持续发弱信号 | 表单本身没有日期/范围/容量;会造成 OTP 噪音 | | Query 把临时 Slot ID交给 Book | 跨账号/Session,必然过期或错配 | | Query 每轮都 OTP + AVANTI | 邮件/限流/服务器状态副作用 | | 用户 Book 不重查直接最终提交 | 机会易失且账号不同 | | 手写 multipart/InsertNewBooking | 会绕过原生同步、token 和 serializer | | 只看 .selected/.act | 负向样本已证明会假阳性 | | 只看一个 Slot 数量字段 | 两个字段职责不同;E43 的正向还是 `1/0`,单看 `Rimanenti=0` 会误杀 | | 对 final/OTP/AVANTI 自动重试 | 可能重复邮件、草稿或预约 | | 为香港复制插件 | 立即形成地区分叉 | | 现在修改 Sentinel/Booker/VS 类型 | 现有强信号和账号架构足够 | | 所有逻辑继续堆进 ita_plugin.py | 接近 1,000 行且协议不变量已复杂到无法纯测 | | 提前设计大工作流引擎 | 一个局部 pure core + adapter 足够 | ## 22. 初见审查 ### 反驳 1:“Query 发 OTP,不是违背 Query 无副作用吗?” 回应:旧边界是在 Calendar 协议未知时设的安全默认。香港已经证明 bookingForm 自身不表达号源,而 E43 证明只有进入 Calendar 并扫描完整范围才能回答“什么时候有号”。R3 不允许每轮发 OTP,而是把一次 OTP + AVANTI 明确建模为“团队账号 Calendar Session 准备”,单独授权、每 Session 一次、前后核对 Reservation,后续 probe 只读。若 Q-CAL-1 发现草稿/预约副作用,就否决该方案,而不是偷偷继续。 ### 反驳 2:“为什么不继续用 BLS 弱信号,最大化复用?” 回应:BLS 的弱信号是一种技术表达,不是所有网站都适合的产品语义。bookingForm 没有日期与容量,所以会持续触发但无法回答库存。生产优先复用 VFS 的强 Calendar 信号;BLS 弱信号保留给 Discovery/人工告警。 ### 反驳 3:“新增 ita_protocol.py 不是自己设计吗?” 回应:没有新增框架或运行时组件。它只是把浏览器副作用与纯解析拆开,让 E23–E44 能机械测试。旧单文件方案形成于 Calendar 协议未知时;现在继续堆叠反而降低长期可验证性。文件增加 1 个,运行链路仍是原有 IVSPlg。 ### 反驳 4:“团队账号看到正向日期,用户账号可能已经看不到时段。” 回应:所以 Query 结果只是“这个时刻团队账号看到了真实正向日期”的强事实,不是预约承诺;快照不携带 times/daily ID,用户 Book 必须重查。Q-XACC 要求 3 个自然窗口 3/3,并测量时间预算。失败就调整或否决跨账号模型,不能用推断上线。 ### 反驳 5:“为什么不预先把用户账号也放进 Calendar,抢得更快?” 回应:当前 OrderBooker 在 create_session() 时没有把完整 user_inputs 传给插件,其他 Sede 可能有用户必填字段。现在修改通用框架属于过早扩权。先测量从热 /UserArea 到 precommit 的 p95;只有它确实错失 Slot,才用复现数据讨论最小的 prewarm 接口。 ### 反驳 6:“final listener timeout 后返回 false,Booker 还是会重试。” 回应:不能简单返回 false,也不能只靠插件内存。B13 前必须写入跨进程 durable fence; timeout、异常、新信号或重启看到 fence 后都只能对账。当前 tracker/grabbed 流程不能 证明具备该能力,所以 FENCE-1 是 FINAL-1 的前置 Gate;不足时必须单独扩展框架, 不能在 Italy 内用本地文件假装解决。 ### 反驳 7:“既然 E43 已经有正向 Slot,为什么还不能直接开发最终点击?” 回应:E43 已经足够实现双层解码、`1/0` 正向与 `0/-1` 负向分类和跨月扫描;E44 又证明通过完整正向 preflight 后,点击会得到唯一且正确的 `.fascia.act`。但最终 response、`/Reservation` 对账和 durable fence 仍未关闭。因此 CS1/CS3/CS4 可以在 final disabled 下推进,E44 关闭的选择态不能被偷换成 FINAL/FENCE 已关闭。 ### 反驳 8:“Query 不查 TimeSlots,怎么敢说 Available?” 回应:这里的 `Available` 是“该时刻该 Sede 的某个日期有正容量”,不是“用户账号已锁定某个时间”。E43 中 Availability 的 `1/0` 与同日唯一正向 TimeSlot 的 `1/0`、普通 DOM、`(1)` 完整一致;VFS/BLS 也已经用“日期强信号、Book 重查时间”的合同运行。Query 快照明确 `times=[]`,Book 必须重查;库存若在两者之间被抢走,是正常竞争,不是 Query 伪造。若未来出现正向日期长期无法在 Book 侧得到任何时段,Q-XACC 会否决或降级该模型。 ### 反驳 9:“为什么不只查询 Calendar 打开时的默认月份?” 回应:E43 已给出直接反例:默认 8 月窗口全负向,但向后到 10 月存在正向库存。只查默认月份会制造确定性的漏报。Query 必须在 route 配置的 lookahead 内从近到远逐月扫描;遇到首个正向月份立即停止,只有范围全部检查完且没有正向日期,才能返回无号。lookahead 是配置和 Gate 数据,不是写死香港月份。 ### 反驳 10:“这能保证永远预约成功吗?” 回应:不能保证第三方库存和网络。但能保证:只在真实正向证据下尝试、用户账号独立重查、最终最多一次、结果不明不盲重提、未知变化安全停止。这是工程上可以验证的 100% 边界。 ### 反驳 11:“既然叫生产 Query,为什么不立即把生产配置切到 calendar?” 回应:本 Change Set 把已验证的 Calendar 扫描合同放进生产插件代码,而不是把尚未关闭的 Session 准备合同伪装成已完成。生产 `calendar` 分支会要求同一插件实例已经完成 route 确认; 默认配置继续保持 `services_probe`。等 CS3B/OTP-AUTO 关闭后,再通过独立配置 Change Set 启用。这既保留了生产代码与调试工具的单一实现,又避免上线一个只能靠人工 OTP 才能维持的 半自动状态。 ## 23. 验证记录 ### 23.1 D0 设计验证 2026-08-29 实际执行的文档级验证: - heading 去重、围栏计数与奇偶校验; - P0 与 P1 假设表的编号唯一性与连续性校验; - R3 引用的 E 编号与唯一事实源做集合差; - 陈旧流程反向扫描; - 邮箱、Bearer、Cookie、明文 password、Turnstile 值模式扫描; - trailing whitespace、文件末尾换行和本地文档链接检查; - 旧恢复文档 SUPERSEDED 指针检查; - git status 复核现有脏工作树,没有清理或回滚用户修改。 以上最终命令组必须全部 exit 0;完整命令与返回值写在本轮交付报告。由于 D0 阶段 只修改设计文档,当时没有运行 Python 测试,也没有把未运行的代码验证写成已验证。 CS1 的后续验证单独记录在 §23.2,不能倒推成 D0 当时已经执行。 过程异常:第一次更新历史文档时,patch 因尾部上下文已经演进而未应用;读取真实 尾部后按实际内容重新执行成功。同一错误只出现一次,没有盲目重试。 ### 23.2 CS1 离线实现验证 2026-08-29 在 CS1 授权边界内实际执行: - `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_ita_protocol -v`: exit 0,28 个测试全部通过; - `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_ita_plugin -v`: exit 0,30 个现有 Italy 回归测试全部通过; - 对 `plugins/ita_protocol.py` 和 `test/test_ita_protocol.py` 执行内存编译:exit 0; - 对协议模块执行 AST import allowlist 检查:exit 0,没有浏览器、HTTP、进程或文件 I/O 依赖; - 扫描香港、Dublin、HKG、1321、4937 和 URL/OTP/AVANTI/final/click 等控制分支: exit 0; - 扫描超过 100 字符的代码行:0;trailing whitespace 与文件末尾换行检查:exit 0; - `ruff` 在当前 `.venv` 中未安装,因此明确记为未执行,不能写成已通过; - 本阶段没有调用浏览器、HTTP 客户端或真实网站调试工具,Italy 网站请求数为 0; - 没有修改 `ita_plugin.py`、配置、工具或现有测试,没有清理、回滚或覆盖工作区原有修改。 ### 23.3 CS2 通用路线接线验证 2026-08-29 在 CS2 授权边界内实际执行: - `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_ita_protocol test.test_ita_route_wiring test.test_ita_plugin test.test_debug_ita_session test.test_debug_ita_query test.test_debug_ita_book test.test_debug_ita_monitor test.test_debug_ita_soak test.test_ita_local_handoff`: exit 0,137 个测试全部通过; - `test.test_ita_route_wiring` 用 Dublin/1321 与 Hong Kong/4937 fixture 调用同一个 `_resolve_route()`,并验证顶层 `service_id` 不回退、未知 capability fail-closed、 Sentinel/Booker route parity,以及运行时代码没有 Sede/service-id 控制分支; - 调试 route 的完全默认值和完全显式值均通过;只覆盖 route 的一部分会被拒绝,避免 组合出“某地 service id + 另一地 routing key/city”的混合路线; - 对 CS2 涉及的 Plugin、配置、工具和测试执行内存编译与 `git diff --check`:exit 0; - 对 `query()`/`book()` 与工具调用路径执行安全扫描:没有 GenerateOTP、 InsertNewBooking 或表单提交调用;配置保持 final disabled; - 初见审查新增原子 route 覆盖约束后,第一次聚焦回归因一个旧测试 fixture 少传 `ITA_VISA_TYPE` 返回 exit 1;修正 fixture 后第二次执行 exit 0,26 个测试全部通过, 没有超过两次; - `ruff` 在当前 `.venv` 中仍未安装,因此明确记为未执行,不能写成已通过; - 本阶段没有启动浏览器或调用真实网站,OTP、AVANTI、InsertNewBooking 请求数均为 0; 没有清理、回滚或覆盖工作区其他既有修改。 ### 23.4 Q-CAL 跳转监听适配验证 2026-08-29 在单独批准的本地修复边界内完成: - 真实 Gate 已证明 pre/post OTP 阶段校验正确,但 AVANTI 后旧校验器要求 listener packet 必须保留原始 `302`,因而 fail-closed;独立 `/Reservation` 审计仍为 `reservations=0, waitlist=0`,没有新增预约或候补; - 本地 HTTP 服务与真实 Chromium/DrissionPage 机械复现了 `POST → 302 → GET Calendar 200` 会被高层 listener 表示为“原始 POST request + 最终 Calendar 200 response”,因此根因是客户端适配假设,不是网站拒绝的充分证据; - 修复只位于 Q-CAL 调试工具:直接 `302` 校验 Booking POST、Calendar Location 与浏览器 最终 Calendar;followed `200` 校验同一 Booking POST、packet 最终 Calendar URL 与浏览器 最终 Calendar。所有 URL 均要求同源,原始 POST 还要求无 query/fragment;任意证据不一致 均拒绝; - 通过时只记录 `direct_302` 或 `followed_redirect_200`,不会输出 query、Token、OTP、个人 数据或表单内容;语义合同升级为 `qcal1-stage-aware-redirect-v2`,生产 `ItaPlugin`、 Query/Book 合同和 final-disabled 边界均未修改; - 聚焦 Q-CAL 测试最终 22/22、完整 Italy 相关离线测试 171/171,均 exit 0;两份改动文件内存 编译、`git diff --check` 和尾随空格检查均 exit 0。首次聚焦测试因测试补丁误改另一个同形 冒号而 exit 1,读取精确行号后一次修正; - 本修复阶段没有启动浏览器、访问 Prenot@Mi、发送 OTP、点击 AVANTI 或调用 final。 Q-CAL-1 仍为 OPEN;下一次真实验证必须重新取得一次 OTP 与一次 AVANTI 的单独授权。 - 新合同第一次真实启动因 Codex 内部终端无法交给负责人而在 OTP 隐藏输入点中止:OTP=1、 AVANTI=0、Calendar=0、final=0,清理成功。负责人随后单独批准第二次 OTP/AVANTI,并在自己 的终端执行。 - 第二次真实执行确认合同和源码指纹正确,pre/post OTP 均 ready;OTP=1、AVANTI POST=1。 listener 已取得 POST packet,但浏览器未在 30 秒内进入 Calendar,工具 fail-closed,未执行 availability probe 或 final。随后独立只读 `/Reservation` 对账仍为 0/0、exit 0。 - 当前不能把失败归因于网站协议变化:两次执行产生了两封 OTP,首先必须确认输入的是不是 第二次运行对应的最新验证码;若验证码无误,则下一步只增加 allowlist 脱敏诊断,记录响应 status/同源 path 与可见错误类别,不记录 OTP、Token、query、表单值或个人信息,再申请新的 一次性真实 Gate。禁止直接重试。 ### 23.5 Q-CAL AVANTI 失败可观测性 负责人确认第二次真实 Gate 使用的是该次新收到的最新 OTP,因此旧验证码假设已降级;但旧 工具只能证明调用过输入方法并观察到 Booking POST,无法证明 OTP 值留在 DOM,也没有保留 Booking Form 返回后的安全错误形状。 经单独授权完成的本地修复如下: - 合同升级为 `qcal1-avanti-diagnostic-v3`;OTP 输入前后分别要求 `otpValuePresent=false/true`,该字段只记录 presence,不记录值或长度; - Booking POST 被 listener 接收后输出固定计数标志;未观察到 POST、Calendar 等待超时或 redirect 校验失败都会打印同一 allowlist 失败诊断后再抛错,不会重试; - URL 只输出 `booking/calendar/services/user_area/other_same_origin/unexpected_origin/missing` 等固定类别;HTTP status 和 DOM 计数只接受合法数值,其余置 null; - DOM 只读取表单是否存在、OTP presence、OTP-invalid 是否可见、AVANTI/Turnstile 布尔状态、 可见 validation/confirm 数量和 final 请求数量。response body、query、OTP、Token、表单值、 错误文案和个人信息均不进入诊断; - Q-CAL 聚焦测试 24/24、Italy 完整离线回归 173/173,均 exit 0;私密 response/query/POST/DOM sentinel 的序列化诊断命中为 0。本阶段真实网站、OTP、AVANTI、Calendar 和 final 请求均为 0。 ### 23.6 OTP macOS 焦点与精确回读 `qcal1-avanti-diagnostic-v3` 的真实 Gate 在人工输入最新 OTP 后报告 `otpValuePresent=false`,并在 AVANTI 前停止;该次 OTP=1,AVANTI/Calendar/final=0。这把 问题从“验证码是否正确”收敛为“自动化没有把值保留在 OTP DOM input”。 根因和修复均复用现有实现: - 当前 DrissionPage 在 macOS 上执行 `input(clear=True)` 时,clear 使用 JavaScript,但该分支 不主动 focus;后续键盘事件可能进入旧焦点; - Italy IAM 登录已经使用“先 `human_click_ele`、再 `input(clear=True)`”,Q-CAL OTP 改为同一 模式,不新增地区分支或另一套输入抽象; - 输入后把 expected OTP 作为浏览器函数参数,只返回 `this.value === expectedOtp` 的布尔值; Python 和日志都不读取实际 DOM value。比较失败则 AVANTI=0; - 按负责人明确要求,终端 OTP 改为可见输入,提示 terminal scrollback 风险;日志仍只输出 `matched=true`,不记录 OTP; - 合同升级为 `qcal1-otp-readback-v4`。真实 Chromium + 本地 `data:` 页面验证 exit 0、外部 请求 0;Q-CAL 聚焦测试 27/27、Italy 离线回归 176/176,均 exit 0。本修复阶段没有真实 Prenot@Mi、OTP、AVANTI、Calendar 或 final 请求。 ### 23.7 Calendar 翻月控件与请求月份闭环 `qcal1-otp-readback-v4` 的真实 Gate 已关闭进入 Calendar 的整条链路:OTP DOM 精确回读为 true、AVANTI POST 观察到 1 次、redirect 表示为 followed 200、浏览器最终到达 `/BookingCalendar`,且 final 请求为 0。随后工具在尝试第二个只读月份 probe 时抛出 `NoRectError`;负责人也观察到页面没有翻月。事后独立 `/Reservation` 审计仍为 `reservations=0, waitlist=0`。 根因不是 availability 协议,而是旧工具把横向时间线的 `a.next` 当成日历翻月控件,并交给 依赖元素矩形的 `human_click_ele()`。当前页面同时存在 Bootstrap datetimepicker 和横向 timeline;两套控件都可能叫 `next`,但职责不同。 第一版 v5 曾根据通用 Bootstrap datetimepicker 上游结构推断 `#datetimepicker .datepicker-days th.next[data-action="next"]`。真实 Gate 到达 Calendar 后却 稳定报告 candidate=0/actionable=0,证明该推断不适用于 Prenot@Mi 当前页面;它在翻月前 fail-closed,OTP=1、AVANTI=1、final=0。随后独立 `/Reservation` 对账仍为 0/0。 无需再次 OTP 即可恢复同一 Calendar 状态。真实只读探针取得了网站当前合同: - `InizializzaCalendario()` 对 `#datetimepicker` 调用 `datetimepicker({inline:true, locale:'it'})`; - 网站监听 `dp.update`,从 `e.viewDate` 取年月并调用 `CaricaTimelineOrizzontale(...)`,后者自然产生 availability POST; - 初始化后的 DOM 有 4 个 `th.dtpicker-next`,恰好 1 个可见;另有 4 个 `th.dtpicker-prev`,同样恰好 1 个可见; - 横向 timeline 的 `a.next` 仍存在但不可见,它没有 `data-action`,职责不是日历翻月; - 只调用网站初始化函数就自然观察到 availability=1,time-slot=0、final=0。 v6 采用以下收敛合同: - 只匹配 `#datetimepicker th.dtpicker-next`;不再匹配 `.cd-horizontal-timeline a.next`,也不 依赖当前网站并不存在的 `.datepicker-days` 或 `data-action`; - 先过滤 disconnected、disabled、aria-disabled、display/visibility/pointer-events/opacity、 无 viewport 交集或被遮挡的节点;只有唯一 actionable 候选时才在同一浏览器脚本中点击; - 候选为 0 时有界等待,候选大于 1 时 fail-closed;不回退到坐标点击,不做第二次业务点击; - listener 必须观察到第二个 `POST RetrieveCalendarAvailability`,严格 parser 必须接受响应; 两次 request 的 `selectedDay` 还必须解析为不同年月,否则即使触发了请求也判定没有翻月; - 日志只输出候选数量、actionable 数量和 clicked 布尔值,不输出日期、response body、Token、 OTP 或运行时服务标识;合同升级为 `qcal1-dtpicker-navigation-v6`。 早先 127.0.0.1 fixture 只证明“隐藏副本不点、唯一可见副本点一次”的通用过滤算法,不能证明 网站 selector;v5 真实 candidate=0 已明确否定其网站结构假设。v6 因此只以网站函数源码和 真实 DOM 为依据,不再从第三方上游模板反推 Prenot@Mi。 v6 本地准出记录:Q-CAL 聚焦测试 30/30、含账号配置测试的 Italy 全量离线回归 179/179,均 exit 0;源码指纹为 `ad4f07908ba5`。 随后利用同一授权账号中可恢复的 Calendar 状态执行真实只读验证,不发送 OTP、不经过 AVANTI:刷新 probe 返回 1 个日期项,点击 probe 返回 22 个日期项;两次 request 的 `selectedDay` 被严格解析为不同月份。点击诊断为 candidate=4、actionable=1、clicked=true。 执行前后 Reservation/Waitlist 均为 0/0,OTP=0、AVANTI=0、final=0,命令 exit 0、清理成功。 这机械关闭了“真实控件可唯一选择、自然触发 availability、请求月份确实变化”的 Q-CAL 翻月 合同,但不代表配置的三个月循环扫描或 Book final 已实现。 初见审查反驳: > “既然 JavaScript `.click()` 不是真实鼠标点击,是否在绕过网站限制?” 回应:这里不触碰日期、时段或最终预约,只驱动真实 DOM 已证明属于 `#datetimepicker` 的唯一 可见 `.dtpicker-next`。网站自己的 `dp.update` handler 才负责发只读 availability 请求;工具 不手工调用该 endpoint。使用 JS 的目的只是避免 DrissionPage 对三个隐藏副本读取 rect 的 客户端异常。真正的业务结果仍要由自然产生的同源 availability 请求及 request 月份变化双重 证明,任一不成立都停止。 ### 23.8 最多十二个未来月份的 Discovery 探针 为了回答“网站最远允许翻到哪个月份”,Q-CAL 工具升级为 `qcal1-bounded-horizon-v7`。这个版本没有改变生产 route 的 `calendar_scan.lookahead_months` 语义;它仍表示包含当前月在内的总扫描月份数。工具另外增加 仅用于 Discovery 的 `ITA_QCAL_FORWARD_MONTHS`,取值范围固定为 1–12,表示从当前月向后 点击多少次。这样不会为了调研而污染生产配置合同。 v7 复用 v6 已验证的 listener、严格 Availability parser、唯一可见 `#datetimepicker th.dtpicker-next` 和 `/Reservation` 对账。它先刷新并解析当前月,再按上限 逐月点击;每次 request 的月份必须恰好增加一个月,包含跨年。发现正向日期后仍继续,仅因为 本次目标是探查网站边界;未来生产 Query 一旦发现正向日期必须立即返回。 工具仍保持:OTP 最多 1 次、AVANTI 最多 1 次、每月只发自然产生的 Availability 请求,日期 点击 0、时段点击 0、`InsertNewBooking` 0。下一月控件持续不可交互时只记录 `next_control_unavailable`,不会在没有服务端证据时武断称为网站业务上限。 离线准出:Q-CAL 聚焦测试 36/36、Italy 全量离线回归 185/185、两文件内存编译、尾随空格 检查和 `git diff --check` 均 exit 0。真实 12 个月结果仍待负责人在自己的终端完成一次 OTP 后取得;在取得输出前不得宣称网站上限已知。 负责人随后把目标从“探最远边界”改为“验证最早可预约日期”。调试输出合同升级为 `qcal1-earliest-date-v8`:它只从严格解析后的正向 `CalendarDay` 中取最小日期,并在 `ITA_QCAL_MONTH_SCAN_RESULT.earliestAvailableDate` 输出 ISO 日期;无正向日期时输出 null。 这不读取 DOM 文案,也不包含运行时日历 ID、Token 或具体时段。 ## 24. CS3A 当前落点与下一道 Gate R3、CS1、CS2 和 CS3A 已在离线边界内完成。生产 `ItaPlugin.query()` 现在拥有显式的 `calendar` 分支,并与 Q-CAL 工具共同复用 `plugins/ita_calendar_query.py`:同一份代码负责 listener、Availability 请求元数据校验、严格 parser、唯一原生翻月控件、最终按钮 guard 和月份 单调递增。生产策略与 Discovery 策略刻意不同:Discovery 可继续探边界;生产在首个正向月份 立即停止,只返回该月最早日期。 这仍不等于“无人值守强 Query 已上线”,更不等于“完整 Italy Book 已跑通”: - 默认 Sentinel/Booker 配置仍是 `query_mode=services_probe`; - `calendar` 分支只接受已经由同一实例确认的 Calendar 状态,缺少准备态时 fail-closed; - CS3B 的自动 OTP、AVANTI 和 route 连续性尚未实现; - Q-CAL-2、Q-XACC、OTP-AUTO、FENCE 和 FINAL 仍是独立 Gate; - Book、时段选择和 `InsertNewBooking` 不在 CS3A 范围内。 **CS3A 已取得一次现场通过结果**:负责人回传同一人工准备的 Session 内两次生产 Query 均为正向、OTP/AVANTI 各一次、最终请求为零、前后预约数量不变及 exit 0,见 §24.4 和 Discovery E45。旧工具只有 `services_probe` 加 `scan_calendar_horizon()` 的执行不能替代 这一证明;本次验收模式直接调用生产分支。 CS3B/OTP-AUTO 仍依赖云端邮箱授权、Italy 邮件匹配和安全日志证据,见 §25。负责人最新 确认 Query 邮箱尚未接入并授权,要求列为待办(Discovery E50、ITA-OTP-01),暂不推进 邮箱接入。已有人工 OTP 验证结果保留;无人值守自动接码仍未完成,不切换生产配置。 ### 24.1 CS3A 离线准出记录 2026-08-30 已机械验证: - 生产扫描器从当前月开始严格逐月前进,首个正向月份立即停止; - 结果只发布首个正向月份中最早日期,`earliest_date` 与唯一 `DateAvailability(times=[])` 一致; - 首月正向、跨年、完整负向 horizon、月份跳跃、请求月份与响应日期不一致、下一月控件失效 均有离线测试;未知或不完整扫描 fail-closed,不能伪装成无号; - 生产 Query、Q-CAL 调试工具共同调用 `plugins/ita_calendar_query.py`,调试工具不再复制 listener、翻月、parser 或 final guard; - 生产模块不存在 `4937`、`Hong Kong`、`slot.hkg` 或 `HKG` 硬编码; - 默认配置未改变,OTP、AVANTI、日期点击、时段点击、最终预约和外部请求均为 0。 实际命令与结果: 1. 聚焦回归:90/90,exit 0; 2. Italy 全量离线回归:198/198,exit 0; 3. 8 个相关 Python 文件内存编译:exit 0; 4. `git diff --check`:exit 0;新增文件及本轮相关测试/文档行尾空白检查:exit 0; 5. 生产模块地区硬编码反向扫描:0 命中,命令 exit 0。 全文件空白扫描曾以 exit 1 报出 `plugins/ita_plugin.py` 的历史行尾空格; `git diff --check` 证明本 Change Set 没有新增这些问题。遵守“不顺手优化”,本轮没有清理与 功能无关的历史格式。 ### 24.2 CS3A 生产 Query 现场验收模式 2026-08-30,负责人授权仅补现有调试工具的生产 Query 验收入口,人工完成一次 OTP 准备。 工具合同为 `qcal1-production-query-v10`。本次没有修改扫描算法、生产配置、自动邮件读取或 Book;真实网站执行由负责人在自己的终端进行。随后收到一次现场通过结果,详见 §24.4; 这里保留当时批准的验收步骤与边界,不外推为长期稳定性或完整 Book 验收。 #### 入口与复用边界 - `tools/debug_ita_calendar_gate.py` 增加显式 `ITA_QCAL_MODE=production_query`;未指定时仍是 原有 `discovery_horizon` 模式,避免悄悄改变旧命令语义。 - 复用原有账号、持久化浏览器 profile、route resolver、表单准备、OTP DOM 回读、一次性 AVANTI 和 `/Reservation` 前后计数;不新建第二套登录或预约流程。 - 准备阶段仍只调用一次 `services_probe`。确认同一实例的 route 后,只在内存把模式改为 `calendar`,连续调用两次真实 `ItaPlugin.query()`,无论成功失败都恢复内存模式。 - 两次生产调用均使用已有 `scan_until_first_available_month()`,不替换扫描函数、不伪造网络 响应,不调用旧 `scan_calendar_horizon()`。结果复用 VFS 风格 `VSQueryResult` 及已有 `to_snapshot_payload()`;只验证序列化,不向 Redis 发布测试信号。 - 插件只新增本实例的 `last_calendar_query_scan` 诊断字段。每次 `query()` 开头清空,成功 扫描后写入;配置、Session 重建和 cleanup 也清空。它不是缓存,不参与下一次业务决策, 不进入共享快照,也不能作为 Book 的时间依据。 - 被动 Network 计数借用仓库已有 CDP callback 注册方式。使用页面 driver,和生产 `page.listen` 的独立连接并存;拒绝覆盖已有 handler。不启用 Fetch 拦截、不改请求、 不保留 body、Cookie 或 Token,退出时卸载自己的 callback。 #### 什么算现场验收完成 1. 一次 Session 创建、一次 OTP、一次 AVANTI 后完成 **两次**生产 Calendar Query; 两次之间间隔 3 秒,不自动重试失败流程。 2. 每次都逐月扫描,在首个正向月份停止,并返回该月最早日期;范围上限包含起始月。 第二次必须重新从第一次的初始月份扫描,不能直接把上次停留的月份当起点。 3. 实际返回的 `success`、状态、最早日期、唯一 `DateAvailability(times=[])` 及共享快照 必须与该次生产扫描证据一致;不能只验证一条自行打印的日期。 4. 每次 Query 的 Network 增量:OTP=0、AVANTI POST=0、最终请求=0,Availability 请求数 等于该次扫描月份数。页面初始化可能自动选择日期并读取时段,这不等于工具主动选时段。 5. `/Reservation` 预约和候补数量前后相同;全程已知最终端点请求数为 0。 6. 两次中至少一次自然得到正向日期,聚合输出 `passed=true`,cleanup 成功,进程返回 0。 库存可能在两次查询之间变化,因此**不要求两次最早日期相同**。如果两次完整扫描都自然 无号,只能证明负向查询完成,正向验收仍未关闭,返回 2。入口本身暂时无号时也返回 2, 不会为了得到成功日志而发送 OTP。 以上是客户端可观察的证据:已知请求的计数与预约数量没有变化,并不能证明服务器内部 绝对没有草稿,也不替代 Q-CAL-2 的长期运行验证。本次不批准无人值守生产运行。 #### 负责人终端命令 香港仅作为已取得字段证据的 route 示例,算法和验收模式不绑定香港或 `4937`。 最多扫描 12 个月,**每次一旦发现首个正向月份就停止**;不会为了用满上限继续翻页。 两次查询都无号时可能各扫描满 12 个月。这不是无限循环。 ```sh cd /Users/zhangwei/JSWorkSpace/open_source/coordinate source .venv/bin/activate ITA_QCAL_MODE=production_query \ ITA_ROUTING_KEY=slot.hkg.it.tourist \ ITA_SERVICE_ID=4937 \ ITA_CITY='Hong Kong' \ ITA_VISA_TYPE='Tourist' \ ITA_CALENDAR_LOOKAHEAD_MONTHS=12 \ ITA_BOOKING_TYPE_CONTROL_ID=typeofbookingddl \ ITA_BOOKING_TYPE_VALUE=1 \ ITA_BOOKING_TYPE_LABELS='Prenotazione Singola|Single booking' \ ITA_PURPOSE_CONTROL_ID=ddls_0 \ ITA_PURPOSE_VALUE=42 \ ITA_PURPOSE_LABELS='Turismo|Tourism' \ PYTHONDONTWRITEBYTECODE=1 \ python -B tools/debug_ita_calendar_gate.py echo "EXIT_CODE=$?" ``` `production_query` 模式只使用 route 的 `ITA_CALENDAR_LOOKAHEAD_MONTHS`,不使用仅属于旧 Discovery 的 `ITA_QCAL_FORWARD_MONTHS`。OTP 仍由负责人输入一次;输入可见,终端历史可能 保留验证码,回传输出时应删除该行。运行时不要手动翻月、刷新、选择时段或点击最终按钮, 避免改变扫描证据和请求计数。 需要回传: - `ITA_QCAL_TOOL_CONTRACT`(版本及源码指纹包含工具、生产插件、共享适配层、纯协议核心); - `ITA_QCAL_MODE`; - 两条 `ITA_QCAL_PRODUCTION_QUERY_RESULT`; - `ITA_QCAL_PRODUCTION_QUERY_GATE_RESULT`; - `ITA_QCAL_GATE_CLEANUP_OK` 和 `EXIT_CODE`;失败时同时提供脱敏的失败行。 | 进程返回值 | 含义 | | --- | --- | | 0 | 两次生产 Query 合同与对账通过,至少一次自然正向,清理成功 | | 1 | 流程、协议或证据检查失败;不要重复发送 OTP 猜原因 | | 2 | 自然库存未提供正向样本,正向 Gate 未完成,不是假装程序成功 | | 3 | 清理异常,需要先检查残留状态 | #### 初见审查 反驳:“工具也能自己扫出正确日期,怎么证明这次验证的是生产实现?” 回应:验收主调用是生产 `ItaPlugin.query()`,扫描证据由其内部实际扫描器产生;工具只比对 返回值和被动请求计数,不实现或替换扫描算法。离线集成测试保留真实 Query、共享扫描器、 parser 和序列化,仅用假浏览器提供受控页面与响应;另外验证旧 horizon 入口没有被调用。 这关闭本地接线路径问题,真实浏览器行为仍需上述现场 Gate,不能由 mock 测试代替。 ### 24.3 本次验收入口的离线验证记录 2026-08-30,本轮未执行真实网站登录、OTP 发送、AVANTI 提交或 Book 操作;下述测试全部 离线。生产配置未修改,工作区原有改动保留。 执行命令及返回结果: ```sh PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_debug_ita_production_query_gate # exit 0;21 tests,OK PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest \ test.test_debug_ita_production_query_gate \ test.test_debug_ita_calendar_gate test.test_ita_plugin test.test_ita_calendar_query # exit 0;102 tests,OK PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest \ test.test_add_ita_query_account test.test_ita_protocol \ test.test_ita_calendar_query test.test_ita_route_wiring test.test_ita_plugin \ test.test_debug_ita_session test.test_debug_ita_query test.test_debug_ita_book \ test.test_debug_ita_calendar_gate test.test_debug_ita_production_query_gate \ test.test_debug_ita_monitor test.test_debug_ita_soak test.test_ita_local_handoff # exit 0;220 tests,OK PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -c 'from pathlib import Path; paths = ["plugins/ita_plugin.py", "tools/debug_ita_calendar_gate.py", "test/test_debug_ita_production_query_gate.py", "test/test_debug_ita_calendar_gate.py", "test/test_ita_plugin.py"]; [compile(Path(p).read_bytes(), p, "exec") for p in paths]; print("COMPILE_OK files=" + str(len(paths)))' # exit 0;COMPILE_OK files=5;不生成 pyc git diff --check # exit 0 if rg -n '[[:blank:]]+$' tools/debug_ita_calendar_gate.py test/test_debug_ita_production_query_gate.py test/test_debug_ita_calendar_gate.py test/test_ita_plugin.py docs/ita_plugin_generic_schengen_design.md; then exit 1; else test "$?" -eq 1; fi # exit 0;本轮所列文件没有行尾空白 if rg -n '4937|Hong Kong|slot\.hkg|HKG' plugins/ita_plugin.py plugins/ita_calendar_query.py plugins/ita_protocol.py; then exit 1; else test "$?" -eq 1; fi # exit 0;生产模块没有香港特定常量 ``` 首次新入口聚焦测试为 101/101、exit 0,但测试替身使用 `__new__` 跳过真实初始化,析构时 产生未初始化属性告警。修正测试替身的 cleanup,并补上“必须恰好两次”的负向检查后, 再次验证 102/102、exit 0,无该告警;没有为消除测试告警而修改生产清理逻辑。 ### 24.4 CS3A 负责人现场回传通过(2026-08-30) 唯一事实记录为 Discovery E45。负责人回传了第二轮完整结果及聚合结果: - 第二轮从 `2026-08`、`2026-09` 的正向日期数 `0/0` 扫描到 `2026-10` 的 `14` 个正向日期; 上限 12 个月、实际 3 个月,停止原因 `first_available_month`,最早日期 `2026-10-13`; - 返回 `Available`、唯一日期、`timesCount=0`,`snapshotVerified=true`; - 第二轮请求增量:Availability=3、OTP=0、AVANTI=0、final=0; - 聚合报告:Query=2、positiveQueries=2、Availability=6、OTP=1、AVANTI=1、final=0; Reservation 和 Waitlist 前后均 `0/0`,`passed=true`; - `ITA_QCAL_GATE_CLEANUP_OK`,`EXIT_CODE=0`。 这是负责人执行 `python -B tools/debug_ita_calendar_gate.py`(production_query 模式)的 回传证据,不是助手再次访问网站。未回传第一轮完整结果、启动版本/源码指纹行和原始 Network,因此不推断第一轮具体日期,也不宣称独立复现或完整字节级运行溯源。 结论:本次人工准备后的生产 Query 验收通过,确信度高。该日期是发现时的线索,不是锁定 库存;Book 仍需用用户账号重查,自动接码、长时间运行和跨 Sede 验证没有因此通过。 ## 25. CS3B / OTP-AUTO 前置核对(未开始业务实现) ### 25.1 当前边界与结论 当前待办(2026-08-30,负责人明确要求): - [ ] **ITA-OTP-01:自动处理首次及重新需要 OTP 的 Calendar 准备,包括邮箱接入和云邮箱 API 授权。** 状态:未完成、 暂缓;负责人已确认“还没有”。恢复时复用现有 VFS/BLS 取信链路,验证授权有效、目标 收件人与新验证码匹配、旧码/串号不命中及日志不泄露。完成标准为取得这些受控取信证据; 仅登记邮箱不算通过 OTP-AUTO;还需证明重登后仅一次安全接续到 Calendar。当前不执行自动接入、取信或发码,也不安排提醒;除该 TODO 外的恢复与持续查询按 CS3R 独立推进。 此前负责人同意进行前置补证。已归档 E45、核对现有接码实现与前置条件;当时邮箱接入 状态未知,现已由 E50 更新为未接入并暂缓。负责人分享的 Gmail 标签两次访问未取得正文(E47),随后通过 手工转述补齐一份英文邮件的发件人、主题和验证码行(E48,已脱敏)。这不是完整原始邮件 或云端取信结果。随后两名指定子代理已找到 webapp 中的原有 IMAP/API 实现,确认 web-ui 没有邮箱授权页面(E49,详见 §26);线上授权仍未验证。不会为了收集证据重新发送 OTP, 也不会读取其他邮件、开启转发、注册邮箱服务或修改业务/生产配置。 可以直接复用的是现有邮箱读取 API 和 VFS 的调用顺序,而不是复制其他网站的固定邮箱、 发件人或模板。接码能力是否对本次 Italy 账号真正可用,仍需真实邮箱授权和受控读取证据。 ### 25.2 已核对的复用依据 | 现有来源 | 源码事实 | Italy 的复用方式/边界 | | --- | --- | --- | | `plugins/vfs_plugin.py:352`、`:891` | 在引发 OTP 的请求前记录 UTC `sent_at`,再传给 `_read_otp_email()` | 复用“先记时间,再单次发码,再取信”的顺序 | | `plugins/vfs_plugin.py:705` | 使用共享 `fetch_mail_content()`;recipient 取当前账号 username;正文 regex,另有 VFS 图片分支 | 直接复用共享 API;不照搬 VFS 图片识别、LLM 或其固定邮件过滤条件 | | `plugins/bls_plugin.py:943` | 同样调用共享 API;循环取信;其单次底层请求上限另由 SDK 决定 | 作为接口复用佐证;不能把 `wait_sec=30` 宣称为整个流程硬超时 | | `toolkit/vs_cloud_api.py:361` | `POST /api/email-authorizations/fetch`,返回 `data.body` 字符串 | 不新建 Provider、IMAP 客户端、Resend、消息队列或邮箱后端 | | `vs_types.py:127` | `VSAccount` 只有 id/username/password,没有 email 字段 | recipient 使用经确认的当前账号 username,不扩充账号模型 | | `tools/debug_ita_calendar_gate.py:745` | `OneShotAction` 在调用前消耗许可,异常也不允许同一 guard 再执行 | 复用现成“一次性动作”合同,不重新设计通用工作流引擎 | | Q-CAL 工具的 preflight、OTP 回读、AVANTI 校验 | 这些行为已经经历人工配合的真实验证 | 后续准备态接线复用这些行为;生产模块不得反向 import `tools` | | `plugins/tls_plugin.py` 的本轮检索 | 未找到 `fetch_mail_content` 或邮箱 OTP 读取调用 | 不把 TLS 插件当成已存在的邮箱接码实现;不推断其他注册工具的能力 | VFS/BLS 当前使用同一个写死的主邮箱。该值不是 Italy 账号,也不是可直接复制的授权依据; 本轮没有记录其真实地址。`authorization_email` 必须来自已有、已获授权的私密配置。 ### 25.3 共享 API 的实际合同与未知项 本节表格保留 E46 首次走读 Coordinate 调用端时的知识边界。后续 E49 已取得 webapp 实现, sender/recipient、关键字、时间窗口及 MIME 行为的最新结论以 §26 为准;线上授权和真实 邮箱测试仍未完成。 | Python 参数 | 发送字段 | 当前能证明的事实 | | --- | --- | --- | | `email` | `email` | VFS/BLS 传主邮箱;目标为 email-authorizations API,不能凭字符串就认为已授权 | | `sender` | `sender` | 过滤值会传给云端;精确地址、显示名、大小写如何匹配,客户端没有实现 | | `recipient` | `recipient` | VFS/BLS 传当前账号 username;跨账号筛选实际由云端负责 | | `subject_keywords` / `body_keywords` | `subjectKeywords` / `bodyKeywords` | 字符串原样传递;云端的包含、分词、AND/OR 语义尚未取得合同 | | `sent_date` | `sentDate` | VFS 使用 UTC `YYYY-MM-DD HH:mm:ss`;云端时区解释/比较边界需验证 | | `expiry` | `expiry` | 转为字符串;不能把调用方填写的 300 秒当成 Prenot@Mi 验证码有效期 | | `only_text` | `onlyText` | 默认 True;不需要沿用 VFS 的图片识别分支 | 单次 HTTP timeout 在客户端固定为 300 秒。`fetch_mail_content()` 本身没有客户端重试循环; 云端是否等待、怎样处理重复邮件并未由此证明。BLS 的外层轮询叠加这个 timeout,不能作为 Italy 的准确等待预算;VFS 的单次调用路径更接近当前“发一次、取一次、不重发”合同。 关键限制:客户端只返回正文,没有把命中邮件的 message id、sender、recipient、接收时间或 命中数量交给调用者。因此“参数传对了”和“后台确实只读到这封新邮件”不是同一项验收。 必须通过既有后端合同或受控正反样本验证,不能只用 mock 参数断言关闭旧码/串号风险。 仓库没有邮箱授权查询或授权建立的 SDK 方法,也没有该服务后端实现。本轮没有猜测新的 API 路由去访问后台。`fetch_mail_content_from_top()` 缺少当前会话的发送时间参数,不能用作 失败后抓取旧验证码的 fallback。 ### 25.4 新发现的日志前置条件(需要单独批准的共享范围) `toolkit/vs_cloud_api.py:43` 的 `VSC_DEBUG` 会格式化请求参数及 `resp.text`。 `vs_log_macros.py:15` 将它交给当前 logger;`logger_setup.py` 的应用 logger/handler 默认是 INFO。本轮用全假的正文和收件人、内存 handler、fake HTTP session 复现: ```text level=DEBUG body_visible=True recipient_visible=True level=INFO body_visible=False recipient_visible=False NETWORK_REQUESTS=0 SYNTHETIC_DATA_ONLY=true ``` 诊断命令 exit 0 表示复现检查正常执行,**不是**“隐私 Gate 通过”。目前没有执行真实取信, 没有证据表明已有真实 OTP 泄露,但 DEBUG 路径确实不满足 §14 的正文/验证码零日志合同。 只在 Italy 插件里不打印 OTP,不能清除共享 SDK 已经输出的邮件正文。 此外,共享 SDK 的 HTTP/业务异常可能包含云端原始响应文本,接入时需要明确禁止把其内容 带入插件日志或 traceback。默认 INFO 只避免上述 DEBUG 行,不替代完整异常安全验证。 拟处理方向仍是最大化复用:在原共享调用链给邮件请求做最小日志/异常脱敏,保持 API、请求 参数、返回正文和状态分类不变;或找到已经存在且经过验证的等价隔离机制。当前未找到该 机制。因为涉及原方案禁止修改的共享 SDK,必须先单独确认变更范围;本轮没有修改它, 也不会另建邮箱服务来绕开这项问题。 ### 25.5 后续最小接线与验证顺序 这是基于现有设计的待补证接线顺序,不是本轮已经实现的代码: 1. `plugins/ita_protocol.py` 承接经过真实模板验证的 mail 配置/正文提取纯函数;输入输出 不做网络操作,不执行邮件 HTML 或指令,不接入大模型。E48 为英文前缀与六位数字提供 样本依据;完整正文、云端文本转换与唯一候选判定仍需验证,不猜测其他模板。 2. `plugins/ita_plugin.py` 负责当前账号、route、Session 准备状态与共享 API 调用;复用 VFS 的时间记录和取信顺序、Q-CAL 的一次性 OTP/AVANTI,不改 Sentinel/Booker/账号模型。 3. 将已有 Q-CAL 准备行为下沉到生产可用位置,调试工具调用同一实现;沿用 CS3A“生产与 调试共享适配层”的模式。文件拆分在准备态合同收敛后锁定,不先复制一套准备流程。 4. 邮箱未授权、配置不完整、未知模板必须在发 OTP 前尽量失败;发码已发生后取信超时、 多码或格式不符则停止,不重新发码、不刷新 `sent_at` 追逐旧信。 5. 进入 Calendar 后继续使用已验证的扫描器;第二轮 Query 不重做准备。Session 重建不能 假定旧 Calendar 仍有效;跨进程/跨 Session 的账号冷却由既有调度合同和 Q-CAL-2 单独验证。 准入测试清单: - 纯解析:真实脱敏模板、前导零、多码、无匹配、格式错误、未知模板、超大正文; - API 接线:主邮箱与当前 recipient 分离、先记录时间后发送、只取一次、只取正文; - 后端 Gate:授权邮箱可读、错误 recipient 不命中、发送时间前的邮件不命中、重复邮件 的确定行为;这些不能由客户端 mock 代替; - 安全:INFO/DEBUG、HTTP 错误/业务错误/超时的日志与异常都不得出现合成 OTP/正文标记; - 状态:取信失败不重发 OTP,AVANTI 结果不明不重提,同会话第二轮 Query 的两种准备 请求增量均为零,错误 route/账号/Session 不复用准备态; - 回归:现有 220 项离线测试保持通过;最终真实 Gate 仍由负责人终端操作,final=0。 E48 已补齐一份邮件字段与验证码行的手工样本,E49 已找到现有管理 API;无需重新发送 OTP,也不再让负责人寻找 web-ui 中不存在的邮箱授权菜单。E50 已确认未接入并要求暂缓。 后续恢复 ITA-OTP-01 时,从单个授权 Query 邮箱开始核对登记和实际可读性;不索取密码、 密钥或整个接口响应,不把待办登记视为已经授权执行。 ### 25.6 本轮验证与初见审查 2026-08-30,仅更新本文及 Discovery。七个受关注的业务/SDK/生产配置文件用 SHA-256 对比 确认未改变;未运行登录/OTP/取信/AVANTI/Book,未修改任何邮箱设置。 - Italy 全量回归沿用 §24.3 的完整 unittest 命令再次执行:220/220,exit 0; - DEBUG/INFO 对照诊断使用当前 `_perform_request` 的 AST 方法体、内存日志和 fake HTTP 响应,命令 exit 0,网络请求 0;结果为 §25.4 的潜在敏感日志路径已复现; - 文档行尾空白检查、`git diff --check`:exit 0。 初见审查:“现成 API 都接收 recipient 和 sentDate,为什么不直接认为旧码/串号问题已解决?” 回应:传参只是客户端事实;该客户端返回的只有正文,不能独立证明后台筛选的结果。沿用 同一 API 是复用架构,补真实过滤与隐私验证是接入验收,两者并不冲突。没有这些证据, 不能用一段能匹配六位数字的代码宣称无人值守接码已完成。 ### 25.7 邮件样本访问状态更新(E47) 负责人已分享现有 OTP 邮件的 Chrome 标签。实例、标签标识、标题和 URL 首次核对均匹配, 但正文读取及一次恢复访问均超时。达到两次上限后停止;没有实际取得发件人或正文,不能 把标签标题 `OTP Code` 当成完整邮件模板,也不能关闭邮箱云端接入或 OTP-AUTO Gate。 改由负责人提供同一封邮件的脱敏截图或文字,仅需发件人地址、主题和验证码相关正文; 验证码用 `[OTP]` 替换,个人资料及动态链接移除。无需重新发送 OTP、导出整个邮箱或安装 新邮件服务。现有 API 复用方向、共享 SDK 日志问题及后端正反样本验收要求均保持不变。 ### 25.8 邮件字段与提取合同候选(E48) 负责人手工提供的样本已脱敏归档:显示名 `Prenotami`、发件地址 `noreply-prenotami@esteri.it`、主题 `OTP Code`、正文片段 `OTP Code:[OTP]`,样本验证码 为六位 ASCII 数字。样本转述的字段/形态确信度高,但并非助手读取原始邮件或云端命中结果。 在不新增邮件服务的前提下,现有 `fetch_mail_content()` 的候选过滤值可收敛为上述发件地址、 主题及正文前缀;`recipient` 仍是经核对的当前 Italy 账号,`authorization_email` 仍来自 已授权的私密配置,两者不能混用。不能假设云端将地址、关键字和时间按期望精确组合匹配。 解析沿用 VFS 的确定性正文提取模式,仅在 `OTP Code:` 上下文取六位数字,保留前导零; 无匹配、多候选或未知模板均停止。完整正文是否还有其他候选、HTML 转文本形态、其他语言 和有效期尚未取得证据;不能把这份样本扩大为全语言/全领区验证,也不使用全文任意六位 数字或大模型猜码。具体实现与测试仍在独立 CS3B 范围内,当前没有新增代码。 当前仍未关闭:云端邮箱授权/收件人对应关系、后台排除旧码/串号的正反例、SDK 日志/异常 安全以及自动填码到 Calendar 的真实验收。人工分享邮件内容不等于授予云端服务新的权限。 ## 26. VFS/BLS 邮件链路跨项目复核(E49,未开始实现) ### 26.1 复用结论与职责 两名负责人指定的 `luna_worker/max` 分别只读调查 `web-ui@b21b7ca` 与 `webapp@fbb82bb`。 结论是**可以复用原有整条邮件服务链路,不需要新建 Provider 或后台**,但现有行为不能 直接宣称满足 Italy 的精确新邮件、隐私和一次性准备合同。完整证据与验证命令见 Discovery E49。 | 层 | 已有实现 | 本阶段动作 | | --- | --- | --- | | web-ui | Next.js 门户、用户/站点账号/任务管理;门户绑定邮箱及 email_verified | 无邮箱授权页面,不新增页面,不把门户邮箱验证当作 IMAP 授权 | | Coordinate | VFS/BLS 共用 `VSCloudApi.fetch_mail_content()`,八参数 POST Query | 保留 API 调用路径与 VFS 发码前 UTC 时间记录顺序 | | webapp | FastAPI 管理员 API、邮箱凭据登记、IMAP 取信与候选筛选 | 使用现有服务;本轮只查源码,不修改、不实际取信 | 管理 API 的已确认路径是 `GET /api/email-authorizations/email/{email}`;默认 API 文档在 webapp 根路径 `/docs`(部署 host/反代路径未验证)。它要求管理员 Bearer session,并会 返回包含授权码等凭据的对象,没有 exists-only 接口;不能让负责人粘贴完整 JSON。 记录存在也不能证明 IMAP 凭据仍有效,模型没有 active/expiry/last-check 状态。 ### 26.2 从“未知”收敛出的实际合同差异 1. `sender/recipient` 是 raw From/To 子串,不是精确邮箱地址;多关键字 CSV 是 OR-any。 单纯把完整官方发件地址填入参数,不能宣称完成了地址认证或本地精确校验。 2. 取信只扫描 INBOX 最近 10 个消息序列号;按最后一个 Received 转 UTC 后排序,匹配 `[sentDate, sentDate + expiry]` 闭区间,取首个命中。没有唯一性、去重或消费语义。 3. `onlyText=True` 仍保留 HTML,可重复输出 MIME plain/HTML 中的同一码。E48 的候选解析 规则必须覆盖此差异;相同码的 MIME 重复不等于不同验证码冲突,也不能未经验证便对 任意引用/转发去重并取首码。纯函数归一策略需在实现前固定并用真实云端形态验收。 4. 后端轮询预算与 SDK HTTP timeout 不是端到端硬限时;IMAP 阻塞阶段无显式 socket timeout。 5. 默认读写 SELECT + RFC822 有隐式已读副作用,最近候选邮件可能在筛选前已被读取。 未来现场 Gate 要说明这一邮箱状态影响;本轮没有执行 fetch。 6. 返回只有 body,缺少 From/To/时间/唯一标识。客户端 mock 参数正确,不能关闭跨账号 或旧码验收;不能承诺在 Italy 端凭不存在的 metadata 做完整复核。 ### 26.3 最小下一步与变更纪律 当前下一步只核对一个目标邮箱的登记存在性、管理员身份和非敏感配置完整性;在负责人 自己的已授权环境执行,原始凭据不输出、不入日志。该检查不取信、不发 OTP、不修改登记。 获得登记证据后,再制定最小的真实取信 Gate:账号/From/To/Received 时间、正常邮件与 旧邮件/错误收件人、MIME形态、耗时和已读变化,不能仅测“能解析六位数字”。所需动作、 目标邮箱和副作用另行说明,不把此轮只读源码调查当成真实取信授权。 已定位的共享 SDK 日志问题、后端子串筛选与响应/日志风险是明确的接入约束;若关闭 Italy 既定准入条件需要改 webapp 或 SDK,应提交小范围合同/测试计划并单独批准。不修改 VFS/BLS 行为、不替换 Provider、不增加邮箱管理 UI,不在调查中顺手整改硬编码凭据。 ### 26.4 验证与确信度 - 两仓静态调研、路由/字段对应:高;各仓 HEAD/clean 状态已记录。 - 主代理实际 SDK 方法 + fake HTTP 验证:exit 0,八参数与空 body/一次调用均确认。 - 主代理实际 `_extract_body` + 合成 MIME:五场景七断言通过,exit 0;HTML保留、相同前缀 出现两次、空白折叠已离线复现;endpoint八参数 Query/类型绑定也通过。 - 这两项离线诊断网络请求为 0,不导入后端应用;没有运行会加载环境/数据库的 pytest。 - 邮箱登记、实际登录有效性、线上部署一致性、自动接码及完整 Book:未验证,不宣称通过。 初见审查:“是不是发现现有服务不够严格,就准备重写一套?” 回应:不是。Provider、授权存储、管理员鉴权、API与调用顺序都有现成实现。当前只补事实 和准入证据;若确需改变匹配或脱敏行为,也限定在既有链路的小范围变更,经批准后再做。