From 131c2b6353daa9cfa4b40648117eaccbe71374ef Mon Sep 17 00:00:00 2001 From: void Date: Sun, 8 Nov 2026 21:16:04 +0800 Subject: [PATCH] =?UTF-8?q?docs(importer):=20=E8=A1=A5=E5=85=85=E5=AF=BC?= =?UTF-8?q?=E5=87=BA=E6=B5=81=E7=A8=8B=E3=80=81=E6=95=B0=E6=8D=AE=E6=A8=A1?= =?UTF-8?q?=E5=9E=8B=E4=B8=8E=20ZPK=20=E5=86=85=E5=AE=B9=E5=88=86=E6=9E=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README:三步流程、接口与下载地址、破解参数、日常命令与性能说明 - DATA-MODEL:词书/词条及关联数据的实体关系 - zpk-decrypted-content-analysis:ZPK 解密后的字段结构分析 Co-Authored-By: Claude Sonnet 4.6 --- importer/README.md | 295 ++++ importer/docs/DATA-MODEL.md | 1363 +++++++++++++++++ .../docs/zpk-decrypted-content-analysis.md | 150 ++ 3 files changed, 1808 insertions(+) create mode 100644 importer/README.md create mode 100644 importer/docs/DATA-MODEL.md create mode 100644 importer/docs/zpk-decrypted-content-analysis.md diff --git a/importer/README.md b/importer/README.md new file mode 100644 index 0000000..ca149aa --- /dev/null +++ b/importer/README.md @@ -0,0 +1,295 @@ +# Lexis Export Toolkit + +> 本目录是 `word-market` monorepo 的 `importer` 子项目。以下命令均在 `importer/` 目录下执行。 + +这个目录是“不背单词 / Lexis”离线导出工具包。整个流程三步,每步产出都是可读明文: + +1. 下载词书目录(游客态接口,产出可读 JSON) +2. 逐个下载所有词书,解密并导出单词(产出可读 SQLite / CSV) +3. 逐个下载所有词书所有单词的 ZPK,并解密为 JSONL(产出可读 JSONL) + +解密逻辑抽成独立工具(`decrypt-sqlcipher2-db.py`、`decrypt-zpk-aes.py`),可单独调用,也被步骤 2/3 复用。 + +## 环境 + +- Windows + PowerShell +- Python 3.10+ +- Python 依赖:`pycryptodome` +- 不依赖 `adb`:主流程已完全走游客态 HTTP 接口与静态 CDN,不再从设备拉取数据 +- 可选:`bin\jadx-1.5.6`,只在复核 APK / `libcommon.so` 常量时需要 + +安装依赖: + +```powershell +pip install pycryptodome +``` + +## 目录 + +```text +README.md +run.py # 一键逐个执行三步流程 +src\ + fetch-book-catalog.py # 步骤1:从服务端拉取词书目录(游客态接口) + download-wordbooks.py # 步骤2:逐个下载词书、解密并导出单词与 zpk 字段 + download-zpk.py # 步骤3:从词表去重后逐个下载所有 ZPK 并解密为 JSONL + decrypt-sqlcipher2-db.py # 独立工具:离线解密单个 SQLCipher2 词书 DB(可单独调用) + decrypt-zpk-aes.py # 独立工具:离线解密 ZPK 为 JSONL(可单独调用) + archive\ # 已归档:旧版分步工具(download-all-wordbooks.py、download-all-zpk.py、export-wordbook-words.py、export-word-zpk-index.py 等) +output\ # 统一输出目录(三步流程的所有产物) + book-catalog.json # 步骤1 产出(可读) + book-catalog-full.json # 步骤1 产出(可读) + databases\ # 步骤2 原始加密 DB(中间缓存,非最终产出) + decrypted-databases\ # 步骤2 解密后 DB(可读) + wordbook-words\ # 步骤2 每本词书单词 CSV(可读) + all-wordbook-words.csv # 步骤2 全量词表(可读,步骤3 输入) + unique-zpk-index.csv # 步骤3 去重 ZPK 索引(可读) + zpk-cache\0\ # 步骤3 加密 ZPK(中间缓存,非最终产出) + zpk-jsonl\ # 步骤3 解密后 JSONL(可读) + wordbook-download-report.csv # 步骤2 下载报告 + wordbook-word-summary.csv # 步骤2 导出报告 + zpk-download-report.csv # 步骤3 下载/解密报告 +bin\ + is_cool_lexis_5_11_1_1787132405511.apk + jadx-1.5.6\ +``` + +## 关键路径 + +- 原始 APK:`bin\is_cool_lexis_5_11_1_1787132405511.apk` +- 词书目录:`output\book-catalog.json`(精简字段,可读) +- 词书目录全量:`output\book-catalog-full.json`(接口原始 tabs/books) +- 原始词书 DB:`output\databases\LangEasyLexisV3_.db`(中间缓存) +- 解密后词书 DB:`output\decrypted-databases\LangEasyLexisV3_.sqlite`(可读) +- 全量词表:`output\all-wordbook-words.csv`(可读) +- 唯一 ZPK 索引:`output\unique-zpk-index.csv`(可读) +- ZPK 缓存:`output\zpk-cache\0\*.zpk`(中间缓存) +- ZPK 解密输出:`output\zpk-jsonl\zpk-decrypted.jsonl`(可读) +- 下载报告:`output\wordbook-download-report.csv`、`output\zpk-download-report.csv` + +## 完整流程 + +整个流程三步:下载词书目录 -> 逐个下载所有词书 -> 逐个下载所有词书所有单词的 ZPK。 + +一键顺序执行三步(任一步失败即停): + +```powershell +python run.py +``` + +也可单独执行每一步(以下是三个步骤的命令): + +步骤1:拉取词书目录(游客接口,无需登录/设备): + +```powershell +python src\fetch-book-catalog.py +``` + +步骤2:逐个下载所有词书(下载 zip -> 校验 MD5 -> 解包 -> 解密 DB -> 导出单词与 zpk 字段): + +```powershell +python src\download-wordbooks.py --workers 16 +``` + +步骤3:从全量词表去重后逐个下载所有 ZPK,并解密为 JSONL(断点续传): + +```powershell +python src\download-zpk.py --workers 96 --timeout 6 --progress-every 1000 +``` + +离线解密已下载的 ZPK(独立工具,可单独调用,非必要): + +```powershell +python src\decrypt-zpk-aes.py --output output\zpk-jsonl\zpk-decrypted.jsonl +``` + +## 词书列表接口 + +词书目录不再依赖设备偏好文件,直接走游客态接口拉取: + +```text +GET https://api.beingfine.cn/v3/3/bb/wordbooks/for-guest/{timestamp} +``` + +请求参数(query): + +```text +type=3/bb/wordbooks/for-guest +app_id=600000001 +udid=<任意,可为空> +umid=<任意,可为空> +version=5.11.1 +user_id=0 +channel=isCool +timestamp={当前毫秒时间戳} +timezone=480 +pad=0 +token=tk85bf4d7d70a4d5028187ba6dfb3649 +``` + +请求头: + +```text +Referer: https://app.bbdc.cn +User-Agent: LangEasyLexis/5.11.1 +``` + +响应为明文 JSON,`result_code=200`,`data_body` 是字符串形式的 JSON, +包含 `tabs`(分类)、`books`(全部词书,约 1000 本)、`last_update_time`。 +该接口不校验 `sign`、`udid`、`umid`,无需逆向签名算法。 + +实现位置:`src\fetch-book-catalog.py`。 + +## 词书 DB 破解信息 + +词书 DB 是 SQLCipher2 风格分页加密: + +- key:`arsenal iscool` +- page size:`1024` +- reserve:`48` +- KDF:`PBKDF2-HMAC-SHA1` +- iterations:`4000` +- 每页 IV:页面尾部 reserve 区前 16 字节 + +实现位置:`src\decrypt-sqlcipher2-db.py`(独立工具,`download-wordbooks.py` 会导入复用)。 + +`src\archive\derive-lexis-db-keys.py`(已归档,日常流程不需要)用来复核 `libcommon.so` 中 `getDBKey()` 的常量派生。它默认读取 APK 反编译资源里的: + +```text +jadx-out\resources\lib\x86\libcommon.so +``` + +如果以后要复核 key 派生,先用 `bin\jadx-1.5.6` 重新反编译 `bin\is_cool_lexis_5_11_1_1787132405511.apk` 生成 `jadx-out`。 + +## 词书下载 + +词书 DB zip 走静态 CDN: + +```text +{cdn_base}/dicts/v3/{code}/{version}/LangEasyLexisV3_{code}.db.zip +``` + +可用 CDN: + +```text +http://static.beingfine.cn +https://hwstatic.beingfine.cn +https://ccastatic.beingfine.cn +``` + +请求头: + +```text +Referer: https://app.bbdc.cn +User-Agent: LangEasyLexis/5.11.1 +``` + +下载工具会校验 `Content-MD5`,并自动 fallback 到下一个 CDN。 + +## ZPK 下载 + +ZPK 文件走静态 CDN: + +```text +{cdn_base}/r/{zpkName}.zpk +``` + +`zpkName` 来自词书数据库的 `zpk` 字段,格式: + +```text +{bid}_{word_id}_{version}_{updated_unix} +``` + +下载工具同样支持断点续传、`Content-MD5` 校验和 CDN fallback。 + +## ZPK 解密算法 + +`.zpk` 是 protobuf field 1 包住的 AES 密文: + +```text +.zpk + -> protobuf field 1 bytes: AES-256-CBC ciphertext + -> key = md5(word).hexdigest().encode("ascii") + -> iv = b"IscoolInitVector" + -> PKCS7/PKCS5 unpad + -> protobuf field 1 bytes: UTF-8 JSON +``` + +Python 等价实现: + +```python +import hashlib +from Crypto.Cipher import AES +from Crypto.Util.Padding import unpad + +key = hashlib.md5(word.encode("utf-8")).hexdigest().encode("ascii") +iv = b"IscoolInitVector" +plaintext = AES.new(key, AES.MODE_CBC, iv).decrypt(ciphertext) +plaintext = unpad(plaintext, 16) +``` + +实现位置:`src\decrypt-zpk-aes.py`。 + +## 日常命令 + +继续下载缺失 ZPK(已下载的自动跳过,已解密的自动跳过下载与解密): + +```powershell +python src\download-zpk.py --workers 96 --timeout 6 --progress-every 1000 +``` + +重新离线解密已下载的 ZPK(覆盖写): + +```powershell +python src\decrypt-zpk-aes.py --output output\zpk-jsonl\zpk-decrypted.jsonl +``` + +重新导出词表(下载已存在则跳过,只重跑解密与导出): + +```powershell +python src\download-wordbooks.py --workers 16 +``` + +单独解密一个词书 DB(独立工具): + +```powershell +python src\decrypt-sqlcipher2-db.py output\databases\LangEasyLexisV3_.db output\decrypted-databases\LangEasyLexisV3_.sqlite +``` + +`download-zpk.py` 每次运行都会从 `all-wordbook-words.csv` 重建 `unique-zpk-index.csv`,无需单独生成索引。 + +## 当前状态 + +- 三步流程输出统一到 `output\`,每步产出都是可读明文;加密产物(`databases\`、`zpk-cache\0\`)仅作为断点续传的中间缓存。 +- 完整跑完:`output\unique-zpk-index.csv` 约 115104 个唯一 ZPK 名,`output\zpk-jsonl\zpk-decrypted.jsonl` 是最终可读解密产物。 +- 旧的动态调试、native trace、内存采样脚本已清理;当前 ZPK 正文算法不依赖真机调试。 + +## 下载性能与中断 + +`src\download-zpk.py` 已改成长连接 worker 池: + +- 默认并发:`64` +- 推荐并发:`64` 到 `96`;如果本机网络和 CDN 都稳,可以试 `128` +- 推荐请求超时:`--timeout 6` +- 每个 worker 会复用到 CDN 的 HTTP keep-alive 连接,避免每个小 ZPK 都重新握手 +- 默认 `--cdn-mode primary` 会优先使用 HTTP 主 CDN;如果主 CDN 被限速,可以试 `--cdn-mode spread` +- 任务队列只保留少量待下载项,内存占用稳定,`Ctrl+C` 后不会等待海量 Future 收尾 +- 按 `Ctrl+C` 会停止继续投递任务,写出部分报告,并以退出码 `130` 结束 + +如果 `Ctrl+C` 后仍短暂卡住,是正在执行的少量 HTTP 请求还在等待 socket 超时;把 `--timeout` 降到 `3` 到 `5` 可以更快退出: + +```powershell +python src\download-zpk.py --workers 96 --timeout 5 --progress-every 1000 +``` + +如果主 CDN 明显限速,可以分散到 3 个 CDN 试一次: + +```powershell +python src\download-zpk.py --workers 96 --timeout 5 --progress-every 1000 --cdn-mode spread +``` + +冒烟测试不要覆盖正式报告时可以单独指定报告路径: + +```powershell +python src\download-zpk.py --limit 20 --out-dir output\zpk-cache-test\0 --jsonl output\zpk-jsonl-test\zpk-decrypted.jsonl --report output\zpk-download-smoke-report.csv +``` diff --git a/importer/docs/DATA-MODEL.md b/importer/docs/DATA-MODEL.md new file mode 100644 index 0000000..2a49205 --- /dev/null +++ b/importer/docs/DATA-MODEL.md @@ -0,0 +1,1363 @@ +# 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` | 含 `` 高亮标签 | +| `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.` | `synonym_group` / `synonym_group_member` / `synonym_antonym`,`exam_id`(`bigint`) | 列转行 + 拆分 | +| `synonym_data..free` | `synonym_group.canonical_word_id`(`bigint`) | | +| `synonym_data..syn` | `synonym_group_member` | | +| `synonym_data..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)均已标注观察依据,落库后应结合应用查询逻辑复核。 diff --git a/importer/docs/zpk-decrypted-content-analysis.md b/importer/docs/zpk-decrypted-content-analysis.md new file mode 100644 index 0000000..df8e497 --- /dev/null +++ b/importer/docs/zpk-decrypted-content-analysis.md @@ -0,0 +1,150 @@ +# ZPK 解密内容分析报告 + +## 1. 报告范围 + +本报告分析 `output/zpk/decrypted/` 下的 ZPK 解密结果,分析对象为每个 ZPK 对应的独立 JSON 文件。 + +分析时间:2026-09-03 + +## 2. 产物概况 + +| 项目 | 结果 | +| --- | --- | +| 解密文件数量 | 139,296 个 | +| 文件总大小 | 2,380,901,642 字节,约 2.22 GiB | +| 文件格式 | UTF-8 JSON | +| 文件组织 | 一个原始 `.zpk` 对应一个解密 `.json` | +| 聚合情况 | 不使用 JSONL 或汇总文件 | + +文件名保持基础名称一致,仅扩展名不同: + +```text +zpk/original/0_100001_35_1689360732.zpk +zpk/decrypted/0_100001_35_1689360732.json +``` + +## 3. 顶层字段 + +根据解密样本,JSON 顶层包含以下业务字段: + +| 字段 | 类型 | 内容 | +| --- | --- | --- | +| `meta` | object | 词条元数据,如考试分类、数据版本 | +| `word` | string | 英文单词或词组 | +| `us_pron` | string | 美式音标 | +| `uk_pron` | string | 英式音标 | +| `spell` | array | 拼写或词形相关数据 | +| `confuse` | array | 易混淆词列表 | +| `confuse_exps` | array | 易混淆词对应的解释 | +| `interpret` | string | 词条释义文本 | +| `phrase` | array | 短语数据,包含短语、类型和序号信息 | +| `example` | string | JSON 编码的例句数据 | +| `zpk` | string | ZPK 文件标识 | + +解密结果还保留了 `raw` 字段。该字段是解密得到的完整内层 JSON 对象副本,用于确保原始业务信息没有因结构化导出而丢失。 + +## 4. 重点数据结构 + +### 4.1 `meta` + +典型结构如下: + +```json +{ + "book_exam": "", + "data_version": "1.0" +} +``` + +`meta` 用于描述词条所属分类及数据版本。字段可能因词条版本不同而变化,读取程序不应假设所有字段都存在。 + +### 4.2 词形与发音 + +- `word` 保存主词条。 +- `us_pron` 与 `uk_pron` 保存美式、英式发音标记。 +- `spell` 为数组,当前样本中可能为空数组。 + +这些字段应按原值保存,不应进行清洗、转写或字段删减。 + +### 4.3 释义 + +`interpret` 为包含词性的中文释义文本,可能包含换行符、多个词性以及特殊标点。例如一个词条可能同时包含名词、动词和形容词释义。 + +因此,导出或二次处理时不能按单行文本处理,也不能仅保留第一条释义。 + +### 4.4 易混淆词 + +`confuse` 与 `confuse_exps` 为两个相互关联的数组: + +- `confuse`:易混淆词。 +- `confuse_exps`:与易混淆词按位置对应的解释。 + +读取时应保留数组顺序;当两个数组长度不一致时,应保留原始数组,不应强行补齐或删除元素。 + +### 4.5 短语 + +`phrase` 是对象数组。对象可能包含: + +| 字段 | 类型 | 含义 | +| --- | --- | --- | +| `p` | array | 短语内容 | +| `t` | number | 短语类型 | +| `pseqs` | object | 短语序号或关联信息 | + +即使 `p` 为空,也应保留该对象,因为其类型和序号信息仍属于原始数据。 + +### 4.6 例句 + +`example` 在当前数据中是一个 JSON 字符串,而不是直接嵌套的 JSON 对象。其内部通常包含: + +```json +{ + "v": 1, + "data": [ + { + "type": "99", + "i": {}, + "g": [ + { + "eid": "例句标识", + "e": "英文例句", + "c": "中文翻译", + "fid": "媒体或资源标识", + "sid": "句子标识", + "i": "图片资源路径", + "b": "来源书名", + "u": "音频资源路径", + "s": 0 + } + ] + } + ] +} +``` + +例句记录可能包含英文文本、中文翻译、图片路径、音频路径、来源书名及多个内部 ID。处理程序应先将 `example` 作为字符串保留;如需解析,应在副本上执行 JSON 解析。 + +## 5. 解密结果完整性要求 + +当前解密流程应遵循以下规则: + +1. 原始 `.zpk` 文件只读,不覆盖、不重写。 +2. 每个 `.zpk` 只生成一个对应的 `.json` 文件。 +3. 解密结果保留内层 JSON 的全部字段。 +4. 保留空数组、空对象、换行符、特殊字符和资源路径。 +5. 不将多个 ZPK 合并为 JSONL、CSV 或其他汇总文件。 +6. `zpk`、`zpk_path`、`index_word`、`book_occurrences` 等流程元信息如存在,应与原始业务字段并存,不得替换原始字段。 + +## 6. 数据使用建议 + +- 读取 JSON 时使用 UTF-8 编码。 +- 对未知字段采用兼容读取方式,不因字段缺失而使整批任务失败。 +- 例句字段需要二次解析时,应捕获 JSON 解析异常,并保留原始字符串。 +- 不建议基于 `definition_count` 或 `phrase_count` 等派生统计字段替代原始数组内容。 +- 文件级处理应以 ZPK 文件名作为稳定主键。 + +## 7. 结论 + +ZPK 解密文件是以单词为中心的词典扩展数据,核心内容包括发音、释义、易混淆词、短语和例句资源。数据中存在嵌套 JSON 字符串、空数组和资源引用等情况,不能按扁平表格进行无损替代。 + +当前推荐的存储方式为原始 ZPK 与独立解密 JSON 一对一对应,并完整保留解密得到的全部业务字段。