================================================================================
抖音福袋挂机程序 - 完整流程图（WPS详细版）
================================================================================

【文档说明】
本文件包含完整的程序流程图，可以直接在WPS中创建流程图使用。
建议使用WPS演示（WPS演示文稿）的"插入 → 形状 → 流程图"功能创建。

【版本信息】
版本: V3.3.3+
最后更新: 2025-12-XX
主要更新: 30分钟超时保护、手动操作功能、并行OCR优化、回退逻辑修复

================================================================================
一、主流程图
================================================================================

【开始】程序启动
    ↓
【操作】初始化环境（加载配置/连接设备）
    ↓
【判断】是否在运行时间内？
    ├─ 否 → 【结束】程序结束
    └─ 是 → 继续
    ↓
【循环】主循环开始
    ↓
【判断】检查30分钟超时（V3.3.3+）
    ├─ 【判断】是否成功参与过？
    │   ├─ 是 → 【判断】距离最后参与是否超过30分钟？
    │   │   ├─ 是 → 【操作】返回推荐页面（多次点击返回键，最多10次）
    │   │   │   ↓
    │   │   │   【操作】点击关注标签
    │   │   │   ↓
    │   │   │   【操作】点击进入直播间（连点2次）
    │   │   │   ↓
    │   │   │   【操作】重置超时时间
    │   │   │   ↓
    │   │   │   【延迟】延迟2秒 → 返回主循环
    │   │   └─ 否 → 继续
    │   └─ 否 → 【判断】运行时间是否超过30分钟？
    │       ├─ 是 → 【操作】返回推荐页面（同上）
    │       └─ 否 → 继续
    ↓
【判断】是否启用高价值预约且有预约队列？
    ├─ 是 → 【处理】处理预约回退
    │   ├─ 检查队列是否已满
    │   ├─ 检查是否需要回退到预约直播间
    │   └─ 【判断】是否已触发预约回退？
    │       ├─ 是 → 【返回】本轮结束，等待下一轮
    │       └─ 否 → 继续
    └─ 否 → 继续
    ↓
【操作】获取屏幕截图
    ↓
【判断】截图成功？
    ├─ 否 → 【记录】记录错误 → 【延迟】延迟1秒 → 返回主循环
    └─ 是 → 继续
    ↓
【操作】阶段诊断（判断当前页面状态）
    ↓
【判断】是否在抖音前台？
    ├─ 否 → 【恢复】尝试恢复进入直播间
    │   ├─ 点击桌面图标
    │   ├─ 点击直播按钮
    │   └─ 点击进入直播间
    │   ↓
    │   【延迟】延迟后返回 → 返回主循环
    └─ 是 → 继续
    ↓
【判断】当前页面阶段？
    │
    ├─ COUPON_POPUP（优惠券弹窗）
    │   ↓
    │   【处理】处理优惠券弹窗（按返回键关闭）
    │   ↓
    │   【延迟】延迟0.5秒 → 返回主循环
    │
    ├─ SHOPPING_REDPACKET_POPUP（购物红包弹窗）
    │   ↓
    │   【处理】处理购物红包弹窗（点击关闭按钮）
    │   ↓
    │   【延迟】延迟0.5秒 → 返回主循环
    │
    ├─ FUDai_RESULT（抽奖结果弹窗）
    │   ↓
    │   【处理】处理抽奖结果（点击我知道了/领取并使用）
    │   ↓
    │   【延迟】延迟0.5秒 → 返回主循环
    │
    ├─ FANS_CLUB_JOIN（粉丝团加入）
    │   ↓
    │   【处理】处理粉丝团加入（点击加入/关闭）
    │   ↓
    │   【延迟】延迟0.5秒 → 返回主循环
    │
    ├─ FUDai_DETAIL（福袋详情页）
    │   ↓
    │   【跳转】→ 进入"福袋详情读取流程"（见第二部分）
    │
    ├─ IN_LIVE_ROOM / LIVE_OR_UNKNOWN（在直播间）
    │   ↓
    │   【操作】查找福袋图标（优化查找器）
    │   ↓
    │   【判断】找到福袋？
    │   ├─ 否 → 【判断】是否启用切换？
    │   │   ├─ 是 → 【操作】上滑切换直播间
    │   │   └─ 否 → 【延迟】延迟1秒
    │   │   ↓
    │   │   返回主循环
    │   │
    │   └─ 是 → 【操作】点击福袋图标（等待2.5秒）
    │       ↓
    │       【验证】验证详情页是否打开
    │       ├─ 像素检测
    │       └─ OCR检测邀你抢红包
    │       ↓
    │       【判断】验证成功？
    │       ├─ 否 → 【记录】记录错误 → 【延迟】延迟1秒 → 返回主循环
    │       └─ 是 → 【设置】设置验证标志（缩短后续等待时间）
    │           ↓
    │           【跳转】→ 进入"福袋详情读取流程"（见第二部分）
    │
    ├─ RECOMMEND_PAGE（推荐页）
    │   ↓
    │   【导航】导航到直播间
    │   ├─ 点击关注标签
    │   └─ 点击进入直播间
    │   ↓
    │   【延迟】延迟2秒 → 返回主循环
    │
    ├─ FOLLOW_LIST / LIVE_LIST（关注列表/直播列表）
    │   ↓
    │   【导航】导航到直播间
    │   ↓
    │   【延迟】延迟1秒 → 返回主循环
    │
    ├─ LIVE_CLOSED（直播已关闭）
    │   ↓
    │   【操作】上滑切换直播间
    │   ↓
    │   【延迟】延迟1秒 → 返回主循环
    │
    └─ UNKNOWN（未知阶段）
        ↓
        【记录】记录未知阶段
        ↓
        【延迟】延迟1秒 → 返回主循环
    ↓
