语言学田调录音助手（Wanluk）

1. 基本设计

• 参考对象：北语录音软件的字例导入、录音、文件管理；交互气质对标「不背单词」——大字号、极简控件、一键「下一字/词」。
• 音韵框架：字例坐标为传统音韵学六维（声、呼、等、韵、调、摄），摄（she）为字库浏览的一级分组维度。
• 一期范围：本地字库、作业列表、沉浸式连续录音、录音打包分享；不做云端同步与中台上传。
• 跨端：单模块 :app 先行；二期再评估 KMP 拆 shared。
• 存储策略：应用专属目录 context.getExternalFilesDir()，Android 11+ 不申请 broad storage。

---

2. 功能设计

2.1 字例管理模块

2.1.1 核心字段（Room）

抛弃字表中冗余的历史注音与方言罗马字，只保留田调坐标与展示内容。

字段名	数据库列	类型	说明	必选
聲	sheng	String	声母（端、透、泥等）	是
呼	hu	String	开口 / 合口 / 齐齿 / 撮口	是
等	deng	Int	一 / 二 / 三 / 四等（存 1–4）	是
韻	yun	String	韵部（东、冬、钟等）	是
調	diao	String	平 / 上 / 去 / 入	是
攝	she	String	韵摄（通、江、止等）	是
組	zu	String?	韵组（辅助分类）	否
例字	core_char	String	核心单字	是
组词	phrases	String?	多个组词用英文逗号 , 分隔；当前内置字表无此列，导入为 null	否
备注	remark	String?	调查备注 / 字表原注 / 特殊发音说明	否
罕度	rarity	Int	0–3，越小越常见；来自内置字表「罕度」列	是（内置库）

逻辑主键：同一「音韵坐标 + 例字」可对应多条记录（多音字、又音）。表内使用自增 id；作业列表引用 id 列表，避免仅用 core_char 去重。

2.1.2 本地存储（已定案：Room 为唯一主存）

项	一期决议
主存储	仅 Room；不做 JSON 主存再迁库的降级路径
Gson	仅用于 CSV/JSON 导入导出与备份，不用于日常读写
Protobuf	二期再评估（跨端 / 后端契约）
UI 列表	LazyColumn + 按 she 的 stickyHeader 分组
缺字补充	字库页 FAB「快速建字」，写入 WordCaseDao.insertWordCases

分层：UI (Compose) → ViewModel → WordCaseRepository → WordCaseDao / CsvImporter

Room 使用要点：

1. 首次启动若 word_cases 为空：从 assets/WordCaseList.csv 解析，事务批量 insertWordCases。
2. 字库页订阅 getAllWordCases() 或 getWordCasesByShe / getWordCasesByYun 的 Flow。
3. Schema 变更走 Room Migration；exportSchema 建议二期改为 true 便于审查。

建议索引（首次迁移）：she、yun、core_char；可选 (sheng, yun, diao) 组合筛选。

2.1.3 内置字表：WordCaseList.csv 数据契约

资产路径：:foundation/src/main/assets/WordCaseList.csv（合并进 APK 后通过 assets/WordCaseList.csv 读取）。

项	现状
编码	UTF-8 带 BOM（便于 Excel 编辑；导入器会跳过 BOM）
数据行	10292 条（含主表与两批补充字条；多读音已拆为独立行）
表头列数	11 列

表头与落库映射

CSV 列名	落库字段	转换规则
聲	sheng	原样；空则触发「续行规则」
呼	hu	原样
等	deng	一→1, 二→2, 三→3, 四→4（导入层转换）
韻	yun	原样
調	diao	原样
組	zu	可空
攝	she	原样
單字	core_char	原样
多音	—	不入库；见下方语义
原註	remark	非空则写入
罕度	rarity	整数 0–3（0 最常见，3 最罕见/表外字）

罕度划分（当前字表）

• 依据《通用规范汉字表》一、二级字表及表外字；繁体按简繁对应关系标注。
• 一级字再细分为 0（较常用）与 1（次常用）；二级字多为 2；两表皆无者为 3。
• 当前分布约：0 → 3066，1 → 1105，2 → 3404，3 → 2717。

多音 列语义（0 / 1）

