# 秒过知识库更新维护手册

本目录用于每年 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`。

## 四、标准操作流程

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

```bash
cd /Users/chengjie/Documents/git/miaoguo_system_server
```

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

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

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

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

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

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

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

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

## 五、程序的语文 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`：

```bash
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。

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

```bash
# 只生成完整 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/`：每次执行前的数据库完整备份。