云学堂助手 v2.7.0 · 单视频自动播放 / 完成后转下一门 实跑与回归
================================================================

结论
----
用户反馈的两个问题是同一个根因链条上的两处断点，均已在真实站点复现并修复：

1) 进入课程「有概率」不自动播放
   - 平台的播放页不只有 #/course/play。单个视频课程点开后走的是
     #/scan?kngId=… -> #/video/play?kngId=…，音频/课件还有 #/audio/play、#/ppt/play。
   - v2.6.0 的 route() 只把 #/course/play 识别为课程页，其它播放页返回 'other'，
     主循环既不跑 courseTick 也不跑 manualCourseTick：不点「开始学习」、不接管视频。
   - 真实站点「氦泄漏通用」（type=2 / fileType=video / 60 秒，列表第 307 页）复现：
     进课后 150 秒内 S.phase 一直是 entering，video=null，面板停在
     「进入课程（1 分钟）：氦泄漏通用」，done=0。

2) 一门课学完后不自动转到下一门
   - 平台课程真正学完时，汇总文案会从「已完成 0/1」变成 **「已完成学习」**；
     单视频页则是「已完成 0%」->「已完成 67%」-> **「已完成学习」**。
     此时倒计时和进度条都会消失。
   - v2.6.0 的 readSummary() 只匹配 /已完成(\d+)\/(\d+)/，读不到「已完成学习」和百分比，
     永远不判完成：停在课程页、不回列表、也不选下一门；而且播放器会把视频重置到 0 秒，
     v.ended 变回 false，脚本又调用 play() 从头重播。
   - 真实站点「如何搭建分销体系，实现用户指数级增长？（上篇）」（1 节 / 127 秒）复现：
     127 秒时 study/summary 已返回 finishNum=1/1、acqHours=127，页面汇总变成「已完成学习」，
     但 20 秒后 S.completedThisRun 仍为 0、S.current 未清空，video 被重新 play 到 0.5 秒。

真实站点证据
------------
复现环境：https://kfmic.yunxuetang.cn（江丰云课堂），2026-10-22，Asia/Shanghai。
登录凭据来自用户级环境变量 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD，没有写入脚本或仓库。

A. 单视频课程的实际路由与完成文案（#/video/play）
------------------------------------------------
  NAV /kng/#/scan?kngId=283c683a-fa98-4f69-9e08-c45116118aa1
  NAV /kng/#/video/play?kngId=283c683a-fa98-4f69-9e08-c45116118aa1&projectId=&btid=&gwnlUrl=
  NET /kng/study/kngInfo {"title":"氦泄漏通用","type":2,"fileType":"video",...}
  NET /kng/study/summary {"finishNum":0,"totalNum":1,...,"studyHours":60}
  页面汇总：已完成 0%  ->  已完成 33%  ->  已完成 67%  ->  已完成学习
  倒计时：  还需 59秒 …（从 60 秒开始，注意视频本身 107 秒，平台按 required time 计时）
  开始按钮：<button class="yxtf-button yxtf-button--primary yxtf-button--larger">开始学习</button>

  修复前（v2.6.0）在该页连续 150 个 tick 的状态：
    status=进入课程（1 分钟）：氦泄漏通用
    phase=entering  done=0  video=-  sum=已完成0%  150 秒无变化

B. 多课时课程完成后汇总变成「已完成学习」
----------------------------------------
  NET /kng/study/summary {"finishNum":0,"totalNum":1,...,"studyHours":127}
  [14s] 页面汇总：已完成0/1
  [21s] 视频开始播放：video=play@0/127.1
  [148s] NET /kng/study/summary {"finishNum":1,"totalNum":1,"acqHours":127,...}
  [149s] 页面汇总：已完成学习（倒计时、进度条消失）
         status=学习中：视频如何搭建分销体系，实现用户指数型增长？（上）
         done=0  video=PAUSE@0/127.1
  [150s] video=play@0.5/127.1   ← 平台重置后脚本又把视频从头播放

修复内容（v2.7.0）
------------------
1) route() 识别全部播放页：#/course/play、#/video/play、#/audio/play、#/ppt/play、
   #/document/play、#/article/play，以及进课过渡页 #/scan。
   新增 mediaPage() 区分「有目录的多课时课程」和「单媒体播放页」。

2) readSummary() 同时解析三种真实完成文案：
   - 已完成 2/3      -> { x:2, y:3, complete:false, kind:'ratio' }
   - 已完成 67%      -> { x:67, y:100, complete:false, kind:'percent' }
   - 已完成学习      -> { x:100, y:100, complete:true, kind:'done' }
   另用 [role="progressbar"] 的 aria-valuenow 兜底。