【延迟】延迟1秒
    ↓
【判断】是否在运行时间内？
    ├─ 否 → 【结束】程序结束
    └─ 是 → 【判断】是否有异常？
        ├─ 是 → 【记录】记录异常，延迟2秒 → 返回主循环
        └─ 否 → 返回主循环


================================================================================
二、福袋详情读取流程（核心流程）
================================================================================

【开始】开始读取福袋详情
    ↓
【判断】优化查找器已验证？（_fudai_detail_verified）
    ├─ 是 → 【操作】短暂等待0.3秒，清除验证标志
    └─ 否 → 【操作】正常等待1.2秒
    ↓
【循环】开始重试循环（最多2次）
    ↓
【检测】检测优惠券弹窗
    ├─ 颜色统计
    ├─ 模板匹配
    └─ OCR确认"开心收下"
    ↓
【判断】是优惠券弹窗？
    ├─ 是 → 【操作】关闭优惠券弹窗
    │   ↓
    │   【返回】coupon_popup状态
    │   ↓
    │   【结束】
    └─ 否 → 继续
    ↓
【检测】检测任务数量（像素检测参与按钮位置）
    ↓
【判断】任务数 = 0？
    ├─ 是 → 【返回】error状态（认为不在福袋详情页，跳过OCR识别）
    │   ↓
    │   【结束】
    └─ 否 → 继续
    ↓
【判断】任务数在1-3范围内？
    ├─ 否 → 【操作】设置为2个任务
    └─ 是 → 【操作】使用检测到的任务数
    ↓
【操作】裁剪OCR区域（根据任务数选择坐标）
    ├─ 裁剪福袋内容区域
    │   ├─ 1个任务：(390, 1300, 980, 1530)
    │   ├─ 2个任务：(390, 1240, 980, 1470)
    │   └─ 3个任务：(390, 1160, 980, 1390)
    ├─ 裁剪倒计时区域
    │   ├─ 1个任务：(390, 1180, 690, 1300)
    │   ├─ 2个任务：(390, 1110, 690, 1230)
    │   └─ 3个任务：(390, 1010, 690, 1130)
    └─ 裁剪价值区域
        ├─ 1个任务：(390, 1520, 1000, 1630)
        ├─ 2个任务：(390, 1460, 1000, 1580)
        └─ 3个任务：(390, 1380, 1000, 1490)
    ↓
【并行】并行OCR识别（3个线程同时执行）
    ├─ 线程1：OCR识别福袋内容（模式0）
    ├─ 线程2：OCR识别倒计时（模式0）
    └─ 线程3：OCR识别价值（模式0）
    ↓
