Files
douyin_guaji-main/docs/预约系统详细流程.md
Your Name 95b4517bdd feat: Enhance logging and parameter tracking capabilities
- Refactor `gui_core.py` to improve code readability and maintainability by adding line breaks for long statements.
- Introduce `inspect_lines.py` script for inspecting specific line ranges in files.
- Add `generate_param_locations.py` to scan the repository and generate a report of function definitions, argparse parameters, and tracking calls.
- Implement `param_usage_tool.py` for analyzing `param_usage.json` records and scanning code for tracking calls.
- Create `simulate_reservation_preempted_flow.py` and `simulate_reservation_preempted_flow_dynamic.py` to validate behavior of reservation logic under specific conditions.
- Add global parameter tracking feature in `run_cli.py` to enable detailed usage tracing.
2026-01-03 19:12:58 +08:00

13 KiB
Raw Permalink Blame History

预约系统详细流程说明

一、预约记录流程

1.1 触发条件

当识别到高价值福袋时,会触发预约记录流程:

  • 高价值判断:福袋价值 >= high_value_fudai_threshold_yuan(默认配置)
  • 倒计时检查:倒计时大于阈值(skip_if_countdown_gt_seconds)
  • 剩余秒数检查:剩余秒数 > high_value_fudai_join_ahead_seconds(默认120秒)

1.2 记录前检查

在记录预约之前,会进行以下检查:

  1. 观看任务检查:

    • 检查是否是"观看X分钟"类任务
    • 如果是观看任务,不记录预约,直接关闭详情页并切换直播间
  2. 黑名单检查:

    • 检查福袋内容是否命中黑名单
    • 如果命中黑名单,不记录预约,直接关闭详情页并切换直播间

1.3 预约去重策略

add_reservation_core_logic 函数会检查是否已存在相同预约:

去重判断条件(满足任一条件即视为重复):

  1. 完全匹配:(future_ts, content) 相同,且直播间名字相同(规范化后)
  2. 兼容匹配:(future_ts, content) 相同(兼容旧数据,没有直播间名字的情况)
  3. 相似度匹配(处理OCR误差):
    • 直播间名称相似(相似度 >= 0.6 或互为子串)
    • 开奖时间相近(相差5秒内)
    • 奖品价值相同(允许0.01的误差)
    • 内容核心部分相似(相似度 >= 0.7)

处理方式:

  • 如果检测到重复预约:
    • 新价值 > 旧价值:更新为更高价值的记录
    • 新价值 <= 旧价值:保留旧记录,丢弃新记录

1.4 预约排序规则

预约队列按以下规则排序(_sort_reservations_inplace):

  1. 主排序键:future_ts(预计开奖时间戳)升序 - 越早开奖越优先
  2. 次排序键:prize_value_yuan(奖品价值)降序 - 价值越高越优先
  3. 第三排序键:created_ts(创建时间)升序 - 创建越早越优先

1.5 队列裁剪

  • 队列上限:high_value_fudai_max_reservations(默认3个)
  • 裁剪规则:如果队列超过上限,按排序规则裁剪掉优先级最低的记录
  • 裁剪日志:记录被丢弃的预约详情(价值、开奖时间、内容等)

二、预约回退流程

2.1 主循环检查

在主循环 run_once_basic 中,每次都会检查预约队列:

  1. 队列满检查(优先处理):

    • 如果队列已满(len(reservations) >= max_reservations)
    • 且未在等待状态(queue_full_waiting_at_earliest = False)
    • 调用 handle_queue_full_wait_at_earliest 回退到最早开奖的预约直播间
  2. 队列满等待状态检查:

    • 如果已在等待状态(queue_full_waiting_at_earliest = True)
    • 回退后的立即参与由回退处理流程内决定(已移除 _reservation_back_direct_attend 标志),此时会在流程中直接处理参与逻辑或进入阶段诊断
  3. 预约回退窗口检查:

    • 如果队列未满,调用 process_reservation_attend_window 检查是否需要回退

2.2 队列满处理流程(handle_queue_full_wait_at_earliest)

触发条件:

  • 队列长度 >= high_value_fudai_max_reservations
  • 未在等待状态

处理步骤:

  1. 排序队列:确保取到最早开奖的预约
  2. 检查锁定期:如果已在锁定期内,跳过回退
  3. 阶段诊断:回退前先进行阶段诊断,处理弹窗等异常状态
  4. 回退到最早直播间:
    • 计算位置差(current_room_pos - target_pos)
    • 如果不在目标位置,先下滑一次确保在直播列表中
    • 调用 seek_reservation_room_callback 回退到目标直播间
  5. 立即参与行为:
    • 回退到目标直播间时会触发立即参与的行为(不再通过 _reservation_back_direct_attend 标志),同时设置锁定期为当前时间(focus_until = now_ts)以保证短期内不切换直播间
  6. 等待页面加载:延迟1.5秒等待页面加载完成

