feat: add local hexagram content for offline reading

Load a versioned Wikisource jing plus project-authored plain drafts so results can show labeled original and vernacular texts without unauthorized modern translations. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-19 11:48:16 +08:00
parent 4235cf9011
commit 534c88993e
33 changed files with 5626 additions and 29 deletions
@@ -2,7 +2,7 @@

 > 文档状态：方案基线
 > 最后核验：2026-08-19
-> 当前阶段：正式产品名“灵机”；P0/P1 已完成；P3 离线主流程（方法说明、起念、手录、卦名/动爻结果）已可走通；P4 仅完成会话级本机保存与设置，问卦簿与本地解释未开始；P2 授权内容未开始；P-1 v0.3 待视觉复核；P5 未开始
+> 当前阶段：正式产品名“灵机”；P0/P1 已完成；P3 离线主流程（方法说明、起念、手录、卦名/动爻结果）已可走通；P4 仅完成会话级本机保存与设置，问卦簿与本地解释未开始；P2 已接入维基文库《易经》原文与项目自撰白话草稿，待内容负责人审校；P-1 v0.3 待视觉复核；P5 未开始

 本目录是 Brainwave 的项目知识事实源。产品决策、领域算法、架构边界、验收标准和已知失败模式必须写入仓库；聊天记录、口头约定和临时提示不构成项目规范。

@@ -22,6 +22,7 @@
 | [移动端交互原型](prototype.md) | 评审流程、视觉或开始 Compose 页面前 | 可点击原型、截图入口、确认清单和 Android 映射 |
 | [系统架构](architecture.md) | 新增包、依赖、数据源或网络能力时 | 分层、依赖方向、运行时数据流 |
 | [数据与内容](data-content.md) | 修改卦库、历史记录或内容来源时 | 数据契约、授权、隐私和迁移规则 |
+| [内容审校](content-review.md) | 审校卦辞来源或准备发布时 | 来源、异文和签核状态 |
 | [AI 解释与安全](ai-safety.md) | 修改提示词、模型调用或解释结果时 | AI 调用门、输入输出契约和安全边界 |
 | [质量门禁](quality-gates.md) | 实现、评审、发布前 | 自动化验证、需求追踪和完成定义 |
 | [依赖与许可证](dependency-licenses.md) | 新增/升级依赖或准备分发时 | 当前解析依赖、SPDX 与权威许可来源 |
@@ -69,7 +69,7 @@ app/src/main/java/net/opcapp/flash/

 测试按相同包结构镜像放入 `src/test` 和 `src/androidTest`。

-当前已落地的包：`app/`、`core/model`、`core/designsystem`、`domain/casting`、`data/content`（接口与测试 fake）、`data/history`、`data/settings`、`feature/onboarding`、`feature/home`、`feature/question`、`feature/casting`、`feature/result`、`feature/settings`。尚未创建 `feature/history`、`feature/explanation`、`domain/explanation` 和 `data/ai`。首页不为问卦簿或「解」生成空占位。
+当前已落地的包：`app/`、`core/model`、`core/designsystem`、`domain/casting`、`data/content`（assets 解析器与测试 fake）、`data/history`、`data/settings`、`feature/onboarding`、`feature/home`、`feature/question`、`feature/casting`、`feature/result`、`feature/settings`、`feature/content`。尚未创建 `feature/history`、`feature/explanation`、`domain/explanation` 和 `data/ai`。首页不为问卦簿或「解」生成空占位。

 ## 4. 依赖方向

