brainwave/docs/implementation-plan.md

分阶段实施计划

状态：P-1 核心原型已确认，首页/问卦簿与默认本机保存 v0.3 已完成待视觉复核；P0 尚未开始 计划原则：先用原型确认高返工成本体验，再锁定确定性领域核心，随后接内容和 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 分支初始化。
• 确认正式应用名称、package/application ID、minSdk。
• 配置 Kotlin、Compose、Material 3、Hilt、Room、DataStore、Navigation 和 Version Catalog。
• 配置 Gradle Wrapper、格式化、lint、单元测试和 CI。
• 建立 系统架构中的包结构和空 feature 边界。
• 将根 AGENTS.md 设计为短地图，指向本目录和验证命令。
• 增加 verifyLocal 聚合任务及基础 secret scan。

退出条件：

• Windows 上一条命令可执行格式、lint、单测和 debug 构建。
• CI 使用同一组命令。
• 空应用可在模拟器启动，导航到占位欢迎页。
• 没有生产服务密钥或真实内容。

4. P1：领域核心

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

任务：

• 建立 CoinSide、LineValue、Polarity、CastRound、CastResult。
• 实现六轮输入校验和 CastEngine。
• 建立经过双重校验的 64 卦模式映射表。
• 实现之卦变换和动爻位置。
• 实现版本化序列化 DTO。
• 完成 8 种币面、4,096 种六爻、64 模式和已知夹具测试。
• 增加 domain 无 Android/网络依赖的架构门禁。

退出条件：

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

5. P2：内容数据管线

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

任务：

• 决定原文版本、现代白话来源和授权。
• 实现 JSON schema、解析器和内容版本。
• 录入/导入 64 卦、卦辞、384 条爻辞及所需特殊文本。
• 建立来源清单、许可证清单和内容审核记录。
• 实现构建期完整性校验与映射交叉校验。
• 实现 HexagramContentRepository fake 与 assets 版本。

退出条件：

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

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

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

任务：

• 实现颜色、字体、间距、形状和动画令牌。
• 实现卦象 Canvas、动爻标记和读屏语义。
• 实现首次说明、起念、投币和结果页面。
• 实现 CastingSessionViewModel 状态机及 SavedState 恢复。
• 支持前五轮返回修改、第六轮封印和明确重新起卦。
• 接入本地内容并区分原文/本地白话。
• 完成深浅主题、字体缩放、TalkBack、横屏和大屏适配。

退出条件：

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

7. P4：本地解释与历史

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

任务：

• 实现版本化本地解释模板。
• 实现“可以试的一小步”的非裁决式结构。
• 实现 Room 历史：第六爻锁定后按策略自动保存快照，问题原文、当次解读和行动记录默认保存到同一会话。
• 实现 autoSaveHistory 总开关及三个默认开启的内容开关；支持总开关关闭后的“保存本次”和全局设置不变的“本次不保存/删除本次记录”。
• 实现按时间倒序的问卦簿、派生“最近一次”、空态、详情、解释版本、单条删除和清空全部确认。
• 在首页实现固定本机保存/AI 发送边界说明和设置入口；本地保存设置与 AI 同意版本保持独立。
• 配置 backup/data-extraction 规则，排除历史 Room 数据库及辅助文件。
• 完成 migration、策略组合、事务关联、删除、备份排除、隐私和离线测试。

退出条件：

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

8. P5：AI 解读

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

前置阻塞：

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

任务：

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

退出条件：

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

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

贯穿所有阶段：

• 建立 CI、架构检查、内容校验、secret scan 和依赖许可证报告。
• 建立脱敏崩溃监控和最小匿名指标。
• 增加可复现 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。