yianxue-assistant/实施开发方案.md

# 谊安学助手实施开发方案

日期：2026-10-18。依据 [需求.md](需求.md)，在现有用户脚本上增量开发，完成后构建、验证、提交并推送当前仓库。

## 1. 开发顺序与交付

| 阶段 | 实施内容 | 验收重点 |
|---|---|---|
| 统一题库 | 三岗位来源统一存储、检索与精确匹配；旧数据迁移；生成统一 CSV | 5520 条来源记录不丢失；无岗位文件可用；重复导入不增生；冲突不覆盖 |
| 六栏面板 | 总览、视频、考试、题库、控制台、其他设置；保留拖拽与折叠 | 窄屏可操作；全局暂停常驻；切栏不启动任务或导出 |
| 学习调度 | 从实际页面发现任务，按稳定标识排队；四种模式，顺序与并行 | 不猜业务接口；已完成不重做；受前置条件约束；独立视频与考试任务不重复领取 |
| 视频与恢复 | 真实播放器倍速、平台记录、课中题检测、受限恢复及检查点 | 播放结束不误判完成；主动暂停/弹题不刷新；重试有上限；人工重开默认暂停 |
| 考试流程 | 主题关联预检、整卷预检、逐题间隔、分值读取、选中全文核验、交卷、缺题人工确认开关 | 网页题目与答题卡完整；严格大于 80 分；至少 6 分钟；默认缺题人工确认，关闭后按部分题库规则交卷；真实提交结果确认 |
| 集成发布 | 既有复制/搜索/导出/范围/拖拽回归，更新文档与用户脚本 | 本地模拟业务页面完成交互测试；无外网业务请求；提交并推送远程 |

## 2. 模块边界

- `bank-store.js`、`answer-matcher.js`：统一题库与证据匹配，岗位仅作来源信息。
- `assistant-panel.js`：六个功能栏及状态展示，仅通过回调发出用户操作。
- `learning-engine.js`：任务、视频、恢复、检查点、日志及多页面协调。
- `exam-controller.js`：当前考试的主题依据、原始进入时间、分值核算及交卷状态机。
- `answer-runner.js`：按配置间隔点击真实选项，保持每步上下文及全文核验。
- `practice-exporter.js`：统一协调页面识别、用户设置、模块生命周期及站点范围。
- `build-userscript.mjs`：发布单文件用户脚本，名称继续为“谊安学助手 2.0”。

## 3. 状态与操作约束

- 用户启动任务才调度。切栏、搜索、读取日志不改变运行状态。
- 课中题归视频任务；考试交卷规则不应用到课中题或练习。
- 考试先核对主题关联；仅相似词不能授权自动答题。完整题干预检发生在试卷加载后，不能将已进入试卷的场次称为未开考。
- 预计得分仅计入答案唯一、当前选中全文一致的题目实际分值。未知、冲突及分值不明不算正分。
- “题目不全时手动确认交卷”开关默认开启：任意题目未匹配、冲突、未核验或不支持，以及正常未答完提醒均等待人工在网站确认。关闭时允许网页整卷完整、全部可匹配题处理并全文核验、预计得分严格大于 80 分且满 6 分钟的部分题库试卷自动交卷及确认正常未答完提醒；未知题不猜答、不计正分。
- 网页整卷和答题卡完整、主题关联明确、分值与分制可核对、可匹配题均已全文核验、预计得分严格大于 80 分和达到最早交卷时长等通用门槛，在任何开关状态下均生效。
- 用户手动作答、关停自动选择、暂停、题库/主题变更均取消旧交卷计划；继续前重新核验。
- 提交过程保存状态；结果不明先等待检查，不重复点击。网站倒计时独立于脚本暂停。
- 同一任务只由一个有效执行页持有；并行受阻时显示原因，不显示虚假的运行成功。

## 4. 样本与验证策略