@@ -0,0 +1,34 @@
+# 内容审校记录
+
+> 状态：P2 数据包已生成，待内容负责人确认可再分发
+> 内容版本：`zh-Hans-2026.1`
+
+## 已接受来源
+
+| 来源 ID | 文本 | 许可 | 说明 |
+|---|---|---|---|
+| `wikisource-zhouyi-jing-zh-Hans` | 卦辞、爻辞、乾用九、坤用六 | 公版（Wikimedia PD-old） | 维基文库《周易》仅《易经》；不含彖、象、文言等十翼。导入脚本：`scripts/import-zhouyi-wikisource.mjs` |
+| `lingji-plain-zh-Hans-2026.1` | 本地白话 | 项目自撰草稿 | `content/plain/lingji-plain.mjs`；审校完成前不得当作已授权现代译本 |
+
+未采用南怀瑾、傅佩荣或其他仍受版权保护的现代译注。
+
+## 工程入口
+
+- 原始导入：`content/raw/zhouyi-wikisource-jing.json`
+- 发布包：`content/packages/hexagram-content.json`
+- 构建：`node scripts/build-hexagram-package.mjs`
+- 再导入需本机 HTTP 代理（默认 `http://127.0.0.1:1080`）访问 `zh.wikisource.org`
+
+## 已知异文
+
+维基文库复卦初九作「不复远，无袛悔」，与常见通行本「不远复，无祇悔」不同。本包按维基文库底本收录，不在导入时改字。审校时可决定是否改从通行本并提升 `contentVersion`。
+
+## 审校清单
+
+- [ ] 64 卦卦辞、384 爻与通行《易经》对读，记录有意保留的异文
+- [ ] 确认不含十翼
+- [ ] 白话无占断口吻、无未授权现代译注抄袭
+- [ ] 乾用九、坤用六原文无误
+- [ ] 内容负责人签署可再分发
+
+签署前，P2 不得标记完成，商店发布不得进行。
@@ -1,6 +1,6 @@
 # 数据、内容与隐私契约

-> 状态：结构已定义，内容来源与授权仍为发布阻塞项
+> 状态：`zh-Hans-2026.1` 已接入应用；白话为草稿，发布仍待审校
 > 适用范围：卦库 assets、Room、DataStore、导入脚本和内容审核

 ## 1. 数据分类
@@ -58,7 +58,7 @@

 示例中的省略号不是可发布内容。禁止由 AI 在构建时临时补齐缺失卦辞或爻辞。

-机器契约位于 `content/schema/hexagram-content.schema.json`。`specialUsageTexts` 显式声明当前内容版本是否提供乾“用九”和坤“用六”；声明为 `false` 时对应条目的 `specialUsageText` 必须为 `null`，不能用空字符串暗示内容存在。Android parser 尚未建立前，`scripts/verify-content-contract.mjs` 已提供独立构建期校验、稳定 SHA-256 摘要和不含可发布卦辞的自动化夹具；`HexagramContentRepository` 接口与测试 fake 已建立，缺少 ID 或内容版本不匹配时抛出数据完整性错误，不回退到相邻条目。应用当前只使用文王卦名查找表展示结果，不把未授权卦辞打入 APK。
+机器契约位于 `content/schema/hexagram-content.schema.json`。`specialUsageTexts` 显式声明当前内容版本是否提供乾“用九”和坤“用六”；声明为 `false` 时对应条目的 `specialUsageText` 必须为 `null`，不能用空字符串暗示内容存在。`scripts/verify-content-contract.mjs` 校验夹具与 `content/packages/hexagram-content.json`；Kotlin `HexagramContentParser` 用同一套规则加载 assets。`HexagramContentRepository` 在缺少 ID 或内容版本不匹配时抛出数据完整性错误，不回退到相邻条目。来源与审校状态见 [内容审校](content-review.md)。

 ## 3. 内容完整性门禁

@@ -142,14 +142,36 @@
 - 后果：主代码迁移到 `net.opcapp.flash`；Android 壳使用“灵机”和 `minSdk=26`。应用图标、商店文案和签名仍未由本决策确认。当前 `compileSdk/targetSdk=34` 是已安装工具链基线，不代表永久商店目标；发布前须按当时商店要求复核升级。
 - 复审触发：组织域名所有权变化、发布账号要求更换 ID，或依赖/覆盖率数据要求提高最低系统版本。application ID 一旦发布不得轻率更换。

