courser 0.1.0__py3-none-any.whl

courser/__init__.py

@@ -0,0 +1,7 @@
+"""PKU 补退选空余名额监控器。
+
+使用 opencli 驱动真实 Chrome（后台窗口），按人类节奏定期登录补退选页面，
+解析课程列表中的 限数/已选，命中筛选条件且有空余名额时发送邮件通知。
+"""
+
+__version__ = "0.1.0"

courser/config.py

@@ -0,0 +1,176 @@
+"""配置管理。
+
+- config.json：TUI 可编辑的全部配置（轮询间隔、筛选条件、凭据、邮件、浏览器会话）
+- 环境变量（.env）：敏感信息（密码等）可选覆盖
+所有配置集中在「设置」界面维护，代码里不散落魔法配置。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+CONFIG_PATH = Path(os.environ.get("COURSER_CONFIG", str(PROJECT_ROOT / "config.json")))
+DATA_DIR = PROJECT_ROOT / "data"
+STATE_FILE = DATA_DIR / "notified.json"
+SEND_LOG_FILE = DATA_DIR / "send_log.json"   # 每小时发送预算的发送时间戳日志
+
+
+def _env(key: str, default: str = "") -> str:
+    return os.environ.get(key, default)
+
+
+@dataclass
+class Credentials:
+    username: str = ""   # 学号；留空则依赖密码管理器自动填充
+    password: str = ""   # 密码；留空则依赖密码管理器自动填充
+
+    @classmethod
+    def from_dict(cls, d: Optional[dict]) -> "Credentials":
+        d = d or {}
+        return cls(
+            username=str(d.get("username", "") or _env("PKU_USERNAME", "")),
+            password=str(d.get("password", "") or _env("PKU_PASSWORD", "")),
+        )
+
+
+@dataclass
+class Notify:
+    """邮件通知（通过 gws = Google Workspace CLI 发送，需用户自行安装，
+    首次 `gws auth setup` 后 `gws auth login` 授权）。"""
+
+    to: str = ""                       # 收件人邮箱（提醒的目标地址，TUI 设置 / MAIL_TO 提供）
+    gws_from: str = ""                 # gws 发件账号（Gmail 地址，可选；默认取认证账号）
+    min_interval_min: float = 15.0     # 同一课程两次通知的最小间隔（分钟）
+    max_per_hour: int = 5              # 每小时最多发送的邮件封数（只限发信，不影响查询轮次）
+
+    @classmethod
+    def from_dict(cls, d: Optional[dict]) -> "Notify":
+        d = d or {}
+        return cls(
+            to=str(d.get("to", "") or _env("MAIL_TO", "")),
+            gws_from=str(d.get("gws_from", "") or _env("GWS_FROM", "")),
+            min_interval_min=float(d.get("min_interval_min", 15.0)),
+            max_per_hour=max(1, int(d.get("max_per_hour", 5))),
+        )
+
+    @property
+    def configured(self) -> bool:
+        return bool(self.to)
+
+
+@dataclass
+class Filters:
+    names: list[str] = field(default_factory=list)        # 课程名（子串匹配）
+    categories: list[str] = field(default_factory=list)   # 课程类别（子串匹配，如 通识核心课I类）
+    depts: list[str] = field(default_factory=list)        # 开课单位（子串匹配，如 英语语言文学系）
+    match: str = "any"                                    # any=任一命中 / all=全部命中
+
+    @classmethod
+    def from_dict(cls, d: Optional[dict]) -> "Filters":
+        d = d or {}
+        return cls(
+            names=list(d.get("names", [])),
+            categories=list(d.get("categories", [])),
+            depts=list(d.get("depts", [])),
+            match=str(d.get("match", "any")),
+        )
+
+    @property
+    def empty(self) -> bool:
+        return not (self.names or self.categories or self.depts)
+
+    @property
+    def active_groups(self) -> list[tuple[str, list[str]]]:
+        out = []
+        if self.names:
+            out.append(("课程名", self.names))
+        if self.categories:
+            out.append(("课程类别", self.categories))
+        if self.depts:
+            out.append(("开课院系", self.depts))
+        return out
+
+    def to_dict(self) -> dict:
+        return {"names": self.names, "categories": self.categories,
+                "depts": self.depts, "match": self.match}
+
+
+@dataclass
+class Config:
+    interval_min: float = 8.0              # 轮询基本间隔（分钟），实际带随机抖动
+    interval_jitter: float = 0.3           # 抖动比例（±30%）
+    page_delay_min: float = 0.8           # 相邻操作随机间隔下限（秒，人类速度）
+    page_delay_max: float = 2.0            # 相邻操作随机间隔上限（秒）
+    credentials: Credentials = field(default_factory=Credentials)
+    filters: Filters = field(default_factory=Filters)
+    notify: Notify = field(default_factory=Notify)
+    session: str = "courser-watch"         # opencli 浏览器会话名
+    window: str = "background"             # background=后台窗口，不抢焦点
+    force_relogin: bool = False            # 默认复用有效会话；开启才每轮登出重登
+    first_run_done: bool = False           # 初次启动向导是否已完成
+    cli_log: bool = False                  # CLI 模式（无 TUI）
+
+    @classmethod
+    def load(cls, path: Optional[Path] = None) -> "Config":
+        path = path or CONFIG_PATH
+        cfg = cls()
+        if path.exists():
+            try:
+                d = json.loads(path.read_text(encoding="utf-8"))
+            except Exception:
+                d = {}
+            cfg.interval_min = float(d.get("interval_min", cfg.interval_min))
+            cfg.interval_jitter = float(d.get("interval_jitter", cfg.interval_jitter))
+            cfg.page_delay_min = float(d.get("page_delay_min", cfg.page_delay_min))
+            cfg.page_delay_max = float(d.get("page_delay_max", cfg.page_delay_max))
+            cfg.session = str(d.get("session", cfg.session))
+            cfg.window = str(d.get("window", cfg.window))
+            cfg.force_relogin = bool(d.get("force_relogin", cfg.force_relogin))
+            cfg.first_run_done = bool(d.get("first_run_done", cfg.first_run_done))
+            cfg.credentials = Credentials.from_dict(d.get("credentials"))
+            cfg.filters = Filters.from_dict(d.get("filters"))
+            cfg.notify = Notify.from_dict(d.get("notify"))
+        return cfg
+
+    def save(self, path: Optional[Path] = None) -> None:
+        path = path or CONFIG_PATH
+        d = {
+            "interval_min": self.interval_min,
+            "interval_jitter": self.interval_jitter,
+            "page_delay_min": self.page_delay_min,
+            "page_delay_max": self.page_delay_max,
+            "session": self.session,
+            "window": self.window,
+            "force_relogin": self.force_relogin,
+            "first_run_done": self.first_run_done,
+            "credentials": {"username": self.credentials.username,
+                            "password": self.credentials.password},
+            "filters": self.filters.to_dict(),
+            "notify": {"to": self.notify.to, "gws_from": self.notify.gws_from,
+                       "min_interval_min": self.notify.min_interval_min,
+                       "max_per_hour": self.notify.max_per_hour},
+        }
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(d, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    @property
+    def pacing(self) -> tuple[float, float]:
+        return (self.page_delay_min, self.page_delay_max)
+
+
+def load_env_file(path: Optional[Path] = None) -> None:
+    """加载项目根目录 .env（若存在），用于填充 PKU 凭据、GWS_FROM 等环境变量。"""
+    path = path or (PROJECT_ROOT / ".env")
+    if not path.exists():
+        return
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        os.environ.setdefault(k.strip(), v.strip())

courser/course_table.py

@@ -0,0 +1,123 @@
+"""课程表规范 schema + 单元格格式化（唯一来源）。
+
+课程表是所有输出渠道共享的**核心展示对象**，这里确立它的 canonical 定义：
+
+    Course
+       │
+       ▼
+   COURSE_COLUMNS（列定义） + course_display（字段→显示文本）
+       │
+   ┌───┴─────────────┐
+   ▼                 ▼
+ TUI 列布局          Email(HTML/纯文本)
+ 终端宽度/折行/颜色   HTML/markdown 标签
+
+各渠道**共享**：列 key / 标题 / 对齐语义 / 数据格式化（course_display）。
+各渠道**不共享**：终端宽度、折行规则、ANSI 颜色、HTML/markdown 标签。
+
+这样『限选/已选 拆分』『空余右对齐』只改这一处，TUI 主表 / TUI 筛选表 /
+邮件 HTML / 邮件纯文本 自动同步，杜绝各模块手写字符串再分裂。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .models import Course
+
+
+@dataclass(frozen=True)
+class Column:
+    """一列课程表的规范定义。
+
+    - 结构列（页数/课程号/限选/已选/空余）：width 固定；weight 为 0。
+    - 文本列（课程名/类别/开课单位/教师）：width=None，按 weight 弹性分配。
+    """
+
+    key: str
+    title: str
+    align: str = "left"
+    width: Optional[int] = None      # 固定宽（结构列/数值列）
+    min_width: int = 0               # 弹性文本列的底线
+    weight: float = 0.0              # 弹性文本列的宽度权重
+    preferred: Optional[int] = None  # 弹性文本列的 cap
+
+    @property
+    def is_structural(self) -> bool:
+        """结构列（固定宽，数值/ID），文本列（弹性）的对立面。"""
+        return self.width is not None
+
+
+# 课程表规范顺序：页数 → 空余。TUI 实际渲染会把文本列塞进中间
+# （页数/课程号, [文本列…], 限选/已选/空余）；这是终端布局 adapter 的决定，
+# 仍在 _columns() 里基于本 schema 推导，不另写第二份列定义。
+COURSE_COLUMNS: list[Column] = [
+    Column("page", "页数",        align="right",  width=4),
+    Column("no", "课程号",        align="left",   width=10),
+    Column("name", "课程名",      align="left",   min_width=12, weight=3.0, preferred=30),
+    Column("cat", "课程类别",     align="center", min_width=8,  weight=1.5, preferred=20),
+    Column("dept", "开课单位",    align="left",   min_width=8,  weight=1.5, preferred=20),
+    Column("teacher", "教师",     align="left",   min_width=10, weight=2.0, preferred=26),
+    Column("quota", "限选",       align="right",  width=5),
+    Column("selected", "已选",    align="right",  width=5),
+    Column("avail", "空余",       align="right",  width=5),
+]
+
+# key → Column 的便捷查找
+_COLUMN_BY_KEY: dict[str, Column] = {c.key: c for c in COURSE_COLUMNS}
+
+
+def column(key: str) -> Optional[Column]:
+    """按 key 取列定义；未知 key 返回 None。"""
+    return _COLUMN_BY_KEY.get(key)
+
+
+def course_display(c: Course, key: str) -> str:
+    """课程某一列的**显示文本**（canonical 格式化）。
+
+    所有渠道都从这里取值，保证格式一致：
+    - 数值列：None/未知 → '—'，有值 → str
+    - 文本列：空 → '—'
+    邮件额外用到的课程字段（班号/上课信息）也归入本表单。
+    """
+    if key == "page":
+        return str(c.page) if c.page else "—"
+    if key == "no":
+        return c.course_no or "—"
+    if key == "name":
+        return c.name or "—"
+    if key == "cat":
+        return c.category or "—"
+    if key == "dept":
+        return c.dept or "—"
+    if key == "teacher":
+        return c.teacher or "—"
+    if key == "class_no":
+        return c.class_no or "—"
+    if key == "schedule":
+        return c.schedule or "—"
+    if key == "quota":
+        return str(c.quota) if c.quota is not None else "—"
+    if key == "selected":
+        return str(c.selected) if c.selected is not None else "—"
+    if key == "avail":
+        return str(c.avail) if c.avail >= 0 else "—"
+    return ""
+
+
+def course_order_key(c: Course) -> tuple[int]:
+    """选课网顺序：页码升序；同页保持原始列表顺序。"""
+    return (c.page if c.page > 0 else 10**9,)
+
+
+def ordered_courses(courses: list[Course]) -> list[Course]:
+    """按选课网顺序返回课程副本；Python 稳定排序保留同页上下顺序。"""
+    return sorted(courses, key=course_order_key)
+
+
+def seats_display(c: Course) -> str:
+    """限选/已选 合并串（邮件纯文本等散文场景用）；缺失回退原始串。"""
+    if c.quota is not None and c.selected is not None:
+        return f"{c.selected}/{c.quota}"
+    return (c.seats_raw or "").replace(" ", "") or "—"

