miaoguo_system_server/.vscode/秒过知识库更新

秒过知识库更新维护手册

本目录用于每年 2 月、9 月教材改版后的秒过知识库维护。目标是：只需放入新版教材图片、整理两份源数据、依次运行 dry-run、apply、audit，即可完成更新并留下可追溯记录。

一、不可违反的规则

1. 语文 HanziUnit 禁止 DELETE，只能 UPDATE 旧行或 INSERT 新行。旧 ID 可能已被历史试题或用户数据引用。
2. 英语 Words 允许按目标 BookID 删除后重建，但必须先备份，并且所有写入都必须在事务中完成。
3. 每一本更新后，都要同步校准 MiaoguoBook.UnitNum、MiaoguoBook.WordNum。
4. 识字表的蓝色多音字也要写入 HanziUnit.Example，并计入 WordNum。
5. 书中重复出现的名称统一写成字面值 语文园地，不添加“一、二”等编号；先后次序由唯一且连续的 OrderID 区分。
6. 数据库连接复用 src/config/dev.js，脚本和报告不得复制、打印或另存数据库密码。
7. 未通过源数据校验、BookID 映射校验、汉字字典覆盖校验时，不得开始写库。

二、表和书籍映射

程序使用 MiaoguoBook.BookIDOld 查找旧系统数据表的书籍 ID。字段名是 BookIDOld，不是口头描述中常写的 BookOldID。

类别	MiaoguoBook.ID	数据表	关联字段	主要字段
语文写字表	1～12	HanziUnit	HanziBookID=BookIDOld	UnitType、Name、Example、OrderID
语文词语表	33～42	HanziUnit	HanziBookID=BookIDOld	UnitType、Name、Example、OrderID
语文识字表	43～52	HanziUnit	HanziBookID=BookIDOld	UnitType、Name、Example、OrderID
英语单词表	285～292、301～305	Words	BookID=BookIDOld	Word、LessonID、LessonName、Soundmark、Translate、Sort
英语常用表达法	293～300	Words	BookID=BookIDOld	Word、LessonID、LessonName、Translate、Sort

本次确认的 HanziUnit.UnitType：识字表为 1，词语表为 2，写字表为 5。

三、教材图片转录规则

语文

• 每个教材栏目生成一个 units 元素，name 按书中栏目名写，example 保存这一栏的完整数据。
• 识字表、写字表的 Example 是连续汉字，不加逗号；使用 Unicode 字符数统计 WordNum。
• 词语表的 Example 使用英文逗号分隔，按非空词条数统计 WordNum。
• 识字表要分别记录教材标注的普通识字数、蓝色多音字数；两者之和必须等于 wordNum。
• 多次出现的 语文园地 保持同名，依靠数组位置最终生成 OrderID=1..N。

英语

• 教材图 01～08 是单词表，09～14 是常用表达法；页码和星号不写入数据库。
• LessonID 使用 1～N，LessonName 使用 Unit 1～Unit N。
• 每个教材条目生成一条记录；短语、地名、拆行内容仍是一条记录。
• 音标由教材的 /.../ 统一保存为 [...]；教材未给音标时保存 NULL，不能臆造。
• 过去式、also Earth 等教材注释保留在 Translate。
• 英文句子中的省略符统一沿用现有库格式 ˈ，中文标点保留教材语义。
• Sort 在每个单元内从 1 连续递增。接口本身按 LessonID,Sort,ID 排序，因此不依赖自增 ID 碰巧保持顺序。
• WordRemark、Level、EnglishExplanation、ExampleSentence 没有教材来源时保存 NULL。

四、标准操作流程

以下命令均在仓库根目录执行：

cd /Users/chengjie/Documents/git/miaoguo_system_server

1. 将本批次教材图片放入统一来源目录，按学科、年级、上下册命名。
2. 复制上次的 source_chinese_*.json、source_english_*.json，替换为本批次数据，同时改脚本中的文件名和目标书籍映射。
3. 运行只读预检：

