study-tool/docs/architecture.md

# 架构说明

## 目录

```
app.py                     启动壳：把 src 加进 sys.path，调用 study_tool.app.main()
pyproject.toml             打包配置（src 布局，console script: study-tool）
src/study_tool/
  __init__.py              包信息（版本）
  __main__.py              python -m study_tool 入口
  app.py                   组装：FastAPI、鉴权中间件、页面 / health、启动 main()
  webapp.py                FastAPI 实例（路由模块从这里注册，避免循环导入）
  config/                  全局路径常量（ROOT / DATA / STATIC_DIR），不放任何平台常量
    settings.py            系统设置读写（大模型 + 学习方式）
  runtime.py               运行状态 RUNS + 统一日志 log()
  database/                SQLite 存储（SQLAlchemy ORM）
    models.py              ORM 模型：settings / kv / accounts / login_log / run_log / run_state / snapshots
    __init__.py            engine / Session + 读写函数（账号、设置、日志、状态、缓存、快照）
  models.py                通用 HTTP 请求模型（Pydantic）；测验请求模型在 plugins/guanyixue/quiz.py
  llm/                     大模型调用（OpenAI 兼容），后续大模型代码都放这里
  bank.py                  题库匹配 + 大模型兜底（与平台无关）：只决定「这题选什么」，不碰平台页面 / 接口
  engine.py                账号级编排：课程循环、会话续期、按 platform 分发
  platforms/               平台运行时（见下）
    base.py                Platform 契约（id / label / 槽位 / capabilities）
    contract.py            生命周期 ↔ 槽位 ↔ 能力名映射
    errors.py              SessionExpired（平台层错误类型）
    registry.py            注册表：register / get / detect / all
  plugins/                  插件式平台（加载器扫目录，新增插件不改代码）
    __init__.py            load_plugins / discover / set_enabled / reload（启停 + 热重载）
    gdgxk/
      plugin.json           注册信息：id / title / name（只放元数据）
      main.py              广东公需课：Platform 子类（登录 / 课程 / 学习 / 续期）
      utils/http.py        域名 / UA / XHR 上报封装与 SessionExpired
      utils/login.py       base64 账号密码 + 图形验证码 + ITLMS 换票
      utils/course.py      课程列表卡片 / 学习页上报参数 / 进度页活动清单
      utils/learn.py       活动页打开 → 注册播放 → 1x 心跳上报
      utils/exam.py        课程考核：解析内嵌题面 → 题库/AI 答题 → POST finishTest2 交卷
      utils/bank.py        题库入口：读 bank/*.json，调核心 bank.answer（题库优先、大模型兜底）
      bank/                本年题库数据（*.json，格式 [{"q": 题干, "a": "B"}]），换年份只加文件
      script/              插件专属脚本：capture-jsglpt.py（抓包取证）、test-gdgxk.py（接口自测）
    guanyixue/
      plugin.json           注册信息：id / title / name
      main.py              莞易学：Platform 子类，按 generation 分发
      config.py            站点地址 / 登录授权入口 / 课程板块 / Node 与 desenc.js 定位 / 快照兜底目录
      utils/http.py        会话 / cookie / 身份 / 新版平台 token
      utils/login.py       账号密码登录 / CASTGC 续期 / token 换取
      utils/course.py      旧版课程列表 / 结构解析 / 页面代际分发
      utils/feedback.py    旧版反馈表与测验提交
      utils/learn.py       旧版学习流程：反馈表 + 测验 + 课件心跳
      utils/spa.py         新版 SPA：StudyClient / 接口学习 / 视频流程
      detect.py            页面代际识别（legacy 旧版 / spa 新版）
      script/              插件专属脚本：des.js、desenc.js（Node 调用）、study_video.py（命令行刷视频）
      capture.py           抓包调试：把页面 XHR/fetch 落成 data/capture-*.json
      quiz.py              测验解析 / 交卷 / AI 答题（含 /api/quiz/*、测验请求模型、答题提示词、题型名）
  routes/                  HTTP 接口（load_routes() 启动时扫描本目录，新增文件自动注册）
    accounts.py            账号 / 登录 / 登录记录
    misc.py                课程 / 发现 / 学习 / 停止 / 抓包 / 快照 / 平台列表
    logs.py                /api/log、/api/runs
    settings.py            /api/settings
    llm.py                 /api/llm/test
web/                      前端源码（React 19 + TypeScript + Vite + Tailwind CSS v4）
static/                   前端构建产物（index.html + assets/ + favicon.svg，提交进仓库）
script/reference/         不参与运行的参考脚本：dgjy-toolkit.user.js、study-axios.mjs
（插件专属脚本跟着插件走：plugins/<名字>/script/，如莞易学的 des.js、desenc.js、study_video.py）
```