特点:

  • 队列满后立即参与,不等待开奖窗口
  • 锁定期设置为当前时间,不阻塞后续流程

2.3 预约回退窗口处理流程(process_reservation_attend_window)

触发条件:

  • 队列未满,或已在等待状态但需要检查时间窗口
  • 多间模式(needswitch = True)

处理步骤:

步骤1:获取目标预约

  • 排序队列,取队头(最早需要处理的预约)
  • 检查 future_ts 是否有效,无效则丢弃

步骤2:计算时间窗口

  • 基础提前量:high_value_fudai_join_ahead_seconds(默认120秒)
  • 动态提前量计算:
    dynamic_ahead = max(
        基础提前量,
        回退步数 * 回退延迟 + 18秒缓冲
    )
    
    • 回退步数 = current_room_pos - target_pos
    • 回退延迟 = reservation_back_swipe_delay_s(默认0.6秒)
  • 时间窗口:
    • 开始时间:future_ts - dynamic_ahead
    • 结束时间:future_ts + poll_before_open_seconds(默认10秒)

步骤3:锁定期检查

  • 无锁定期(focus_until = 0):直接允许检查时间窗口
  • 锁定期已过期(now_ts >= focus_until):允许检查时间窗口
  • 锁定期未结束:
    • 检查是否是同一个预约(允许5秒误差)
    • 如果是同一个预约,且已在目标位置,检查时间窗口是否到达
    • 如果不是同一个预约,不允许回退(需要等待当前预约完成)
  • 队列满立即参与(focus_until == now_ts):跳过时间窗口检查,直接参与

步骤4:时间窗口检查

  • 未到时间窗口(now_ts < future_ts - dynamic_ahead):
    • 跳过回退,记录剩余秒数
  • 已过时间窗口(now_ts > future_ts + poll_before):
    • 清理过期预约,跳过回退
  • 在时间窗口内(future_ts - dynamic_ahead <= now_ts <= future_ts + poll_before):
    • 执行回退操作

步骤5:执行回退

  1. 计算位置差:pos_diff = current_room_pos - target_pos
  2. 位置调整:
    • 如果不在目标位置(pos_diff != 0),先下滑一次确保在直播列表中
  3. 回退到目标直播间:
    • 调用 seek_reservation_room_callback 回退到目标直播间
    • 通过直播间标题匹配找到目标直播间
  4. 设置锁定期:
    • focus_until = future_ts + poll_before_open_seconds
    • 在锁定期内不再切换直播间
  5. 设置待处理标志:
    • reservation_after_action_pending = True
    • 表示预约回退后需要处理

三、预约参与流程

3.1 预约回退后的参与

场景1:队列满后立即参与

  • 队列满后会在回退流程内触发立即参与行为(不再设置 _reservation_back_direct_attend),并设置锁定期为当前时间

场景2:时间窗口内回退

  • 回退到目标直播间后,设置锁定期和待处理标志
  • 下一轮主循环中,阶段诊断检测到直播间或福袋详情页
  • 检查直接参与标志,如果设置了则直接参与

3.2 直接参与标志处理

在福袋详情页(stage == "FUDai_DETAIL"): 回退后参与由回退流程直接处理;已移除 _reservation_back_direct_attend 与 _force_attend_after_reservation_back,不再依赖这些运行时标志。详情页检测到回退待处理时会直接进入参与处理逻辑或按常规验证流程执行。

在直播间(stage == "IN_LIVE_ROOM"):

  1. 检查回退待处理状态(直接参与标志已移除)
  2. 如果为 True:
    • 清除直接参与标志
    • 设置强制参与标志
    • 查找福袋并打开详情页
    • 然后直接参与

3.3 回退后参与决策

回退后不再通过运行时强制参与标志跳过验证;现在的决策基于时间窗口与回退上下文:当回退到目标直播间且时间窗口满足参与条件时,流程会直接执行参与逻辑;否则按常规的验证与预约记录处理。


四、预约队列管理

4.1 队列清理

  • 自动清理:每次调用 process_reservation_attend_window 时,如果预约已过期,会自动清理
  • 清理条件:future_ts <= now_ts(已过开奖时间)
  • 清理日志:记录被清理的预约详情

4.2 状态文件

  • 文件路径:state/reservations.json
  • 写入时机:
    • 添加预约时
    • 队列裁剪时
    • 预约回退时
    • 清理过期预约时
  • 文件内容:
    • 预约队列数据
    • 当前直播间信息
    • 更新时间戳

4.3 预约完成处理

  • 所有预约完成:如果 queue_full_waiting_at_earliest = True 且 reservations 为空
  • 处理方式:
    • 重置到第一个直播间(回退 room_pos 次)
    • 清除等待标志
    • 清除锁定期

五、关键配置参数

