# 理论题库旧格式批量导入预览:前后端联调文档 ## 1. 适用范围 本文对应“题库管理 → 理论题库 → 批量导入”的三步流程: 1. 上传文件; 2. 预览确认并处理异常; 3. 确认导入并展示结果。 接口读取原有五列层级题库模板,例如 `污水三级理论题库.xlsx`。正式导入仍由原接口和 原拆题方法完成;新增确认接口只在内存中应用预览页决定,再把修正版文件交给原导入服务。 落库已改为增量模式:完全匹配的题目保留原ID更新,不存在的题目新增,未出现在文件中的历史 题目和目录不删除。 支持 `.xlsx`、`.xls`,单文件不超过 10MB。文件名必须包含以下一种路由信息: - `污水`或`污泥` + `一级`~`五级`; - `技能竞赛`。 所有接口均要求当前登录用户为管理员,认证方式与项目其他管理接口一致。 ## 2. 接口总览 | 步骤 | 方法 | 路径 | 说明 | |---|---|---|---| | 预览 | POST | `/theoretical/library/import/preview` | 只读解析、重复校验、异常分类,不写数据库 | | 确认 | POST | `/theoretical/library/import/confirm` | 应用处理决定后调用原拆题导入 | | 兼容导入 | POST | `/theoretical/library/import` | 原接口,保留给无异常文件或旧前端使用 | ## 3. 上传预览 ### 3.1 请求 `POST /theoretical/library/import/preview` `Content-Type: multipart/form-data` | 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | `file` | File | 是 | 原始 Excel 文件 | ### 3.2 成功响应示例 项目统一响应外壳中的业务数据位于 `data`: ```json { "code": 200, "msg": "操作成功", "data": { "fileName": "污水三级理论题库.xlsx", "scope": "污水三级", "totalCount": 120, "normalCount": 116, "abnormalCount": 4, "insertCount": 110, "updateCount": 10, "questionTypeCounts": { "判断题": 40, "单选题": 50, "多选题": 30 }, "abnormalQuestions": [ { "sourceRow": 18, "sequence": 9, "type": "单选题", "rawProblem": "以下(B)方法常用于处理含铅(Pb)废水。", "problem": "以下(B)方法常用于处理含铅(Pb)废水。", "answer": "P", "importAction": "INSERT", "firstLevelName": "基本要求", "secondLevelName": "职业道德", "thirdLevelName": "基本知识", "fourthLevelName": "知识点一", "options": [ {"label": "A", "content": "吸附"}, {"label": "B", "content": "沉淀"} ], "answerCandidates": [ {"index": 0, "rawText": "(B)", "content": "B", "startIndex": 2, "endIndex": 5}, {"index": 1, "rawText": "(Pb)", "content": "Pb", "startIndex": 14, "endIndex": 18} ], "issues": [ { "code": "ANSWER_BRACKET_AMBIGUOUS", "message": "题干检测到 2 组英文字母括号,请点选一组作为标准答案位" } ], "abnormal": true } ], "normalQuestions": [] } } ``` ### 3.3 前端展示映射 | 原型区域 | 响应字段 | |---|---| | 题目总数 | `totalCount` | | 无需处理 | `normalCount` | | 待处理初始值 | `abnormalCount` | | 预计新增 | `insertCount` | | 预计更新 | `updateCount` | | 左侧题型树 | `questionTypeCounts`,再按题目 `type` 分组 | | 异常题目 Tab | `abnormalQuestions` | | 无异常 Tab | `normalQuestions` | | 题干虚线括号 | `answerCandidates` 的字符坐标和 `index` | `answer` 是旧拆题算法产生的默认结果。存在 `ANSWER_BRACKET_AMBIGUOUS` 时不能直接采用, 必须以管理员选择的 `answerCandidates.index` 为准。 每题的 `importAction` 为 `INSERT` 或 `UPDATE`。`UPDATE` 同时返回 `duplicateQuestionId`,表示确认导入后保留该题ID并更新答案、选项、编号等旧Excel字段;这类 数据库命中是正常增量动作,不进入异常 Tab。 ## 4. 异常代码与处理组件 | code | 含义 | 前端处理 | |---|---|---| | `ANSWER_BRACKET_AMBIGUOUS` | 题干至少两组纯英文字母括号 | 点选答案括号,提交 `answerCandidateIndex` | | `DUPLICATE_IN_FILE` | 与本文件前一题重复 | “跳过/仍然导入”,提交 `skip` | | `OPTION_MISSING` | 题目下一行没有选项 | 编辑完整选项后提交 `options` | | `OPTION_PARSE_ERROR` | 未识别出(A)~(E)标记 | 编辑完整选项后提交 `options` | | `OPTION_DUPLICATE_LABEL` | 选项字母重复 | 编辑完整选项后提交 `options` | | `OPTION_LABEL_DISCONTINUOUS` | 选项字母跳号 | 编辑完整选项后提交 `options` | | `ANSWER_OPTION_MISSING` | 答案字母不存在对应选项 | 编辑完整选项后提交 `options` | 同一题可能同时包含多个 `issues`,必须全部处理。前端可以维护本地 `resolved` 状态: - 初始待处理数 = `abnormalCount`; - 某题所需字段全部填写后标记已处理; - 待处理数大于 0 时禁用“确认导入”; - 已处理题仍保留在异常 Tab,可在确认前继续修改。 ## 5. 确认导入 ### 5.1 请求 `POST /theoretical/library/import/confirm` `Content-Type: multipart/form-data` | Part | Content-Type | 必填 | 说明 | |---|---|---|---| | `file` | Excel 对应类型 | 是 | 必须是本次预览使用的原文件 | | `decisions` | `application/json` | 有异常时是 | 异常题处理决定数组;无异常可传 `[]` 或不传 | `decisions` 示例: ```json [ { "sourceRow": 18, "answerCandidateIndex": 0 }, { "sourceRow": 36, "skip": true }, { "sourceRow": 52, "skip": false }, { "sourceRow": 68, "options": [ {"label": "A", "content": "低 DO"}, {"label": "B", "content": "高 SRT"}, {"label": "C", "content": "高 F/M"}, {"label": "D", "content": "营养失衡"} ] } ] ``` 字段规则: | 字段 | 必填条件 | 说明 | |---|---|---| | `sourceRow` | 始终必填 | 直接使用预览返回值,不要用列表序号代替 | | `skip` | 文件内重复题必填 | `true` 跳过,`false` 仍然导入;数据库命中无需提交 | | `answerCandidateIndex` | 答案括号歧义且未跳过 | 使用候选项的 `index` | | `options` | 选项异常且未跳过 | 2~5 项,从 A 开始连续、不可重复、内容非空,并覆盖答案字母 | 同一题有多种异常时将所需字段合并在同一个对象中。后端会重新预览原文件并校验所有异常; 任何一题未处理都会整体拒绝,不会删除或写入数据。 ### 5.2 浏览器 FormData 示例 ```javascript const form = new FormData(); form.append('file', selectedFile); form.append( 'decisions', new Blob([JSON.stringify(decisions)], { type: 'application/json' }) ); await axios.post('/theoretical/library/import/confirm', form); ``` 不要手工设置 `Content-Type` 的 boundary,让浏览器或 Axios 自动生成。 ### 5.3 成功响应 确认接口原样返回旧导入服务的统一 `Result`,现有实现以 `code` 和 `msg` 表示结果: ```json { "code": 200, "msg": "导入成功" } ``` 确认后按文件名对应范围执行增量导入,不再删除该范围旧数据。 ### 5.4 增量匹配与更新范围 一道题只有以下字段全部精确一致时才判定为 `UPDATE`: - 题库范围 `scope`; - 原四级层级路径; - 题型; - 拆题后的完整题干。 匹配不自动去空格、不忽略大小写,题干多一个空格也会作为新题新增。命中更新时保留原题ID, 只覆盖旧Excel携带的编号、答案和选项等字段;后台维护的状态、难度、分值、解析、关键词及创建人 保持原值。文件中没有出现的历史题目和目录不删除。 ## 6. 推荐前端调用时序 1. 前端先校验扩展名和 10MB 大小; 2. 调用 `/import/preview`,保存原始 `File` 对象; 3. 渲染双 Tab,按 `issues.code` 收集处理决定; 4. 待处理数归零后,将同一个 `File` 和 `decisions` 提交 `/import/confirm`; 5. 成功后分别展示 `insertCount` 和 `updateCount`;文件内选择跳过的题目从对应数量中扣除; 6. 关闭弹窗并刷新题库树、统计和列表。 如果预览后用户重新选择文件,必须清空旧预览及全部 `decisions`,禁止把旧行号应用到新文件。 ## 7. 常见错误 | 场景 | 后端提示 | |---|---| | 空文件 | 请选择需要导入的 Excel 文件 | | 超过 10MB | 文件大小不能超过 10MB | | 格式错误 | 仅支持 .xlsx 或 .xls 文件 | | 文件名无法路由 | 文件名需包含污水/污泥(一级~五级)或技能竞赛 | | 异常未处理 | 第 N 行异常尚未处理 | | 文件内重复题未选择动作 | 第 N 行重复题需选择跳过或仍然导入 | | 未选择答案括号 | 第 N 行需选择有效的答案括号 | | 修正选项不合法 | 第 N 行修正后的选项字母必须从 A 开始连续且不可重复 | ## 8. 数据库变更 本功能不新增表、不新增字段,也不需要 MySQL 建表或变更语句。重复检查直接读取现有 `theoretical_library` 表;正式写入继续由原导入服务完成。 ## 9. 样例文件验收结果 使用本次提供的 `污水三级理论题库.xlsx` 进行本地真实文件解析:共拆出 1200 题, 其中判断题 300、单选题 600、多选题 300;在不连接现有题库重复数据的情况下, 1181 题无异常、19 题需处理。部署环境命中的相同数据库题目会计入 `updateCount`,不会增加 异常数;文件内重复、答案括号歧义和选项异常仍会增加待处理数量。