• 多音=0：常规范式，音韵坐标齐全。
• 多音=1 且坐标齐全：同一 單字 的独立音韵条目（如「中」平上去各一条）。
• 坐标为空（续行）：继承上一条非空音韵行的七维坐标（聲–攝），仍生成独立 id（例：「僮」书僮义与「僮族」义分两行）。

导入伪代码（内置库）

lastCoords = null
for each dataRow:
  coords = parse 聲..攝
  if coords all empty and lastCoords != null:
    coords = lastCoords
  else if coords any non-empty:
    lastCoords = coords
  else: skip
  entity = map(coords, 單字, 原註→remark, 罕度→rarity, deng 中文→Int)
  buffer.add(entity)
insertWordCases(buffer) // 单事务

解析注意

• 使用 YunmuCsvImporter：按固定 11 列索引解析；多音 列跳过；兼容 UTF-8 BOM。
• 内置库行数应为 10292；与库内计数不一致时会清空并重导（仅内置 demo 阶段策略）。
• 用户自定义 CSV 一期要求字段内不含未转义逗号（引号转义放二期）。

自定义 CSV 导入（用户字库）

• 表头与上表「落库列」一致或为其子集；罕度 可省略（默认 0）。
• UTF-8、逗号分隔；编码与列契约不符时拒绝导入并提示。
• JSON 备份：与 WordCaseEntity 同名字段的对象数组，供导出/恢复，非运行时主存。

2.1.4 分类、筛选、作业与导入格式（已定案）

浏览与筛选

• 默认按 she 分组展示；支持按 yun 二次筛选。
• 一期顶栏搜索：sheng、yun、core_char；呼 / 等 / 调 的 UI 筛选预留，Repository 扩展 SQL。
• 同一 core_char 的多条记录分条展示，勾选作业时展示完整音韵坐标，不合并为一行。

作业列表

• 字库多选 → 生成「本次录音作业」。
• 一期默认：用 DataStore 持久化字例 id 有序列表与当前进度；杀进程后可恢复未完成作业。
• 傻瓜模式：进入作业后全屏录音，仅「录音 / 重录 / 下一字」与进度；按作业内 id 顺序自动前进。

导入方式（对应原稿「按组 / 单字」）

方式	一期	说明
按摄 / 韵浏览多选	是	在分组列表中勾选加入作业
搜索单字 / 声 / 韵	是	顶栏搜索后多选
按「组」一键全选	二期	需「组」级预设包或收藏

「排版格式」决议（原 TODO）
指导入文件的表头命名与列语义，不是 UI 排版。规范即 §2.1.3 映射表；不提供第二套异名列导入。用户 CSV 与内置库共用同一契约。

缺字链路（原 TODO）
字库 FAB → 最小表单（必填：声、呼、等、韵、调、摄、例字）→ insert；可选 zu、phrases、remark；remark 可默认前缀「现场新增」。

二期再放：收藏 / 常用字例、全表或筛选结果导出 JSON/CSV。

2.1.5 拓展能力分期

能力	期别
内置 WordCaseList.csv 灌库	一期
FAB 快速建字	一期
用户 CSV 导入	一期
收藏、字库导出	二期

---

2.2 录音业务模块

2.2.1 录音控制

• 一期仅 MediaRecorder，输出 M4A（AAC）；44.1 kHz / 16 bit / 单声道。
• WAV、AudioRecord 双通路 列为二期。
• 声明 RECORD_AUDIO；长时间录音按实测决定是否前台服务。

2.2.2 文件命名与目录

命名模板（一期：固定模板 + 可配置前缀）

{Prefix}_{Date}_{She}_{Yun}_{Char}_{Count}.m4a

示例：方言点A_20240520_通_东_冻_1.m4a

占位符	含义
Prefix	设置页方言点名前缀
Date	yyyyMMdd
She / Yun	当前字例 she / yun
Char	单字模式 core_char；读词模式为当前词文本
Count	同作业同字例第 n 次录音

目录结构

/Android/data/com.wanluk/files/
├── record/
│   └── {yyyyMMdd}/
│       └── {she}/
│           └── *.m4a
├── .trash/          # 重录移入的旧文件
└── export/          # 打包 ZIP

