feat: add Huayi question bank assistant v1.1.0

README.md

@@ -0,0 +1,108 @@
+# 华谊题库助手
+
+用于华谊学习平台练习页面的油猴脚本：按题库采集题目和平台提供的标准答案，恢复题目选择复制，按实际名称导出 CSV，一次导入多个题库，输入文字或划选题干查答案。当前版本 **1.1.0**。
+
+安装文件：[`dist/huayi-question-bank.user.js`](dist/huayi-question-bank.user.js)。这是构建后的完整脚本，无须安装 Node.js 或运行服务器。
+
+## 安装与开始使用
+
+1. 在浏览器中安装并启用 Tampermonkey（油猴）。
+2. 打开油猴管理面板，选择“新建脚本”，将安装文件的全部内容粘贴进去并保存。
+3. 打开或刷新 `https://www.shhuayi-elearning.cn/` 下的练习页面。安装后应重新进入练习，以便观察首次加载的题目响应。
+4. 右下角出现“题库助手”。默认开始采集正常加载的练习题；已加载的批量题目会一起记录。若答案需要作答后才返回，则在正常练习后补齐。
+5. 在“文字搜索”中输入或粘贴至少两个字符，按回车或点“搜索”。也可以在页面划选题干后松开鼠标自动查询。
+6. 在“题库 / 导出”中检查实际题库名、范围内题数及文件名预览，再导出 CSV 或备份 JSON。默认只导出当前题库，全部题库需要手动选择。
+
+浏览器需允许油猴在该网站运行用户脚本。若没有出现面板，先确认扩展已启用、该站点有运行权限，再刷新页面。
+
+## 本次方案：按题库分别统计、搜索和导出
+
+旧版会累积的原因是：默认选择“全部题库”，主统计也是所有本地记录的总数，导出文件统一叫“华谊题库”。保存多个题库本身是正常行为，但当前库的展示与导出范围应该明确区分。
+
+1. 识别当前选中的培训大纲条目、练习标题和任务 ID；接口提供的题库 ID 用于建立对应。切换期间旧题目与晚到响应保留原来源，不能套上新库名称。
+2. 面板顶部始终显示当前实际题库名和本库题数。导出页默认“当前题库”；切换左侧题库后自动跟随，统计、CSV / JSON 内容和文件名预览一起更新。
+3. 需要合并备份时，手动选择“全部题库”。题库总数与全部题数在“已保存题库”单独显示，各库名称和题数分别列出。
+4. 文件名使用实际题库名称，例如 `华谊集团化工总控工（高级）-单选题库1_500题_20261029.csv`。Windows 不允许的文件名字符会替换成下划线；全部备份明确命名“全部题库”。
+5. 对旧数据，只在正常响应重新确认了相同题库 ID 的准确名称时修正该 ID 的历史名称；不按题型或相同题干猜测其他题库的归属。
+
+## 文字搜索
+
+- 输入或粘贴完整题干、题干片段、选项内容或标准答案关键词，支持按钮、回车和输入后自动查询，也可点“清空”。
+- “搜索题库”可选当前库、任意已保存库或全部库；默认当前库。搜索范围与导出范围独立，跨库查答案不会让导出自动变成全部。
+- “搜索内容”可选全部文字、仅题干、仅选项、仅标准答案；多个关键词可用空格分隔，按同时包含处理。
+- 结果标注命中题干、选项或答案，显示来源题库。只把已确认答案用于答案字段搜索，冲突和待补记录仍可通过题干找到。
+- 每次最多展示 50 条结果，可细化关键词继续查找。
+
+## 一次导入多个题库
+
+点击“导入多个题库”，在文件选择器中用 Ctrl / Shift 同时选择多个 CSV 和 JSON。两种格式可以混选；文件中已有的题库名称、ID 和答案分别保留。单个合并备份文件也可包含多个题库。
+
+没有来源题库名称的文件使用文件名（不含扩展名）作为名称。例如 `判断题库2.csv` 中没有来源列，导入后显示“判断题库2”。相同题目重复导入会合并，不同题库分别管理。若任一文件格式错误，本次整批不导入，并显示具体出错文件。
+
+导入成功后可在“已保存题库”查看各库名称和题数，再在搜索 / 导出下拉框选择相应题库。导入不会改变页面当前正在练习的题库，也不会自动将导出范围切为全部。
+
+## 隐藏、收起与恢复
+
+| 操作 | 效果 | 恢复方式 |
+| --- | --- | --- |
+| 右上角“收起” | 只显示面板标题栏 | 点击“展开” |
+| 右上角“隐藏” | 面板隐藏，默认保留圆形“题库”按钮 | 点击悬浮按钮 |
+| 设置中取消“隐藏时保留悬浮按钮”，再隐藏 | 面板和悬浮按钮均隐藏 | **Alt + Shift + Q** 或油猴菜单 |
+| 油猴菜单“完全隐藏题库助手” | 直接完全隐藏 | **Alt + Shift + Q** 或菜单“显示题库助手” |
+
+显示状态、悬浮按钮偏好和复制开关会保留，刷新后继续生效。隐藏时划选题干仍会更新查询，但不会重新弹出面板。隐藏与暂停采集是独立操作；需要暂停时，使用“题库 / 导出”中的“暂停采集”。
+
+## 正确答案如何防止错位
+
+- 保存标准答案的文字内容、正确选项 ID，以及同一条题目的完整选项。原始 A/B/C 字母仅供参考。
+- 查到答案后，核验当前题干、题型和完整选项集合，再根据当前顺序显示字母。
+- 例如采集时正确答案为 B“提高温度”，当前页面该内容移至 C，面板显示“提高温度；当前页面对应：C”。
+- 多选题保存正确选项的完整集合；判断题保存“正确 / 错误”。
+- 未取得标准答案时显示“待补”。学生选择、答题卡上的对错和题号不会被当作标准答案。
+- 重复选项无法唯一对应、选项内容发生变化、同一题出现不同答案时，显示未确认或冲突，冲突内容保留在备份中。
+
+## CSV 与 JSON
+
+CSV 使用 UTF-8 BOM，兼容 Excel 查看，支持中文、逗号、双引号及单元格换行。列包括：来源题库、题库 ID、题目 ID、题型、题干、各选项、正确答案内容、采集时答案字母、解析、答案状态、答案来源、采集时间和完整记录 JSON。
+
+**助手导出的 CSV 含“完整记录JSON”列，回导时以该列为准。** 如果要在 Excel 中手工修改可读列并回导，请删除“完整记录JSON”整列，再导入；修改该列之外的展示文字不会改变完整记录。长数字 ID 和以公式字符开头的内容在可读列使用文本保护，原文保存在 JSON 中。
+
+也可导入自己的标准 CSV。最小示例：
+
+```csv
+来源题库,题型,题干,选项A,选项B,正确答案内容,答案状态
+示例题库,单选题,示例题干,选项一,选项二,选项二,已确认
+示例题库,判断题,示例判断题,正确,错误,错误,已确认
+```
+
+“正确答案内容”填写完整答案文字。多选使用 JSON 字符串数组或在同一单元格中逐行填写完整选项，不能仅填写 A/B 字母。“我的答案”列不作为标准答案读取。建议直接以助手导出的表格作为模板。
+
+JSON 备份包含 `schemaVersion: 1` 和 `records` 数组，保留完整选项标识、来源、答案和冲突。两种格式均按题目合并，导入不会清空现有题库。每个文件限制 20 MB，每批文件合计限制 50 MB、50000 条记录。
+
+## 采集范围与当前验证边界
+
+脚本在当前账号正常练习时，观察已收到的题目 / 答案响应，并补充当前页面 DOM。不主动提交答案。接口没有提供标准答案时，保留待补状态；仅安装脚本不会凭空补出答案。
+
+目前适配了保存页面中的真实题目结构，以及业务脚本中可确认的练习接口：`/upm/start`、`/upm/wrong/start`、`/pra/{id}/questions` 和对应单题作答结果。接口适配限制在本站及学习平台域名。脚本不发送题库到外部服务器，来源 URL 不保存查询参数。
+
+本地分析时使用的原保存 HTML 显示判断题库共 500 题，实际只含第 62 题的题干和选项，没有该题标准答案。原始网页及其资源文件不纳入仓库；仓库中的浏览器测试使用脱敏的最小题目结构夹具。离线页面不能单独还原 500 道题或全部答案，在线正常练习能否一次返回全部题目和全部标准答案，仍需要在实际登录页面确认。
+
+题库保存在油猴脚本存储中，关闭面板、刷新或暂停采集不会清空。更换浏览器、卸载脚本或清理扩展数据前，请先导出 JSON 备份。
+
+## 源码与验证
+
+无需第三方前端依赖，源码分为：
+
+- `src/core.js`：答案规范化、去重与冲突、检索、字母映射、CSV。
+- `src/adapter.js`：本站响应观察、题目 DOM 读取、复制恢复。
+- `src/app.js`：面板、隐藏恢复、存储、导入导出。
+
+```powershell
+npm run build
+npm test
+npm run check
+```
+
+真实浏览器测试使用 `npm run test:browser`，需要现有 Playwright 和 Chromium；可通过 `QB_PLAYWRIGHT_MODULE`、`QB_CHROMIUM_EXECUTABLE` 指定环境路径。测试固定读取 `tests/fixtures/question.html`，使用本地模拟接口，不需要原始保存网页或平台账号。构建、语法检查和核心单元测试只需 Node.js，无第三方依赖。
+
+修改源码后执行 `npm run build`，再把新的 `dist/huayi-question-bank.user.js` 更新到油猴。