courser 0.1.0__tar.gz

courser-0.1.0/.env.example

@@ -0,0 +1,18 @@
+# ===== courser 敏感配置模板 =====
+# 复制为 .env（.env 已被 .gitignore 忽略），或直接在 TUI「设置」里填写。
+
+# ---- PKU 学号/密码（可选）----
+# 不配置则依赖浏览器密码管理器自动填充（打开登录页等待一小会直接点登录）。
+# 注意：在 opencli 自动化窗口中，少数环境密码管理器不会自动填充，
+# 此时必须在这里（或 TUI 设置）配置，脚本会先填好再点登录。
+# PKU_USERNAME=
+# PKU_PASSWORD=
+
+# ---- 邮件通知（gws = Google Workspace CLI）----
+# 发送邮件走 gws，需先安装并授权：
+#   brew install googleworkspace-cli    或  npm install -g @googleworkspace/cli
+#   gws auth setup   （首次：初始化 Google Cloud 项目 / OAuth / 启用 API）
+#   gws auth login   （浏览器完成 OAuth2 授权）
+# 收件邮箱在 TUI「设置 → 邮件通知」填写（也可用环境变量覆盖）：
+# MAIL_TO=you@example.com
+# GWS_FROM=            # gws 发件账号（Gmail 地址，可选，默认取认证账号）

courser-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# ---- 运行时产物（含凭据/邮件配置，绝不入库） ----
+config.json
+.env
+data/
+*.log
+.gws-*/
+
+# ---- Python / uv ----
+.venv/
+.uv-cache/
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.pytest_cache/
+
+# ---- 编辑器/系统 ----
+.DS_Store
+.idea/
+.vscode/

courser-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

courser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xjsongphy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