## 分层

- **入口层**：`app.py`（根）+ `study_tool/app.py`。前者只负责 `sys.path` 与启动，后者组装应用。
- **接口层**：`routes/*` 与 `plugins/guanyixue/quiz.py` 里的 `/api/quiz/*`，只做参数校验、调用引擎、返回结果。
- **领域层**：`engine.py`（账号级编排：课程循环 / 会话续期 / 按平台分发）、`platforms/*`（平台运行时）、`plugins/*`（平台实现，含各自的学习流程）、`notify.py`（故障上报 / 推送渠道注册）、`llm/` 与 `plugins/guanyixue/quiz.py` 的解析逻辑。
- **基础设施**：`database/`（SQLAlchemy ORM + SQLite）、`runtime.py`（状态 + 日志）、`config/`（常量 + 设置）。

依赖方向单向：接口 → 领域 → 基础设施。基础设施不反向 import 接口。

新代码的 import 一律显式（如 `from study_tool.config import JSPX`），不要再新增 `from xxx import *`；历史遗留的 star import 只保留在拆分前就存在的模块里。

`engine.py` 与 `routes/*` 只用 `registry.get(...)` 取平台实现，不 import 具体平台模块；
平台实现之间只有同平台不同代际会互相 import（`course.py` → `spa.py`），依赖保持单向，避免成环。

## 平台插件与识别

平台实现在 `platforms/` 或插件目录 `plugins/<名字>/`，都通过注册表注入，`engine` 只按
`course["platform"]` 分发：

```python
# engine.run_one_course 末尾
pf = registry.get(d.get("platform"))
pf.study(key, s, d, workers=..., cap=..., enable_quiz=..., ...)
```

`Platform` 契约（见 `platforms/base.py`）：一个平台 = 一个 `Platform` 子类，类属性放元数据，
自己确实有的阶段实现成方法；注册时只实例化子类，不再逐项绑定函数。

```python
class Platform:
    id = ""  # course["platform"] 的取值
    label = ""  # 日志 / 界面展示名，如「莞易学」
    entries = ()  # 登录入口 / 学习入口的 URL 片段
    # 槽位：子类实现哪个阶段就覆盖成方法（第一个参数是 self）；保持 None = 该平台没有这项能力
    study = None  # study(self, key, s, d, **opts) -> None
    session = None  # session(self, cookies) -> requests.Session
    dump_cookies = None  # dump_cookies(self, session) -> [cookie]
    login = None  # login(self, username, password) -> (session, user)
    list_courses = None  # list_courses(self, session) -> [course]
    discover = None  # discover(self, session, plan_id, project_id, name) -> 课程描述
    renew_session = None  # renew_session(self, session) -> bool，无密码续期
    profile = None  # profile(self, session) -> 显示名
    # capabilities() 按非空槽位推导能力名
```

`registry.detect(url, html)` 按 `entries` 命中平台；「添加账号」时选择的平台写进
`accounts.platform`，之后登录 / 刷新课程 / 发现课程都用 `registry.get(account["platform"])`
取实现。课程发现时把平台 id 写进 `course["platform"]`，把页面代际写进
`course["generation"]`（`legacy` / `spa`）；引擎按平台分发，平台内部再按代际选择学习实现。

`opts` 固定包含：`workers / cap / enable_quiz / enable_feedback / mode / parallel /
quiz_key / cookies / plan / project / name`。插件可以只取自己需要的。

### 生命周期与能力

阶段与槽位对应，缺的阶段不实现即可（不要抛 `NotImplementedError`）：

- 登录 / 会话：`login`、`session`、`renew_session`、`profile`
- 查询课程：`list_courses`
- 课程详情：`discover`
- 学习：`study`
- 测验：`quiz(self, s, d, b)` 取题、`quiz_submit(self, s, b)` 按用户答案交卷；能力名 `quiz`（两者都实现才显示）。`/api/quiz*` 接口由莞易学插件注册、内部按 `registry.get(platform)` 分发，前端只在 `capabilities` 含 `quiz` 时显示「打开测验」
- 抓包调试：`capture(self, key, cookies, minutes)` + `captures(key)` / `capture_reset(key)`；能力名 `capture`，前端据此显示「抓包」

### 插件可删除

整个 `plugins/<名字>/` 目录删掉后，系统照常启动（目录全空也行），只是少一个平台：

