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

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

151 lines
5.0 KiB
Markdown

# 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 一对一对应,并完整保留解密得到的全部业务字段。