courser/editing.py

@@ -0,0 +1,99 @@
+"""可复用的行内字段编辑器（设置页 / 首启向导等所有输入共用）。
+
+它不依赖任何具体 UI 控件：只维护一段文本缓冲 + 光标位置，外部把按键的原始信息
+喂进来（key / char / printable），它处理移动光标、删除、在光标处插入并返回
+'commit' / 'cancel' 让调用方决定何时落盘。渲染也由它统一负责（含密码打码与
+块状光标 ▌），保证各处输入外观与行为完全一致——原值保留、不清空重输、键盘
+移动光标、支持中文输入。
+"""
+
+from __future__ import annotations
+
+from rich.markup import escape
+
+
+class FieldEditor:
+    """一个复用的行内单行编辑器实例。
+
+    用法：
+        ed.begin(value, kind="text")        # 进入编辑，光标置于末尾
+        out = ed.feed(key, char, printable)  # 每来一个键调用一次
+        # out 为 'commit' / 'cancel' 时由调用方落盘或放弃；其余在内部处理
+        markup = ed.markup()                 # 渲染带光标的文本（供页面显示）
+        ed.reset()                           # 结束编辑
+    """
+
+    CURSOR = "▌"
+
+    def __init__(self) -> None:
+        self.text = ""
+        self.caret = 0
+        self.kind = "text"        # text | password
+        self.active = False
+
+    # -- 生命周期 -----------------------------------------------------
+    def begin(self, value: str, kind: str = "text") -> None:
+        """开始编辑：原值保留，光标默认在末尾（追加式修改）。"""
+        self.active = True
+        self.text = value
+        self.kind = kind
+        self.caret = len(value)
+
+    def reset(self) -> None:
+        self.active = False
+        self.text = ""
+        self.caret = 0
+
+    # -- 取值 ---------------------------------------------------------
+    def markup(self) -> str:
+        """渲染当前缓冲：密码打码为 •，光标处显示块状 ▌（转义后安全）。"""
+        shown = self.text if self.kind != "password" else "•" * len(self.text)
+        c = max(0, min(self.caret, len(shown)))
+        return ("[cyan]" + escape(shown[:c]) + self.CURSOR +
+                escape(shown[c:]) + "[/]")
+
+    def _insert(self, text: str) -> None:
+        self.text = self.text[:self.caret] + text + self.text[self.caret:]
+        self.caret += len(text)
+
+    def _backspace(self) -> None:
+        if self.caret > 0:
+            self.text = self.text[:self.caret - 1] + self.text[self.caret:]
+            self.caret -= 1
+
+    def _delete(self) -> None:
+        if self.caret < len(self.text):
+            self.text = self.text[:self.caret] + self.text[self.caret + 1:]
+
+    def feed(self, key: str, char: str | None,
+             printable: bool) -> str | None:
+        """处理一次按键，返回 'commit' / 'cancel' / None。
+
+        key / char / printable 取自某个 TUI 的按键事件；本方法只做纯文本编辑，
+        不落盘、不渲染——这样任何调用方（设置页、首启向导…）都能复用。
+        """
+        if not self.active:
+            return None
+        if key == "enter":
+            return "commit"
+        if key == "escape":
+            return "cancel"
+        if key == "left":
+            self.caret = max(0, self.caret - 1)
+        elif key == "right":
+            self.caret = min(len(self.text), self.caret + 1)
+        elif key == "home":
+            self.caret = 0
+        elif key == "end":
+            self.caret = len(self.text)
+        elif key == "backspace":
+            self._backspace()
+        elif key == "delete":
+            self._delete()
+        else:
+            # 可打印字符在光标处插入（含中文）。Textual 里字母常只有 key 无 char，
+            # 这里统一回退到单字符的 key。
+            t = char if char else (key if len(key) == 1 else None)
+            if t and printable:
+                self._insert(t)
+        return None

