refactor(plugins): 莞易学迁到 pugins/guanyixue

- platforms/guanyixue.py → pugins/guanyixue/main.py - jspx.py / study.py / detect.py 一并搬进插件目录，插件自包含：热重载会把实现模块一起重新 import，不再是半截插件 - 导入路径改成 study_tool.pugins.guanyixue.*；quiz.py 两处引用同步更新 - platforms/__init__.py 只剩运行时，load_builtin() 只调 load_plugins() - 新增 pugins/guanyixue/pugin.json（id / title / name） - 同步 AGENTS.md、docs/architecture.md、docs/pugin.md、docs/OPTIMIZATION.md
2026-10-31 16:18:45 +08:00
parent 8e8d6b83f1
commit 491fd08c1e
11 changed files with 74 additions and 38 deletions
@@ -23,6 +23,24 @@
 3. `.env` 改 `PORT=8849` 重启 → 实际监听 8849；命令行 `set PORT=8850` 再启动应压过 `.env`。
 4. `.env` 里 `BIND_ADDR=127.0.0.1` → 只绑本机；改 `0.0.0.0` → 同网段可访问。

+## 莞易学迁到插件目录
+
+**状态**：已实现，待实测确认。
+
+### 做了什么
+
+- `platforms/guanyixue.py` → `pugins/guanyixue/main.py`；`jspx.py` / `study.py` / `detect.py`
+  一并搬进 `pugins/guanyixue/`，插件自包含，热重载能覆盖全部实现模块。
+- 导入路径改成 `study_tool.pugins.guanyixue.*`；`quiz.py` 里对 `jspx` / `study` 的引用同步更新。
+- `platforms/__init__.py` 只剩运行时，`load_builtin()` 只调 `load_plugins()`。
+- 新增 `pugins/guanyixue/pugin.json`（id / title / name）。
+
+### 怎么测
+
+1. `GET /api/plugins` 列出 `gdgxk` 与 `guanyixue`，两者 enabled / loaded 都是 true。
+2. 莞易学：刷新课程 → 发现课程 → 开始学习（旧版 / 新版各一次）；测验弹窗照常。
+3. 插件弹窗里对 guanyixue 点「重载」后再跑一次学习，行为不变。
+
 ## 插件热加载 + 启用/停用清单

 **状态**：已实现，待实测确认。
@@ -24,15 +24,21 @@ src/study_tool/
    contract.py            生命周期 ↔ 槽位 ↔ 能力名映射
    errors.py              SessionExpired（平台层错误类型）
    registry.py            注册表：register / get / detect / all
-    detect.py              页面代际识别（legacy 旧版 / spa 新版）
-    guanyixue.py           莞易学平台：合并 jspx 登录入口与 study 学习入口
-    jspx.py                莞易学旧版：会话 / 登录 / 课程抓取 / 旧版学习流程
-    study.py               莞易学新版 SPA：StudyClient / 接口学习 / 视频流程
  pugins/                  插件式平台（加载器扫目录，新增插件不改代码）
    __init__.py            load_plugins / discover / set_enabled / reload（启停 + 热重载）
    gdgxk/
      pugin.json           注册信息：id / title / name（只放元数据）
-      main.py              广东公需课：SSO 换票 + 视频进度心跳
+      main.py              广东公需课：Platform 子类（登录 / 课程 / 学习 / 续期）
+      utils/http.py        域名 / UA / XHR 上报封装与 SessionExpired
+      utils/login.py       base64 账号密码 + 图形验证码 + ITLMS 换票
+      utils/course.py      课程列表卡片 / 学习页上报参数 / 进度页活动清单
+      utils/learn.py       活动页打开 → 注册播放 → 1x 心跳上报
+    guanyixue/
+      pugin.json           注册信息：id / title / name
+      main.py              莞易学：Platform 子类，按 generation 分发
+      jspx.py              旧版页面：会话 / 登录 / 课程抓取 / 旧版学习流程
+      study.py             新版 SPA：StudyClient / 接口学习 / 视频流程
+      detect.py            页面代际识别（legacy 旧版 / spa 新版）
  routes/                  HTTP 接口
    accounts.py            账号 / 登录 / 登录记录
    misc.py                课程 / 发现 / 学习 / 停止 / 抓包 / 快照 / 平台列表
