英语词书导入方案（以雅思为例）

2026年9月首次执行：雅思词汇 3346 词导入秒过知识库。本文档记录完整过程，供后续导入其他英语词书（考研、托福、GRE 等）复用。原始数据和导入脚本见本目录 ielts/。

一、涉及的表和关键约束

表	库	作用	本次新增
`WordBooks`	kylx365_db	旧知识库词书表（浏览/背单词入口）	6 条（ID 212-217）
`MiaoguoBook`	秒过库	新知识库词书表（检测入口）	6 条（ID 306-311，自增）
`Words`	kylx365_db	单词明细，`BookID`=WordBooks.ID	3346 条

关键约束：

MiaoguoBook.BookIDOld 指向 WordBooks.ID，两表各加一套记录是正常设计（旧新知识库并存）。
Words.BookID 关联的是 WordBooks.ID（BookIDOld），不是 MiaoguoBook.ID。
WordBooks 的 ID 必须人工分配（取当前 MAX(ID)+1 起），因为服务端代码里有大量按 BookID 范围硬编码的分支（见第四节）。
MiaoguoBook.Sort 决定词库列表排序（雅思=14，排在六级 13 之后）。
写库必须走事务，导入前先 --dry-run 预检。

二、数据准备

2.1 数据源与合并去重

本次两个渠道（放在 ielts/ 下）：

ielts-xdf-random.json：新东方 3050 词，含音标/词性/中文释义。
ielts-4000.json：526 词（学术词汇表），仅英文释义。

合并规则（脚本内置）：

以小写规范化后的单词为 key 去重，xdf 优先；
4000 独有的 296 词：优先从现有四六级/高考词库（BookID 169-183）取中文释义+音标；取不到的用英文释义顶替；
音标统一为 [xxx] 格式（参照四级 [əˈbændən]）；
释义格式 词性+中文（参照 vt.丢弃；放弃）；教材没有音标时存 NULL，不臆造。

2.2 分册规则

每课固定 10 词（WORDS_PER_LESSON=10），LessonID 从 1 递增，LessonName 由服务端按 Lesson N 生成；
3500 左右的词量分 6 册（第一部分~第六部分），均分后前几册多 1 词；
Words.Sort 本批次统一为 0（接口按 LessonID,Sort,ID 排序，插入顺序即最终顺序）。

三、书字段命名规则（参照四六级）

WordBooks（旧表）

Category   = '雅思英语'          # 词书分类名（唯一，用于查重）
Name       = '第一部分' ~ '第六部分'
Name2      = '词汇558'           # 该册词数
Grade      = '高中,大学'         # 客户端按用户年级过滤，多学段用逗号分隔
Category2  = '大学英语'          # 一级分类 = MiaoguoBook.LibraryName1
Category3  = '雅思考试单词'      # 二级分类 = MiaoguoBook.LibraryName2
WordType   = '单词'
Sort       = 14                  # 词书排序
Package    = Name
BookImageName = 'ieltsWords'     # 图片名（见 3.3）
Image      = '../images/examine_subject_a00N.png'  # N=册序号，沿用现有占位图

MiaoguoBook（新表）

BookIDOld     = WordBooks.ID
Category      = 'English'
LibraryName1  = '大学英语'        # 词库列表一级
LibraryName2  = '雅思考试单词'    # 词库列表二级
Grade         = '高中,大学'
Category2     = '课外拓展'
BookName      = '第一部分' ~ '第六部分'
UnitNum       = 每册 Lesson 数
WordNum       = 每册词数
BookImageName = 'ieltsWords'
KnowledgeImageName = ''
TestFunction  = JSON（read: 念单词说含义 / write: 听写单词，照抄六级的即可）

封面图片（COS）

命名规则参照四六级 picZs_en_cet4Words_cov，雅思为 picZs_en_ieltsWords_cov，需要三张后缀 _a/_b/_c 的 PNG 上传到 COS 图片目录（AI 生成的图在 ielts/generated/）。服务端列表接口会拼成 picZs_en_<BookImageName>_cov。

四、服务端代码适配（易漏步骤！）

src/api/miaoguo/miaoguoController.js 的 GetTestEnglishWords 中，BookID 分支全部是硬编码范围。新词书如果不加范围，检测页（GetMiaoguoTestExamine → 内部再调 GetTestEnglishWords）会返回空列表且不报错。

2026年9月为雅思（WordBooks ID 212-217）所做的修改：