【判断】检查原始OCR内容是否为"观看X分钟"任务？
    ├─ 是 → 【操作】设置观看任务标志（_is_watch_task_detected=True）
    │   ↓
    │   【返回】watch_task状态
    │   ↓
    │   【操作】关闭详情页
    │   ↓
    │   【结束】（跳过后续所有处理）
    └─ 否 → 继续
    ↓
【操作】提取参与人数和份数，清理内容文本
    ├─ 提取：共X份、X人已参与
    └─ 清理：移除份数和参与人数信息
    ↓
【判断】检查清理后内容是否为"观看X分钟"任务？
    ├─ 是 → 【操作】设置观看任务标志
    │   ↓
    │   【返回】watch_task状态
    │   ↓
    │   【操作】关闭详情页
    │   ↓
    │   【结束】（跳过后续所有处理）
    └─ 否 → 继续
    ↓
【等待】等待所有OCR完成
    ↓
【判断】倒计时识别成功？
    ├─ 否 → 【操作】分割倒计时区域
    │   ├─ 前1/3：识别分钟
    │   └─ 中1/3：识别秒
    │   ↓
    │   【操作】组合为 mm:ss 格式
    └─ 是 → 继续
    ↓
【操作】解析倒计时，转换为时间戳
    ├─ 解析 mm:ss 格式
    └─ 计算未来时间戳
    ↓
【验证】验证详情数据合理性
    ├─ 内容不能为空（至少2个字符）
    ├─ 价值应该大于0
    ├─ 价值应该合理（不超过100万）
    ├─ 倒计时应该合理（0-24小时）
    ├─ 参与人数不能是负数
    ├─ 份数应该合理（至少1份）
    └─ 时间文本应该存在
    ↓
【判断】数据验证通过？
    ├─ 否 → 【判断】是否还有重试次数？
    │   ├─ 是 → 【延迟】延迟0.8秒重试 → 返回循环开始
    │   └─ 否 → 【返回】error状态
    │       ↓
    │       【结束】
    └─ 是 → 继续
    ↓
【检查】倒计时一致性检查（与第一次读取对比）
    ├─ 计算时间流逝
    ├─ 计算预期倒计时
    └─ 计算实际差异
    ↓
【判断】倒计时合理？（差异不超过30%）
    ├─ 否 → 【操作】使用第一次读取的结果
    └─ 是 → 【操作】使用当前结果
    ↓
【返回】ok状态，详情元组
    ├─ content（内容）
    ├─ time_text（倒计时文本）
    ├─ participants（参与人数）
    ├─ copies（份数）
    ├─ prize_value_yuan（价值）
    └─ countdown_tuple（倒计时元组）
    ↓
【结束】


================================================================================
三、福袋筛选决策流程
================================================================================

【开始】开始筛选决策
    ↓
【操作】读取福袋详情（内容/倒计时/价值/人数）
    ↓
【判断】状态检查
    ├─ watch_task → 【返回】观看任务已跳过（已在OCR阶段处理）
    │   ↓
    │   【结束】
    ├─ coupon_popup → 【返回】优惠券弹窗已关闭
    │   ↓
    │   【结束】
    ├─ error → 【返回】识别错误
    │   ↓
    │   【结束】
    └─ ok → 继续
    ↓
【验证】数据验证通过？
    ├─ 否 → 【返回】丢弃
    │   ↓
    │   【结束】
    └─ 是 → 继续
    ↓
【判断】内容关键词是否在黑名单？
    ├─ 是 → 【返回】丢弃
    │   ↓
    │   【结束】
    └─ 否 → 继续
    ↓
【判断】价值 >= 最小阈值？
    ├─ 否 → 【返回】丢弃
    │   ↓
    │   【结束】
    └─ 是 → 继续
    ↓
【判断】参与人数在范围内？
    ├─ 否 → 【返回】丢弃
    │   ↓
    │   【结束】
    └─ 是 → 继续
    ↓
【判断】倒计时检查
    ├─ 剩余秒数 < 最小阈值？ → 【返回】丢弃
    └─ 剩余秒数 > 最大阈值？
        ├─ 是 → 【判断】价值达到高价值阈值？
        │   ├─ 是 → 【操作】记录为预约（特殊处理：倒计时大于阈值但价值高）
        │   │   ↓
        │   │   【返回】已记录预约
        │   │   ↓
        │   │   【结束】
        │   └─ 否 → 【返回】丢弃
        │       ↓
        │       【结束】
        └─ 否 → 继续
    ↓