node .vscode/秒过知识库更新/update_knowledge_base_2026_fall.mjs --dry-run

1. 审查 dry-run 报告，重点确认：目标 MiaoguoBook.ID/BookIDOld、当前行数→目标行数、UnitNum/WordNum、语文新增数和 deletes=0、英语各单元条数。
2. 执行事务更新：

node .vscode/秒过知识库更新/update_knowledge_base_2026_fall.mjs --apply

程序会在获取数据库行锁后、第一条写入前，把目标 MiaoguoBook、HanziUnit、Words 的完整旧数据写入 backups/。之后才执行更新；任一写入或提交前逐字段核验失败，整个事务回滚。

1. 事务提交后，再独立运行一次只读审计：

node .vscode/秒过知识库更新/update_knowledge_base_2026_fall.mjs --audit

1. 人工复核报告，并至少抽查每套数据的首行、末行、语文园地、英语每单元首末词。

五、程序的语文 ID 保留策略

对于每本语文书，程序按以下优先级映射新版单元：

1. 同名旧行优先复用，重复名称按原排序逐个匹配；
2. 仍未匹配的新版单元，复用尚未占用的旧行并更新其内容；
3. 新版行数超过旧版时，差额使用 INSERT；
4. 如果新版行数少于旧版，程序立即报错，不写库，因为这会要求删除语文旧行。

所有复用的旧行保留原 ID 和原 IsLocked。新增行默认 IsLocked=1。所有目标行都重新写入连续的 OrderID=1..N。

六、检查项和判定标准

• JSON 可以解析，且数据集、书籍 ID 没有重复。
• 每套源数据由 Example/entries 重新计算出的数量等于声明的 wordNum。
• 识字表满足“普通识字数 + 蓝色多音字数 = WordNum”。
• 数据库目标 MiaoguoBook.BookIDOld 与源文件一致。
• 识字、写字涉及的每个汉字都能在 HanziWord.Name 找到；缺字时阻止写库。
• 语文更新后行数等于单元数，OrderID 从 1 连续到 N 且无重复，逐行 UnitType/Name/Example 与源文件完全一致。
• 英语更新后逐行 Word/LessonID/LessonName/Soundmark/Translate/Sort 与源文件完全一致，未提供字段仍为 NULL。
• 所有 MiaoguoBook.UnitNum/WordNum 与最终数据一致。
• 备份中的所有语文旧 HanziUnit.ID 在更新后仍然存在。

七、备份与异常恢复

• 每次 --apply 都会生成唯一时间戳备份，绝不能覆盖上一次备份。
• 备份是写入前的完整数据库快照，包含目标书籍元数据、语文行和英语行，可用于生成逆向 SQL。
• 不要直接手工执行整文件恢复。先在事务中按主键比对当前状态和备份，再决定恢复范围。
• 语文仍受“禁止 DELETE”约束：恢复旧行应按 ID 做 UPDATE；本次新增行如何处理必须根据线上引用情况单独确认，不能盲删。
• 英语可在事务内按目标 BookID 重建为备份内容，同时恢复对应 MiaoguoBook.UnitNum/WordNum。
• 数据库提交后若发现教材源数据本身有误，应修正源 JSON、重新 dry-run，再走一次新的备份和事务更新，不要绕开程序直接改散行。

八、MiaoguoLiteracy 词语依赖检查

词语表中的每个最终词语还依赖 MiaoguoLiteracy。维护时不能只更新 HanziUnit.Example，还必须检查线上接口实际会取到的 JSONString 是否具有可用的 CHN：

node .vscode/秒过知识库更新/audit_miaoguo_literacy_2026_fall.mjs

检查范围应覆盖新版词语表的全部最终词语，并标记相对旧版新出现的词语。检查逻辑与 GetMiaoguoLiteracyWords 保持一致：排除 SearchType=shici/eng，按 Word,SearchType DESC 选取每个词的首条记录。以下情况都视为缺失并在写入前列清单：