courser-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: courser
+Version: 0.1.0
+Summary: PKU 补退选空余名额监控：opencli 驱动后台 Chrome，人类节奏轮询，命中筛选即邮件提醒（纯文本持久监控 TUI）
+Project-URL: Homepage, https://github.com/xjsongphy/courser
+Project-URL: Repository, https://github.com/xjsongphy/courser
+Project-URL: Issues, https://github.com/xjsongphy/courser/issues
+Author: xjsongphy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: pku,reminder,textual,tui,监控,补退选,选课
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: rich>=15.0.0
+Requires-Dist: textual>=8.2.8
+Description-Content-Type: text/markdown
+
+# courser
+
+北大补退选课程名额监控工具。它在本机 Chrome 中登录选课系统，按设定间隔读取补退选列表；当符合条件的课程出现空余时，发一封邮件提醒。
+
+它只做查询和提醒，不会替你选课，也不会处理验证码。
+
+> 请只用于自己的账号，并遵守学校的相关规定。登录、查询和翻页之间会保留随机间隔；遇到风控提示或验证码时，程序会停止本轮，而不是继续尝试。
+
+```bash
+# 从 PyPI 安装（只带 rich/textual；opencli/gws 需另装，见下方）
+pipx install courser        # 或：uv tool install courser
+
+# 或从源码跑
+python -m venv .venv && . .venv/bin/activate
+pip install -e .
+```
+
+> 发布到 PyPI 只包含 courser 自身与 `rich`/`textual` 两个 Python 依赖。
+> **opencli / gws 不随包发布，需在本机单独安装**（见下方 Quick start 的说明）。
+
+## Quick start
+
+需要：Python 3.12+、[uv](https://docs.astral.sh/uv/)、Chrome，以及两个已完成配置的命令行工具：
+
+- [OpenCLI](https://github.com/jackwener/OpenCLI)：连接本机 Chrome。安装扩展、启动 daemon 后，运行 `opencli doctor`，确认检查通过。
+- [Google Workspace CLI](https://github.com/googleworkspace/cli)（`gws`）：发送提醒邮件。
+  安装：`npm install -g @googleworkspace/cli`。
+  首次先执行 `gws auth setup`（一次性初始化 Google Cloud 项目 / OAuth 配置 / 启用 API），
+  再执行 `gws auth login` 授权 Gmail；之后 token 失效时重新 `gws auth login` 即可。
+
+```bash
+git clone https://github.com/xjsongphy/courser
+cd courser
+uv sync
+cp config.example.json config.json
+uv run courser
+```
+
+第一次启动会询问收件邮箱。其余设置可以在程序的设置页完成。
+
+若你更愿意由 Chrome 或密码管理器填充北大学号和密码，保持 `credentials` 为空即可；也可以写入 `config.json`，或通过环境变量 `PKU_USERNAME`、`PKU_PASSWORD` 提供。
+
+## What it does
+
+- 每轮从 IAAA 登录，打开补退选页面，并按网站实际页数读取课程；不依赖固定页数。
+- 按课程名、课程类别和开课院系筛选。可选择任一条件命中或全部条件命中。
+- 只有“限数大于已选”的课程才会提醒；同一门课有冷却时间，邮件也有每小时上限。
+- 提供一个终端界面查看最近结果、调整筛选和设置、查看日志。文字选择风格为 Textual
+  自接管：鼠标拖动选择、松手即自动复制到剪贴板（OSC 52），并 toast 提示；滚轮滚
+  页面，帮助 / 日志 / 详情页均可用。
+
+## Run one check
+
+```bash
+uv run courser --once
+```
+
+这会跑完一轮并把结果打印到终端，适合确认登录和筛选是否正常。持续运行则直接执行 `uv run courser`。
+
+## Configuration
+
+复制 `config.example.json` 得到 `config.json` 后，最常需要改的是下面几项：
+
+```jsonc
+{
+  "interval_min": 8.0,       // 查询间隔（分钟）
+  "filters": {
+    "names": [],             // 课程名，支持子串匹配
+    "categories": [],        // 课程类别
+    "depts": ["英语语言文学系"],
+    "match": "any"          // any：任一条件；all：全部条件
+  },
+  "notify": {
+    "to": "you@example.com",
+    "min_interval_min": 15.0,
+    "max_per_hour": 5
+  }
+}
+```
+
+`config.json` 不会提交到 Git。运行日志写在 `data/courser.log`；登录、浏览器连接或邮件发送出问题时，先看这里。
+
+## Troubleshooting
+
+`opencli doctor` 需要全部通过。若登录页填入账号密码后仍未跳转，先在同一个 Chrome 中手动完成一次登录，再执行 `uv run courser --once`。验证码和二次验证需要你本人处理，courser 不会代填。
+
+## Development
+
+```bash
+uv run python tests/unit/test_opencli.py
+uv run python tests/integration/test_round_runner.py
+uv run python tests/tui/test_navigation.py
+uv run python tests/tui/test_responsive.py
+```
+
+真实网站的端到端检查仍需手动执行：
+
+```bash
+uv run courser --once
+```
+
+## License
+
+[MIT](LICENSE)

courser-0.1.0/README.md

@@ -0,0 +1,104 @@
+# courser
+
+北大补退选课程名额监控工具。它在本机 Chrome 中登录选课系统，按设定间隔读取补退选列表；当符合条件的课程出现空余时，发一封邮件提醒。
+
+它只做查询和提醒，不会替你选课，也不会处理验证码。
+
+> 请只用于自己的账号，并遵守学校的相关规定。登录、查询和翻页之间会保留随机间隔；遇到风控提示或验证码时，程序会停止本轮，而不是继续尝试。
+
+```bash
+# 从 PyPI 安装（只带 rich/textual；opencli/gws 需另装，见下方）
+pipx install courser        # 或：uv tool install courser
+
+# 或从源码跑
+python -m venv .venv && . .venv/bin/activate
+pip install -e .
+```
+
+> 发布到 PyPI 只包含 courser 自身与 `rich`/`textual` 两个 Python 依赖。
+> **opencli / gws 不随包发布，需在本机单独安装**（见下方 Quick start 的说明）。
+
+## Quick start
+
+需要：Python 3.12+、[uv](https://docs.astral.sh/uv/)、Chrome，以及两个已完成配置的命令行工具：
+
+- [OpenCLI](https://github.com/jackwener/OpenCLI)：连接本机 Chrome。安装扩展、启动 daemon 后，运行 `opencli doctor`，确认检查通过。
+- [Google Workspace CLI](https://github.com/googleworkspace/cli)（`gws`）：发送提醒邮件。
+  安装：`npm install -g @googleworkspace/cli`。
+  首次先执行 `gws auth setup`（一次性初始化 Google Cloud 项目 / OAuth 配置 / 启用 API），
+  再执行 `gws auth login` 授权 Gmail；之后 token 失效时重新 `gws auth login` 即可。
+
+```bash
+git clone https://github.com/xjsongphy/courser
+cd courser
+uv sync
+cp config.example.json config.json
+uv run courser
+```
+
+第一次启动会询问收件邮箱。其余设置可以在程序的设置页完成。
+
+若你更愿意由 Chrome 或密码管理器填充北大学号和密码，保持 `credentials` 为空即可；也可以写入 `config.json`，或通过环境变量 `PKU_USERNAME`、`PKU_PASSWORD` 提供。
+
+## What it does
+
+- 每轮从 IAAA 登录，打开补退选页面，并按网站实际页数读取课程；不依赖固定页数。
+- 按课程名、课程类别和开课院系筛选。可选择任一条件命中或全部条件命中。
+- 只有“限数大于已选”的课程才会提醒；同一门课有冷却时间，邮件也有每小时上限。
+- 提供一个终端界面查看最近结果、调整筛选和设置、查看日志。文字选择风格为 Textual
+  自接管：鼠标拖动选择、松手即自动复制到剪贴板（OSC 52），并 toast 提示；滚轮滚
+  页面，帮助 / 日志 / 详情页均可用。
+
+## Run one check
+
+```bash
+uv run courser --once
+```
+
+这会跑完一轮并把结果打印到终端，适合确认登录和筛选是否正常。持续运行则直接执行 `uv run courser`。
+
+## Configuration
+
+复制 `config.example.json` 得到 `config.json` 后，最常需要改的是下面几项：
+
+```jsonc
+{
+  "interval_min": 8.0,       // 查询间隔（分钟）
+  "filters": {
+    "names": [],             // 课程名，支持子串匹配
+    "categories": [],        // 课程类别
+    "depts": ["英语语言文学系"],
+    "match": "any"          // any：任一条件；all：全部条件
+  },
+  "notify": {
+    "to": "you@example.com",
+    "min_interval_min": 15.0,
+    "max_per_hour": 5
+  }
+}
+```
+
+`config.json` 不会提交到 Git。运行日志写在 `data/courser.log`；登录、浏览器连接或邮件发送出问题时，先看这里。
+
+## Troubleshooting
+
+`opencli doctor` 需要全部通过。若登录页填入账号密码后仍未跳转，先在同一个 Chrome 中手动完成一次登录，再执行 `uv run courser --once`。验证码和二次验证需要你本人处理，courser 不会代填。
+
+## Development
+
+```bash
+uv run python tests/unit/test_opencli.py
+uv run python tests/integration/test_round_runner.py
+uv run python tests/tui/test_navigation.py
+uv run python tests/tui/test_responsive.py
+```
+
+真实网站的端到端检查仍需手动执行：
+
+```bash
+uv run courser --once
+```
+
+## License
+
+[MIT](LICENSE)

courser-0.1.0/config.example.json

@@ -0,0 +1,28 @@
+{
+  "first_run_done": false,
+  "interval_min": 8.0,
+  "interval_jitter": 0.3,
+  "page_delay_min": 0.8,
+  "page_delay_max": 2.0,
+  "session": "courser-watch",
+  "window": "background",
+  "force_relogin": true,
+  "credentials": {
+    "username": "",
+    "password": ""
+  },
+  "filters": {
+    "names": [],
+    "categories": [],
+    "depts": [
+      "英语语言文学系"
+    ],
+    "match": "any"
+  },
+  "notify": {
+    "to": "you@example.com",
+    "gws_from": "",
+    "min_interval_min": 15.0,
+    "max_per_hour": 5
+  }
+}

courser-0.1.0/courser/__init__.py

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

courser-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-0.1.0/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 "—"