【返回】通过筛选
    ↓
【判断】价值达到高价值阈值？
    ├─ 是 → 【判断】剩余秒数 <= 阈值？
    │   ├─ 是 → 【操作】立即参与抽奖（剩余秒数在阈值内）
    │   └─ 否 → 【操作】记录为预约（剩余秒数大于阈值）
    └─ 否 → 【操作】立即参与抽奖
    ↓
【判断】参与成功？（V3.3.3+）
    ├─ 是 → 【操作】更新最后成功参与时间（_last_successful_attend_ts）
    │   ↓
    │   【操作】关闭详情页
    │   ↓
    │   【延迟】延迟1秒 → 返回主循环
    └─ 否 → 【记录】记录错误
    ↓
        【延迟】延迟1秒 → 返回主循环


================================================================================
四、阶段诊断流程
================================================================================

【开始】开始阶段诊断
    ↓
【操作】获取屏幕截图
    ↓
【检测】检测是否在直播间（优先级最高）
    ├─ 像素检测（检测右上角图标）
    ├─ 模板匹配检测
    └─ OCR检测
    ↓
【判断】在直播间？
    ├─ 是 → 【标记】标记：在直播间
    │   ↓
    │   【并行】并行像素检测（所有特征同时检测）
    │   ├─ 优先级1：检测抽奖结果弹窗
    │   ├─ 优先级1.5：检测购物红包背景
    │   ├─ 优先级2：检测优惠券背景
    │   ├─ 优先级2：检测参与按钮
    │   ├─ 优先级2：检测粉丝团加入
    │   └─ 优先级3：检测福袋详情页
    │   ↓
    │   【判断】检测到抽奖结果？
    │   ├─ 是 → 【OCR验证】OCR验证抽奖结果
    │   │   ├─ 检测"没有抽中"/"抽中福袋"
    │   │   └─ 检测"我知道了"按钮
    │   │   ↓
    │   │   【判断】OCR验证通过？
    │   │   ├─ 是 → 【返回】FUDai_RESULT
    │   │   └─ 否 → 继续检查其他
    │   │
    │   ├─ 检测到购物红包？
    │   │   ↓
    │   │   【OCR验证】OCR验证购物红包
    │   │   ├─ 检测"邀你抢"/"抢红包"
    │   │   ↓
    │   │   【判断】OCR验证通过？
    │   │   ├─ 是 → 【返回】SHOPPING_REDPACKET_POPUP
    │   │   └─ 否 → 继续检查其他
    │   │
    │   ├─ 检测到优惠券？
    │   │   ↓
    │   │   【OCR验证】OCR验证优惠券
    │   │   ├─ 检测"开心收下"
    │   │   ↓
    │   │   【判断】OCR验证通过？
    │   │   ├─ 是 → 【返回】COUPON_POPUP
    │   │   └─ 否 → 继续检查其他
    │   │
    │   ├─ 检测到参与按钮？
    │   │   ↓
    │   │   继续检查粉丝团
    │   │
    │   ├─ 检测到粉丝团？
    │   │   ↓
    │   │   【返回】FANS_CLUB_JOIN
    │   │
    │   └─ 检测到详情页？
    │       ↓
    │       【OCR验证】OCR验证详情页
    │       ├─ 检测"邀你抢红包"
    │       ↓
    │       【判断】OCR验证通过？
    │       ├─ 是 → 【返回】FUDai_DETAIL
    │       └─ 否 → 【返回】IN_LIVE_ROOM
    │
    └─ 否 → 【标记】标记：不在直播间
        ↓
        【判断】页面类型？
        ├─ 推荐页 → 【返回】RECOMMEND_PAGE
        ├─ 关注列表 → 【返回】FOLLOW_LIST
        ├─ 直播列表 → 【返回】LIVE_LIST
        └─ 其他 → 【返回】UNKNOWN
    ↓
【结束】


================================================================================
五、福袋查找流程（优化查找器）
================================================================================

【开始】开始查找福袋
    ↓
【操作】初始化循环（设置最大等待时间5秒）
    ↓
【循环】循环查找
    ↓
