Files
word-market/importer/docs/DATA-MODEL.md
T
voidandClaude Sonnet 4.6 131c2b6353 docs(importer): 补充导出流程、数据模型与 ZPK 内容分析
- README:三步流程、接口与下载地址、破解参数、日常命令与性能说明
- DATA-MODEL:词书/词条及关联数据的实体关系
- zpk-decrypted-content-analysis:ZPK 解密后的字段结构分析

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-08 21:16:04 +08:00

1364 lines
65 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Lexis 词库数据实体关系模型
> 分析范围:`output/` 下除加密源文件外的全部数据
> 排除目录:`wordbooks/original/**`(1,024 个 SQLCipher `.db`)、`zpk/original/**`(143,200 个 `.zpk`)
> 分析日期:2026-11-04
> 目标:还原文件之间的真实关联,按关系数据库设计规范(1NF/2NF/3NF)重整实体、字段与主外键,形成可直接落库的模型。
---
## 0. 强制约定
1. **所有主键、外键统一使用 `bigint`**,包括代理主键、自增主键、业务 ID、关联 ID。
2. **外键列一律命名为 `<实体>_id`,禁止使用 `*_code` 作为外键**。
- `exam_code`、`book_code` 只作为业务唯一键/展示属性,可以保留 `UNIQUE`,但不得被其他表引用。
- 其他表引用考试、词书时,必须存 `exam_id`、`book_id`。
3. 外部系统提供的、可能超出 `bigint` 范围或非数字的标识(如句子 `sid`/`eid`),一律:
- 增加 `bigint` 代理主键;
- 原始值放入 `source_*` 字符串列并加 `UNIQUE`。
4. 非 ID 的数值(序号、位置、层级、计数、标志位)不强制 `bigint`,按范围使用 `smallint` / `integer`。
---
## 1. 数据源清单
### 1.1 文件与规模
| 数据源 | 文件数 | 记录数 | 格式 / 编码 | 作用 |
|---|---:|---:|---|---|
| `book-catalog.json` | 1 | 1,025 | JSON / UTF-8(中文已损坏,见 §7) | 词书商店目录 |
| `wordbooks/decrypted/*.csv` | 1,024 | 1,228,421 | CSV / UTF-8-BOM | 每本词书的词条清单与学习顺序 |
| `zpk/decrypted/*.json` | 143,200 | 143,200(38,116 个词条) | JSON / UTF-8 | 词条完整内容(释义、例句、短语、易混词等) |
| `wordroot-export/*.csv` | 14 | — | CSV / UTF-8-BOM | 词根词缀、单词卡片、词族、近反义词 |
| `synonym-derivative-export/*.csv` | 6 | — | CSV / UTF-8-BOM | 与 `wordroot-export` 重复的导出子集 |
### 1.2 `wordroot-export` 各表实际行数
> 注意:`README.txt` 与 `wordroot-schema.md` 中的行数(1,863 / 212 / 154 / 12,001)比实际 CSV 少 2 行,以实际数据为准。
| 文件 | 行数 | 含义 |
|---|---:|---|
| `root.csv` | 1,865 | 词根字典 |
| `prefix.csv` | 214 | 前缀字典 |
| `suffix.csv` | 156 | 后缀字典 |
| `card_info.csv` | 12,003 | 单词卡片主表 |
| `word_family.csv` | 22,717 | 词族词条主表 |
| `word_family_variant.csv` | 288 | 词族变体 |
| `word_family_mini_group.csv` | 37,984 | 词族小组(成员 ID 列表) |
| `word_group.csv` | 12,265 | 卡片 → 分组关联 |
| `word_family_exam.csv` | 13 | 考试编码字典 |
| `synonym_words.csv` | 6,279 | 近义词词头 |
| `synonym_data.csv` | 8,383 | 近义词义项 + 分考试近反义关系 |
| `synonyms-joined.csv` | 8,383 | `synonym_data` 的反规范化视图 |
### 1.3 重复文件结论
- `synonym-derivative-export/` 中的 `synonym_data.csv`、`synonym_words.csv`、`synonyms-joined.csv`、`derivative-mini-groups.csv`、`derivative-family.csv` 与 `wordroot-export/` 中对应文件 **字节级完全相同**。
- `wordroot-export/word_family.csv` 与 `synonym-derivative-export/derivative-family.csv` 数据相同,仅少一列 `hightlight`。
- **建模时只保留一份 `wordroot-export` 数据**,`synonym-derivative-export` 视为导出副本,不单独建表。
---
## 2. 全局关联分析
### 2.1 四个业务域
```text
A. 词书域 book-catalog.json + wordbooks/decrypted/*.csv
│
│ book_id
▼
B. 词条词典域 zpk/decrypted/*.json(38,116 个词条,143,200 个词条版本)
│
│ 以 word / index_word 字符串弱关联
▼
C. 词根词族域 wordroot-export(card_info / word_family / 词缀 / 小组)
D. 近反义词域 synonym_words / synonym_data(独立词头集合,同样以 word 字符串弱关联)
```
### 2.2 源文件之间的关联键(数据剖析用,不等于模型外键)
| 关联 | 左 | 右 | 关联字段 | 覆盖率 |
|---|---|---|---|---:|
| 词书目录 ↔ 词书清单 | `book-catalog.id` | `wordbook.book_id` | 整数 | 1024 / 1024 全部一致 |
| 词书目录 ↔ 词书清单 | `book-catalog.code` | `wordbook.book_code` | 字符串 | 1024 / 1025(目录多 1 本 `KBYXKSDG`) |
| 词书清单 ↔ 词条 JSON | `wordbook.zpk` | `zpk/decrypted/{zpk}.json` | 文件键 | 1,228,421 行 → 仅 1 个被引用文件缺失 |
| 词书清单 ↔ 词条 ID | `wordbook.id` | `zpk` 文件名第 2 段 | 整数 | 1,228,420 / 1,228,421 |
| 词族 ↔ 变体 | `word_family_variant.word_family_id` | `word_family.id` | 整数 | 288 / 288 |
| 词族 ↔ 顶层词族 | `word_family.top_id` | `word_family.id` | 自引用 | 22,717 / 22,717,且每个顶层 ID 都存在自指行 |
| 卡片 ↔ 词族引用 | `word_group.f_id` | `word_family.id` | 整数 | **值域覆盖,但语义不匹配,见 §7.3** |
| 义项 ↔ 例句块 | `interpret_v2.*.oids` / `oseqs` | `example.data[].oid` | 整数 | 抽样 11,014 / 11,014 |
| 例句使用模式 ↔ 短语 | `example.g[].uid` | `phrase.p[].pid` | 整数 | 非零 `uid` 均能对应短语 ID |
| 近义词头 ↔ 义项 | `synonym_data.word_id` | `synonym_words.id` | 整数 | 8,383 / 8,383 |
| 近反义成员 | `syn` / `ant` JSON 内 ID | `synonym_words.id` | 整数 | 100% 可解析 |
> `book-catalog.code ↔ wordbook.book_code` 只是源文件之间的对照关系。**在模型中两表合并为 `book`,主键为 `book_id bigint`,`book_code` 仅作 `UNIQUE` 业务键,不被任何外键引用。**
### 2.3 只能用字符串关联的边界
`card_info`、`word_family`、`synonym_words` 与 `zpk` 词条 **没有数值外键**,只能按单词文本关联:
| 集合 | 去重词数 | 与 zpk 词条(38,000 个 `index_word`)的交集 |
|---|---:|---:|
| `zpk.index_word` | 38,000 | — |
| `card_info.word` | 11,998 | 11,662(97.2%) |
| `word_family.word` | 22,710 | 17,587(77.4%) |
| `synonym_words.word` | 6,279 | 6,231(99.2%) |
> 结论:**词条文本(归一化小写)是跨域的弱关联键**。落库时建议建立 `word_lexeme` 维表统一文本,但不强制外键,避免导入失败。
---
## 3. 命名与建模约定
### 3.1 命名规范
- 表名:`snake_case`、单数、业务语义名。
- 主键:代理主键优先,命名 `<表名>_id`,类型 `bigint`。
- 外键:`<被引用实体>_id`,类型 `bigint`;**禁止 `*_code` 作为外键**。
- 业务编码(`exam_code`、`book_code`):可为 `varchar` + `UNIQUE`,只做展示/对照。
- 弱关联/字符串引用:`*_ref` 或 `*_text`,不建外键。
- 布尔:`is_*` / `has_*`。
- 顺序:`seq_*` 或 `position`;时间:`*_at`。
- 枚举:`*_code`(仅作为属性值,不参与关联)。
- 原始来源字段保留在 `source_*` 中,不参与业务语义。
### 3.2 关键重整决策
| 原始形态 | 问题 | 重整方案 |
|---|---|---|
| `prefix.csv` / `root.csv` / `suffix.csv` 三张同构表 | 结构完全一致,三套 ID | 合并为 `morpheme`,`morpheme_id bigint` 统一代理主键,原 ID 存 `source_morpheme_id` |
| `grade="1,2,6,9"` 逗号串 | 违反 1NF | 拆为 `*_exam` 关联表,外键 `exam_id bigint` |
| `word_family_mini_group.word_ids="1,2"` | 违反 1NF | 拆为 `*_member` 关联表,外键 `family_entry_id bigint` |
| `word_family.json`、`word_family_variant.json` | JSON 内嵌考试 → 排名/成员 | 拆为 `*_exam_order` / `*_member` 表,外键 `exam_id bigint` |
| `synonym_data` 的 9 个考试列,每列一个 JSON | 列数随考试扩展、JSON 内嵌集合 | 拆为 `synonym_group` + `synonym_group_member` + `synonym_antonym`,外键 `exam_id bigint` |
| `zpk` 内 `raw` 字段 | 与顶层字段完全重复 | 不建模,视为导入冗余 |
| `hightlight` | 展示用 HTML,含拼写错误 | 重命名 `highlighted_word`,仅作展示快照 |
| `interpret` 纯文本 | 词性 + 中文混排 | 保留为 `definition_text`;结构化义项另见 `word_sense` |
| 句子 `sid` / `eid` 为 28 位字符串 | 超出 `bigint` | 增加 `sentence_id bigint` 代理主键,原值存 `source_sentence_key` / `source_sentence_ext_key` |
---
## 4. 实体模型
### 4.1 公共维表
#### `exam` 考试维表
来源:`word_family_exam.csv`(13 行),并补充 zpk 中出现的特殊编码,统一以 `exam_id bigint` 关联。
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `exam_id` | **bigint** | PK | 真实考试 1–13;`0` = `def`;`14` = `XX`;`15` = `OTHER` |
| `exam_code` | varchar(16) | UNIQUE NOT NULL | 业务编码,**不参与外键** |
| `exam_name_zh` | varchar(32) | NOT NULL | 中考、高考、四级…… |
| `is_grade_usable` | boolean | NOT NULL | 仅 `exam_id` 1–10 会出现在 `card.grade` / `word_family.grade` 中 |
| `is_pseudo` | boolean | NOT NULL | `def` / `XX` / `OTHER` 为伪考试视图 |
**考试 ID 分配:**
| exam_id | exam_code | 含义 | 来源 |
|---:|---|---|---|
| 0 | `def` | 默认/通用视图 | `phrase.pseqs`、`interpret_v2`、`oseqs` |
| 1 | `ZK` | 中考 | `word_family_exam` |
| 2 | `GK` | 高考 | `word_family_exam` |
| 3 | `CET4` | 四级 | `word_family_exam` |
| 4 | `CET6` | 六级 | `word_family_exam` |
| 5 | `KY` | 考研 | `word_family_exam` |
| 6 | `IELTS` | 雅思 | `word_family_exam` |
| 7 | `TOEFL` | 托福 | `word_family_exam` |
| 8 | `PRO4` | 专四 | `word_family_exam` |
| 9 | `PRO8` | 专八 | `word_family_exam` |
| 10 | `ZSB` | 专升本 | `word_family_exam` |
| 11 | `KB` | 考博 | `word_family_exam` |
| 12 | `SAT` | SAT | `word_family_exam` |
| 13 | `GRE` | GRE | `word_family_exam` |
| 14 | `XX` | 未分类/扩展视图 | zpk |
| 15 | `OTHER` | 近义词 `other` 列 | `synonym_data` |
---
### 4.2 域 A:词书目录
#### `book` 词书
来源:`book-catalog.json` + 每个词书 CSV 的 `book_*` 列。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `book_id` | **bigint** | PK | `catalog.id` / `wordbook.book_id` | 两处完全一致 |
| `book_code` | varchar(32) | UNIQUE NOT NULL | `catalog.code` / `book_code` | 业务键,不被外键引用 |
| `book_name` | varchar(128) | NOT NULL | `catalog.name`(损坏)→ `book_name` | 优先取词书 CSV 中的正确中文名 |
| `description` | text | | `catalog.desc` | 中文可能损坏 |
| `exam_id` | **bigint** | FK → `exam.exam_id`,可空 | `catalog.exam` / `book_exam` | 空串表示非考试类 |
| `declared_entry_count` | integer | | `catalog.count` / `book_count` | 与清单声明的词条数一致;与实际行数有 18 本不符 |
| `cover_url` | text | | `catalog.cover` | |
| `package_url` | text | | `catalog.url` | 指向 `.db` 包 |
| `content_version` | integer | | `catalog.version` | 内容版本 |
| `schema_version` | integer | | `catalog.bookVersion` | 目录结构版本,全部为 3 |
| `sort_by` | varchar(16) | | `catalog.sortBy` | 全部 `seq_book` |
| `sort_at` | bigint | | `catalog.sortTime` | Unix 秒 |
| `is_for_sale` | smallint | | `catalog.forSale` | |
| `is_purchased` | smallint | | `catalog.purchased` | |
| `is_opt` | smallint | | `catalog.opt` | |
| `source_code` | smallint | | `catalog.src` | 全部 0 |
| `catalog_type` | smallint | | `catalog.type` | 全部 0 |
| `labels` | text | | `catalog.labels` | |
| `publish_log` | text | | `catalog.publishLog` | |
| `pkg_page` | jsonb | | `catalog.pkgPage` | 结构未展开,保留原 JSON |
| `external_link` | jsonb | | `catalog.externalLink` | 基本为空对象 |
| `has_wordbook_file` | boolean | NOT NULL | 派生 | 目录中有、磁盘无 → false(1 本:`KBYXKSDG`) |
#### `book_phrase_book` 词书内嵌短语书关联
来源:`catalog.phraseBookIds`(数组)。
| 字段 | 类型 | 约束 |
|---|---|---|
| `book_id` | **bigint** | PK, FK → `book.book_id` |
| `phrase_book_id` | **bigint** | PK, FK → `book.book_id`(可能指向未导出的词书,导入时可延迟校验) |
| `position` | smallint | NOT NULL |
#### `book_entry` 词书词条(学习顺序)
来源:`wordbooks/decrypted/*.csv` 每一行。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `book_entry_id` | **bigint** | PK(代理) | — | |
| `book_id` | **bigint** | FK → `book.book_id` | `book_id` | |
| `entry_id` | **bigint** | FK → `word_entry.entry_id` | `id` | 同一 `book_id` 内唯一 |
| `display_word` | varchar(256) | NOT NULL | `word` | 词书中的展示形式(可能是短语/句子) |
| `headword_text` | varchar(256) | | `main_word` | 主词/词根提示,指向 `word_entry.index_word` 的弱引用 |
| `seq_book` | integer | | `seq_book` | 词书内顺序 |
| `seq_az` | integer | | `seq_az` | 字母序 |
| `seq_freq` | integer | | `seq_freq` | 词频排名,0 表示未知 |
| `seq_rand` | integer | | `seq_rand` | 随机顺序 |
| `source_zpk_key` | varchar(64) | | `zpk` | 原始 JSON 文件键,仅溯源 |
约束:`UNIQUE (book_id, entry_id)`;索引 `(book_id, seq_book)`。
---
### 4.3 域 B:词条词典(zpk)
`zpk` 文件名为 `0_{entry_id}_{variant_code}_{unix_ts}`。其中第 2 段等于目录 `id`,`variant_code` 有 293 种取值,语义未明,建模为 `source_variant_code`。
#### `word_entry` 词条
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `entry_id` | **bigint** | PK | 文件名第 2 段 | 38,116 个唯一词条 |
| `headword` | varchar(256) | NOT NULL | `word` | 词条原形 |
| `index_word` | varchar(256) | NOT NULL, INDEX | `index_word` | 归一化索引词;38,000 个唯一值 |
| `definition_text` | text | | `interpret` | 原始“词性 + 中文释义”文本 |
| `us_pronunciation` | varchar(128) | | `us_pron` | 美音 |
| `uk_pronunciation` | varchar(128) | | `uk_pron` | 英音 |
| `data_version` | varchar(8) | | `meta.data_version` | `1.0`(8,635)/ `2.0`(134,556)/ 空(9) |
| `book_exam_id` | **bigint** | FK → `exam.exam_id`,可空 | `meta.book_exam` | 原值为考试编码,按 `exam_code → exam_id` 映射 |
| `occurrence_count` | integer | | `book_occurrences` | 声明被多少词书收录;与实际统计有 4,744 条不一致 |
| `has_listening_examples` | boolean | | `example.is_type_99` | 是否存在纯听力语料例句 |
| `source_zpk_key` | varchar(64) | UNIQUE | `zpk` | 文件键 |
| `source_variant_code` | integer | | 文件名第 3 段 | 溯源,非外键 |
| `source_timestamp` | bigint | | 文件名第 4 段 | Unix 秒 |
> `zpk_path`、`raw` 不建模:前者是导出机绝对路径,后者与顶层字段逐字段相同(抽样 5,000 条 0 差异)。
#### `word_spelling_variant` 拼写变体
来源:`spell[]`。
| 字段 | 类型 | 约束 |
|---|---|---|
| `entry_id` | **bigint** | PK, FK → `word_entry.entry_id` |
| `position` | smallint | PK |
| `variant` | varchar(256) | NOT NULL |
#### `word_sense` 义项
来源:`interpret_v2[]`(134,556 条词条具备)。结构为 `group.p + group.d[]`。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `sense_id` | **bigint** | PK(代理) | — | |
| `entry_id` | **bigint** | FK → `word_entry.entry_id` | — | |
| `sense_no` | integer | NOT NULL | `d.id` | 词条内义项序号(1,2,3,4,6,8… 不连续) |
| `part_of_speech` | varchar(32) | | `group.p` | `n.` / `vt.` / `vi. vt.` / `phrv.` … |
| `gloss_zh` | text | | `d.i` | 中文释义 |
| `secondary_exam_codes` | text | | `d.s` | 次要考试编码列表(数组),逗号分隔存储 |
| `flag_h` | smallint | | `d.h` | 数值标记,观察值为 0 |
索引:`(entry_id, sense_no)`。**不设唯一约束**——全量数据中存在同一词条内 `sense_no` 重复的记录。
#### `sense_object` 义项对象(释义 ID)
来源:`interpret_v2[].d[].oids[]`;同时被 `example.data[].oid`、`oseqs` 引用。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `meaning_id` | **bigint** | PK(代理) | — | 统一代理主键 |
| `entry_id` | **bigint** | FK → `word_entry.entry_id` | — | |
| `source_meaning_id` | **bigint** | NOT NULL, INDEX | `oid` | 原始释义对象 ID |
| `sense_id` | **bigint** | FK → `word_sense.sense_id` | — | |
> **重要**:`oid` 只在词条内唯一,跨词条重复严重(64,492 个值中有 53,875 个重复);即使在同一词条内也有 5 条记录重复。因此不能把 `oid` 直接作为全局主键,必须使用 `meaning_id` 代理键,并以 `(entry_id, source_meaning_id)` 建立普通索引。一个义项通常对应 1 个 `meaning_id`,结构上允许 1:N。
#### `sense_exam` 义项适用考试
来源:`interpret_v2[].d[].t[]`。
| 字段 | 类型 | 约束 |
|---|---|---|
| `sense_id` | **bigint** | PK, FK → `word_sense.sense_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id` |
#### `sense_relation` 义项间关系
来源:`d.synids` / `d.antonymids` / `d.refids`(仅少量记录)。
| 字段 | 类型 | 约束 |
|---|---|---|
| `sense_id` | **bigint** | PK, FK → `word_sense.sense_id` |
| `relation_type` | varchar(16) | PK:`synonym`/`antonym`/`reference` |
| `position` | smallint | PK |
| `target_meaning_id` | **bigint** | FK → `sense_object.meaning_id` |
#### `entry_exam_meaning_order` 分考试义项顺序
来源:`example.oseqs`,形如 `{"def":{"core":["29070"],"ext":["29091"]}}`。
| 字段 | 类型 | 约束 |
|---|---|---|
| `entry_id` | **bigint** | PK, FK → `word_entry.entry_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id`(`def` 映射为 0) |
| `scope` | varchar(8) | PK:`core` / `ext` |
| `position` | smallint | PK |
| `meaning_id` | **bigint** | FK → `sense_object.meaning_id` |
#### `phrase` 短语/搭配
来源:`phrase[].p[]`。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `phrase_id` | **bigint** | PK(代理) | — | 统一代理主键 |
| `entry_id` | **bigint** | FK → `word_entry.entry_id` | — | |
| `source_phrase_id` | **bigint** | INDEX | `pid` | 原始短语 ID;仅在词条内唯一 |
| `meaning_id` | **bigint** | FK → `sense_object.meaning_id` | `oid` | 所属义项 |
| `group_type` | smallint | NOT NULL | `phrase[].t` | 观察到 1 / 2 两类短语组 |
| `text_en` | text | NOT NULL | `en` | |
| `text_zh` | text | | `cn` | |
| `audio_ref` | varchar(64) | | `fid` | 外部发音资源标识,非外键 |
| `extra_code` | varchar(16) | | `bd` | 极少数记录存在的附加编码 |
约束:`UNIQUE (entry_id, source_phrase_id)`。`pid` 跨词条存在重复(936 个值重复,最多 2 次),不能直接作为全局主键。
#### `phrase_exam` 短语适用考试
来源:`phrase.p[].exams[]`。
| 字段 | 类型 | 约束 |
|---|---|---|
| `phrase_id` | **bigint** | PK, FK → `phrase.phrase_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id` |
#### `phrase_exam_order` 分考试短语顺序
来源:`phrase[].pseqs`(`exam → [pid...]`)。
| 字段 | 类型 | 约束 |
|---|---|---|
| `entry_id` | **bigint** | PK, FK → `word_entry.entry_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id`(`def` 映射为 0) |
| `group_type` | smallint | PK |
| `position` | smallint | PK |
| `phrase_id` | **bigint** | FK → `phrase.phrase_id` |
#### `example_group` 例句块
来源:`example.data[]`。一个块对应一个释义对象在某一类例句下的集合。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `example_group_id` | **bigint** | PK(代理) | — | |
| `entry_id` | **bigint** | FK → `word_entry.entry_id` | — | |
| `meaning_id` | **bigint** | FK → `sense_object.meaning_id`,可空 | `oid` | type 99 无此字段 |
| `group_kind` | smallint | NOT NULL | `type` | `1` 核心释义例句;`2` 扩展释义例句;`3` 短语动词例句;`4` 习语例句;`99` 听力语料块 |
| `part_of_speech` | varchar(32) | | `i.p` | |
| `entry_kind_code` | varchar(16) | | `i.t` | `NORMAL` / `PHRV` / `IDM` / `PHR` |
| `head_form` | varchar(256) | | `i.u` | 如 `work sth↔off` |
| `definition_en` | text | | `i.e` | 英文释义 |
| `definition_zh` | text | | `i.c` | 中文释义 |
| `youdao_code_1` | varchar(64) | | `i.yu` | 罕见 |
| `youdao_code_2` | varchar(64) | | `i.yo` | 罕见 |
| `source_exam_codes` | text | | `exams[]` | 原始编码快照;规范值见 `example_group_exam` |
约束:`UNIQUE (entry_id, meaning_id, group_kind)`(`meaning_id` 为空时不适用)。
#### `example_group_exam` 例句块适用考试
来源:`example.data[].exams[]`。
| 字段 | 类型 | 约束 |
|---|---|---|
| `example_group_id` | **bigint** | PK, FK → `example_group.example_group_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id` |
#### `example_usage` 例句用法模式
来源:`example.data[].g[]`(仅当 `group_kind ≠ 99`)。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `usage_id` | **bigint** | PK(代理) | — | |
| `example_group_id` | **bigint** | FK → `example_group.example_group_id` | — | |
| `pattern_id` | **bigint** | INDEX | `uid` | 0 表示无模式;非 0 时与 `phrase.phrase_id` 对应 |
| `pattern_text` | text | | `u` | 如 `~ (about sth)` |
| `position` | smallint | | 数组下标 | |
#### `example_sentence` 例句句子
来源:`example.data[].g[].s[]`(普通块)与 `example.data[].g[]`(type 99 块)。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `sentence_id` | **bigint** | PK(代理) | — | 统一 bigint 主键 |
| `source_sentence_key` | varchar(64) | INDEX | `sid` | 原始句子标识;**不唯一**(31,002 个重复值) |
| `source_sentence_ext_key` | varchar(64) | INDEX | `eid` | 另一套原始标识;**不唯一**(最多重复 6,081 次) |
| `example_group_id` | **bigint** | FK → `example_group.example_group_id` | — | |
| `usage_id` | **bigint** | FK → `example_usage.usage_id`,可空 | — | type 99 为空 |
| `position` | smallint | | `s` | 组内顺序 |
| `text_en` | text | NOT NULL | `e` | 含 `<b>` 高亮标签 |
| `text_zh` | text | | `c` | |
| `audio_ref` | varchar(64) | | `fid` | 外部发音资源标识,非外键 |
| `audio_url` | text | | `u` | |
| `image_path` | text | | `i` | |
| `source_title` | varchar(256) | | `b` | 来源书名/剧名 |
| `is_listening_corpus` | boolean | NOT NULL | 派生 | type 99 为 true |
#### `entry_exam_sentence` 考试例句(写作/真题语料)
来源:`exam_sentences`(82,032 条词条具备),结构 `{exam: [{en,cn,src}]}`。
| 字段 | 类型 | 约束 |
|---|---|---|
| `entry_id` | **bigint** | PK, FK → `word_entry.entry_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id` |
| `position` | smallint | PK |
| `text_en` | text | NOT NULL |
| `text_zh` | text | |
| `source_desc` | text | |
#### `confusable_word` 易混词
来源:`confuse[]` + `confuse_exps[]`;`confuse_v2[]` 为结构化版本(81,698 条词条具备)。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `confusable_id` | **bigint** | PK(代理) | — | |
| `entry_id` | **bigint** | FK → `word_entry.entry_id` | — | |
| `position` | smallint | | 数组下标 | |
| `word_text` | varchar(256) | NOT NULL | `confuse[]` 或 `confuse_v2.w` | |
| `gloss_zh` | text | | `confuse_exps[]` 或 `confuse_v2.i` | |
| `pos_code` | smallint | | `confuse_v2.p` | 观察值 0 |
| `spelling_flag` | varchar(8) | | `confuse_v2.sp` | 罕见 |
约束:`UNIQUE (entry_id, word_text)`。
---
### 4.4 域 C:词根词缀与词族
#### `morpheme` 词素(前缀/词根/后缀统一表)
来源:`prefix.csv`、`root.csv`、`suffix.csv`。三表结构完全相同,合并后用统一 `bigint` 代理主键区分。
`display` 统一格式为 `<词素> = <英文释义> <中文释义>`,可解析为结构化字段。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `morpheme_id` | **bigint** | PK(统一代理) | — | 全表唯一,供外键引用 |
| `morpheme_type` | varchar(8) | NOT NULL | 文件来源 | `prefix` / `root` / `suffix` |
| `source_morpheme_id` | **bigint** | NOT NULL | `id` | 原表内 ID |
| `form` | varchar(64) | INDEX | `display` 的 `=` 左侧 | 如 `duct`、`caco-`、`-ar` |
| `display_text` | varchar(256) | NOT NULL | `display` | 原始展示文本 |
| `meaning_en` | varchar(256) | | `=` 右侧英文部分 | 可能为空 |
| `meaning_zh` | varchar(256) | | `=` 右侧中文部分 | |
| `note` | varchar(256) | | 剩余文本 | 如“构成形容词” |
约束:`UNIQUE (morpheme_type, source_morpheme_id)`。
#### `card` 单词卡片
来源:`card_info.csv`(12,003 行)。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `card_id` | **bigint** | PK | `id` | |
| `word` | varchar(256) | NOT NULL, INDEX | `word` | |
| `highlighted_word` | text | | `hightlight` | 展示用 HTML 快照 |
| `memory_note` | text | | `memory` | 记忆提示 |
| `example_text` | text | | `example` | 例句文本(英中换行分隔) |
| `prefix_morpheme_id` | **bigint** | FK → `morpheme.morpheme_id`,可空 | `prefix` | 0/空 表示无 |
| `root_morpheme_id` | **bigint** | FK → `morpheme.morpheme_id`,可空 | `root` | |
| `suffix_morpheme_id` | **bigint** | FK → `morpheme.morpheme_id`,可空 | `suffix` | |
| `default_family_ref` | **bigint** | 无外键 | `default_f_id` | 旧版/外部表引用,**不可解析**,见 §7.3 |
| `is_hidden` | boolean | NOT NULL | `hidden` | |
> 三个词缀外键在导入时需根据 `morpheme_type` 将原 ID 映射为统一 `morpheme_id`。
#### `card_exam` 卡片适用考试
来源:`card_info.grade`(逗号分隔的数字考试 ID)。
| 字段 | 类型 | 约束 |
|---|---|---|
| `card_id` | **bigint** | PK, FK → `card.card_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id` |
#### `word_family` 词族词条
来源:`word_family.csv`(22,717 行)。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `family_entry_id` | **bigint** | PK | `id` | |
| `top_family_id` | **bigint** | FK → `word_family.family_entry_id` | `top_id` | 顶层词族;顶层行 `id = top_id` |
| `word` | varchar(256) | NOT NULL, INDEX | `word` | |
| `highlighted_word` | text | | `hightlight` | |
| `interpretation` | text | | `interpret` | 词性 + 中文释义 |
| `prefix_morpheme_id` | **bigint** | FK → `morpheme.morpheme_id`,可空 | `prefix` | 0 表示无 |
| `suffix_morpheme_id` | **bigint** | FK → `morpheme.morpheme_id`,可空 | `suffix` | 0 表示无 |
| `group_level_1` | smallint | | `group1` | 分组层级 1(1–21) |
| `group_level_2` | smallint | | `group2` | 分组层级 2(1–10) |
| `group_level_3` | smallint | | `group3` | 分组层级 3(1–9) |
> 词根字段在 `word_family` 中不存在;只有 prefix/suffix。
#### `word_family_exam` 词族适用考试
来源:`word_family.grade`。
| 字段 | 类型 | 约束 |
|---|---|---|
| `family_entry_id` | **bigint** | PK, FK → `word_family.family_entry_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id` |
#### `word_family_exam_order` 词族分考试顺序
来源:`word_family.json`,形如 `{"0":1,"1":2,"10":2}`;键为考试 ID(`0` 表示默认视图),值为组内序号。
| 字段 | 类型 | 约束 |
|---|---|---|
| `family_entry_id` | **bigint** | PK, FK → `word_family.family_entry_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id`(`0` = `def`) |
| `position` | integer | NOT NULL |
#### `word_family_variant` 词族变体
来源:`word_family_variant.csv`(288 行)。
| 字段 | 类型 | 约束 | 来源 |
|---|---|---|---|
| `variant_id` | **bigint** | PK | `id` |
| `variant_word` | varchar(256) | NOT NULL | `variant` |
| `family_entry_id` | **bigint** | FK → `word_family.family_entry_id` | `word_family_id` |
| `top_family_id` | **bigint** | FK → `word_family.family_entry_id` | `top_id` |
| `highlighted_word` | text | | `hightlight` |
| `interpretation` | text | | `interpret` |
| `prefix_morpheme_id` | **bigint** | FK → `morpheme.morpheme_id`,可空 | `prefix` |
| `suffix_morpheme_id` | **bigint** | FK → `morpheme.morpheme_id`,可空 | `suffix` |
#### `word_family_variant_member` 变体分考试成员
来源:`word_family_variant.json`,形如 `{exam_id: ["analyze","analyzer","*"]}`。
| 字段 | 类型 | 约束 |
|---|---|---|
| `variant_id` | **bigint** | PK, FK → `word_family_variant.variant_id` |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id`(`0` = `def`) |
| `position` | smallint | PK |
| `member_word` | varchar(256) | NOT NULL;`*` 为占位符 |
| `is_placeholder` | boolean | NOT NULL |
#### `word_family_mini_group` 词族小组
来源:`word_family_mini_group.csv`(37,984 行)。
| 字段 | 类型 | 约束 |
|---|---|---|
| `mini_group_id` | **bigint** | PK |
| `size` | smallint | NOT NULL(派生) |
#### `word_family_mini_group_member` 小组成员
来源:`word_ids` 逗号串。
| 字段 | 类型 | 约束 |
|---|---|---|
| `mini_group_id` | **bigint** | PK, FK → `word_family_mini_group.mini_group_id` |
| `family_entry_id` | **bigint** | PK, FK → `word_family.family_entry_id` |
| `position` | smallint | PK |
> 源数据中 122 个 token 不是整数:`*`(11,061 次)及带引号的单词文本(如 `"aerator"`)。导入时应写入异常表或按异常丢弃。
#### `card_family_link` 卡片—分组关联
来源:`word_group.csv`(12,265 行)。
| 字段 | 类型 | 约束 | 来源 | 说明 |
|---|---|---|---|---|
| `link_id` | **bigint** | PK | `id` | |
| `card_id` | **bigint** | FK → `card.card_id` | `card_info_id` | 全部可解析 |
| `group_no` | smallint | NOT NULL | `group_id` | 取值 1–50,是分组层级/编号,非 ID |
| `family_ref` | **bigint** | 无外键 | `f_id` | 旧版/外部表引用,见 §7.3 |
| `is_hidden` | boolean | NOT NULL | `hidden` | |
---
### 4.5 域 D:近义词 / 反义词
#### `synonym_word` 近义词词头
来源:`synonym_words.csv`(6,279 行)。
| 字段 | 类型 | 约束 |
|---|---|---|
| `word_id` | **bigint** | PK |
| `word` | varchar(256) | NOT NULL, INDEX |
#### `synonym_sense` 近义词义项
来源:`synonym_data.csv` 的 `id/word_id/pos/interpret`(8,383 行)。
| 字段 | 类型 | 约束 | 来源 |
|---|---|---|---|
| `sense_id` | **bigint** | PK | `id` |
| `word_id` | **bigint** | FK → `synonym_word.word_id` | `word_id` |
| `part_of_speech` | varchar(32) | | `pos` |
| `gloss_zh` | text | | `interpret` |
> 6,279 个词头中 19 个没有任何义项。
#### `synonym_group` 近义词组(按义项 + 考试)
来源:每个考试列 JSON 的 `syn` 与 `free`。
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
| `sense_id` | **bigint** | PK, FK → `synonym_sense.sense_id` | |
| `exam_id` | **bigint** | PK, FK → `exam.exam_id` | `zk→1, gk→2, cet4→3, cet6→4, ky→5, ielts→6, toefl→7, zsb→10, other→15` |
| `canonical_word_id` | **bigint** | FK → `synonym_word.word_id`,可空 | `free`;多数落在组内,亦可能指向组外 |
| `member_count` | smallint | NOT NULL(派生) | |
#### `synonym_group_member` 近义词组成员
来源:`syn` 逗号串。
| 字段 | 类型 | 约束 |
|---|---|---|
| `sense_id` | **bigint** | PK |
| `exam_id` | **bigint** | PK |
| `position` | smallint | PK |
| `member_word_id` | **bigint** | FK → `synonym_word.word_id` |
> 双列外键 `(sense_id, exam_id)` 指向 `synonym_group`。成员集合大小 2–12(最长可更大),`word_id` 自身不保证在首位,但 99.8% 位于组内。
#### `synonym_antonym` 反义词
来源:每个考试列 JSON 的 `ant`(单值 8,930 次,逗号多值 425 次)。
| 字段 | 类型 | 约束 |
|---|---|---|
| `sense_id` | **bigint** | PK |
| `exam_id` | **bigint** | PK |
| `position` | smallint | PK |
| `antonym_word_id` | **bigint** | FK → `synonym_word.word_id` |
#### 视图 `v_synonym_joined`
对应 `synonyms-joined.csv`:`synonym_sense JOIN synonym_word`,并按考试展开 `synonym_group_member`。
---
## 5. 实体关系图
### 5.1 全局 ER(Mermaid)
```mermaid
erDiagram
exam ||--o{ book : "exam_id"
book ||--o{ book_entry : contains
book ||--o{ book_phrase_book : embeds
word_entry ||--o{ book_entry : referenced_by
word_entry ||--o{ word_spelling_variant : has
word_entry ||--o{ word_sense : has
word_sense ||--o{ sense_object : defines
word_sense ||--o{ sense_exam : applies_to
word_sense ||--o{ sense_relation : relates
word_entry ||--o{ phrase : has
word_entry ||--o{ example_group : has
word_entry ||--o{ entry_exam_sentence : has
word_entry ||--o{ confusable_word : has
word_entry ||--o{ entry_exam_meaning_order : orders
phrase }o--|| sense_object : explains
phrase ||--o{ phrase_exam : applies_to
phrase ||--o{ phrase_exam_order : ordered_in
example_group }o--o| sense_object : explains
example_group ||--o{ example_group_exam : applies_to
example_group ||--o{ example_usage : groups
example_usage ||--o{ example_sentence : contains
example_group ||--o{ example_sentence : contains
card ||--o{ card_exam : applies_to
card }o--o{ morpheme : "morpheme_id"
card ||--o{ card_family_link : joins
word_family ||--o{ word_family : "top_family_id"
word_family ||--o{ word_family_variant : has
word_family ||--o{ word_family_exam : applies_to
word_family ||--o{ word_family_exam_order : ordered_in
word_family_variant ||--o{ word_family_variant_member : expands
word_family_mini_group ||--o{ word_family_mini_group_member : contains
word_family ||--o{ word_family_mini_group_member : member_of
synonym_word ||--o{ synonym_sense : has
synonym_sense ||--o{ synonym_group : has
synonym_group ||--o{ synonym_group_member : contains
synonym_sense ||--o{ synonym_antonym : has
exam ||--o{ synonym_group : scopes
```
### 5.2 域 B 内部关联(zpk)
```mermaid
erDiagram
word_entry ||--o{ word_sense : "interpret_v2"
word_sense ||--o{ sense_object : "oids"
sense_object ||--o{ example_group : "example.data[].oid"
word_entry ||--o{ example_group : "example.data[]"
example_group ||--o{ example_usage : "g[]"
example_usage ||--o{ example_sentence : "s[]"
example_group ||--o{ example_sentence : "type 99 直接挂句"
word_entry ||--o{ phrase : "phrase[].p[]"
sense_object ||--o{ phrase : "phrase.p[].oid"
phrase ||--o{ example_usage : "uid = phrase_id(弱)"
word_entry ||--o{ entry_exam_meaning_order : "example.oseqs"
word_entry ||--o{ entry_exam_sentence : "exam_sentences"
word_entry ||--o{ confusable_word : "confuse / confuse_v2"
exam ||--o{ entry_exam_meaning_order : "exam_id"
exam ||--o{ entry_exam_sentence : "exam_id"
```
### 5.3 基数汇总
| 关系 | 基数 | 约束 |
|---|---|---|
| `book` → `book_entry` | 1 : N | `UNIQUE(book_id, entry_id)` |
| `word_entry` → `book_entry` | 1 : N | 同一词条最多被 284 本词书收录 |
| `word_entry` → `word_sense` | 1 : N | 2.0 版本有结构化义项 |
| `word_sense` → `sense_object` | 1 : N | 通常 1:1 |
| `example_group` → `example_sentence` | 1 : N | |
| `word_family` 自引用 | N : 1 | 每个 `top_family_id` 都存在自指根行(5,629 个族) |
| `word_family_mini_group` ↔ `word_family` | N : M | 通过成员表 |
| `card` ↔ `word_family` | 弱关联 | 仅能经 `family_ref` 旧 ID,无法可靠连接 |
| `synonym_sense` → `synonym_group` | 1 : N(每个考试 1 组) | 复合键 `(sense_id, exam_id)` |
---
## 6. 跨域统一:`word_lexeme` 文本维表(可选)
由于词书、词族、近义词与 zpk 之间没有数值外键,建议增加一个轻量文本维表,用于搜索与跨域跳转,但**不建立强制外键**。
| 字段 | 类型 | 说明 |
|---|---|---|
| `lexeme_id` | **bigint** | PK |
| `normalized_text` | varchar(256) | `lower(trim(word))`,UNIQUE |
| `display_text` | varchar(256) | 首次出现的展示形式 |
各域保留自己的 `word` 字段,同时可冗余 `lexeme_id` 以便联查。不强制约束的原因:三个域的词表并非同源,直接外键会导致导入失败(如卡片词有 336 个不在 zpk 中)。
---
## 7. 数据质量问题与建模注意事项
### 7.1 文件级问题
| 问题 | 影响 | 处理 |
|---|---|---|
| 1 个被引用的 zpk 文件缺失:`0_53785_101_1775241011`(`jealous`,涉及 `CHLJ2027`、`JBB2027`、`LLYC` 等书) | 词书行无法展开词条详情 | `book_entry.source_zpk_key` 保留,`entry_id` 仍有效;词条详情允许为空 |
| 目录多 1 本 `KBYXKSDG` | 目录条目无词书文件 | `book.has_wordbook_file = false` |
| 18 本词书的声明词条数 ≠ 实际 CSV 行数 | 统计不一致 | 以实际行数为准,另存 `declared_entry_count` |
| `book_occurrences` 与词书实际收录数有 4,744 条不一致 | 不能作为精确统计 | 视为源端快照,不作为约束 |
| `book-catalog.json` 中文名/描述含 U+FFFD | 不可恢复 | 以词书 CSV 的 `book_name` 为准 |
| `README.txt` / `wordroot-schema.md` 行数比 CSV 少 2 | 文档过期 | 以 CSV 实际行数为准 |
| `synonym-derivative-export` 为重复导出 | 重复数据 | 只导入一份 |
### 7.2 结构级问题
| 问题 | 处理 |
|---|---|
| `word_family_mini_group.word_ids` 含 `*` 与带引号单词 | 拆表时过滤非整数;另建异常表或记录日志 |
| `interpret_v2` 义项序号不连续(1,2,3,4,6,8) | 保留 `sense_no` 原值,不重排 |
| `phrase.p[].exams` 与 `pseqs` 不一致 | `pseqs` 作为分考试顺序的权威来源,`exams` 仅作辅助 |
| `example.data[].g[].uid` 为 0 或不存在于 `phrase` | 允许 `pattern_id = 0`,不建强制外键 |
| `word_family_variant.json` 内 `*` 占位符 | `is_placeholder` 标记 |
| zpk `meta` 缺失 9 条、`phrase` 缺失 9 条 | 允许为空,`data_version` 置 null |
| 9 条 `example` 仅含 `v`/`data`,无 `oseqs`/`is_type_99` | 允许可选字段为空 |
| 句子 `sid`/`eid` 为 28 位字符串 | 使用 bigint 代理主键 + `source_sentence_key` 字符串列 |
| `sid` 跨词条重复 31,002 个值,`eid` 最多重复 6,081 次 | 两者都不能作为唯一键,只建普通索引 |
| `phrase.pid` 跨词条重复 936 个值(最多 2 次) | `phrase_id` 使用代理主键,`UNIQUE(entry_id, source_phrase_id)` |
| `sense.oid` 跨词条重复 53,875 个值,同一词条内也有 5 例重复 | `meaning_id` 使用代理主键,`(entry_id, source_meaning_id)` 仅建普通索引 |
| `sense_no` 在同一词条内存在重复 | 去掉 `UNIQUE(entry_id, sense_no)`,仅保留索引 |
| `sense.synids/antonymids/refids` 无法解析到 `oid` | 全量导入实际写入 0 行;保留原始文本或后续单独建关系表 |
| `phrase.exams`、`grade`、`t[]` 中存在重复考试编码 | 导入时按 `(实体, exam_id)` 去重 |
### 7.3 无法解析的旧引用(重点)
`card_info.default_f_id`(1,258 个不同值)与 `word_group.f_id`(1,259 个不同值):
- 两者值域高度重合(交集 1,243),范围均为 1–3,043。
- 它们 **不是** `word_family.id` 的语义外键:抽样中 `f_id` 指向的词族词与卡片词 0% 匹配;仅约 31% 的 `f_id` 恰好是某个词族的顶层行。
- 判断为**旧版本或外部“词族分组表”的 ID**,在本次导出中该表缺失,ID 空间已重排。
**建模结论**:保留为 `default_family_ref` / `family_ref`(`bigint`),不加外键约束,文档标注“不可解析”。若后续拿到原始分组表,再补建 `family_group` 实体并迁移。
---
## 8. 字段重命名对照表
| 原文件.字段 | 新表.字段 | 说明 |
|---|---|---|
| `card_info.hightlight` | `card.highlighted_word` | 修正拼写 |
| `card_info.memory` | `card.memory_note` | 语义更明确 |
| `card_info.example` | `card.example_text` | 与例句实体区分 |
| `card_info.hidden` | `card.is_hidden` | 布尔化 |
| `card_info.prefix/root/suffix` | `card.prefix_morpheme_id` 等(`bigint`) | 原类型内 ID → 统一 `morpheme_id` |
| `card_info.default_f_id` | `card.default_family_ref`(`bigint`) | 旧引用,非外键 |
| `word_family.hightlight` | `word_family.highlighted_word` | |
| `word_family.interpret` | `word_family.interpretation` | |
| `word_family.group1/2/3` | `word_family.group_level_1/2/3` | 层级语义 |
| `word_family.top_id` | `word_family.top_family_id`(`bigint`) | 自引用 |
| `word_family.prefix/suffix` | `word_family.*_morpheme_id`(`bigint`) | 统一词素主键 |
| `word_family_variant.variant` | `word_family_variant.variant_word` | |
| `word_family_variant.word_family_id` | `word_family_variant.family_entry_id`(`bigint`) | 统一命名 |
| `word_family_mini_group.word_ids` | `word_family_mini_group_member`(表) | 1NF |
| `word_group.card_info_id` | `card_family_link.card_id`(`bigint`) | |
| `word_group.group_id` | `card_family_link.group_no` | 1–50 的分组层级,非 ID |
| `word_group.f_id` | `card_family_link.family_ref`(`bigint`) | 旧引用 |
| `word_group.hidden` | `card_family_link.is_hidden` | |
| `synonym_data.id` | `synonym_sense.sense_id`(`bigint`) | |
| `synonym_data.interpret` | `synonym_sense.gloss_zh` | |
| `synonym_data.<exam列>` | `synonym_group` / `synonym_group_member` / `synonym_antonym`,`exam_id`(`bigint`) | 列转行 + 拆分 |
| `synonym_data.<exam>.free` | `synonym_group.canonical_word_id`(`bigint`) | |
| `synonym_data.<exam>.syn` | `synonym_group_member` | |
| `synonym_data.<exam>.ant` | `synonym_antonym` | |
| `book-catalog.id` | `book.book_id`(`bigint`) | 模型主键 |
| `book-catalog.code` | `book.book_code` | 业务唯一键,非外键 |
| `book-catalog.exam` | `book.exam_id`(`bigint`) | 编码转 ID |
| `book-catalog.bookVersion` | `book.schema_version` | 与 `version` 区分 |
| `book-catalog.sortTime` | `book.sort_at` | |
| `wordbook.book_id` | `book_entry.book_id`(`bigint`) | |
| `wordbook.zpk` | `book_entry.source_zpk_key` | 仅溯源 |
| `wordbook.main_word` | `book_entry.headword_text` | 弱文本引用 |
| `zpk.index_word` | `word_entry.index_word` | |
| `zpk.book_occurrences` | `word_entry.occurrence_count` | 源端统计快照 |
| `zpk.meta.book_exam` | `word_entry.book_exam_id`(`bigint`) | 编码转 ID |
| `zpk.interpret` | `word_entry.definition_text` | |
| `zpk.interpret_v2` | `word_sense` + `sense_object` + `sense_exam` | 结构化 |
| `zpk.phrase` | `phrase` + `phrase_exam` + `phrase_exam_order` | |
| `zpk.example` | `example_group` + `example_usage` + `example_sentence` + `entry_exam_meaning_order` | |
| `zpk.exam_sentences` | `entry_exam_sentence` | |
| `zpk.confuse/confuse_exps/confuse_v2` | `confusable_word` | |
| `zpk.spell` | `word_spelling_variant` | |
| `zpk.raw` | — | 不建模(完全冗余) |
| `zpk.zpk_path` | — | 不建模(导出机路径) |
---
## 9. 建议索引
```sql
-- 域 A
CREATE INDEX idx_book_entry_book_seq ON book_entry (book_id, seq_book);
CREATE INDEX idx_book_entry_entry ON book_entry (entry_id);
-- 域 B
CREATE INDEX idx_word_entry_index_word ON word_entry (index_word);
CREATE INDEX idx_word_sense_entry ON word_sense (entry_id, sense_no);
CREATE INDEX idx_sense_object_sense ON sense_object (sense_id);
CREATE INDEX idx_phrase_entry ON phrase (entry_id);
CREATE INDEX idx_phrase_meaning ON phrase (meaning_id);
CREATE INDEX idx_example_group_entry ON example_group (entry_id, group_kind);
CREATE INDEX idx_example_group_meaning ON example_group (meaning_id);
CREATE INDEX idx_example_sentence_group ON example_sentence (example_group_id);
CREATE INDEX idx_example_sentence_usage ON example_sentence (usage_id);
CREATE INDEX idx_confusable_entry ON confusable_word (entry_id);
-- 域 C
CREATE INDEX idx_morpheme_form ON morpheme (morpheme_type, form);
CREATE INDEX idx_word_family_word ON word_family (word);
CREATE INDEX idx_word_family_top ON word_family (top_family_id);
CREATE INDEX idx_mini_member_family ON word_family_mini_group_member (family_entry_id);
CREATE INDEX idx_card_word ON card (word);
CREATE INDEX idx_card_family_link_card ON card_family_link (card_id);
-- 域 D
CREATE INDEX idx_synonym_word_text ON synonym_word (word);
CREATE INDEX idx_syn_group_member_word ON synonym_group_member (member_word_id);
CREATE INDEX idx_syn_antonym_word ON synonym_antonym (antonym_word_id);
```
---
## 10. 附录:核心建表 DDL(PostgreSQL)
> 下面是可读版 DDL。实际可执行、且同时兼容 SQLite / PostgreSQL / MySQL 的完整 DDL 在 `import_lexis.py` 中,由脚本按方言自动转换(`jsonb→JSON/TEXT`、`boolean→TINYINT(1)/INTEGER`、移除 `DEFERRABLE` 等)。
> 所有主键、外键统一 `bigint`;`exam_code`、`book_code` 只作业务唯一键。
```sql
CREATE TABLE exam (
exam_id bigint PRIMARY KEY, -- 主键;0=def 默认视图,1-13 真实考试,14=XX 未分类,15=OTHER 其他
exam_code varchar(16) NOT NULL UNIQUE, -- 考试业务编码,仅作唯一键,不参与外键
exam_name_zh varchar(32) NOT NULL, -- 考试中文名称
is_grade_usable boolean NOT NULL DEFAULT FALSE, -- 是否可用于年级/考试编码(仅 1-10 为真)
is_pseudo boolean NOT NULL DEFAULT FALSE -- 是否为伪考试视图(def/XX/OTHER)
);
CREATE TABLE book (
book_id bigint PRIMARY KEY, -- 词书主键,对应目录 id
book_code varchar(32) NOT NULL UNIQUE, -- 词书业务唯一编码,取自文件名后缀
book_name varchar(128) NOT NULL, -- 词书名称
description text, -- 词书描述
exam_id bigint REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 关联考试 id,空表示非考试类
declared_entry_count integer, -- 源端声明的词条数
cover_url text, -- 封面图片地址
package_url text, -- 词书数据包地址
content_version integer, -- 内容版本
schema_version integer, -- 目录结构版本
sort_by varchar(16), -- 排序方式
sort_at bigint, -- 排序时间,Unix 秒
is_for_sale smallint, -- 是否售卖
is_purchased smallint, -- 是否已购买
is_opt smallint, -- 是否可选项
source_code smallint, -- 来源编码
catalog_type smallint, -- 目录类型
labels text, -- 标签文本
publish_log text, -- 发布日志
pkg_page jsonb, -- 包页面配置,JSON
external_link jsonb, -- 外部链接配置,JSON
has_wordbook_file boolean NOT NULL DEFAULT TRUE -- 是否存在词书清单文件
);
CREATE TABLE book_phrase_book (
book_id bigint NOT NULL REFERENCES book(book_id) DEFERRABLE INITIALLY DEFERRED, -- 词书 id
phrase_book_id bigint NOT NULL REFERENCES book(book_id) DEFERRABLE INITIALLY DEFERRED, -- 内嵌短语书的词书 id
position smallint NOT NULL, -- 内嵌顺序
PRIMARY KEY (book_id, phrase_book_id)
);
CREATE TABLE word_entry (
entry_id bigint PRIMARY KEY, -- 词条主键,取自 zpk 文件名第 2 段
headword varchar(256) NOT NULL, -- 词条原形
index_word varchar(256) NOT NULL, -- 归一化索引词
definition_text text, -- 原始释义文本(词性 + 中文)
us_pronunciation varchar(128), -- 美式音标
uk_pronunciation varchar(128), -- 英式音标
data_version varchar(8), -- 源数据版本
book_exam_id bigint REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 所属考试 id
occurrence_count integer, -- 源端声明的收录词书数
has_listening_examples boolean NOT NULL DEFAULT FALSE, -- 是否包含听力语料例句
source_zpk_key varchar(64) UNIQUE, -- 源 zpk 文件键,仅溯源
source_variant_code integer, -- 源文件名中的变体编码
source_timestamp bigint -- 源文件名中的时间戳,Unix 秒
);
CREATE TABLE book_entry (
book_entry_id bigint PRIMARY KEY, -- 词书词条关联主键
book_id bigint NOT NULL REFERENCES book(book_id) DEFERRABLE INITIALLY DEFERRED, -- 词书 id
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
display_word varchar(256) NOT NULL, -- 词书中的展示词形
headword_text varchar(256), -- 主词/词根提示,弱文本引用
seq_book integer, -- 词书内顺序
seq_az integer, -- 字母序
seq_freq integer, -- 词频排名,0 表示未知
seq_rand integer, -- 随机顺序
source_zpk_key varchar(64), -- 源 zpk 文件键,仅溯源
UNIQUE (book_id, entry_id)
);
CREATE TABLE word_spelling_variant (
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
position smallint NOT NULL, -- 变体顺序
variant varchar(256) NOT NULL, -- 拼写变体文本
PRIMARY KEY (entry_id, position)
);
CREATE TABLE word_sense (
sense_id bigint PRIMARY KEY, -- 义项主键(代理)
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
sense_no integer NOT NULL, -- 词条内义项序号,源值不连续
part_of_speech varchar(32), -- 词性
gloss_zh text, -- 中文释义
secondary_exam_codes text, -- 源字段 s,次要考试编码列表,逗号分隔
flag_h smallint -- 源字段 h,数值标记
);
CREATE TABLE sense_object (
meaning_id bigint PRIMARY KEY, -- 释义对象主键(代理)
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
source_meaning_id bigint NOT NULL, -- 源释义对象 id(oid),仅词条内唯一
sense_id bigint REFERENCES word_sense(sense_id) DEFERRABLE INITIALLY DEFERRED -- 所属义项 id
);
CREATE TABLE sense_exam (
sense_id bigint NOT NULL REFERENCES word_sense(sense_id) DEFERRABLE INITIALLY DEFERRED, -- 义项 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
PRIMARY KEY (sense_id, exam_id)
);
CREATE TABLE sense_relation (
sense_id bigint NOT NULL REFERENCES word_sense(sense_id) DEFERRABLE INITIALLY DEFERRED, -- 义项 id
relation_type varchar(16) NOT NULL, -- 关系类型:synonym/antonym/reference
position smallint NOT NULL, -- 关系内顺序
target_meaning_id bigint NOT NULL REFERENCES sense_object(meaning_id) DEFERRABLE INITIALLY DEFERRED, -- 目标释义对象 id
PRIMARY KEY (sense_id, relation_type, position)
);
CREATE TABLE entry_exam_meaning_order (
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
scope varchar(8) NOT NULL CHECK (scope IN ('core','ext')), -- 释义范围:core 核心 / ext 扩展
position smallint NOT NULL, -- 范围内顺序
meaning_id bigint NOT NULL REFERENCES sense_object(meaning_id) DEFERRABLE INITIALLY DEFERRED, -- 释义对象 id
PRIMARY KEY (entry_id, exam_id, scope, position)
);
CREATE TABLE phrase (
phrase_id bigint PRIMARY KEY, -- 短语主键(代理)
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
source_phrase_id bigint, -- 源短语 id(pid),仅词条内唯一
meaning_id bigint REFERENCES sense_object(meaning_id) DEFERRABLE INITIALLY DEFERRED, -- 所属释义对象 id
group_type smallint NOT NULL, -- 短语组类型,源值 1/2
text_en text NOT NULL, -- 英文短语
text_zh text, -- 中文释义
audio_ref varchar(64), -- 发音资源标识,非外键
extra_code varchar(16), -- 源附加编码 bd
UNIQUE (entry_id, source_phrase_id)
);
CREATE TABLE phrase_exam (
phrase_id bigint NOT NULL REFERENCES phrase(phrase_id) DEFERRABLE INITIALLY DEFERRED, -- 短语 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
PRIMARY KEY (phrase_id, exam_id)
);
CREATE TABLE phrase_exam_order (
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
group_type smallint NOT NULL, -- 短语组类型
position smallint NOT NULL, -- 分考试顺序
phrase_id bigint NOT NULL REFERENCES phrase(phrase_id) DEFERRABLE INITIALLY DEFERRED, -- 短语 id
PRIMARY KEY (entry_id, exam_id, group_type, position)
);
CREATE TABLE example_group (
example_group_id bigint PRIMARY KEY, -- 例句块主键(代理)
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
meaning_id bigint REFERENCES sense_object(meaning_id) DEFERRABLE INITIALLY DEFERRED, -- 所属释义对象 id,type 99 为空
group_kind smallint NOT NULL, -- 例句块类型:1 核心,2 扩展,3 短语动词,4 习语,99 听力语料
part_of_speech varchar(32), -- 词性
entry_kind_code varchar(16), -- 词条类型码:NORMAL/PHRV/IDM/PHR
head_form varchar(256), -- 词头形式
definition_en text, -- 英文释义
definition_zh text, -- 中文释义
youdao_code_1 varchar(64), -- 源附加编码 yu
youdao_code_2 varchar(64), -- 源附加编码 yo
source_exam_codes text -- 源考试编码快照,规范值见 example_group_exam
);
CREATE TABLE example_group_exam (
example_group_id bigint NOT NULL REFERENCES example_group(example_group_id) DEFERRABLE INITIALLY DEFERRED, -- 例句块 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
PRIMARY KEY (example_group_id, exam_id)
);
CREATE TABLE example_usage (
usage_id bigint PRIMARY KEY, -- 用法模式主键(代理)
example_group_id bigint NOT NULL REFERENCES example_group(example_group_id) DEFERRABLE INITIALLY DEFERRED, -- 例句块 id
pattern_id bigint REFERENCES phrase(phrase_id) DEFERRABLE INITIALLY DEFERRED, -- 关联短语 id(源 uid 解析)
pattern_text text, -- 用法模式文本
position smallint NOT NULL -- 组内顺序
);
CREATE TABLE example_sentence (
sentence_id bigint PRIMARY KEY, -- 句子主键(代理)
source_sentence_key varchar(64), -- 源句子标识 sid,不唯一
source_sentence_ext_key varchar(64), -- 源句子扩展标识 eid,不唯一
example_group_id bigint NOT NULL REFERENCES example_group(example_group_id) DEFERRABLE INITIALLY DEFERRED, -- 例句块 id
usage_id bigint REFERENCES example_usage(usage_id) DEFERRABLE INITIALLY DEFERRED, -- 用法模式 id,type 99 为空
position smallint, -- 组内顺序
text_en text NOT NULL, -- 英文句子,含高亮标签
text_zh text, -- 中文翻译
audio_ref varchar(64), -- 发音资源标识,非外键
audio_url text, -- 音频地址
image_path text, -- 图片路径
source_title varchar(256), -- 来源书名或剧名
is_listening_corpus boolean NOT NULL DEFAULT FALSE -- 是否听力语料例句
);
CREATE TABLE entry_exam_sentence (
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
position smallint NOT NULL, -- 顺序
text_en text NOT NULL, -- 英文例句
text_zh text, -- 中文翻译
source_desc text, -- 来源说明
PRIMARY KEY (entry_id, exam_id, position)
);
CREATE TABLE confusable_word (
confusable_id bigint PRIMARY KEY, -- 易混词主键(代理)
entry_id bigint NOT NULL REFERENCES word_entry(entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词条 id
position smallint NOT NULL, -- 顺序
word_text varchar(256) NOT NULL, -- 易混词文本
gloss_zh text, -- 中文释义
pos_code smallint, -- 源词性编码
spelling_flag varchar(8), -- 拼写标记
UNIQUE (entry_id, word_text)
);
CREATE TABLE morpheme (
morpheme_id bigint PRIMARY KEY, -- 词素主键(统一代理)
morpheme_type varchar(8) NOT NULL CHECK (morpheme_type IN ('prefix','root','suffix')), -- 词素类型:prefix/root/suffix
source_morpheme_id bigint NOT NULL, -- 源表内 id
form varchar(64), -- 词素形式
display_text varchar(256) NOT NULL, -- 原始展示文本
meaning_en varchar(256), -- 英文释义
meaning_zh varchar(256), -- 中文释义
note varchar(256), -- 备注
UNIQUE (morpheme_type, source_morpheme_id)
);
CREATE TABLE card (
card_id bigint PRIMARY KEY, -- 卡片主键
word varchar(256) NOT NULL, -- 单词
highlighted_word text, -- 高亮 HTML 快照
memory_note text, -- 记忆提示
example_text text, -- 例句文本
prefix_morpheme_id bigint REFERENCES morpheme(morpheme_id) DEFERRABLE INITIALLY DEFERRED, -- 前缀词素 id
root_morpheme_id bigint REFERENCES morpheme(morpheme_id) DEFERRABLE INITIALLY DEFERRED, -- 词根词素 id
suffix_morpheme_id bigint REFERENCES morpheme(morpheme_id) DEFERRABLE INITIALLY DEFERRED, -- 后缀词素 id
default_family_ref bigint, -- 旧版词族引用,不可解析,无外键
is_hidden boolean NOT NULL DEFAULT FALSE -- 是否隐藏
);
CREATE TABLE card_exam (
card_id bigint NOT NULL REFERENCES card(card_id) DEFERRABLE INITIALLY DEFERRED, -- 卡片 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
PRIMARY KEY (card_id, exam_id)
);
CREATE TABLE word_family (
family_entry_id bigint PRIMARY KEY, -- 词族词条主键
top_family_id bigint NOT NULL REFERENCES word_family(family_entry_id) DEFERRABLE INITIALLY DEFERRED, -- 顶层词族 id,自引用
word varchar(256) NOT NULL, -- 单词
highlighted_word text, -- 高亮 HTML 快照
interpretation text, -- 词性 + 中文释义
prefix_morpheme_id bigint REFERENCES morpheme(morpheme_id) DEFERRABLE INITIALLY DEFERRED, -- 前缀词素 id
suffix_morpheme_id bigint REFERENCES morpheme(morpheme_id) DEFERRABLE INITIALLY DEFERRED, -- 后缀词素 id
group_level_1 smallint, -- 分组层级 1
group_level_2 smallint, -- 分组层级 2
group_level_3 smallint -- 分组层级 3
);
CREATE TABLE word_family_exam (
family_entry_id bigint NOT NULL REFERENCES word_family(family_entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词族词条 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
PRIMARY KEY (family_entry_id, exam_id)
);
CREATE TABLE word_family_exam_order (
family_entry_id bigint NOT NULL REFERENCES word_family(family_entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词族词条 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
position integer NOT NULL, -- 分考试顺序
PRIMARY KEY (family_entry_id, exam_id)
);
CREATE TABLE word_family_variant (
variant_id bigint PRIMARY KEY, -- 变体主键
variant_word varchar(256) NOT NULL, -- 变体词
family_entry_id bigint NOT NULL REFERENCES word_family(family_entry_id) DEFERRABLE INITIALLY DEFERRED, -- 所属词族词条 id
top_family_id bigint NOT NULL REFERENCES word_family(family_entry_id) DEFERRABLE INITIALLY DEFERRED, -- 顶层词族 id
highlighted_word text, -- 高亮 HTML 快照
interpretation text, -- 词性 + 中文释义
prefix_morpheme_id bigint REFERENCES morpheme(morpheme_id) DEFERRABLE INITIALLY DEFERRED, -- 前缀词素 id
suffix_morpheme_id bigint REFERENCES morpheme(morpheme_id) DEFERRABLE INITIALLY DEFERRED -- 后缀词素 id
);
CREATE TABLE word_family_variant_member (
variant_id bigint NOT NULL REFERENCES word_family_variant(variant_id) DEFERRABLE INITIALLY DEFERRED, -- 变体 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
position smallint NOT NULL, -- 顺序
member_word varchar(256) NOT NULL, -- 成员词
is_placeholder boolean NOT NULL DEFAULT FALSE, -- 是否为 * 占位符
PRIMARY KEY (variant_id, exam_id, position)
);
CREATE TABLE word_family_mini_group (
mini_group_id bigint PRIMARY KEY, -- 小组主键
size smallint NOT NULL -- 小组成员数
);
CREATE TABLE word_family_mini_group_member (
mini_group_id bigint NOT NULL REFERENCES word_family_mini_group(mini_group_id) DEFERRABLE INITIALLY DEFERRED, -- 小组 id
family_entry_id bigint NOT NULL REFERENCES word_family(family_entry_id) DEFERRABLE INITIALLY DEFERRED, -- 词族词条 id
position smallint NOT NULL, -- 组内顺序
PRIMARY KEY (mini_group_id, family_entry_id)
);
CREATE TABLE card_family_link (
link_id bigint PRIMARY KEY, -- 关联主键
card_id bigint NOT NULL REFERENCES card(card_id) DEFERRABLE INITIALLY DEFERRED, -- 卡片 id
group_no smallint NOT NULL, -- 分组编号(1-50)
family_ref bigint, -- 旧版词族引用,不可解析,无外键
is_hidden boolean NOT NULL DEFAULT FALSE -- 是否隐藏
);
CREATE TABLE synonym_word (
word_id bigint PRIMARY KEY, -- 近义词词头主键
word varchar(256) NOT NULL -- 单词
);
CREATE TABLE synonym_sense (
sense_id bigint PRIMARY KEY, -- 近义词义项主键
word_id bigint NOT NULL REFERENCES synonym_word(word_id) DEFERRABLE INITIALLY DEFERRED, -- 词头 id
part_of_speech varchar(32), -- 词性
gloss_zh text -- 中文释义
);
CREATE TABLE synonym_group (
sense_id bigint NOT NULL REFERENCES synonym_sense(sense_id) DEFERRABLE INITIALLY DEFERRED, -- 近义词义项 id
exam_id bigint NOT NULL REFERENCES exam(exam_id) DEFERRABLE INITIALLY DEFERRED, -- 考试 id
canonical_word_id bigint REFERENCES synonym_word(word_id) DEFERRABLE INITIALLY DEFERRED, -- 规范词 id(源 free),可为空
member_count smallint NOT NULL, -- 近义词成员数
PRIMARY KEY (sense_id, exam_id)
);
CREATE TABLE synonym_group_member (
sense_id bigint NOT NULL, -- 近义词义项 id
exam_id bigint NOT NULL, -- 考试 id
position smallint NOT NULL, -- 组内顺序
member_word_id bigint NOT NULL REFERENCES synonym_word(word_id) DEFERRABLE INITIALLY DEFERRED, -- 成员词 id
PRIMARY KEY (sense_id, exam_id, position),
FOREIGN KEY (sense_id, exam_id) REFERENCES synonym_group(sense_id, exam_id) DEFERRABLE INITIALLY DEFERRED
);
CREATE TABLE synonym_antonym (
sense_id bigint NOT NULL, -- 近义词义项 id
exam_id bigint NOT NULL, -- 考试 id
position smallint NOT NULL, -- 组内顺序
antonym_word_id bigint NOT NULL REFERENCES synonym_word(word_id) DEFERRABLE INITIALLY DEFERRED, -- 反义词 id
PRIMARY KEY (sense_id, exam_id, position),
FOREIGN KEY (sense_id, exam_id) REFERENCES synonym_group(sense_id, exam_id) DEFERRABLE INITIALLY DEFERRED
);
```
---
## 11. 一键导入脚本
脚本:`import_lexis.py`(与本模型同步实现,支持 SQLite / PostgreSQL / MySQL)。
### 11.1 运行方式
```bash
# 默认 SQLite,零依赖
python import_lexis.py --recreate
# 指定 SQLite 文件
python import_lexis.py --db sqlite --sqlite-path D:/data/lexis.db --recreate
# PostgreSQL(需 pip install psycopg2-binary)
python import_lexis.py --db postgres \
--dsn "postgresql://user:pass@127.0.0.1:5432/lexis" --recreate
# MySQL(需 pip install pymysql)
python import_lexis.py --db mysql \
--dsn "mysql://user:pass@127.0.0.1:3306/lexis?charset=utf8mb4" --recreate
```
### 11.2 行为说明
| 行为 | 说明 |
|---|---|
| 数据范围 | 只读 `wordbooks/decrypted`、`zpk/decrypted`、`wordroot-export`、`book-catalog.json`,跳过所有 `original` 加密目录 |
| 词条版本 | 每个 `entry_id` 取文件名时间戳最新的 zpk 作为 `word_entry` 内容;`book_entry.source_zpk_key` 仍保留各词书实际引用的版本键 |
| 缺失 zpk | `0_53785_101_1775241011` 写入占位 `word_entry`,保证 `book_entry` 外键成立 |
| 主键 | 所有代理主键由脚本按确定性顺序分配,全部为 `bigint` |
| 外键 | 只引用 `*_id`;`exam_code` / `book_code` 仅作业务唯一键 |
| 批量写入 | 默认 20,000 行/批;每批按依赖顺序刷盘,兼容 MySQL 即时外键 |
| 数据库差异 | SQLite 关闭外键检查并在结束后执行 `PRAGMA foreign_key_check`;MySQL 导入期间关闭 `FOREIGN_KEY_CHECKS`;PostgreSQL 使用 `DEFERRABLE INITIALLY DEFERRED` |
| 索引 | 数据导入完成后统一创建,避免拖慢写入 |
| 调试 | `--limit-books N` 只导入前 N 本词书 |
### 11.3 实测结果
- SQLite 全量:3,642,355 行,约 53 秒。
- 导入后外键校验通过。
---
## 12. 统计结论速查
### 12.1 源文件口径
| 指标 | 数值 |
|---|---:|
| 词书目录条目 | 1,025 |
| 有清单文件的词书 | 1,024 |
| 词书词条关联行 | 1,228,421 |
| 唯一词条(`id`) | 38,116 |
| 唯一 `index_word` | 38,000 |
| zpk JSON 文件(含同一词条多版本) | 143,200 |
| 被引用但缺失的 zpk | 1 |
| 卡片 | 12,003 |
| 词族词条 | 22,717 |
| 顶层词族数 | 5,629 |
| 词族变体 | 288 |
| 词族小组 | 37,984 |
| 近义词词头 / 义项 | 6,279 / 8,383 |
| 带结构化义项的文件(全部版本) | 134,556 |
| 带 `exam_sentences` 键的文件 | 82,032(多数为空数组) |
| 带易混词结构(v2)的文件 | 81,698 |
| 普通释义例句块(全部 143,200 个文件) | 约 470,000 |
### 12.2 实际落库口径(每个 `entry_id` 取最新 zpk 版本)
| 表 | 行数 |
|---|---:|
| `book` | 1,025 |
| `book_entry` | 1,228,421 |
| `word_entry` | 38,116 |
| `word_sense` | 53,642 |
| `sense_object` | 53,880 |
| `phrase` | 27,923 |
| `example_group` | 69,348 |
| `example_usage` | 71,964 |
| `example_sentence` | 235,744 |
| `entry_exam_sentence` | 3,282 |
| `confusable_word` | 158,870 |
| `card` | 12,003 |
| `word_family` | 22,717 |
| `word_family_variant` | 288 |
| `word_family_mini_group_member` | 101,278 |
| `synonym_sense` | 8,383 |
| `synonym_group_member` | 188,003 |
| **合计** | **3,642,355** |
> 全量导入耗时约 53 秒(SQLite,批量 20,000),导入后 `PRAGMA foreign_key_check` 通过。以上数字由 `import_lexis.py` 实测得出。
---
> 本文档以实际文件内容为准,`wordroot-schema.md` 中的旧行数、旧字段说明仅作参考。所有“推断”性语义(如 `group_kind` 1/2/3/4、`group_type` 1/2)均已标注观察依据,落库后应结合应用查询逻辑复核。