- 保存网页按静态 DOM 解析，不运行其中原站脚本，也不向业务服务器发送请求。
- 使用真实考试样本验证分值标记、40 题全文匹配及选项换序，使用独立本地模型验证网站选中状态回读。
- 使用可控制时钟与本地提交模型覆盖 80/大于 80、6 分钟前后、人工暂停、未知分值、重复提交及恢复。
- 使用课程/视频模拟页面覆盖倍率、平台完成条件、课中弹题阻塞、卡顿恢复和多页协调。
- 用桌面与窄屏浏览器验证六栏、拖拽、切换状态及控制台；截图保存在系统临时目录。

## 5. 真实环境验收边界

当前包未包含实际课中弹题内容，也没有完整登录后的课程解锁、平台后台播放及正式交卷结果流程。实现采用保守 DOM 识别：结构或结果无法确认时进入等待人工，不猜答案、不伪造学习进度、不绕过网站验证。发布记录须分别说明本地已验证能力和需要在真实环境核实的流程。

验收完成后将需求、实施方案、源代码、测试、统一题库和构建后的脚本一并提交，推送至 `ssh://git@192.168.10.31:2222/qishizhe/yianxue-shauti.git`。

## 6. 本次实现与验证记录

- 发布版本 2.1.0，脚本名称保持“谊安学助手 2.0”。以上模块已接入构建后的单文件脚本，六栏共享全局控制及状态。
- 统一题库保留 5520 条来源记录，2458 道唯一题、2459 个答案组合、1 道冲突题；合并脚本核对原 28 个 CSV 的字段和真实导入结果。
- 增加统一题库、课程状态机、课中题、考试交卷、六栏及完整考试/视频流程回归，连同既有用例共 13 个测试套件。
- 浏览器验证使用本地 Chrome / Playwright，覆盖桌面、390px 窄屏及 320×480 小窗口；Browser 插件在当前环境不可用。截图位于系统临时目录，不提交至仓库。
- 实际保存题目用于验证全文、类型、分值与选项乱序。课程任务、平台完成、并行心跳、课中题判分和提交结果通过独立本地模型验证，没有参加真实考试或调用业务提交接口。
- 补充回归保护异步保存期间的暂停/题库/页面/分值变化、重考计时隔离、未知提交防重复、课中题选中后立即暂停、视频先结束后的并行汇总及平台完成状态展示。

代码交付并不替代第 5 节的真实账号环境验收；未识别的页面结构、身份验证、结果或后台限制会停止受影响任务并提示人工处理。

## 7. 2.1.1 调整：缺题人工确认开关

- “考试答题”栏新增“题目不全时手动确认交卷”开关（`manualConfirmIncomplete`），默认开启，设置跨页面及刷新保存。
- 开启时要求整卷每题唯一精确匹配且当前选中全文核验通过，题库缺题、冲突、未核验、无法唯一映射或不支持时等待人工；网站正常未答完提醒也由用户确认。关闭时恢复部分题库自动交卷，保留题库主题预检、全部可匹配题已处理并全文核验、预计得分严格大于 80 分及默认 6 分钟等条件，允许自动确认本场正常未答完提醒。
- 网页题目或答题卡加载不全、分值或分制不明、主题关联不明确、可匹配题未处理或核验失败、80 分及以下、计时未到、暂停、身份验证及结果不明等条件始终阻止自动交卷。开关不能覆盖这些通用门槛。
- 在入口、提交前复查及确认阶段统一核对开关和通用门槛。切换开关立即暂停当前答题与交卷计划，须用户明确继续后重验，不能关闭时立即提交。未知题不猜答，人工补选的未知答案不自动计正分。
- 本次验收重点：网页整卷完整、已核验 84 分但有 4 题未匹配时，开关开启则满 6 分钟仍不点击提交/确认，关闭并明确继续重验后可按原规则交卷及确认正常未答完提醒；完整 100 分且每题核验通过，达到时长并满足其他条件后可正常自动交卷。另覆盖任何开关状态下的加载不全、分值不明、80 分、主题不明，以及开关默认值、持久化和切换中止。
- 本节记录本次实施与验收范围，测试结果以本次实际执行记录为准。