+## ADR-015：自有白话 + 维基文库公版《易经》原文
+
+- 状态：`Accepted`
+- 日期：2026-08-19
+- 关联：TBD-005、FR-R-005、P2
+- 决定：安装包内的经典原文取自维基文库《周易》的《易经》部分（卦辞、爻辞，以及乾用九、坤用六），不含十翼；现代白话由本项目自撰，标为草稿，待内容负责人审校后才视为可再分发。不把南怀瑾、傅佩荣等现代译注入 APK。
+- 原因：需要可核验、可再分发的公版原文，同时避免把仍受版权保护的现代译文误当成古籍公版。
+- 备选：等待商业授权会继续阻塞离线阅读；使用来源不明的网络译文无法通过内容门禁。
+- 后果：原文事实源为 `content/raw/zhouyi-wikisource-jing.json`，经 `scripts/import-zhouyi-wikisource.mjs` 导入并由 Wikimedia `zh-hans` 转换；白话事实源为 `content/plain/lingji-plain.mjs`；发布包为 `content/packages/hexagram-content.json`，构建时拷入 assets。应用内必须区分“原文”与“本地白话”，并提供内容来源页。P2 在审校签核前不得标为完成。
+- 复审条件：维基文库页面结构变化、发现与通行本有影响阅读的异文、或内容负责人改用另一公版底本。
+
+## ADR-016：乾用九、坤用六在内容具备时展示
+
+- 状态：`Accepted`
+- 日期：2026-08-19
+- 关联：TBD-006、P2/P3
+- 决定：内容包声明并收录乾“用九”、坤“用六”。结果页仅在本卦为乾且六爻皆老阳，或本卦为坤且六爻皆老阴时展示对应特殊文本。
+- 原因：用九/用六是《易经》文本的一部分，不是另造的占断；只有全动时才按传统用法出示，避免静卦或单爻动时误读。
+- 备选：一律隐藏会丢掉已具备的原文；凡见乾坤都展示会把特殊用法当成普通爻辞。
+- 后果：`specialUsageTexts.qian/kun` 必须为 true，且仅乾、坤可有 `specialUsageText`。之卦为乾坤但不满足全九/全六时不展示用九/用六。
+- 复审条件：产品决定对之卦或非全动情形也提示该文本。
+
 ## 未决问题

 | ID | 问题 | 推荐默认 | 阻塞阶段 |
 |---|---|---|---|
 | TBD-001 | 应用图标与商店素材 | 产品名已由 ADR-014 确认为“灵机”；图标不使用未确认成稿 | P6 商店配置 |
 | TBD-004 | 问题是否允许留空 | 允许选择“不写具体内容”，但需显式操作 | P3 |
-| TBD-005 | 经典原文、现代白话的版本与授权 | 自有白话 + 可核验公版原文 | P2，发布阻塞 |
-| TBD-006 | 乾用九、坤用六是否纳入 MVP | 内容具备时展示 | P2/P3 |
+| TBD-005 | 经典原文、现代白话的版本与授权 | 已由 ADR-015 接受；内容负责人审校仍阻塞发布 | P2，发布阻塞 |
+| TBD-006 | 乾用九、坤用六是否纳入 MVP | 已由 ADR-016 接受：全九/全六时展示 | P2/P3 |
 | TBD-009 | AI 模型供应商与自有后端 | 供应商无关接口；先交付本地版 | P5 |
 | TBD-010 | 服务端问题/回复保留期 | 最小化且明确披露，优先不持久化正文 | P5，发布阻塞 |
 | TBD-011 | 高风险本地资源表覆盖地区 | 首发市场确认后维护，不让模型编号码 | P5 |
