ita_book_cs4a.md 7.9 KB

CS4A:Book 日历时段选择工作记录

日期:2026-08-30。状态:CS4A 离线已验证,尚未接入 Book 总入口或现场验收。

Phase: VERIFIED(仅本文件限定的离线增量)。Approval: 本地开发、测试;不包含真实登录、 OTP、取信、前置表单提交、最终预约、提交代码或上线。Evidence/Risks: 聚焦 25 项、Italy 回归 245 项均通过;现场会话、响应新鲜度和完整 Book 仍未验证。

本文件只记录 总设计 CS4 的一个增量,不替代 总设计或 Discovery 事实账本。负责人已允许推进 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. 调用合同(实现前固定)

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 聚焦测试

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 回归

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 静态检查与改动隔离

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。 新增文件还单独执行以下行尾空白检查:

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 任务链接,也不把本轮测试通过当作已预约或上线许可。