- 核心（`engine` / `routes` / `database` / 前端）不 import 任何具体插件，不写死平台 id；账号的 `platform` 默认空串，前端平台下拉、「打开测验」「抓包」都按 `GET /api/platforms` 返回的 `capabilities` 动态显示。
- 插件在 import 时用 `@app.post(...)` 注册的接口，由加载器（`plugins/__init__.py`）记账：停用 / 重载 / 加载失败时一并摘除，不会残留也不会重复注册。
- 插件专属的常量、脚本、请求模型、依赖都放在插件目录里（`config.py`、`script/`、`quiz.py`），不放核心目录。
- 已有账号选的平台被删后，该账号登录 / 刷新课程会返回 `no_platform`，不影响其它账号。

`Platform.capabilities()` 按非空槽位推导能力名（映射见 `platforms/contract.py`）：
`login` / `session` / `renew` / `profile` / `courses` / `discover` / `study`。
`GET /api/platforms` 一并返回 `capabilities`，前端据此决定显示哪些按钮。
流程顺序只有一个实现（引擎），插件只负责单步。

### 内置：莞易学

`jspx.dgjy.net`（登录入口）和 `study.dgjy.net`（学习入口）是同一个平台，统一注册为
`id=guanyixue`、`label=莞易学`，实现在 `plugins/guanyixue/`。两代课程页：

- `utils/http.py` / `utils/login.py`：会话、cookie、账号密码登录与 CASTGC 续期。
- `utils/course.py`：旧版课程页（`tier-tree-one` / `tier3`）的课程抓取与代际分发。
- `utils/feedback.py` / `utils/learn.py`：旧版反馈表、测验与刷课件（`_study_builtin`）。
- `utils/spa.py`：新版 Vue SPA，`StudyClient` + `/train/course/front/*` 接口，
  以及新版学习流程（`run_study_course`：接口上报 / 真播视频）。
- `main.py`：注册平台并按 `course["generation"]` 分发；`detect.py` 只判断页面代际，
  不判断平台归属。

### 内置：广东公需课

`id=gdgxk`，`plugins/gdgxk/` 实现（插件目录，`plugin.json` 只放 id / title / name，`main.py`
只放 `Platform` 子类，登录 / 解析 / 心跳工具在 `utils/`）：
在 `jsglpt.gds.edu.cn` 登录（账号、密码
都是 base64），再用 `ssoItlmsGxkTicket.action` 换票进 `jsxx.gds.edu.cn`；视频按真实
流逝时间上报 `updateViewTime1`。没有测验 / 反馈表，所以不实现对应能力。

### 新增一个平台

1. 新建 `../src/study_tool/plugins`，写 `plugin.json`（`id` / `title` / `name`）和 `main.py`：

   ```python

from study_tool.platforms import registry
   from study_tool.platforms import Platform


   class MyPlatform(Platform):
       id = "<平台 id>"
       label = "展示名"
       entries = ("<登录入口域名>", "<学习入口域名>")

       def session(self, cookies=None): ...
       def dump_cookies(self, s): ...
       def login(self, username, password): ...
       def list_courses(self, s): ...
       def discover(self, s, plan_id, project_id, name=""): ...
       def profile(self, s): ...

       def study(self, key, s, d, **opts):
           # 用 s（requests.Session，带该账号 cookie）把课程活动跑完
           # 日志一律 runtime.log(key, ...)
           ...


   PLATFORM = registry.register(MyPlatform())
   ```

   平台确实没有的阶段不要写，保持基类的 `None`，引擎按能力判断走不走那个分支。

2. 不用改任何代码：`load_plugins()` 扫目录时会自动 import 这个插件。实现复杂时可以像
   `plugins/guanyixue/` 那样把工具按阶段拆到 `utils/`（http / login / course / learn / spa）。

3. 平台注册后会自动出现在「添加账号」的平台下拉框；账号选了该平台，登录 / 刷新课程 /
   发现课程 / 学习都走它的实现，不需要改路由或前端。

已内置莞易学（`guanyixue`）和广东公需课（`gdgxk`），都在 `plugins/` 下；`accounts.platform` 是
平台分发依据，接入新平台只需建一个插件目录，引擎与路由不用改。

## 故障推送

`notify.py` 是通知中心：核心代码只调 `notify.fault(kind, key, title, content)` /
`notify.retry(key, what)`，不 import 任何具体推送服务；真正发请求的渠道在插件里。

```python
class Channel:  # notify.Channel
    id = ""
    label = ""

    def send(self, title, content, context=None): ...  # 失败抛异常


NOTIFY = notify.register(DaidaiPush())  # 插件 main.py 末尾注册
```

