Files
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

65 KiB
Raw Permalink Blame History

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 四个业务域

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")。导入时应写入异常表或按异常丢弃。

来源: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)

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)

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. 建议索引

-- 域 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 只作业务唯一键。


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 运行方式

# 默认 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)均已标注观察依据,落库后应结合应用查询逻辑复核。