courser/filters.py

@@ -0,0 +1,61 @@
+"""筛选规则匹配。
+
+三个维度：课程名 / 课程类别 / 开课院系。
+- 每个维度可以有多个条目；同一维度内为「或」匹配（子串包含即可）。
+- 维度之间的组合由 match 决定：
+    any  = 任一维度命中即算（默认，对应「英语系 或 通识课I类」这类需求）
+    all  = 所有非空维度都必须命中
+- 未配置任何筛选时，不命中任何课程（避免误报）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .config import Filters
+from .models import Course
+
+
+@dataclass
+class FilterSet:
+    filters: Filters = field(default_factory=Filters)
+
+    def _hit(self, field_value: str, entries: list[str]) -> bool:
+        if not entries:
+            return False
+        fv = field_value or ""
+        return any(e and e in fv for e in entries)
+
+    def _hit_categories(self, c: Course, entries: list[str]) -> bool:
+        """课程类别命中：一门课可同时属于多类，
+        只要任一独立类别包含任一筛选条目即命中（保留子串语义）。"""
+        if not entries:
+            return False
+        cats = c.categories
+        if not cats:
+            return False
+        return any(e and any(e in cat for cat in cats) for e in entries)
+
+    def matches(self, c: Course) -> bool:
+        if self.filters.empty:
+            return False
+        groups_hit = []
+        if self.filters.names:
+            groups_hit.append(self._hit(c.name, self.filters.names))
+        if self.filters.categories:
+            groups_hit.append(self._hit_categories(c, self.filters.categories))
+        if self.filters.depts:
+            groups_hit.append(self._hit(c.dept, self.filters.depts))
+        if self.filters.match == "all":
+            return all(groups_hit)
+        return any(groups_hit)
+
+    def matched(self, courses: list[Course]) -> list[Course]:
+        return [c for c in courses if self.matches(c)]
+
+    def describe(self) -> str:
+        if self.filters.empty:
+            return "（未配置筛选 → 不会告警）"
+        mode = "满足任一条件" if self.filters.match != "all" else "满足全部条件"
+        parts = [f"{k}: {' / '.join(v)}" for k, v in self.filters.active_groups]
+        return f"{mode} | " + " ; ".join(parts) if parts else "（未配置筛选）"

courser/human.py

@@ -0,0 +1,33 @@
+"""人类节奏模拟：相邻操作之间随机间隔。
+
+所有 sleep 都使用随机区间，避免固定间隔暴露自动化痕迹；
+同时保持低频（间隔较短的操作按秒计，轮询按分钟计）。
+"""
+
+from __future__ import annotations
+
+import random
+import time
+
+__all__ = ["sleep_rand", "jitter", "human_delay_range"]
+
+
+def sleep_rand(lo: float, hi: float) -> float:
+    """随机休眠 [lo, hi] 秒并返回实际休眠时长。"""
+    if hi < lo:
+        lo, hi = hi, lo
+    secs = random.uniform(lo, hi)
+    time.sleep(secs)
+    return secs
+
+
+def jitter(value: float, ratio: float = 0.3) -> float:
+    """在 value*(1-ratio) ~ value*(1+ratio) 之间随机抖动（用于轮询间隔，分钟级）。"""
+    return value * random.uniform(1.0 - ratio, 1.0 + ratio)
+
+
+def human_delay_range(base_lo: float = 6.0, base_hi: float = 14.0) -> tuple[float, float]:
+    """两次页面操作之间的随机间隔范围（秒）：在基准区间上再做一次随机缩放。"""
+    lo = base_lo * random.uniform(0.8, 1.2)
+    hi = base_hi * random.uniform(0.9, 1.3)
+    return (min(lo, hi), max(lo, hi))

courser/logfile.py

@@ -0,0 +1,35 @@
+"""持久化日志：写入 data/courser.log（gitignored），自动滚动。
+
+所有运行痕迹（每轮登录/抓取/命中/发送/失败原因/风控）都会落盘，
+便于排查"为什么登录不进去"这类问题。
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from pathlib import Path
+
+from .config import DATA_DIR
+
+LOG_FILE = Path(os.environ.get("COURSER_LOG", str(DATA_DIR / "courser.log")))
+_MAX_BYTES = 2 * 1024 * 1024  # 单文件 2MB，超出滚动为 courser.log.1
+_lock = threading.Lock()
+
+
+def log(msg: str, level: str = "INFO") -> None:
+    line = f"{time.strftime('%Y-%m-%d %H:%M:%S')} [{level}] {msg}\n"
+    try:
+        with _lock:
+            LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+            if LOG_FILE.exists() and LOG_FILE.stat().st_size > _MAX_BYTES:
+                LOG_FILE.replace(LOG_FILE.with_suffix(".log.1"))
+            with LOG_FILE.open("a", encoding="utf-8") as f:
+                f.write(line)
+    except Exception:
+        pass  # 日志失败绝不能影响主流程
+
+
+def error(msg: str) -> None:
+    log(msg, "ERROR")