3) courseTick()：
   - 单视频/音频页不再走目录对齐，也不把百分比进度当成「一节学完」去切节；
   - 汇总 complete 时（比例满、100%、已完成学习）统一 completeCurrent()；
   - 新增 doneLatchKey：倒计时归零/video.ended 后记住本节已播完，
     平台把播放器重置到 0 秒时不再自动 play，避免完成后重播；
   - 单媒体页等待记账时只轮询汇总，不调用 advanceLesson()。

4) 进课判定改用 URL 的 kngId：startCourse() 把课程 id 写入 S.current.id，
   courseTick() 优先用 kngId 比对，标题短暂是 loading.../在线课堂 时不再误判；
   宽限从 12 秒提高到 30 秒（CFG.entryGraceMs）。#/scan 只是过渡页，此时不做完成判定，
   防止读到上一门课残留的「已完成学习」。

5) 自动播放兜底：「开始学习」冷却 15 秒 -> 3 秒（3 秒没起播就补点）；
   选择器在 button/a 之外支持最内层 div/span，并跳过 disabled 按钮；
   手动模式（手动课程自动连播）在单媒体页也会点开始；
   点课程卡片后 4 秒仍停在列表时自动补点，最多 2 次，不再直接记为失败跳过。

6) 完成文案连续两次读到才确认（三种完成文案统一），避免 SPA 切页瞬间
   把上一门课的完成文案算到新课程上。completeCurrent() 改为强制返回列表
   （不受 goToList 5 秒节流影响），并先 pause 播放器；列表页把「已完成/已学习」
   也当作完成状态过滤。

回归用例（本地复刻 DOM，Playwright）
------------------------------------
  node .run-tmp/align/run.mjs       => 13 PASS / 0 FAIL（起点对齐 + 自动切节）
  node .run-tmp/complete/run.mjs    =>  8 PASS / 0 FAIL
    E1 首次点卡片无反应：自动补点进入课程
    U1 readSummary 解析 x/y、百分比、已完成学习
    U2 route 识别 course/video/audio/ppt/scan
    V1 单视频课：自动播放 -> 完成后进入下一门
    C1 多课时课：已完成学习 -> 回列表 -> 下一门
    L1 标题 loading 但 kngId 匹配：不误判、继续播放
    T1 倒计时归零后平台重置视频：不重播，汇总更新后照常进入下一门
    D1 「开始学习」是 div 时仍能自动播放

真机修复后验证
--------------
场景 1：已完成的多课时课程（#/course/play，汇总「已完成学习」）
  [11s] 课程完成：如何搭建分销体系，实现用户指数级增长？（上篇）第 1 门，返回列表选下一门
  [12s] NAV /kng/#/list
  [15s] 回到列表第 1 页，继续…
  [22s] 短课程队列已就绪：待学 5131 门；最短 2 分钟
  [25s] 进入课程（2 分钟）：如何制定渠道战略
  [27s] 跳过：如何制定渠道战略（课程包含考试/测验章节）
  [28s] 回到列表第 13 页，继续… -> 第 63 页
  [31s] 进入课程（2 分钟）：APP做裂变的三大专属玩法
  [38s] 学习中：视频APP做裂变的三大专属玩法（video=0.6/132.1）
  [PASS] complete=true next=APP做裂变的三大专属玩法 playing=true

场景 2：已完成的单视频课程（#/video/play，汇总「已完成学习」）
  [11s] 课程完成：氦泄漏通用 第 1 门，返回列表选下一门
  [12s] NAV /kng/#/list
  [16s] 短课程队列已就绪：待学 5131 门；最短 2 分钟
  [19s] 进入课程（2 分钟）：如何制定渠道战略 -> 跳过（考试/测验章节）
  [25s] 进入课程（2 分钟）：APP做裂变的三大专属玩法
  [32s] 学习中：视频APP做裂变的三大专属玩法（video=1.3/132.1）
  [PASS] complete=true next=APP做裂变的三大专属玩法 playing=true

复现命令（本机）
----------------
  $env:PLAYWRIGHT_PATH="<playwright 包目录>"
  $env:CHROME_PATH="<chromium 可执行文件>"
  node .run-tmp/align/run.mjs
  node .run-tmp/complete/run.mjs
  # 真机观测/验证需要 YUN_XUE_TANG_USR / YUN_XUE_TANG_PWD
  $env:YUN_XUE_TANG_USR=...; $env:YUN_XUE_TANG_PWD=...
  node .run-tmp/real/probe-bugs2.mjs      # 修复前：video/play 全程不动作
  node .run-tmp/real/verify-fix.mjs       # 修复后：两个场景 PASS

清理说明
--------
- 登录态 storageState（.run-tmp/real/state.json）与调试截图只在本地调试目录，验证完成后删除。
- 仓库内没有写入账号、密码、token 或 cookie。