5.1 预约相关配置

  • high_value_fudai_enabled:是否启用高价值预约(默认:根据配置)
  • high_value_fudai_threshold_yuan:高价值阈值(元)
  • high_value_fudai_max_reservations:最大预约数量(默认:3)
  • high_value_fudai_join_ahead_seconds:预约参与阈值(默认:120秒)
  • poll_before_open_seconds:开奖前轮询时间(默认:10秒)
  • high_value_fudai_max_swipe_back:最大回退次数(默认:60)

5.2 时间窗口计算

  • 基础提前量:high_value_fudai_join_ahead_seconds(默认120秒)
  • 动态提前量:max(基础提前量, 回退步数 * 0.6 + 18)
  • 时间窗口开始:future_ts - dynamic_ahead
  • 时间窗口结束:future_ts + poll_before_open_seconds

六、完整流程示例

示例1:正常预约流程

1. 识别到高价值福袋(价值100元,倒计时300秒)
   ↓
2. 检查:价值 >= 阈值 ✓
   ↓
3. 检查:剩余秒数 > 120秒 ✓
   ↓
4. 检查:不是观看任务 ✓
   ↓
5. 检查:未命中黑名单 ✓
   ↓
6. 检查:队列未满 ✓
   ↓
7. 添加到预约队列
   ↓
8. 排序队列(按开奖时间、价值、创建时间)
   ↓
9. 写入状态文件
   ↓
10. 继续寻找其他福袋
    ↓
11. 当时间窗口到达(开奖前120秒)
    ↓
12. 回退到目标直播间
    ↓
13. 设置锁定期(直到开奖后10秒)
    ↓
14. 识别福袋详情并参与
    ↓
15. 参与成功后,等待开奖
    ↓
16. 开奖后处理结果

示例2:队列满流程

1. 识别到高价值福袋
   ↓
2. 添加到预约队列
   ↓
3. 队列已满(>= 3个)
   ↓
4. 立即回退到最早开奖的预约直播间
   ↓
5. 触发立即参与行为(已移除 `_reservation_back_direct_attend` 标志)
   ↓
6. 设置锁定期为当前时间(立即参与)
   ↓
7. 下一轮主循环:检测到直播间
   ↓
8. 检查直接参与标志:为 True
   ↓
9. 查找福袋并打开详情页
   ↓
10. 设置强制参与标志
    ↓
11. 直接参与(跳过倒计时检查)
    ↓
12. 参与成功后,等待开奖

示例3:预约去重流程

1. 识别到高价值福袋A(价值100元,开奖时间T1)
   ↓
2. 添加到预约队列
   ↓
3. 再次识别到相同福袋A(价值100元,开奖时间T1)
   ↓
4. 检查去重条件:
   - future_ts 相同 ✓
   - content 相同 ✓
   - 直播间名字相同 ✓
   ↓
5. 判断为重复预约
   ↓
6. 新价值 <= 旧价值:保留旧记录,丢弃新记录

七、日志输出说明

7.1 预约记录日志

  • [预约] add_reservation_core_logic 函数入口:记录预约信息
  • [预约] 添加新预约到队列:新预约添加
  • [预约] 检测到重复预约,更新为更高价值:重复预约更新
  • [预约] 预约队列已满,丢弃最低优先级记录:队列裁剪

7.2 预约回退日志

  • [预约] process_reservation_attend_window 函数入口:回退检查开始
  • [预约] process_reservation_attend_window 详细检查:时间窗口和锁定期检查
  • [预约] 时间窗口未到,跳过回退:未到时间窗口
  • [预约] 进入预约参与窗口,准备回退到目标直播间:开始回退
  • [预约] 已回退到目标直播间,等待详情识别与参与:回退成功

7.3 队列满处理日志

  • [预约] handle_queue_full_wait_at_earliest 函数入口:队列满处理开始
  • [预约] 队列已满,回退到最早开奖的预约直播间等待:开始回退
  • [预约] 队列满回退后,直接设置参与标志(立即参与,不等待开奖窗口):设置立即参与
  • [预约] 已回退到最早开奖的预约直播间,立即参与(不等待开奖窗口):回退成功

八、注意事项

  1. 单间模式:如果 needswitch = False,不启用预约回退逻辑,预约会在当前直播间自动识别和参与

  2. 锁定期机制:回退到预约直播间后,会设置锁定期,在锁定期内不再切换直播间,避免错过开奖

  3. 时间窗口:动态提前量会根据回退步数自动调整,确保有足够时间回退到目标直播间

  4. 队列满处理:队列满后立即回退到最早开奖的预约直播间,不等待开奖窗口,立即参与

  5. 预约去重:使用多种策略判断重复预约,包括完全匹配和相似度匹配,处理OCR误差

  6. 状态持久化:预约队列会写入状态文件,程序重启后可以恢复预约队列