【判断】是否超时？
    ├─ 是 → 【返回】未找到
    │   ↓
    │   【结束】
    └─ 否 → 继续
    ↓
【操作】获取屏幕截图（首次可复用已有截图）
    ↓
【操作】保存调试图像（检测前）
    ↓
【检测】像素检测福袋图标（在热点区域搜索）
    ↓
【判断】像素检测成功？
    ├─ 否 → 【延迟】延迟重试0.6秒 → 返回循环
    └─ 是 → 继续
    ↓
【判断】模板匹配是否启用？（fudai_template_match_enabled）
    ├─ 否 → 【操作】直接使用像素检测结果（跳过模板验证）
    │   ↓
    │   【操作】保存调试图像（检测成功）
    │   ↓
    │   【操作】点击福袋图标（等待2.5秒）
    │   ↓
    │   【验证】验证详情页是否打开
    │   ↓
    │   【操作】等待界面加载（0.8秒）
    │   ↓
    │   【检测】像素检测验证（检测福袋详情页特征）
    │   ↓
    │   【判断】像素验证成功？
    │   ├─ 是 → 【设置】设置验证标志（_fudai_detail_verified=True）
    │   │   ↓
    │   │   【返回】成功
    │   │   ↓
    │   │   【结束】
    │   └─ 否 → 【OCR验证】OCR验证（检测邀你抢红包区域）
    │       ↓
    │       【判断】OCR验证成功？（检测到邀你抢/抢红包/抢手气）
    │       ├─ 是 → 【设置】设置验证标志
    │       │   ↓
    │       │   【返回】成功
    │       │   ↓
    │       │   【结束】
    │       └─ 否 → 【判断】是否还有重试次数？（最大2次）
    │           ├─ 是 → 【延迟】延迟0.3秒 → 返回验证详情页
    │           └─ 否 → 【返回】未找到
    │               ↓
    │               【结束】
    │
    └─ 是 → 【验证】模板匹配验证（在检测区域验证）
        ↓
        【判断】模板验证通过？
        ├─ 是 → 【操作】保存调试图像（检测成功）
        │   ↓
        │   【操作】点击福袋图标（等待2.5秒）
        │   ↓
        │   【验证】验证详情页是否打开
        │   ↓
        │   【操作】等待界面加载（0.8秒）
        │   ↓
        │   【检测】像素检测验证（检测福袋详情页特征）
        │   ↓
        │   【判断】像素验证成功？
        │   ├─ 是 → 【设置】设置验证标志（_fudai_detail_verified=True）
        │   │   ↓
        │   │   【返回】成功
        │   │   ↓
        │   │   【结束】
        │   └─ 否 → 【OCR验证】OCR验证（检测邀你抢红包区域）
        │       ↓
        │       【判断】OCR验证成功？（检测到邀你抢/抢红包/抢手气）
        │       ├─ 是 → 【设置】设置验证标志
        │       │   ↓
        │       │   【返回】成功
        │       │   ↓
        │       │   【结束】
        │       └─ 否 → 【判断】是否还有重试次数？（最大2次）
        │           ├─ 是 → 【延迟】延迟0.3秒 → 返回验证详情页
        │           └─ 否 → 【返回】未找到
        │               ↓
        │               【结束】
        │
        └─ 否 → 【判断】是否信任像素检测？（在可信区域且模板失败）
            ├─ 是 → 【操作】保存调试图像（检测成功）
            │   ↓
            │   继续点击流程（同上）
            └─ 否 → 【延迟】延迟重试0.6秒 → 返回循环


================================================================================
六、预约处理流程
================================================================================

【开始】开始处理预约
    ↓
【判断】预约队列是否已满？
    ├─ 是 → 【判断】是否已在等待状态？
    │   ├─ 否 → 【操作】回退到最早开奖的预约直播间，等待开奖
    │   │   ↓
    │   │   【返回】已触发回退
    │   │   ↓
    │   │   【结束】
    │   └─ 是 → 【判断】所有预约是否已完成？
    │       ├─ 是 → 【操作】重置到第一个直播间（回退room_pos次）
    │       │   ↓
    │       │   【返回】已重置
    │       │   ↓
    │       │   【结束】
    │       └─ 否 → 【返回】已触发回退
    │           ↓
    │           【结束】
    └─ 否 → 继续
    ↓