GET6 分支范围扩展（约 4796 行）：

} else if ((Number(param.BookID) >= 169 && Number(param.BookID) <= 183)
        || (Number(param.BookID) >= 212 && Number(param.BookID) <= 217)) {
    ...
    else if (Number(param.BookID) >= 212 && Number(param.BookID) <= 217)
        param.Type = "GET6";

让雅思与六级走完全相同的渲染逻辑（发音 + 基本中文释义 + 高亮）。

JSONString 空值兜底（同函数循环开头）：GET6 分支依赖 MiaoguoLiteracy.JSONString，雅思有约 50 个词（多为英式 -ise 拼写、复合词，如 epitomise、minimise）在 MiaoguoLiteracy 中没有词典数据，JSON.parse(null) 会直接崩溃。已加兜底：无 JSONString 时用百度 TTS + Words 表的音标/释义构建内容。

下次导入新书时需要：

把新的 BookID 范围加入该分支（或借机重构为查表配置）；
评估新书词汇在 MiaoguoLiteracy 的覆盖率，确认兜底逻辑覆盖无词典词。

其余接口无需改动：GetMiaoguoTestLibrary、GetMiaoguoTestUnit、GetMiaoguoTestExamine 的 English 分支对 BookID 无范围限制。

五、导入操作步骤

cd /Users/chengjie/Documents/git/miaoguo_system_server

# 1. 预检（只读，校验 ID 未被占用、无重复 Category、显示分册统计）
node "秒过知识库更新/04-英语词书导入/ielts/import_ielts.js" --dry-run

# 2. 确认输出后正式导入（事务：WordBooks 6 条 + MiaoguoBook 6 条 + Words 3346 条）
node "秒过知识库更新/04-英语词书导入/ielts/import_ielts.js" --import

脚本内置防呆：START_BOOK_ID（212）被占用、或 Category 已存在时中止。

导入后验证

# 1. 词库列表应出现新分类，Grade 正确
curl -s "http://localhost:3010/api/GetMiaoguoTestLibrary" | python3 -m json.tool | grep -A3 雅思

# 2. 单元列表（应返回 Lesson 1..N）
curl -s "http://localhost:3010/api/GetMiaoguoTestUnit?BookID=<MiaoguoBook.ID>" | head -c 500

# 3. 检测列表 read/write（各应返回 10 词，格式同六级）
curl -s "http://localhost:3010/api/GetMiaoguoTestExamine?UserID=1&BookID=<MiaoguoBook.ID>&UnitName=Lesson%201&UnitID=1&TestType=read"
curl -s "http://localhost:3010/api/GetMiaoguoTestExamine?UserID=1&BookID=<MiaoguoBook.ID>&UnitName=Lesson%201&UnitID=1&TestType=write"

重要：GetMiaoguoTestExamine 有 globalCache，若导入前调用过会缓存空结果。改代码或导数据后必须重启服务（npm run dev，非 nodemon 不会自动重载）。

六、本次结果记录（2026-09-15）

WordBooks：ID 212-217，每册 557~558 词，各 56 Lesson。
MiaoguoBook：ID 306-311（BookIDOld=212-217），Sort=14，Grade 先设"大学"后按需求改为"高中,大学"。
Words：3346 条（xdf 3050 + 4000 独有 296，其中 171 词从四六级词库补了中文释义，125 词用英文释义）。
服务端代码：GetTestEnglishWords 增加 212-217 → GET6 分支 + JSONString 兜底（见第四节）。
踩坑记录：
1. 导入完成后检测页为空 → 原因是硬编码 BookID 范围未包含新书（第四节）；
2. 词库列表看不到新书 → Grade 会被客户端按用户年级过滤，多学段可用逗号分隔；
3. 接口返回旧数据 → globalCache 缓存，需重启服务。

七、下次导入新书 Checklist

整理词源数据为 JSON（word/phonetic/pos/zh），放本目录新建子文件夹
复制 import_ielts.js 修改：START_BOOK_ID、SORT、Category、Category2/3、Grade、BOOK_IMAGE_NAME、分册数
生成封面图三张（picZs_en_<name>_cov_a/b/c.png）上传 COS
--dry-run 预检 → 人工确认分册统计 → --import
miaoguoController.js 的 GetTestEnglishWords 增加新 BookID 范围分支
检查新书词汇在 MiaoguoLiteracy 的覆盖率（兜底逻辑已就位，但需确认）
重启服务，按第五节验证三个接口
小程序端用对应学段账号实际走一遍词库列表 → 单元 → 检测流程

英语词书导入方案-雅思.md 8.1 KB Histórico Raw