feat: add offline casting flow and local history sessions

Replace the development fixture shell with method intro, question, coin entry, and result screens. Persist locked casts in private Room storage under the save policy, and document remaining P2 content and P4 history-list gaps. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-19 10:58:09 +08:00
parent d82ab836a2
commit 4235cf9011
47 changed files with 3075 additions and 355 deletions
@@ -1,8 +1,8 @@
 # Brainwave 项目文档

 > 文档状态：方案基线
-> 最后核验：2026-08-07
-> 当前阶段：正式产品名“灵机”；P0 Android 壳与本地门禁已建立，真机闭环正在执行；P-1 v0.3 待品牌文案刷新和视觉复核；P1 已完成；P2 授权内容未开始
+> 最后核验：2026-08-19
+> 当前阶段：正式产品名“灵机”；P0/P1 已完成；P3 离线主流程（方法说明、起念、手录、卦名/动爻结果）已可走通；P4 仅完成会话级本机保存与设置，问卦簿与本地解释未开始；P2 授权内容未开始；P-1 v0.3 待视觉复核；P5 未开始

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

@@ -90,4 +90,4 @@
 - 测试命令、构建方式或发布门禁改变；
 - 出现可能再次发生的缺陷。

-文档链接、需求编号和验证命令将随工程骨架一起接入 CI 检查。当前尚无 Gradle 工程，不能声称任何构建或测试已经通过。
+文档链接、需求编号和验证命令由 `verifyLocal` 机械检查。授权真机存在时另跑设备仪器测试；未运行的门禁不得写成已经通过。
@@ -69,6 +69,8 @@ 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`。首页不为问卦簿或「解」生成空占位。
+
 ## 4. 依赖方向

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

 ## 3. 内容完整性门禁

@@ -88,6 +88,8 @@

 ## 5. Room 数据模型提案

+当前实现只有 `CastingSessionEntity` / `casting_sessions`（schema version 1）。`ExplanationEntity` 与 `ActionNoteEntity` 仍是提案，不得在 UI 中假装已经保存解读或行动。
+
 历史记录不是起卦事实源，但应保存可复核的快照：

 ```text
@@ -1,9 +1,9 @@
 # 依赖与许可证清单

-> 状态：Android debug runtime 与 debug unit-test runtime 依赖图已建立自动覆盖门禁
-> 适用范围：实际解析的 Android 调试运行时、单元测试运行时，以及直接使用的构建入口
+> 状态：Android debug runtime、debug unit-test runtime 与 debug instrumentation-test runtime 依赖图已建立自动覆盖门禁
+> 适用范围：实际解析的 Android 调试运行时、单元测试/仪器测试运行时，以及直接使用的构建入口

-本清单不是上架包的最终 third-party notices。每次新增或升级依赖时，必须同步 `config/dependency-licenses.json` 并运行 `\.\gradlew.bat verifyLocal`；发布前仍须对 release runtime 生成完整报告，复核许可证文本与随包义务。
+本清单不是上架包的最终 third-party notices。每次新增或升级依赖时，必须同步 `config/dependency-licenses.json` 并运行 `.\gradlew.bat verifyLocal`；发布前仍须对 release runtime 生成完整报告，复核许可证文本与随包义务。

 ## 直接条目