courser/models.py

@@ -0,0 +1,116 @@
+"""领域模型（domain objects）。
+
+全系统共用的数据对象，不归属任何具体实现（抓取 / 监控 / UI 都不该自己定义它们）。
+- Course      补退选列表中的一门课程
+- FetchResult 一次抓取（一轮登录 + 翻页）的原始结果
+- RoundResult 一轮完整监控（抓取 → 筛选 → 通知决策）的最终结果
+- FetchError / LoginError  抓取流程异常
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# 同一门课可同时属于多类（如「任选、思政选择性必修」），类别格内用分隔符并列
+_CATEGORY_SPLIT_RE = re.compile(r"[、,，/；;]")
+
+# 表格脚部分页栏文本特征：这些行会被误判成 Course，必须剔除
+_PAGER_MARKERS = ("page", "previous", "next", "跳到", "dopagersubmit",
+                  "first /", "/ last")
+
+
+class FetchError(RuntimeError):
+    """抓取流程中的一般错误。"""
+
+
+class LoginError(FetchError):
+    """登录失败（可能需要验证码/二次验证，或账号问题）。"""
+
+
+@dataclass
+class Course:
+    """补退选列表中的一门课程（仅可用课程列表，不含已选课程）。"""
+
+    course_no: str = ""
+    name: str = ""
+    category: str = ""
+    credits: str = ""
+    weekly_hours: str = ""
+    teacher: str = ""
+    class_no: str = ""
+    dept: str = ""
+    grade: str = ""
+    schedule: str = ""
+    pnp: str = ""
+    seats_raw: str = ""
+    quota: Optional[int] = None      # 限数
+    selected: Optional[int] = None   # 已选
+    avail: int = -1                  # 空余 = 限数 - 已选；-1 表示未知
+    status: str = ""                 # 选课状态：可申请 / 不可申请 / 已选上 / (空)
+    seq: str = ""                    # 课程稳定 id（course_seq_no）
+    links: dict = field(default_factory=dict)
+    page: int = 0                    # 在选课网列表中的页码（1 起）
+
+    @property
+    def categories(self) -> list[str]:
+        """该课的独立课程类别。同一门课可同时属于多类，
+        如「任选、思政选择性必修」拆成 ['任选', '思政选择性必修'] 两类。"""
+        return [p for p in (s.strip() for s in _CATEGORY_SPLIT_RE.split(self.category)) if p]
+
+    @property
+    def has_seats(self) -> bool:
+        return self.avail > 0
+
+    @property
+    def key(self) -> str:
+        return self.seq or f"{self.course_no}#{self.class_no}"
+
+
+@dataclass
+class FetchResult:
+    courses: list[Course] = field(default_factory=list)
+    pages: int = 0
+    login_mode: str = ""          # login_click / sso_auto
+    ok: bool = True
+    error: str = ""
+    cancelled: bool = False       # 用户主动停止本轮，不属于抓取故障
+    warning_hit: bool = False     # 页面文本中检测到风控/警告提示语
+    warning_checked: bool = False  # 本轮是否真正进入了补退选页面、并读取了至少一页文本
+                                 # （有观察风控警告的机会，才计入风控触发率分母）
+
+
+def is_real_course(c: "Course") -> bool:
+    """剔除被误当课程的表格脚/分页栏：无课程号，或文本带分页栏特征。
+
+    选课网可用列表每页末尾有一行「Page X of Y · First/Previous/Next/Last ·
+    跳到：function doPagerSubmit(...)」的页脚，会被 parse_course 读成一门伪课程，
+    其字符串含 JS 文本，渲染时可能触发 markup 解析崩溃。这里做兜底过滤。
+    """
+    no = (c.course_no or "").strip()
+    if not no:
+        return False
+    text = (f"{no} {c.name or ''}").lower()
+    return not any(m in text for m in _PAGER_MARKERS)
+
+
+@dataclass
+class RoundResult:
+    ts: float = 0.0
+    ok: bool = True
+    error: str = ""
+    cancelled: bool = False       # 用户主动停止本轮，不显示为抓取失败
+    login_mode: str = ""
+    pages: int = 0
+    total: int = 0
+    courses: list = field(default_factory=list)
+    matched: list = field(default_factory=list)
+    notified: list = field(default_factory=list)
+    duration_s: float = 0.0
+    warning_hit: bool = False        # 页面检测到风控提示语
+    risk_percent: int = 0            # 最近 N 次有效抓取中实际警告触发率（0~100）
+    risk_label: str = "无"
+    risk_hits: int = 0               # 最近窗口内触发警告的有效抓取次数
+    risk_total: int = 0              # 最近窗口内的有效抓取总次数