229 lines
10 KiB
Markdown
229 lines
10 KiB
Markdown
# 分阶段实施计划
|
||
|
||
> 状态：P-1 v0.3 待视觉复核；P0 仓库门禁已建立但 Android 壳受 TBD-001～003 阻塞；P1 已完成并通过穷举测试；P2 内容契约已建立但授权内容未开始
|
||
> 计划原则：先用原型确认高返工成本体验，再锁定确定性领域核心，随后接内容和 UI，最后接网络 AI
|
||
|
||
## 1. 依赖图
|
||
|
||
```text
|
||
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 映射写入[原型说明](prototype.md)。
|
||
- 收集用户对视觉、录入控件、结果层级与解释语气的明确反馈。
|
||
|
||
退出条件：
|
||
|
||
- 可点击主流程及关键异常状态可在 360 × 792 浏览器中复现。
|
||
- `9,8,8,8,8,8` 显示复 24 → 坤 2、初爻动；全 7 显示乾 1 且无之卦。
|
||
- 原型不发起外部请求，不伪装真实 AI，不把工作名当作正式决定。
|
||
- 用户确认或提出一轮可执行的修改意见；确认前不把视觉固化为生产 Compose 页面。
|
||
|
||
核心 v0.1 已由用户确认；v0.3 已同步 ADR-012 并通过十八状态浏览器审计，首页、问卦簿和保存设置待用户视觉复核。
|
||
|
||
## 3. P0：仓库与 Android 骨架
|
||
|
||
目标：建立可构建、可测试、可导航的原生 Android 项目。
|
||
|
||
任务：
|
||
|
||
- [x] 读取并遵守[本地开发环境](environment.md)：JDK 17、SDK 34、命令行优先、Gradle Wrapper、真机验证。
|
||
- [ ] 基于 Google `android/architecture-templates` 的 `base` 分支初始化 Android 壳；模板定制需要 TBD-002 的正式 application ID，不能用临时发布身份替代。
|
||
- [ ] 确认正式应用名称、package/application ID、minSdk（TBD-001～003）。
|
||
- [ ] 配置 Compose、Material 3、Hilt、Room、DataStore 和 Navigation；Version Catalog 已先用于 JVM harness。
|
||
- [ ] 配置 Gradle Wrapper、格式化、lint、单元测试和 CI：Wrapper、无依赖格式门禁、JVM 单测与 CI 已完成；Android lint 要等 application 插件启用。
|
||
- [ ] 建立 [系统架构](architecture.md)中的包结构和空 feature 边界：`domain/casting` 已落地，其余随 Android 壳建立。
|
||
- [x] 将根 `AGENTS.md` 设计为短地图，指向本目录和验证命令。
|
||
- [x] 增加 `verifyLocal` 聚合任务、文档链接、领域边界、内容契约与基础 secret scan。
|
||
|
||
退出条件：
|
||
|
||
- Windows 上一条命令可执行格式、lint、单测和 debug 构建。
|
||
- CI 使用同一组命令。
|
||
- 空应用可在模拟器启动，导航到占位欢迎页。
|
||
- 没有生产服务密钥或真实内容。
|
||
|
||
## 4. P1：领域核心
|
||
|
||
目标：在纯 Kotlin 中完成并证明三枚铜币算法。
|
||
|
||
任务：
|
||
|
||
- [x] 建立 `CoinSide`、`LineValue`、`Polarity`、`CastRound`、`CastResult`。
|
||
- [x] 实现六轮输入校验和纯 `CastEngine`；记录时间与内容版本在计算后附加。
|
||
- [x] 建立带完整性自检的 64 卦文王序号映射表。
|
||
- [x] 实现之卦变换和 1～6 的 bottom-up 动爻位置。
|
||
- [x] 实现 `schemaVersion=1` 的序列化 DTO，并在读取时用保存的十八枚币重新计算校验派生值。
|
||
- [x] 完成 8 种币面、4,096 种六爻、64 模式和已知夹具测试。
|
||
- [x] 增加 domain 无 Android、数据库和网络依赖的机械架构门禁。
|
||
|
||
退出条件：
|
||
|
||
- [领域规则](domain-rules.md)全部被测试覆盖。
|
||
- 测试无随机、无网络、无系统时间依赖。
|
||
- `CastEngine` API 经评审后冻结为 `coin-v1`。
|
||
|
||
当前证据：`.\gradlew.bat :app:test --offline` 中 `CastEngineTest` 执行 10 个测试、0 失败；实现位于 `app/src/main/java/brainwave/domain/casting/`。`brainwave` 是内部代码命名空间，不是 TBD-002 的 application ID。
|
||
|
||
## 5. P2：内容数据管线
|
||
|
||
目标：建立可追踪、可校验、可发布的本地内容包。
|
||
|
||
任务：
|
||
|
||
- [ ] 决定原文版本、现代白话来源和授权（TBD-005，发布阻塞）。
|
||
- [ ] 实现 JSON schema、解析器和内容版本：`schemaVersion=1` 的机器 schema 已完成；Android/Kotlin assets 解析器待 Android 壳建立。
|
||
- [ ] 录入/导入 64 卦、卦辞、384 条爻辞及所需特殊文本。
|
||
- [ ] 建立来源清单、许可证清单和内容审核记录；schema 已强制每个来源包含版本、许可证与 URL。
|
||
- [x] 实现构建期完整性校验、文王序号/上下卦/bottom-up 交叉校验、稳定 SHA-256 摘要及 8 个负向夹具。
|
||
- [ ] 实现 `HexagramContentRepository` fake 与 assets 版本：接口、强校验只读模型和测试 fake 已完成，assets 实现待 Android parser。
|
||
|
||
退出条件：
|
||
|
||
- 64 卦/384 爻数据完整、唯一且来源可追踪。
|
||
- 缺失、重复、非法顺序和错误映射测试均能失败。
|
||
- 内容负责人确认可再分发。
|
||
|
||
## 6. P3：核心用户流程与东方设计系统
|
||
|
||
目标：完成离线起念、六次录入和结果阅读。
|
||
|
||
任务：
|
||
|
||
- 实现颜色、字体、间距、形状和动画令牌。
|
||
- 实现卦象 `Canvas`、动爻标记和读屏语义。
|
||
- 实现首次说明、起念、投币和结果页面。
|
||
- 实现 `CastingSessionViewModel` 状态机及 SavedState 恢复。
|
||
- 支持前五轮返回修改、第六轮封印和明确重新起卦。
|
||
- 接入本地内容并区分原文/本地白话。
|
||
- 完成深浅主题、字体缩放、TalkBack、横屏和大屏适配。
|
||
|
||
退出条件：
|
||
|
||
- 飞行模式可以从起念走到完整结果。
|
||
- 已知夹具的屏幕卦象、名称、动爻和之卦一致。
|
||
- AI/网络代码尚未存在也不影响流程。
|
||
- [UX 与东方视觉](ux-design.md)检查表通过。
|
||
|
||
## 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 解释与安全](ai-safety.md)所有验收测试通过。
|
||
- APK 无生产模型密钥。
|
||
- 抓包显示只有用户明确动作触发请求，载荷与同意说明一致。
|
||
- 服务端故障不会改变或隐藏 `CastResult`。
|
||
|
||
## 9. P6：质量、发布与运营
|
||
|
||
贯穿所有阶段：
|
||
|
||
- [x] 建立 CI、架构检查、内容校验、secret scan 和当前 JVM 依赖许可证报告；Android release 依赖启用后扩展报告。
|
||
- 建立脱敏崩溃监控和最小匿名指标。
|
||
- 增加可复现 screenshot/accessibility 测试环境。
|
||
- 准备隐私政策、内容来源、免责声明和应用商店素材。
|
||
- 每次重复缺陷更新[失败记忆](failure-memory.md)和机械护栏。
|
||
- 定期清理未使用依赖、重复 helper、过期文档和 TODO。
|
||
|
||
发布条件完全遵循[质量门禁](quality-gates.md#6-发布门禁)。
|
||
|
||
## 10. 编码任务模板
|
||
|
||
后续任务应使用以下结构，减少代理猜测：
|
||
|
||
```markdown
|
||
## 目标
|
||
一个可验证的结果。
|
||
|
||
## 范围
|
||
- 允许修改：...
|
||
- 不在范围：...
|
||
|
||
## 需求
|
||
- 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。
|