brainwave/docs/implementation-plan.md

分阶段实施计划

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

1. 依赖图

P-1 可点击原型与视觉确认
 ↓
P0 工程骨架
 ├── P1 起卦领域核心 ──→ P3 主流程 UI ──→ P4 本地完整 MVP
 ├── P2 内容数据管线 ──→ P3 主流程 UI
 └── P6 质量与发布（贯穿）

P4 本地完整 MVP ──→ P5 AI 后端与解释

P1 与 P2 可并行，但 P3 不能在领域与内容契约未稳定时复制原型算法或硬编码卦辞。P-1 的视觉确认不改变 P1/P2 的工程门禁。

2. P-1：可点击原型与视觉确认

目标：在 Android 工程初始化前确认核心流程、信息层级、手动录入方式、AI 同意门和东方文化视觉方向。

任务：

• 建立 360 × 792 基准视口的高保真 HTML 原型和设计令牌。
• 覆盖欢迎、回访首页、起念、六轮录入、结果、本地/AI 选择、同意、成功与失败状态。
• 覆盖默认本机自动保存、首页告知、设置开关、当次退出、解读关联、清空全部、问卦簿列表/空态/详情和删除确认，并保持首页单一主操作。
• 使用已知夹具核对本卦、之卦、动爻和无动爻布局。
• 导出关键状态截图，并把评审入口与 Android 映射写入原型说明。
• 收集用户对视觉、录入控件、结果层级与解释语气的明确反馈。

退出条件：

• 可点击主流程及关键异常状态可在 360 × 792 浏览器中复现。
• 9,8,8,8,8,8 显示复 24 → 坤 2、初爻动；全 7 显示乾 1 且无之卦。
• 原型不发起外部请求，不伪装真实 AI，不把工作名当作正式决定。
• 用户确认或提出一轮可执行的修改意见；确认前不把视觉固化为生产 Compose 页面。

核心 v0.1 已由用户确认；v0.3 已同步 ADR-012 并通过十八状态浏览器审计，首页、问卦簿和保存设置待用户视觉复核。

3. P0：仓库与 Android 骨架

目标：建立可构建、可测试、可导航的原生 Android 项目。

任务：

• 读取并遵守本地开发环境：JDK 17、SDK 34、命令行优先、Gradle Wrapper、真机验证。
• 参照 Google android/architecture-templates 的 base 分支建立单模块 Android 壳和分层边界。
• 确认正式应用名称“灵机”、namespace/application ID net.opcapp.flash、minSdk=26（ADR-014）。
• 配置 Compose、Material 3、Hilt、Room、DataStore 和 Navigation，并由 Version Catalog 固定兼容版本。
• 配置 Gradle Wrapper、格式、Android lint、单元测试、debug APK、依赖许可证门禁和 CI 同入口验证。
• 建立 系统架构中的 app、core/designsystem、domain、data、feature/home 与 feature/result 边界；未实施 feature 不创建空包。
• 将根 AGENTS.md 设计为短地图，指向本目录和验证命令。
• 增加 verifyLocal 聚合任务、文档链接、领域边界、内容契约与基础 secret scan。

退出条件：

• Windows 上一条命令可执行格式、lint、单测和 debug 构建。
• CI 使用同一组命令。
• 开发验证应用可在授权真机启动，并从首页导航到已知领域夹具结果页。
• 没有生产服务密钥或真实内容。

完成证据（2026-08-08）：verifyLocal、13 个 debug 单元测试、lintDebug、主/测试 APK 构建均通过；调试 APK 在 Samsung API 31 设备冷启动到 MainActivity，MainActivityTest 真机执行 1/1 通过，并验证首页进入“复 24 → 坤 2、初爻动”结果页。因本机 ADB 1.0.32/1.0.41 server 冲突，设备门禁使用仓库脚本显式选择可枚举该设备的 ADB，未改写 SDK 工具。

4. P1：领域核心

目标：在纯 Kotlin 中完成并证明三枚铜币算法。

任务：

• 建立 CoinSide、LineValue、Polarity、CastRound、CastResult。
• 实现六轮输入校验和纯 CastEngine；记录时间与内容版本在计算后附加。
• 建立带完整性自检的 64 卦文王序号映射表。
• 实现之卦变换和 1～6 的 bottom-up 动爻位置。
• 实现 schemaVersion=1 的序列化 DTO，并在读取时用保存的十八枚币重新计算校验派生值。
• 完成 8 种币面、4,096 种六爻、64 模式和已知夹具测试。
• 增加 domain 无 Android、数据库和网络依赖的机械架构门禁。

退出条件：

