feat: add portable role-based question bank assistant

README.md

@@ -1,59 +1,78 @@
-# 谊安学练习题库导出
+# 谊安学助手 2.0
 
-进入谊安学“练习”页面后自动下载 CSV，包含题干、全部选项、参考答案、答案对应选项、题目解析及图片链接。也可手动导出 JSON、TXT。
+一个可直接安装的油猴脚本，集成岗位题库搜索、自动选择答案、允许复制文字，以及原有 CSV / JSON / TXT 导出功能。题库在浏览器本地解析和保存，内置 JSZip，无 CDN 依赖。
 
-脚本读取网页中已加载的参考答案，包括隐藏答案，不点击选项或“查看答案”，不提交练习。样本中的“查看答案”会记录错题，因此采用直接读取的方式。
+## 安装和更新
 
-## 在线自动导出
+1. 在 Chrome / Edge 中安装并启用油猴（Tampermonkey）。
+2. 新建脚本，将 `谊安学题库导出.user.js` 的全部内容粘贴进去，保存。升级时替换原脚本全文，不要同时启用新旧两份脚本。
+3. 刷新网页，点击右下角“题库助手”入口展开面板。
+4. 选择“主操 / 班长 / 副操”，点击“导入题库”，选择 ZIP、CSV 或 JSON 文件。
 
-1. 在 Chrome / Edge 浏览器的油猴（Tampermonkey）中新建脚本。
-2. 将 `谊安学题库导出.user.js` 的全部内容粘贴进去，保存并启用。
-3. 刷新谊安学网页，正常登录，点击进入“练习”。
-4. 等待题目和答案加载完毕，CSV 会自动下载至浏览器下载目录，右下角显示导出状态。也可点击 CSV / JSON / TXT 按钮重新导出。
+脚本使用 `@match *://*/*` 和 `@match file:///*`，不固定域名、IP、端口或网址路径，换地址后无需修改脚本。普通网页均显示可折叠入口；`chrome://` 等浏览器限制页面无法注入。访问本地 HTML 时，需在扩展设置中开启“允许访问文件网址”。
 
-脚本匹配 `http://10.119.67.7/clientcn/*` 和对应 HTTPS 地址，仅在 `/exam/<id>/questions?flag=exercise` 页面自动导出；考试页面不会触发。站点地址变化时，修改脚本顶部的 `@match` 地址。
+**网址通用不等于所有平台都能自动答题。** 自动选择适配提供的谊安学桌面练习页结构，还需明确识别为“练习”；考试/测试页面及无法识别的页面不会自动选择。`file:` 保存网页只用于搜索、复制和导出，不执行自动选择。
 
-如果脚本未运行，请检查油猴是否启用、浏览器是否允许扩展运行用户脚本。如果提示已发起下载但没有文件，点击右下角导出按钮；浏览器若提示下载权限，允许本页面下载。
+## 导入题库与搜索答案
 
-## 从已下载网页导出
+- ZIP 内按“主操 / 班长 / 副操”目录自动归类；成功导入后全量替换已有题库。提供的 `题库.zip` 已核对为 28 个 CSV、5,520 条记录：主操 1,620、班长 2,340、副操 1,560。
+- 单个或多个 CSV / JSON 建议先选择岗位；文件缺少岗位信息时，使用当前选择的岗位。导入会更新相同岗位、课程和来源的数据，保留其他岗位及其他来源。
+- 所有文件先解析和验证，再保存。题干、选项或参考答案无效时，会提示文件及题目位置，原题库保留。
+- 油猴存储在同一浏览器中跨网址共享题库及岗位设置，刷新后无需重新导入。无油猴存储 API 时，回退为当前网站的本地存储，面板会明确提示；此模式不能跨网址共享。
 
-1. 解压原始网页压缩包。
-2. 双击本项目的 `离线导出题库.html`，保持它与 `question-bank-core.js` 放在同一目录。
-3. 选择解压得到的 `谊安学.html`，查看题目数和答案完整性，点击所需导出格式。
+搜索时先选择岗位，可再按课程筛选。输入题干、选项文字或关键词后点击“搜索”；多个关键词用空格分开，结果须同时包含所有关键词。也可选中网页题目文字后点击“用选中文字搜索”。切换岗位会保留当前搜索词并重新查询。
 
-本地工具只解析 HTML 文本，不运行原网站脚本、不连接原网站。不需要登录或安装 Node.js。输入的是解压后的 HTML 文件。
+结果显示完整题干、选项、正确答案及课程来源，支持“复制题目与答案”和分页。相同题目、选项及答案合并来源；答案冲突分别展示并标记。遇到冲突，选择对应课程核对。
 
-油猴脚本也支持原始保存网页；需要在浏览器扩展设置中开启“允许访问文件网址”。通常优先使用上面的离线工具，避免原网页脚本重新启动后清空已保存内容。
+## 两个功能开关
 