【处理】处理预约时间窗口（检查是否有预约即将开奖）
    ↓
【判断】是否有预约在时间窗口内？
    ├─ 是 → 【操作】寻找预约直播间（通过直播间标题匹配）
    │   ↓
    │   【判断】找到直播间？
    │   ├─ 是 → 【操作】滑动到目标直播间
    │   │   ↓
    │   │   【判断】是否在目标直播间？
    │   │   ├─ 是 → 【返回】已触发预约回退
    │   │   │   ↓
    │   │   │   【结束】
    │   │   └─ 否 → 【返回】未触发回退
    │   │       ↓
    │   │       【结束】
    │   └─ 否 → 【返回】未触发回退
    │       ↓
    │       【结束】
    └─ 否 → 【返回】未触发回退
        ↓
        【结束】


================================================================================
七、异常处理流程
================================================================================

【开始】检测到异常
    ↓
【操作】捕获异常
    ↓
【记录】记录错误日志（错误类型/错误信息/堆栈）
    ↓
【判断】异常类型？
    ├─ 截图失败 → 【重试】重试截图（最多3次）
    │   ↓
    │   【判断】重试成功？
    │   ├─ 是 → 【继续】继续执行
    │   └─ 否 → 【记录】记录并继续
    │
    ├─ 网络错误 → 【等待】等待网络恢复（延迟5秒）
    │   ↓
    │   【判断】网络恢复？
    │   ├─ 是 → 【继续】继续执行
    │   └─ 否 → 【等待】继续等待
    │
    ├─ 识别错误 → 【跳过】跳过当前福袋
    │   ↓
    │   【操作】关闭详情页
    │   ↓
    │   【继续】继续执行
    │
    ├─ 任务数为0 → 【返回】返回：不在详情页
    │   ↓
    │   【继续】继续执行
    │
    └─ 其他异常 → 【记录】记录并继续
        ↓
        【延迟】延迟2秒
        ↓
        【继续】继续执行
    ↓
【返回】返回主循环
    ↓
【结束】


================================================================================
关键优化点说明
================================================================================

1. 【并行OCR识别】
   - 内容/倒计时/价值三个OCR操作并行执行
   - 理论上可减少约2/3的OCR总耗时
   - 使用ThreadPoolExecutor实现

2. 【观看任务提前检测】
   - OCR识别内容后立即检查是否为"观看X分钟"任务
   - 如果是则直接返回，跳过倒计时和价值识别
   - 节省时间并避免不必要的处理

3. 【验证标志优化】
   - 优化查找器验证成功后，设置_fudai_detail_verified=True
   - 等待时间从1.2秒缩短到0.3秒
   - 提高响应速度

4. 【任务数为0优化】
   - 检测到任务数为0时，直接跳过OCR识别
   - 节省约12秒的处理时间

5. 【倒计时一致性检查】
   - 多次读取时检查倒计时是否一致
   - 避免识别错误导致的误判
   - 如果差异过大，使用第一次读取的结果

6. 【并行像素检测】
   - 阶段诊断时所有像素特征并行检测
   - 提高检测效率

7. 【预约处理优化】
   - 智能管理预约队列
   - 自动回退到预约直播间
   - 支持队列满时的等待策略


================================================================================
数据流向说明
================================================================================

截图 → 阶段诊断 → 根据阶段执行操作
  ↓
福袋查找 → 点击验证 → 设置验证标志 → 读取详情（缩短等待） → 筛选决策 → 参与/预约/丢弃
  ↓
异常处理 → 记录日志 → 延迟重试 → 继续循环


================================================================================
配置参数影响
================================================================================

- wait_minutes: 控制主循环运行时间（0=无限循环）
- needswitch: 控制是否切换直播间
- min_prize_value_yuan: 最小价值阈值
- skip_if_countdown_gt_seconds: 倒计时最大阈值
- high_value_fudai_threshold_yuan: 高价值阈值
- fudai_finder_optimized_enabled: 是否启用优化查找器
- fudai_verify_after_click: 是否启用点击后验证
- fudai_detail_initial_wait_seconds: 详情读取前等待时间（已验证时自动缩短）
- fudai_detail_max_attempts: 详情读取最大重试次数


================================================================================
结束
================================================================================