@@ -112,25 +118,26 @@ quiz_key / cookies / plan / project / name`。插件可以只取自己需要的
 ### 内置：莞易学

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

- `platforms/jspx.py`：旧版页面（`tier-tree-one` / `tier3`），负责会话、登录、课程抓取，
+- `jspx.py`：旧版页面（`tier-tree-one` / `tier3`），负责会话、登录、课程抓取，
  以及旧版学习流程（`_study_builtin`：反馈表 + 测验 + 刷课件）。
- `platforms/study.py`：新版 Vue SPA，`StudyClient` + `/train/course/front/*` 接口，
+- `study.py`：新版 Vue SPA，`StudyClient` + `/train/course/front/*` 接口，
  以及新版学习流程（`run_study_course`：接口上报 / 真播视频）。
- `platforms/guanyixue.py`：注册平台并按 `course["generation"]` 分发；
-  `platforms/detect.py` 只判断页面代际，不判断平台归属。
+- `main.py`：注册平台并按 `course["generation"]` 分发；`detect.py` 只判断页面代际，
+  不判断平台归属。

 ### 内置：广东公需课

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

 ### 新增一个平台

-1. 新建 `src/study_tool/platforms/<名字>.py`：
+1. 新建 `src/study_tool/pugins/<名字>/`，写 `pugin.json`（`id` / `title` / `name`）和 `main.py`：

   ```python
   from study_tool.platforms import registry
@@ -158,13 +165,14 @@ quiz_key / cookies / plan / project / name`。插件可以只取自己需要的

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

-2. 在 `platforms/__init__.py` 的 `load_builtin()` 里加一行 `from study_tool.platforms import <名字>`。
+2. 不用改任何代码：`load_plugins()` 扫目录时会自动 import 这个插件。实现复杂时可以像
+   `pugins/guanyixue/` 那样在同一目录再拆 `jspx.py` / `study.py` 等实现模块。

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

-已内置莞易学（`guanyixue`）和广东公需课（`gdgxk`）；`accounts.platform` 是平台分发依据，
-接入新平台只需在 `platforms/<平台>.py` 实现对应阶段的槽位，引擎与路由不用改。
+已内置莞易学（`guanyixue`）和广东公需课（`gdgxk`），都在 `pugins/` 下；`accounts.platform` 是
+平台分发依据，接入新平台只需建一个插件目录，引擎与路由不用改。

 ## 前端

@@ -82,7 +82,8 @@ src/study_tool/pugins/
  <名字>/
    pugin.json    注册信息：id / title / name（不写能力绑定）
    main.py       class <名字>(Platform)
-  gdgxk/          广东公需课：pugin.json + main.py
+  gdgxk/          广东公需课：pugin.json + main.py + utils/（拆开的实现模块）
+  guanyixue/      莞易学：pugin.json + main.py + jspx.py / study.py / detect.py
 ```

 约定：
@@ -139,8 +140,7 @@ quiz_key / cookies / plan / project / name`，插件只取自己需要的。
   和 `main.py`（按上面的骨架写 `class <名字>(Platform)`）。
 2. `main.py` 末尾 `PLATFORM = registry.register(<名字>())`。
 3. 不需要改 `load_builtin()`、路由或前端 —— 加载器扫目录时自动 import 各插件。
-   跟 `jspx` / `study` 这类共享实现模块关系紧密的平台，仍可以放 `platforms/<名字>.py`，
-   在 `load_builtin()` 里加一行 import。
+   实现复杂时可以在同一目录再拆 `jspx.py` / `study.py` 这类实现模块（见 `guanyixue/`）。
 4. 启动服务，`GET /api/platforms` 应出现该平台。
 5. 联调顺序：`/api/login` → `/api/courses` → `/api/discover` → `/api/study`。

@@ -153,8 +153,10 @@ quiz_key / cookies / plan / project / name`，插件只取自己需要的。
   平台私有的重登逻辑改成 `_relogin` 这类私有方法。
 3. 加类属性 `id` / `label` / `entries`，删掉模块末尾的逐项注册。
 4. 模块末尾改成 `PLATFORM = registry.register(<类名>())`。
-5. 逐个验证槽位行为与迁移前一致；同一平台的两个代际由 `study` 里按
-   `course["generation"]` 分发（参见 `guanyixue.py`）。
+5. 实现模块（`jspx.py` / `study.py` / `detect.py`）一起搬进 `pugins/<名字>/`，目录内互相
+   引用改成 `study_tool.pugins.<名字>.xxx`；外部（如 `quiz.py`）引用同步改路径。
+6. 逐个验证槽位行为与迁移前一致；同一平台的两个代际由 `study` 里按
+   `course["generation"]` 分发（参见 `pugins/guanyixue/main.py`）。

 ## 硬约束

@@ -197,5 +199,7 @@ quiz_key / cookies / plan / project / name`，插件只取自己需要的。
   `course["platform"]` 分发；平台用自由函数 + 逐项注册；学习流程仍在引擎。
 3. 契约补全：`contract.py` 推导 `capabilities`；`SessionExpired` 移到 `platforms/errors.py`；
   各平台学习流程从引擎搬回平台模块（`engine.py` 只剩账号级编排）。
-4. 类式（当前）：`Platform` 变成普通基类，平台写成子类（类属性 + 方法），
-   禁止逐项传函数注册；`gdgxk` 与 `guanyixue` 已完成迁移。
+4. 类式：`Platform` 变成普通基类，平台写成子类（类属性 + 方法），禁止逐项传函数注册。
+5. 插件目录（当前）：平台全部迁到 `pugins/<名字>/`（`pugin.json` + `main.py`，实现复杂的
+   再拆 `jspx.py` / `study.py` 等），`load_plugins()` 扫目录加载，支持启停与热重载；
+   `gdgxk`、`guanyixue` 都已完成迁移。