-## 导出内容和限制
+**自动选择答案：默认关闭，每次刷新后需手动开启。** 先导入题库、选择岗位，并进入已加载完成的兼容练习页，再开启。脚本按岗位、题型、题干和全部选项精确匹配，优先结合课程来源消歧；按选项文字映射当前字母，支持选项换序。无匹配、冲突未消除、图片题或选项无法唯一对应时，跳过并显示原因。搜索结果不会直接触发自动选择。
+
+脚本点击网页真实选项，网站会按正常逻辑保存练习记录。单选、判断可能点击后立即判分并锁定；关闭开关只能停止后续操作，不能撤回已生效的选择。多选只调整选中集合，显示“待确认”，由用户在网页中确认。不自动点击“查看答案”或交卷。切换岗位、题库或页面时停止旧任务，随后按新上下文处理尚未作答的题目。
+
+**允许复制文字：首次使用默认开启，后续保留设置。** 开启后解除已适配的文字选择、复制和右键限制；关闭后恢复网页原有 `body` 限制属性和相关样式。搜索结果的复制按钮独立可用。
+
+## 网页题目导出
+
+进入兼容练习页后，默认等待题目和参考答案加载完整，再自动下载 CSV；可在面板关闭自动导出，或点击 CSV / JSON / TXT 按钮手动导出。导出直接读取网页中的参考答案，包括隐藏答案，不用导入题库补全缺失答案。
 
 - CSV 使用 UTF-8 BOM，可用 Excel 打开；JSON 保留结构化选项和图片地址；TXT 便于阅读。
-- 参考答案与用户已选择的答案分开处理，导出的是网页提供的参考答案。缺失答案保留为空并提示，不推测答案。
-- 自动导出等待题目内容稳定，并核对答题卡数量；存在缺题或缺答案时不会自动下载，手动导出会标记不完整。没有答题卡数量时，只能核对当前 DOM 中的题目，不能保证包含网站未加载的题目。
-- 本版本针对提供的桌面练习页。分页或滚动后才加载的题目，需要先加载全部内容；未加载的内容无法从 DOM 读取。
-- 图片以链接导出，不会自动打包图片文件。保存网页中的相对图片地址按原始网页地址解析，离线时这些地址可能不可访问。
-- 提供的样本为“安全领导力-1”，有 120 题，单选、多选、判断各 40 题；全部参考答案存在，其中 112 题答案被隐藏。样本的 120 处解析文本均为空，导出时也为空。
-- 同一次页面运行中，相同练习内容只自动下载一次；重新刷新或手动点击导出仍可下载。
+- 缺题或缺答案时不自动下载；手动导出会标记不完整。没有答题卡总数时，只能核对当前页面内容。
+- 分页或滚动后才加载的题目，需要先加载或逐页导出。同一次页面运行中，相同练习内容只自动下载一次。
+- 图片以链接导出，不打包图片文件。保存网页的相对图片地址按原始网址解析，离线时可能无法访问。
 
-## 开发和验证
+从下载的网页导出，也可使用原有独立工具：
 
-`question-bank-core.js` 是 DOM 提取与文件导出核心；`practice-exporter.js` 负责练习页面识别、加载等待、状态面板和自动下载。发布用油猴脚本已构建，可直接安装。
+1. 解压网页压缩包。
+2. 双击 `离线导出题库.html`，保持它与 `question-bank-core.js` 在同一目录。
+3. 选择解压后的 HTML 文件，查看完整性提示，再点击导出格式。
 
-修改源文件后运行：
+离线工具只解析 HTML 文本，不运行原网站脚本、不连接原网站，不需要登录或 Node.js。
+
+## 开发与验证
+
+`question-bank-core.js` 负责网页提取和导出；`bank-store.js`、`answer-matcher.js` 负责本地题库和匹配搜索；`assistant-panel.js`、`copy-controller.js`、`answer-runner.js` 分别负责面板、复制开关和真实选项点击；`practice-exporter.js` 负责页面识别及功能协调。发布脚本已构建，安装时只需一个 `.user.js` 文件。
+
+修改源码后重新构建：
 
 ```powershell
 npm run build
 ```
 
-浏览器验证依赖 Playwright 和本机 Chrome，可执行：
+安装开发依赖并运行验证，需要本机 Chrome：
 
 ```powershell
 npm install
 npm test
 ```
 
-测试使用合成题目模拟隐藏答案、错误选项、延迟加载、页面切换、缺题、缺答案和下载，且不会连接谊安学服务器。若本地存在 `网页样本/考试答案/谊安学.html`，还会核对该样本的 120 道题。
+使用本机 Edge 时可先设置：
 
-原始压缩包、解压网页和实际题库文件已在 `.gitignore` 中排除，不会随源代码提交。
+```powershell
+$env:PLAYWRIGHT_CHANNEL = 'edge'
+npm test
+```
+
+验证使用本地模拟页面，不连接谊安学服务器；真实登录后的线上使用仍需在实际环境验收。本地存在题库 ZIP 或保存网页样本时，还会核对对应内容。原始 ZIP、解压网页及实际导出题库均由 `.gitignore` 排除，不提交到源码仓库。
 
 远程仓库：`ssh://git@192.168.10.31:2222/qishizhe/yianxue-shauti.git`。