重录（一期）：同作业、同字例再次保存时，旧文件移入 .trash/ 或追加 _old；当前目录仅保留最新主文件。二期再支持保留全部版本并标记最新。

2.2.3 分享与上传

• 一期：按日期 / 摄 / 自定义勾选打包 ZIP，系统分享面板导出。
• 二期：上传接口、MD5、分片、重试与客户端限流。

---

2.3 录音界面

2.3.1 布局模式

模式	行为
单字模式	例字约占屏高 40%，居中；组词小字在下，/ 分隔
多字网格	用户选 1×2 / 2×2；点格录音，完成后格背景变绿
读词模式	按 , 解析 phrases；词大号、例字小号；{Char} 用当前词。无 phrases 时回退单字模式

2.3.2 控件区（单字默认）

区域	占比	内容
例字/词展示	~40%	大字号主展示
组词	~15%	辅助信息
录音控制	~25%	录音 / 暂停、重录、时长
导航	~20%	上一字 / 下一字、进度 3/50

录音结束后焦点落在「下一字」；支持连续作业流。

2.3.3 拓展（二期）

音量键快捷、双击音韵卡片、波形预览、文件完整性校验。

---

2.4 兼容性与权限

• minSdk 24，targetSdk 36；平板随 Compose 自适应。
• 权限：RECORD_AUDIO 必选；录音写应用专属目录，不申请 broad storage。
• 首次启动分步授权；拒绝后提供跳转系统设置说明。

---

2.5 二期规划

• 字库 / 录音云同步、收藏与完成度统计
• 语音标注与时间轴
• KMP 拆 shared + iOS UI
• Protobuf / 后端契约
• 离线 ASR（可选）

---

3. TODO 处置结论

原 PRD 两处 TODO 已并入 §2.1.2、§2.1.4；此处仅作索引性决议，便于评审追溯。

TODO-1（2.1.2）：Room 如何使用？是否 JSON 降级？

决议：Room 为唯一主存；JSON/CSV 仅作交换与备份。

• 内置 WordCaseList.csv 首次灌库写入 Room，UI 全程读 DAO 的 Flow。
• 不实现「JSON 主存再迁 Room」双轨，避免双份筛选逻辑与数据漂移。
• Gson 保留在依赖中，仅服务导入导出与备份文件。

TODO-2（2.1.4）：导入排版格式？是否提供缺字链路？

决议：契约化 CSV + 一期 FAB 缺字。

• 排版格式 = §2.1.3 表头与列映射；内置库与用户库同一契约。
• 缺字链路 = 字库 FAB 最小表单入库；收藏、全量导出 放二期，控制一期范围。

---

4. 一期开发路线图

阶段	交付物	依赖
P0	Compose BOM、ComponentActivity、MainActivity、Navigation 空壳	—
P1	assets/WordCaseList.csv、CSV 导入器（含续行与 deng 转换）、按 she 字库列表	Room 实体/DAO
P2	顶栏搜索、多选作业列表、DataStore 持久化	P1
P3	沉浸式录音页、MediaRecorder、命名与目录	P2
P4	重录进 .trash、ZIP 分享	P3
P5	FAB 快速建字、用户 CSV 导入	P1

实现约束（与工程一致）

• 包名、路径统一 com.wanluk（勿用旧稿 com.linguistics.recorder）。
• P0 须补齐 Compose 依赖（当前工程为 AppCompat 骨架）。
• 内置 CSV 位于 :foundation/src/main/assets/WordCaseList.csv，随 :foundation 依赖合并进 APK assets。

---

5. 数据层接口补充（一期须实现）

在现有 DAO 能力（insertWordCases、getAllWordCases、getWordCasesByShe、getWordCasesByYun）之上，Repository/DAO 还需：

• 按 core_char、sheng 模糊搜索
• 按作业 id 列表有序查询
• 单条 insert（FAB 缺字）
• 灌库前 COUNT(*)=0 判断，避免重复导入

---

6. 建议下一步

→ /designer：模块包结构、Repository/ViewModel 接口、Navigation 路由、recording_sessions 表草案（二期录音元数据）。

→ /code：从 P0（Compose + MainActivity） 与 P1（assets 灌库） 开始实现。

---

文档版本：2026-06 · 字表行数以 WordCaseList.csv（10292 条数据行）为准。