@@ -41,4 +41,4 @@
 | `kotlin-runtime-policy` | `org.jetbrains.kotlin` | 运行时传递依赖 | Apache-2.0 | [Kotlin license](https://github.com/JetBrains/kotlin/blob/v1.9.20/license/LICENSE.txt) |
 | `kotlinx-runtime-policy` | `org.jetbrains.kotlinx` | 运行时传递依赖 | Apache-2.0 | [Kotlinx Coroutines license](https://github.com/Kotlin/kotlinx.coroutines/blob/1.7.1/LICENSE.txt) |

-当前没有第三方字体、纹理、插画、音效或可发布《易经》内容进入工程。应用仅使用 Android 系统字体和代码绘制的卦象；这句话只描述本提交时的资源图，不构成未来授权。
+当前没有第三方字体、纹理、插画或音效进入工程。应用使用 Android 系统字体、代码绘制的卦象，以及 `content/packages/hexagram-content.json` 中的维基文库公版《易经》与项目自撰白话草稿；这句话只描述本提交时的资源图，不构成内容负责人已签核。
@@ -157,7 +157,7 @@ Android Studio 不是当前环境的可用前提。项目必须先支持 PowerSh
 - `PATH` 中 ADB 1.0.32 与 SDK ADB 1.0.41 会争用 server；当前三星设备的可重复门禁需要显式选择便携 ADB，后续应评估统一驱动和 Platform Tools。
 - 代理已配置；本轮 Maven 依赖下载成功，但不能据此保证未来网络始终可用。

-已解除的缺口：Gradle Wrapper、Version Catalog、根 `AGENTS.md`、CI、正式 Android 身份和 application 壳均已建立。2026-08-19，`verifyLocal` 通过（含 22 个 debug 单元测试、`lintDebug` 与 debug APK）；便携 ADB 下 Samsung API 31 真机 `run-connected-tests.ps1` 得到 `OK (4 tests)`，覆盖方法说明、保存设置、夹具「复 24 → 坤 2、初爻动」本机保存/当次删除，以及 Room 会话读写。未发现应用崩溃日志。飞行模式人工走查、无障碍抽测和授权内容包仍未做。
+已解除的缺口：Gradle Wrapper、Version Catalog、根 `AGENTS.md`、CI、正式 Android 身份和 application 壳均已建立。2026-08-19，`verifyLocal` 通过（含 debug 单元测试、`lintDebug` 与 debug APK，已校验 `zh-Hans-2026.1` 内容包）；便携 ADB 下 Samsung API 31 真机 `run-connected-tests.ps1` 得到 `OK (4 tests)`，覆盖方法说明、保存设置、夹具「复 24 → 坤 2、初爻动」本机保存/当次删除（结果页已展示原文/白话），以及 Room 会话读写。未发现应用崩溃日志。飞行模式人工走查、无障碍抽测和内容负责人签核仍未做。

 这些缺口分别由[实施计划](implementation-plan.md)的 P0 和[质量门禁](quality-gates.md)处理。环境缺口不是跳过验证的理由；无法运行的门禁必须在交付报告中准确说明。

@@ -1,6 +1,6 @@
 # 分阶段实施计划

-> 状态：P0/P1 已完成；P3 离线主流程已落地但未达到 UX 全表验收；P4 会话保存已落地，问卦簿/解读未开始；P2 授权内容未开始；P-1 v0.3 待视觉复核
+> 状态：P0/P1 已完成；P3 离线主流程已落地但未达到 UX 全表验收；P4 会话保存已落地，问卦簿/解读未开始；P2 已接入公版《易经》与自撰白话草稿，待审校签核；P-1 v0.3 待视觉复核
 > 计划原则：先用原型确认高返工成本体验，再锁定确定性领域核心，随后接内容和 UI，最后接网络 AI

 ## 1. 依赖图
@@ -92,18 +92,18 @@ P1 与 P2 可并行，但 P3 不能在领域与内容契约未稳定时复制原

 任务：

- [ ] 决定原文版本、现代白话来源和授权（TBD-005，发布阻塞）。
- [ ] 实现 JSON schema、解析器和内容版本：`schemaVersion=1` 的机器 schema 已完成；Android/Kotlin assets 解析器待 Android 壳建立。
- [ ] 录入/导入 64 卦、卦辞、384 条爻辞及所需特殊文本。
- [ ] 建立来源清单、许可证清单和内容审核记录；schema 已强制每个来源包含版本、许可证与 URL。
+- [x] 决定原文版本、现代白话来源和授权（TBD-005）：ADR-015 接受“自有白话 + 维基文库公版《易经》原文”；发布仍待审校签核。
+- [x] 实现 JSON schema、解析器和内容版本：`schemaVersion=1` 的机器 schema、Kotlin assets 解析器与 `zh-Hans-2026.1` 包已落地。
+- [x] 录入/导入 64 卦、卦辞、384 条爻辞及乾用九、坤用六；白话为项目自撰草稿。
+- [x] 建立来源清单、许可证清单和内容审核记录：见 [内容审校](content-review.md)；schema 已强制每个来源包含版本、许可证与 URL。
 - [x] 实现构建期完整性校验、文王序号/上下卦/bottom-up 交叉校验、稳定 SHA-256 摘要及 8 个负向夹具。
- [ ] 实现 `HexagramContentRepository` fake 与 assets 版本：接口、强校验只读模型和测试 fake 已完成，assets 实现待 Android parser。
+- [x] 实现 `HexagramContentRepository` fake 与 assets 版本：加载失败时展示完整性错误，不回退到相邻卦。

 退出条件：

- 64 卦/384 爻数据完整、唯一且来源可追踪。
- 缺失、重复、非法顺序和错误映射测试均能失败。
- 内容负责人确认可再分发。
+- [x] 64 卦/384 爻数据完整、唯一且来源可追踪。
+- [x] 缺失、重复、非法顺序和错误映射测试均能失败。
+- [ ] 内容负责人确认可再分发。

 ## 6. P3：核心用户流程与东方设计系统

@@ -116,7 +116,7 @@ P1 与 P2 可并行，但 P3 不能在领域与内容契约未稳定时复制原
 - [x] 实现首次说明、起念、投币和结果页面：方法说明、问题、六轮手录和结果已接入导航；空问题仍被拒绝，TBD-004 未决。
 - [x] 实现 `CastingViewModel` 状态机及 SavedState 恢复：问题、已确认爻和当前轮次写入 `SavedStateHandle`；第六轮才调用 `CastEngine`。
 - [x] 支持前五轮返回修改、第六轮封印和明确重新起卦。
- [ ] 接入本地内容并区分原文/本地白话：结果页只展示卦名、卦号、六爻事实，并明示授权内容包未接入。
+- [x] 接入本地内容并区分原文/本地白话：结果页展示本卦卦辞、动爻爻辞和之卦卦辞，并标注原文/白话；乾全九、坤全六时展示用九/用六。白话仍为待审校草稿。
 - [ ] 完成深浅主题、字体缩放、TalkBack、横屏和大屏适配：深浅色随系统；其余未做发布级验收。

 退出条件：
@@ -126,7 +126,7 @@ P1 与 P2 可并行，但 P3 不能在领域与内容契约未稳定时复制原
 - AI/网络代码尚未存在也不影响流程。
 - [UX 与东方视觉](ux-design.md)检查表通过。

-当前证据（2026-08-19）：`verifyLocal` 通过；仪器测试覆盖方法说明、保存设置和夹具「复 24 → 坤 2、初爻动」的本机保存/当次删除。P3 仍未退出，因为授权卦辞、「解」、问卦簿入口和 UX 全表未完成。飞行模式未做人工走查。
+当前证据（2026-08-19）：`verifyLocal` 通过；仪器测试覆盖方法说明、保存设置和夹具「复 24 → 坤 2、初爻动」的本机保存/当次删除。P3 仍未退出，因为「解」、问卦簿入口和 UX 全表未完成。飞行模式未做人工走查。内容包已接入但白话待审校。

 ## 7. P4：本地解释与历史

@@ -128,7 +128,7 @@
 | FR-C-007 | SavedState/重建测试 | 旋转、切后台、进程恢复 |
 | FR-R-001~003 | UI 语义与 screenshot 测试 | TalkBack、色觉与长文阅读 |
 | FR-R-004 | 网络失败测试 | 飞行模式 |
-| FR-R-005 | 内容 schema/授权清单检查 | 内容负责人签核 |
+| FR-R-005 | 内容 schema/授权清单检查 | 自动校验已接入；内容负责人签核仍待完成 |
 | FR-E-001~003 | 网络调用次数与同意状态测试 | 首次同意流程 |
 | FR-E-004~006 | 输出 schema + 安全用例集 | 安全/产品审核 |
 | FR-H-001~008 | 保存策略、Room 事务/版本、删除、备份排除、零网络调用测试 | 首页告知、设置、当次退出与删除体验 |
@@ -2,7 +2,7 @@

 > 状态：MVP 设计基线
 > 适用范围：Android 手机优先，兼顾横屏、平板和系统无障碍设置
-> 当前实现：Compose 已覆盖方法说明、回访首页、起念、六轮手录、卦名/动爻结果和保存设置；问卦簿列表、「解」与授权卦辞仍未进入应用，不能把本文件尚未实现的页面当成已上线功能
+> 当前实现：Compose 已覆盖方法说明、回访首页、起念、六轮手录、卦名/动爻结果、原文/本地白话和保存设置；问卦簿列表与「解」仍未进入应用，不能把本文件尚未实现的页面当成已上线功能

 ## 1. 体验定位