# CS4A:Book 日历时段选择工作记录 日期:2026-08-30。状态:CS4A 离线已验证,尚未接入 Book 总入口或现场验收。 Phase: VERIFIED(仅本文件限定的离线增量)。Approval: 本地开发、测试;不包含真实登录、 OTP、取信、前置表单提交、最终预约、提交代码或上线。Evidence/Risks: 聚焦 25 项、Italy 回归 245 项均通过;现场会话、响应新鲜度和完整 Book 仍未验证。 本文件只记录 [总设计 CS4](./ita_plugin_generic_schengen_design.md) 的一个增量,不替代 总设计或 [Discovery 事实账本](./ita_plugin_discovery.md)。负责人已允许推进 Book;没有 Query 任务链接不作为阻塞条件。共享设计文档在本轮读取后发生变化,原修改完整保留。 ## 1. 本轮范围和文件 只新增 `plugins/ita_calendar_book.py`、`test/test_ita_calendar_book.py` 和本工作记录。 不修改 `ita_plugin.py`、`ita_protocol.py`、`ita_calendar_query.py`、调试工具、配置或邮箱服务。 因此现有 `ItaPlugin.book()` 仍保持表单前安全停点,本轮不声称完整 Book 已接通。 采用现有 Functional Core + Imperative Shell:新增的只是与 Calendar Query 并列的 Book 浏览器适配层,不新增框架。复用 `parse_availability_packet()`、`parse_time_slots()`、 `available_slot_candidates()`、`DateSelectionState`、`SlotSelectionState`、 `approve_precommit()` 和 `guard_calendar()`。不复制地区分支或重写候选排序规则。 ## 2. 调用合同(实现前固定) ```python approval = select_slot_before_final( book_page, target_day=target_day, availability_packet=current_book_availability_packet, time_slots_packet=current_book_time_slots_packet, ) ``` 前置条件:调用方已证明用户账号、route、日期偏好和 Calendar 准备状态;两个 packet 必须 由该用户页面本次原生动作的监听取得,不能传 Query 快照、跨账号响应或持久化旧 packet。 本模块不负责登录、OTP、翻月、日期点击或证明采集时间。内容一致不等于来源或新鲜度证明; 这些能力属于后续 CS4 编排及现场验收,不能用本次离线结果替代。 行为: 1. 校验同源精确 path/method/status、请求字段和目标日期;TimeSlots 的 `idService` 必须匹配当前 DOM `#idServizio`,不拿 Services 的配置 `service_id` 替代。 2. 复用双层 JSON 与容量规则。合法无号返回 `None`;错日、错服务、结构变化和容量冲突 抛明确错误,不冒充无号。 3. 日期必须已被调用方选中,timeline/content 两个 selected 区域日期一致,且网站最终 handler 使用的第一个全局 selected 仍为正确时间线日期。不会偷偷改日期或补发请求。 4. 在正确日期内容中按 daily ID、时间和数量定位唯一正向时段。使用 scoped hidden input, 不按全局重复 HTML id 查找;点击前后检查负向 class、红点和容量。 5. 时段最多原生点击一次;正确候选已经唯一 active 时不重复点击。最终按钮始终禁用。 6. 返回既有 `PrecommitApproval` 只表示本次选择态通过,不是预约成功或最终提交授权; 真正 final 前仍须重新校验、通过 FENCE/FINAL 验收并取得最终提交授权。 ## 3. 准出条件 - 测试覆盖正向 `1/0`、无号 `0/-1`、容量冲突、错误日期/服务/域名/方法/状态、畸形响应、 重复节点、隐藏值/时间/数量不匹配、负向 active、页面漂移、不重复点击和异常脱敏。 - 不导入调试工具或 Query 插件实例,不构造 HTTP 请求,不操作 OTP/AVANTI,不点击 final。 - 运行时 ID 不进入返回对象 repr、日志或异常;新增 JS 用离线合成 DOM 检查。 - 新模块测试、既有 Italy 回归、编译与 `git diff --check` 返回 0。 - 真实网站操作为 0;真实 session 连续性、监听新鲜度、DOM 交互和预约成功仍待现场验证。 ## 4. 验证记录 以下命令在仓库根目录执行;未启用真实浏览器、网站或邮箱服务。 ### 4.1 聚焦测试 ```sh PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_ita_calendar_book ``` 返回值:`0`;结果:`Ran 25 tests ... OK`,无跳过。包含真实执行新增 JS 源码的 Node 合成 DOM 测试:正向选择、不重复点击、负向/遮挡/重复节点拒绝、点击后日期或域名漂移。 合成 DOM 不是网站浏览器,不能证明真实布局、监听关联或会话有效性。 ### 4.2 既有 Italy 回归 ```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_query \ test.test_ita_local_handoff \ test.test_ita_plugin \ test.test_ita_protocol \ test.test_ita_route_wiring ``` 返回值:`0`;结果:`Ran 245 tests in 3.359s ... OK`,无失败、无跳过。 数量包含既有 220 项和新增 25 项,不代表全仓库或 VFS/BLS 的测试覆盖。 ### 4.3 静态检查与改动隔离 ```sh PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -c 'from pathlib import Path; paths = [Path("plugins/ita_calendar_book.py"), Path("test/test_ita_calendar_book.py")]; [compile(path.read_bytes(), str(path), "exec") for path in paths]; print("COMPILE_OK files=2")' git diff --check ``` 均返回 `0`;编译输出 `COMPILE_OK files=2`,没有写入字节码。 三个新增文件另逐一执行 `git diff --no-index --check -- /dev/null <文件>`:均无空白错误 输出;均返回 `1`,这是 no-index 比较中新文件与 `/dev/null` 不同的返回值,不能记为 `0`。 新增文件还单独执行以下行尾空白检查: ```sh awk '/[[:blank:]]+$/ { print FILENAME ":" FNR ": trailing whitespace"; ita_ws_failed=1 } END { if (!ita_ws_failed) print "NEW_FILES_WHITESPACE_OK files=3"; exit ita_ws_failed }' plugins/ita_calendar_book.py test/test_ita_calendar_book.py docs/ita_book_cs4a.md ``` 返回值:`0`;结果:`NEW_FILES_WHITESPACE_OK files=3`。 `shasum -a 256` 返回 `0`;下面七个共享文件与本轮实现前指纹完全一致: `plugins/ita_plugin.py`、`plugins/ita_protocol.py`、`plugins/ita_calendar_query.py`、 `tools/debug_ita_calendar_gate.py`、`tools/debug_ita_book.py`、 `config/config_sentinel.json`、`config/config_booker.json`。 共享设计文档的并发修改未覆盖,原有脏工作区未回滚。 ## 5. 初见审查 反驳:“参数都对上了,是否就能证明是用户账号刚查到的号?能否直接据此提交预约?” 不能。响应内容和 DOM 一致只能证明本次选择态一致,不能证明响应来自哪个账号、是什么 时候捕获,也不能保证下一瞬间号源仍在。本模块明确要求调用方完成账号/route 连续性和 本次监听关联;它返回既有 `PrecommitApproval`,没有返回预约成功,更没有最终提交能力。 最终按钮沿用现有 guard 禁用;这也不等于拦截页面全部网络副作用,后续现场 Gate 仍须 独立确认最终请求数为 0。 审查修正:在实际时段点击及随后回读时增加同源判断,防止首次 Python URL 检查后页面 跳到同路径的其他域名;新增相应 JS 测试。未修改共享 helper。 确信度:本轮离线合同为高;真实浏览器适配和完整 Book 尚未验证。 ## 6. 下一步(未在本轮实现) 把现有登录/Calendar 准备能力接入 Book 编排,由**申请人自己的会话**重查日期、选日并 监听本次 TimeSlots,然后调用本模块。沿用现有路由与日期偏好规则,不复制 Query 的 浏览器、Cookie、OTP 或 daily ID。先在最终确认按钮前做一次现场验收;无需等待 Query 任务链接,也不把本轮测试通过当作已预约或上线许可。