- 插件 `plugin.json` 写 `"kind": "notify"`，加载器就从 `notify` 注册表校验（默认
  `kind=platform` 走 `registry`）；`/api/plugins` 会多返回 `kind`，能力显示为「推送」。
- 故障类型：`run`（整体运行异常）、`course`（单门课程异常）、`login`（登录失败 /
  会话无法续期）、`progress`（学完仍未完成 / 进度没推进 / 没有可识别活动）、
  `retry`（同一原因反复重试）。每种类型在设置项 `notify` 里有独立开关。
- 触发点在引擎与路由：课程循环前后对比进度快照（`engine._snap` + `notify.check_progress`）、
  课程异常 / 运行异常、`SessionExpired` 续期与重登、`/api/login` 失败；插件内部的重试
  （公需课重登 / 自动重学、莞易学单课时重报）调 `notify.retry` 计数。
- 节流：同一 `(类型, 账号)` 在 `cooldown_min` 分钟内只推一次；`retry` 只在计数刚达到
  `retry_threshold` 时推一次；每轮学习开始 `notify.reset(key)` 清零计数。
- 配置在系统设置 `notify`：`base_url` / `app_key` / `app_secret` / `channel_name` /
  各类型开关 / `retry_threshold` / `cooldown_min`；`POST /api/notify/test` 走同一个
  `notify.send()` 发测试推送。内置渠道插件 `plugins/daidai_push/`（呆呆面板）。

## 前端

`web/` 是独立的前端工程：React 19 + TypeScript + Vite + Tailwind CSS v4。

- `web/src/App.tsx`：账号轮询、操作编排、弹窗状态；`components/` 放卡片 / 弹窗 / 基础 UI。
- `web/src/lib/api.ts`：统一 fetch 封装（401 / 离线判定）与 SSE 读取。
- `web/src/types.ts`：账号、课程、运行状态、测验等接口类型。
- 构建产物输出到仓库根的 `static/`（`index.html` + `assets/*` + `favicon.svg`），
  FastAPI 直接托管：`/` 返回 `static/index.html`（禁止缓存），`/assets` 挂 `StaticFiles`。
- 开发：`cd web && pnpm install && pnpm dev`（5173，`/api` 代理到 `127.0.0.1:8848`）。
- 构建 / 类型检查：`pnpm build` / `pnpm typecheck`。

## 日志

所有日志只走 `runtime.log(key, msg, level="info")`：它统一写控制台、内存（`/api/log`）和 SQLite（`/api/log/history`），三处内容必须一致。

- 禁止在新代码里自己 `print()` 写业务日志，也不要直接调 `store.run_log_add()`；模块只负责组织 `msg`。
- key 约定：账号相关用账号 id（页面卡片「课程日志」直接显示）；全局 / 系统事件用 `"system"`（右上角「系统日志」弹窗显示）。
- 时间戳、级别、格式都由 `runtime.log` 统一拼（`时间 [级别] 内容`），模块里不要自己加时间前缀。
- 前端读日志统一用 `/api/log?key=&since=`（实时）+ `/api/log/history?key=&tail=`（历史兜底），不要另起一套日志接口。

## 发版

通用流程见 `AGENTS.md`「发版本流程」；本项目的具体做法：

- 版本号三处：`metadata.yaml`、`pyproject.toml`、`uv.lock`（其中 `study-tool` 那一段），由 `pyproject.toml` 的 `[tool.bumpversion]` 统一改，不要手改。
- 发版前先 `uv lock` 自检；它若改动了 `uv.lock`，说明某个任务漏提交了锁文件，补进那次任务。
- 命令：`uv tool run bump-my-version bump patch`。工作区需干净；它一次完成改三处版本、提交 `chore(release): vX.Y.Z`、打 tag `vX.Y.Z`，不要再手动 commit 或 `git tag`。
- 发完用 `git log -1` 和 `git tag -l` 确认 tag 存在、HEAD 正确；同名 tag 已存在时工具会失败，不会覆盖。
- 前端有改动时，`pnpm build` 并提交 `static/` 要在发版前的普通提交里完成，发版步骤本身不构建。
- 改了 `[tool.bumpversion]` 配置后，先跑 `uv tool run bump-my-version bump patch --dry-run --allow-dirty -vv`，确认三个文件都会被改。
- 仓库文件是 CRLF，且 bump-my-version 默认按字面量搜索：用正则的条目必须写 `regex = true`，并且不要用 `$` 锚定行尾（`uv.lock` 那条用 `\r?\n` 兼容换行）。