# CS4B:Book 当前会话重查与入口接线 日期:2026-08-30。状态:CS4B 离线已验证;尚未接入完整 Calendar 准备或现场验收。 Phase: VERIFIED(仅离线合同)。Scope: 已准备 Calendar 的用户会话从重查走到最终按钮前。 Non-goals: 不改 Query、共享框架、邮箱服务、生产配置或最终提交。 Done: 离线证明请求来自本次 Book 监听、日期偏好生效、选日后时段/DOM 一致、最终点击为 0; Italy 回归、编译和差异检查返回 0。Approval: 负责人“继续吧”的本地开发授权。 Evidence/Risks: [CS4A](./ita_book_cs4a.md) 已离线验证;完整 Book 和原生选日仍需现场验收。 ## 1. 先确定复用和文件归属 本文件承接[总设计 §9、CS4](./ita_plugin_generic_schengen_design.md),不另立工作流框架。 | 责任 | 既有参照 | 本轮落点 | |---|---|---| | 用户账号与调用入口 | OrderBooker、VFS/BLS 的独立 Book Session | `ita_plugin.py` 中增加薄入口;不改 Booker | | 用户日期偏好 | VFS `expected_start_date` / `expected_end_date` | 保留原字段,严格解析、不修改输入字典 | | 日期正向判断、范围过滤、排序 | `ita_protocol.py` | 直接复用 | | 刷新、原生翻月、单月递增、最终按钮保护 | `ita_calendar_query.py` | 直接调用,不改 Query 行为 | | 当前浏览器请求监听 | USA/TLS 的 `page.listen`,Q-CAL 的 `finally: stop` | 放在 `ita_calendar_book.py` | | 时段选择、点击后校验 | CS4A `select_slot_before_final()` | 直接调用 | | 最终结果类型 | `VSBookResult` | 停点仍返回 `success=False`,不填写预约编号 | 修改范围:`plugins/ita_calendar_book.py`、`plugins/ita_plugin.py`;新增 `test/test_ita_calendar_book_flow.py` 和本记录。原测试及共享文件原则上不修改。 不增加地区分支、配置开关、邮箱 Provider 或 Redis 字段。 ## 2. 输入、流程和输出 ### 2.1 Book 的准备证明 - `ItaPlugin.book()` 在 Calendar 分支只接受本实例**专属 Book 准备记录**;Query 的准备 标记不算证明,也不会被自动转换为 Book 标记。 - 准备记录绑定本实例、当前浏览器对象和 tab、当前账号、登录代次、完整 route 和 Calendar runtime service;重新配置、重新登录和 cleanup 清除记录。日历操作开始后,无论得到 正向停点、无号还是错误,都不允许自动再执行一次 Book;需要新的准备。请求开始前的 账号等参数校验不消耗网络操作额度。 - 调用方必须在用户账号完成已验证的对应 route 的 OTP/AVANTI 跳转后登记。登记方法是 编排层内部接口,不是从 URL 推断 Sede 的方法,也不能证明调用方未观察到的站点事实。 - `user_inputs.username` 必须匹配当前账号;仅一次 Book 执行。账号或 route 中途变化则 停止。未完成 Calendar 准备时保留既有“表单前停止”路径,不隐式发送 OTP/AVANTI。 ### 2.2 重新查询与候选策略 1. 查询只用当前用户 `page`;不接收 Query 的 packet、Cookie、时段或 daily ID。 2. 原生刷新 Calendar,监听本次 Availability 和页面自动产生的 TimeSlots。 3. 两个 packet 均须来自当前 `tab_id`,并通过同源、方法、状态、字段、日期和 runtime service 校验。每次开始监听清空旧队列,每次结束都停止;不写自定义 HTTP 请求。 4. Availability 只产生日期候选;先按既有设计尝试范围内的 Query 提示日,但必须在当前 Book 响应中重新证明正向。提示失效时最多重新从起始月扫描一次,按用户范围内日期升序 回退。每个日期候选最多尝试一次;同一天先容量降序、再开始时间升序,沿用 CS4A。 5. 已由网站自动选中的日期必须使用**本次刷新/翻月时捕获**的匹配 TimeSlots,不能重复 点击同一天并假设一定再发请求。换日期才执行一次原生点击并监听新的 TimeSlots。 6. 请求完成后等待有限时间让 DOM 更新,核对 timeline/content 的实际日期;网站静默回退、 错服务、错月份、重复节点、结构冲突均报错,不能冒充无号。 7. 每轮月数受当前 route 的 `calendar_scan.lookahead_months` 限制;提示日失效最多两轮。 翻月失败或未完整扫完不能报告“已验证整个范围无号”。号源仅在已扫描范围内有效。 8. 当前日期已没有正向时段是正常竞争,可以尝试下一候选;已执行时段点击后出现错误则 直接停止,不换号、不盲目重试。 9. 成功到达停点只保存当前进程内的 `PrecommitApproval`,返回 `VSBookResult(success=False, label="calendar-ready-before-final")`;无合适号返回既有无号停点,异常明确抛出。 本模块不会替调用方发送 OTP 或准备 Calendar。普通 `debug_ita_book.py` 目前仍停在表单; 专用现场验收入口和完整准备编排另接,不能把本轮离线接线当作端到端预约已完成。 ## 3. 为什么需要监听两个响应 E30 的网站初始化函数会程序化点击首日;E33 的 TimeSlots 来自该原生流程。当前已安装 DrissionPage `Listener.start()` 会 `clear()` 队列和 request-id 集合,`DataPacket.tab_id` 可绑定浏览器。先只监听 Availability 再停止,会漏掉已经发出的自动 TimeSlots。 因此复用同一监听器的多 target 能力,不通过移除 `.selected`、伪造 DOM 或手写接口强迫 网站重新发送请求。重复点击 selected 日期的实际网站行为仍待现场证明;实现不依赖它。 ## 4. 假设与准出测试 - HK 正向、其他 route/配置同路径;源代码无城市名或真实 service ID 分支。 - 第一个正向日已自动选中:使用本次时段响应,人工日期点击为 0;其他日期点击为 1。 - 本次监听前的旧数据、错误 tab、错误日期/服务/月份、跳月、监听超时均拒绝。 - 日期范围闭区间、跨年、提示日失效、当前月有号但不在用户范围、全部无号。 - 正向日期的时段被抢完:尝试下一日;格式/容量冲突:报错而不是跳过。 - 账号、route、page、登录代次变化或 Query 准备标记冒用:不查询、不选择。 - 重复 Book 不重新执行;任何阶段失败最终按钮保持禁用、监听器停止。 - 不输出密码、OTP、正文、runtime service、daily ID;不修改 `user_inputs`。 - Node 合成 DOM 检查真实选日脚本;假浏览器检查入口到 CS4A 的完整离线链路。 - 回归需覆盖既有 Query、表单安全停点和本轮新增代码。 ## 5. 验证与初见审查 ### 5.1 实际执行命令 在仓库根目录执行: ```sh PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_ita_calendar_book_flow ``` 返回 `0`;`Ran 51 tests in 0.334s ... OK`,无跳过。 测试运行实际 Book 入口和浏览器编排,仅替换浏览器/Network;选日 JS 另由 Node 的合成 DOM 执行。假浏览器按已读的本站流程及本地监听器源码建模,不能代替真实页面时序与布局验收。 ```sh PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest \ test.test_add_ita_query_account \ test.test_debug_ita_book \ test.test_debug_ita_calendar_gate \ test.test_debug_ita_monitor \ test.test_debug_ita_production_query_gate \ test.test_debug_ita_query \ test.test_debug_ita_session \ test.test_debug_ita_soak \ test.test_ita_calendar_book \ test.test_ita_calendar_book_flow \ test.test_ita_calendar_query \ test.test_ita_local_handoff \ test.test_ita_plugin \ test.test_ita_protocol \ test.test_ita_route_wiring ``` 返回 `0`;`Ran 296 tests in 3.066s ... OK`,无失败、无跳过。包含原有 245 项和本次新增 51 项。最早一次聚焦运行因直接导入了另一测试类而重复收集部分旧测试,已改为通过模块 引用 fixture;这里的 51 和 296 均是修正后的最终实际数量。 回归中显示的 `ITA_QCAL_*`、`ITA_PREFLIGHT_OK` 是假浏览器测试输出,不是新的网站登录、 OTP 或生产 Query 现场证据。 ```sh PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -c 'from pathlib import Path; paths = [Path("plugins/ita_calendar_book.py"), Path("plugins/ita_plugin.py"), Path("test/test_ita_calendar_book_flow.py")]; [compile(path.read_bytes(), str(path), "exec") for path in paths]; print("COMPILE_OK files=3")' git diff --check awk '/[[:blank:]]+$/ { print FILENAME ":" FNR ": trailing whitespace"; ita_ws_failed=1 } END { if (!ita_ws_failed) print "BOOK_FILES_WHITESPACE_OK"; exit ita_ws_failed }' plugins/ita_calendar_book.py test/test_ita_calendar_book_flow.py docs/ita_book_cs4b.md ``` 均返回 `0`。分别输出 `COMPILE_OK files=3`、无差异空白错误、`BOOK_FILES_WHITESPACE_OK`。 编译不写入字节码;没有启动浏览器、读取真实账号配置、取信、发 OTP、执行预约、commit 或部署。原有未提交修改保留。 ### 5.2 共享行为隔离 执行 `shasum -a 256` 返回 `0`,下列文件与本轮开始时完全相同: - `plugins/ita_calendar_query.py`:`e78e19d0f39a6a71e6dcd0474e7353ade63a0f79fb91f5e0ef2b0676616c4802` - `plugins/ita_protocol.py`:`422e63226f3bbb3d9e4c1274d293ed34ccdc4b58e1b180f0c2bd9c199f9279a1` - `tools/debug_ita_calendar_gate.py`:`98021ab36ba8342210cc4deb6da1180328f85a9ef27c351f14ff77a472dda145` - `tools/debug_ita_book.py`:`100c27621bf9eae5d59b507625f127ea0f0151980695cbb40dd6dc72d4a21cb9` - `config/config_sentinel.json`:`90bb58bd4fe5f83ecd54c97e9c8e1760a7c8c8b3ca9c951295490bd5318a2b7c` - `config/config_booker.json`:`a6c7f0f7762916825a559014f94e92f443d995b68bd9ea06dcbb58ae663649c5` `ita_plugin.py` 只接入 Book 分支、准备记录和生命周期清理;没有编辑 `query()` 或 `_query_calendar()` 的实现。Q-CAL 的复合源码指纹会因它包含 `ita_plugin.py` 而变化, 不能把旧的现场日志当作新增 Book 的运行证明。 ### 5.3 初见审查 反驳:“相同 URL 和日期的响应,也可能来自 Query 账号或旧请求,为什么能拿来 Book?” 回应:本轮不是把旧 packet 传入 CS4A;是由当前 Book page 在原生动作前启动监听,清空 旧请求集合并捕获新的 packet。它们还必须匹配当前 tab、当前 runtime service、当前日期, 并通过点击后的 DOM 复核。Query 的准备标记和另一个插件实例的 Book 记录都不能使用。 但这不是网站身份的独立认证:账号、route 和 AVANTI 连续性仍必须由后续准备编排证明; 内部登记方法不能被当成“打开 Calendar 就授权”的捷径。跨账号现场 Gate 尚未关闭。 反驳:“首日时段早已自动加载,再点一次就能重新拿到吗?” 回应:不能假定。本轮在月加载阶段一起捕获自动 TimeSlots;只有它对应当前仍选中的日期 时才使用。若后来切换过日期,即使又回到原自动日期,也会重新点击、监听,拒绝复用旧 DOM 和 packet。对应的正常、后退和错误响应测试均通过。 反驳:“返回无号,就意味着用户整个日期范围都没有号?” 回应:只代表当前 Calendar 起始月、route lookahead 和用户日期范围的交集没有可用候选。 不能外推更远未来;翻月失败、响应缺失、容量矛盾或日期回退均为错误,不返回正常无号。 实际 HTTP `401` / `429` 映射为既有 `SessionExpiredOrInvalidError` / `RateLimiteddError`; 其他协议或结构错误明确失败。最终按钮禁用与观察计数仍不是服务端占位证明或全网络写屏障。 timeout 约束的是各次响应/DOM 等待,不声称覆盖浏览器连接阻塞的整体硬墙钟上限。 ## 6. 剩余工作与现场条件 下一步是把**既有**手工 OTP/AVANTI 验收能力接到 Book 专用入口,使用申请人账号,不使用 Query 的凭据或 profile。在真实 POST/跳转、服务/表单选择和账号连续性都确认后,才调用 `_record_calendar_book_prepared_route()`,再执行这里已离线验证的 Book 分支。 现场验收需证明:准备阶段 OTP/AVANTI 各最多一次;Book 重查期间二者增量为 0;最终请求 始终为 0;请求月份/日期、当前显示时段和 `last_booking_precommit` 一致;预约/候补记录 前后不变。若异常,停止并收集脱敏状态,不重发 OTP 或最终请求。 自动接码、从普通订单 Session 自动准备 Calendar、跨账号正向传播、最终一次提交与对账 仍未完成。旧 `debug_ita_book.py` 继续停在表单,不提供或暗示尚未实现的新 CLI 参数。 确信度:本轮离线合同为高;真实 Book 全流程尚未验证,不能保证预约成功或宣称已上线。