• 领域规则全部被测试覆盖。
• 测试无随机、无网络、无系统时间依赖。
• CastEngine API 经评审后冻结为 coin-v1。

当前证据：.\gradlew.bat :app:testDebugUnitTest 中 CastEngineTest 执行 10 个测试、0 失败；实现位于 app/src/main/java/net/opcapp/flash/domain/casting/，且领域边界脚本禁止 Android/Compose/数据库/网络依赖。

5. P2：内容数据管线

目标：建立可追踪、可校验、可发布的本地内容包。

任务：

• 决定原文版本、现代白话来源和授权（TBD-005，发布阻塞）。
• 实现 JSON schema、解析器和内容版本：schemaVersion=1 的机器 schema 已完成；Android/Kotlin assets 解析器待 Android 壳建立。
• 录入/导入 64 卦、卦辞、384 条爻辞及所需特殊文本。
• 建立来源清单、许可证清单和内容审核记录；schema 已强制每个来源包含版本、许可证与 URL。
• 实现构建期完整性校验、文王序号/上下卦/bottom-up 交叉校验、稳定 SHA-256 摘要及 8 个负向夹具。
• 实现 HexagramContentRepository fake 与 assets 版本：接口、强校验只读模型和测试 fake 已完成，assets 实现待 Android parser。

退出条件：

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

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

目标：完成离线起念、六次录入和结果阅读。

任务：

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

退出条件：

• 飞行模式可以从起念走到完整结果。
• 已知夹具的屏幕卦象、名称、动爻和之卦一致。
• AI/网络代码尚未存在也不影响流程。
• UX 与东方视觉检查表通过。

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

7. P4：本地解释与历史

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

任务：

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

退出条件：

• 默认设置下，完成起卦会写入一条包含问题的 Room 会话，随后生成的解读会关联到同一会话且不静默覆盖旧版本。
• 总开关关闭、单个内容开关关闭和“本次不保存”均按契约生效；未完成草稿不进入 Room。
• 首页准确告知本机保存与 AI 发送边界，不存在未上线功能的空占位。
• 本地解释在无网络时可用。
• 单条删除、清空全部与备份排除策略一致且经过验证。
• 此阶段已经是可发布的本地版候选。

8. P5：AI 解读

目标：在不扩大起卦权限的前提下增加可控 AI 解释。

前置阻塞：

• 模型提供商和后端部署方案确定；
• 隐私政策、数据保留和成本/限流规则确认；
• AI 安全用例集通过产品审核。

任务：

• 建立后端代理、认证、限流、超时和脱敏日志。
• 实现 explanation-v1 请求/响应 schema 与提示词版本。
• Android 实现同意、请求、取消、重试和本地降级。
• 对提示注入、高风险问题、非法输出和模型故障做测试。
• 增加远程功能开关；关闭 AI 时本地版仍完整。

退出条件：

• AI 解释与安全所有验收测试通过。
• APK 无生产模型密钥。
• 抓包显示只有用户明确动作触发请求，载荷与同意说明一致。
• 服务端故障不会改变或隐藏 CastResult。

9. P6：质量、发布与运营

贯穿所有阶段：

• 建立 CI、架构检查、内容校验、secret scan 和当前 JVM 依赖许可证报告；Android release 依赖启用后扩展报告。
• 建立脱敏崩溃监控和最小匿名指标。
• 增加可复现 screenshot/accessibility 测试环境。
• 准备隐私政策、内容来源、免责声明和应用商店素材。
• 每次重复缺陷更新失败记忆和机械护栏。
• 定期清理未使用依赖、重复 helper、过期文档和 TODO。

发布条件完全遵循质量门禁。

10. 编码任务模板

后续任务应使用以下结构，减少代理猜测：

## 目标
一个可验证的结果。

## 范围
- 允许修改：...
- 不在范围：...

## 需求
- FR-C-004
- NFR-DET-001

## 必读
- docs/domain-rules.md
- docs/architecture.md

## 验收
- Given/When/Then 场景
- 要运行的具体命令

## 风险
- 数据迁移 / 隐私 / 内容授权 / 无障碍 / 无

任务应尽量小到单次变更可完整验证，不以“大致完成页面”作为验收描述。

11. MVP 切分建议

最稳妥的发布顺序：

1. 内部算法版：P0–P1，仅验证领域核心。
2. 离线体验版：P2–P3，给测试用户完成起卦与阅读。
3. 本地正式候选：P4，不依赖 AI 即可发布。
4. AI 增强版：P5，通过后由功能开关逐步开放。

这样 AI、后端或供应商选择不会阻塞核心产品，也不会迫使客户端把密钥和高风险逻辑提前塞入 APK。