@@ -25,6 +25,10 @@
 | `javax-inject` | 1 | 运行时传递依赖 | Apache-2.0 | [Maven artifact metadata](https://repo1.maven.org/maven2/javax/inject/javax.inject/1/javax.inject-1.pom) |
 | `junit4` | 4.13.2 | 单元测试 | EPL-1.0 | [JUnit license](https://github.com/junit-team/junit4/blob/r4.13.2/LICENSE-junit.txt) |
 | `hamcrest-core` | 1.3 | 单元测试传递依赖 | BSD-3-Clause | [Hamcrest license](https://github.com/hamcrest/JavaHamcrest/blob/hamcrest-java-1.3/LICENSE.txt) |
+| `hamcrest-library` | 1.3 | 仪器测试传递依赖 | BSD-3-Clause | [Hamcrest license](https://github.com/hamcrest/JavaHamcrest/blob/hamcrest-java-1.3/LICENSE.txt) |
+| `hamcrest-integration` | 1.3 | 仪器测试传递依赖 | BSD-3-Clause | [Hamcrest license](https://github.com/hamcrest/JavaHamcrest/blob/hamcrest-java-1.3/LICENSE.txt) |
+| `gson` | 2.9.0 | 仪器测试传递依赖 | Apache-2.0 | [Gson license](https://github.com/google/gson/blob/gson-parent-2.9.0/LICENSE) |
+| `javawriter` | 2.1.1 | 仪器测试传递依赖 | Apache-2.0 | [JavaWriter license](https://github.com/square/javawriter/blob/javawriter-2.1.1/LICENSE.txt) |

 ## 传递依赖组策略

@@ -1,7 +1,7 @@
 # 本地开发环境基线

 > 状态：已从当前主机实测
-> 最后核验：2026-08-08
+> 最后核验：2026-08-19
 > 适用范围：`D:\OPC\brainwave` 的 Android 开发、构建和设备验证

 本文件记录项目当前可用的本地工具链，不是期望环境清单。后续实现必须先使用这里已经确认的能力；需要升级或安装新工具时，应说明原因并在完成后更新本文件。
@@ -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 壳均已建立；`assembleDebug`、13 个 debug 单元测试、`lintDebug` 与测试 APK 编译已在 JDK 17 上通过。2026-08-08，`app-debug.apk` 已安装并冷启动到 `MainActivity`，Compose 仪器测试 `MainActivityTest` 以 `OK (1 test)` 通过，首页与结果页语义树和截图人工复核通过，未发现应用崩溃日志。
+已解除的缺口：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 会话读写。未发现应用崩溃日志。飞行模式人工走查、无障碍抽测和授权内容包仍未做。

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

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

-> 状态：P0 Android 壳、本地门禁与三星 API 31 真机闭环已完成；P-1 v0.3 待视觉复核；P1 已完成并通过穷举测试；P2 内容契约已建立但授权内容未开始
+> 状态：P0/P1 已完成；P3 离线主流程已落地但未达到 UX 全表验收；P4 会话保存已落地，问卦簿/解读未开始；P2 授权内容未开始；P-1 v0.3 待视觉复核
 > 计划原则：先用原型确认高返工成本体验，再锁定确定性领域核心，随后接内容和 UI，最后接网络 AI

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

 任务：

- 实现颜色、字体、间距、形状和动画令牌。
- 实现卦象 `Canvas`、动爻标记和读屏语义。
- 实现首次说明、起念、投币和结果页面。
- 实现 `CastingSessionViewModel` 状态机及 SavedState 恢复。
- 支持前五轮返回修改、第六轮封印和明确重新起卦。
- 接入本地内容并区分原文/本地白话。
- 完成深浅主题、字体缩放、TalkBack、横屏和大屏适配。
+- [x] 实现颜色、字体、间距、形状和动画令牌：当前为 `LingjiTheme` 纸墨朱砂配色与系统衬线/无衬线配对；独立 token 文件、指定字体包和动效仍未做。
+- [x] 实现卦象 `Canvas`、动爻标记和读屏语义：结果页绘制本卦/之卦，动爻同时使用颜色、圆点和文字。
+- [x] 实现首次说明、起念、投币和结果页面：方法说明、问题、六轮手录和结果已接入导航；空问题仍被拒绝，TBD-004 未决。
+- [x] 实现 `CastingViewModel` 状态机及 SavedState 恢复：问题、已确认爻和当前轮次写入 `SavedStateHandle`；第六轮才调用 `CastEngine`。
+- [x] 支持前五轮返回修改、第六轮封印和明确重新起卦。
+- [ ] 接入本地内容并区分原文/本地白话：结果页只展示卦名、卦号、六爻事实，并明示授权内容包未接入。
+- [ ] 完成深浅主题、字体缩放、TalkBack、横屏和大屏适配：深浅色随系统；其余未做发布级验收。

 退出条件：

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

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

 目标：形成不依赖 AI 的完整 MVP。

 任务：

- 实现版本化本地解释模板。
- 实现“可以试的一小步”的非裁决式结构。
- 实现 Room 历史：第六爻锁定后按策略自动保存快照，问题原文、当次解读和行动记录默认保存到同一会话。
- 实现 `autoSaveHistory` 总开关及三个默认开启的内容开关；支持总开关关闭后的“保存本次”和全局设置不变的“本次不保存/删除本次记录”。
- 实现按时间倒序的问卦簿、派生“最近一次”、空态、详情、解释版本、单条删除和清空全部确认。
- 在首页实现固定本机保存/AI 发送边界说明和设置入口；本地保存设置与 AI 同意版本保持独立。
- 配置 backup/data-extraction 规则，排除历史 Room 数据库及辅助文件。
- 完成 migration、策略组合、事务关联、删除、备份排除、隐私和离线测试。
+- [ ] 实现版本化本地解释模板。
+- [ ] 实现“可以试的一小步”的非裁决式结构。
+- [x] 实现 Room 历史会话：第六爻锁定后按 `autoSaveHistory` 写入 `casting_sessions` 快照；问题原文受内容开关控制。解读与行动表尚未建立。
+- [x] 实现 `autoSaveHistory` 总开关及三个默认开启的内容开关；总开关关闭后结果页提供“保存本次”，已保存时可“本次不保存/删除本次记录”。解读/行动开关目前只保留偏好，不写入任何正文。
+- [ ] 实现按时间倒序的问卦簿、空态、详情、解释版本、单条删除和清空全部确认。首页仅展示条数与最近一次派生摘要，不进入列表。
+- [x] 在首页实现固定本机保存/AI 发送边界说明和设置入口；本地保存设置与 AI 同意版本保持独立。
+- [x] 配置 backup/data-extraction 规则，排除历史 Room 数据库及辅助文件；`verifyLocalDataBoundary` 锁定 `allowBackup=false` 且无 INTERNET 权限。
+- [ ] 完成 migration、策略组合、事务关联、删除、备份排除、隐私和离线测试：schema 1 无需迁移；编解码、Room 仪器测试和首页设置仪器测试已有，策略组合与级联删除未覆盖。

 退出条件：

@@ -1,7 +1,7 @@
 # 产品规格

 > 状态：MVP 方案基线
-> 产品代号：Brainwave（正式名称 TBD）
+> 产品代号：Brainwave（正式名称：灵机）
 > 原始输入：[原始需求.txt](原始需求.txt)

 ## 1. 产品定义
@@ -26,7 +26,7 @@
 .\gradlew.bat verifyLocal
 ```

-`verifyLocal` 聚合无依赖格式检查、10 个领域测试、3 个内容 repository 测试、Android lint、debug APK、已解析 Android 调试/单测依赖许可证、domain 依赖边界、内容契约与负向夹具、文档链接、高置信 secret scan 和原型 JavaScript 语法检查。CI 执行同一个聚合任务。首次解析 Android 依赖时不能强制 `--offline`；缓存完成后可用离线模式复核。
+`verifyLocal` 聚合无依赖格式检查、领域穷举测试、内容 repository 测试、历史编解码测试、问题校验测试、Android lint、debug APK、已解析 Android 调试/单测/仪器测试依赖许可证、domain 依赖边界、内容契约与负向夹具、文档链接、高置信 secret scan、原型 JavaScript 语法检查，以及本机备份排除/无 INTERNET 权限检查。CI 执行同一个聚合任务。首次解析 Android 依赖时不能强制 `--offline`；缓存完成后可用离线模式复核。

 授权真机存在时，Windows 环境还必须执行：

@@ -2,6 +2,7 @@

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

 ## 1. 体验定位