docs(importer): 补充导出流程、数据模型与 ZPK 内容分析
- README:三步流程、接口与下载地址、破解参数、日常命令与性能说明 - DATA-MODEL:词书/词条及关联数据的实体关系 - zpk-decrypted-content-analysis:ZPK 解密后的字段结构分析 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
1 parent
f03ef43c21
commit
131c2b6353
3 files changed
+1808
No files matched your search
File diff suppressed because it is too large.
Load diff
@@ -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 一对一对应,并完整保留解密得到的全部业务字段。
|
||||
Reference in new issue
Block a user