• 完全没有符合条件的记录；
• JSONString 为空或不是合法 JSON；
• JSONString 中没有 CHN；
• CHN.PinYin[0].pinyin/explain 不完整，现有接口无法使用。

缺失词语需要在 MiaoguoLiteracy 新增一条 SearchType=zici 的记录。可以选择语义和结构相近的已有词语作为模板，但必须按新词真实内容修改 Word、拼音、释义、组词、近反义词等字段，不能只替换顶层 Word。新增前先生成清单和拟写内容供人工复核；确认后再备份、事务插入并重新运行本检查，直到缺失数为 0。

本次补录程序的标准命令如下；后续批次复制脚本和源文件并修改年份：

# 只生成完整 JSONString 和写入计划
node .vscode/秒过知识库更新/update_miaoguo_literacy_2026_fall.mjs --dry-run

# 备份后事务插入，并在提交前后检查全部新版词语
node .vscode/秒过知识库更新/update_miaoguo_literacy_2026_fall.mjs --apply

# 独立复查新增行和全部新版词语
node .vscode/秒过知识库更新/update_miaoguo_literacy_2026_fall.mjs --audit

补录程序从 HanziWord 复用每个汉字已有的楷体图和笔顺动画。每条新增记录至少要有 ENG、CHN.HanZi、非空的 CHN.PinYin[0].pinyin/explain、与字数一致的 KaitiArr/BiShunArr2、Synonym/Antonym、TianKong/PinyinTone。

九、常见坑

• 只看 MiaoguoBook.WordNum 不足以证明数据正确，必须从实际 Example/entries 重新计数。
• 旧数据大量 OrderID=0，不能继续依赖自增 ID 排序；本次起统一写连续 OrderID。
• 语文园地 同名是正确数据，不要为“唯一”而擅自编号。
• 英语复合词的音标可能只标在其中一部分，必须忠实保存教材给出的内容，不补写推测音标。
• 图片 OCR 只能辅助，最终必须逐页核对专名、音标、过去式和标点。
• MiaoguoLiteracy 同一个词可能同时有 zici 和 list 等记录；低优先级 list 没有 CHN 不一定影响词语题，必须按线上查询排序判断真正选中的记录。
• 任务目录可能包含真实数据库备份，提交或外发前先确认仓库的数据安全策略。

十、本次文件说明

• source_chinese_2026_fall.json：2026 秋季语文 8 套结构化源数据。
• source_english_2026_fall.json：2026 秋季英语单词表和常用表达法源数据。
• update_knowledge_base_2026_fall.mjs：校验、计划、备份、事务更新、审计程序。
• dry_run_report_2026_fall.json：写库前更新计划和 ID 映射。
• apply_report_2026_fall.json：实际事务、备份位置及提交前后审计。
• audit_report_2026_fall.json：提交后的独立审计结果。
• audit_miaoguo_literacy_2026_fall.mjs：词语依赖的只读检查程序。
• MiaoguoLiteracy缺失清单_2026年秋季.md、miaoguo_literacy_audit_2026_fall.json：本批次补录前缺少可用 CHN 的历史快照。
• MiaoguoLiteracy依赖检查_2026年秋季.md、miaoguo_literacy_dependency_audit_current_2026_fall.json：运行只读检查时更新的当前状态报告。
• source_miaoguo_literacy_2026_fall.json：缺失词语的拼音、释义、英文释义和近反义词源数据。
• update_miaoguo_literacy_2026_fall.mjs：构建完整 CHN、备份、事务补录和全词表复查程序。
• miaoguo_literacy_dry_run_2026_fall.json：20 条补录数据的写入前预览。
• miaoguo_literacy_apply_report_2026_fall.json：补录 ID、完整 JSONString、事务前后审计和备份位置。
• miaoguo_literacy_post_apply_audit_2026_fall.json：补录后的独立审计报告。
• MiaoguoLiteracy补录结果_2026年秋季.md：20 条补录词语的人工复核表。
• 2026年秋季更新结果.md：便于人工复核的最终清单。
• backups/：每次执行前的数据库完整备份。