197 lines
6.4 KiB
Markdown
197 lines
6.4 KiB
Markdown
# 分阶段实施计划
|
||
|
||
> 状态：未开始
|
||
> 计划原则：先锁定确定性领域核心，再接内容和 UI，最后接网络 AI
|
||
|
||
## 1. 依赖图
|
||
|
||
```text
|
||
P0 工程骨架
|
||
├── P1 起卦领域核心 ──→ P3 主流程 UI ──→ P4 本地完整 MVP
|
||
├── P2 内容数据管线 ──→ P3 主流程 UI
|
||
└── P6 质量与发布（贯穿）
|
||
|
||
P4 本地完整 MVP ──→ P5 AI 后端与解释
|
||
```
|
||
|
||
P1 与 P2 可并行，但 P3 不能在领域与内容契约未稳定时复制临时算法或硬编码卦辞。
|
||
|
||
## 2. P0：仓库与 Android 骨架
|
||
|
||
目标：建立可构建、可测试、可导航的原生 Android 项目。
|
||
|
||
任务：
|
||
|
||
- 基于 Google `android/architecture-templates` 的 `base` 分支初始化。
|
||
- 确认正式应用名称、package/application ID、minSdk。
|
||
- 配置 Kotlin、Compose、Material 3、Hilt、Room、DataStore、Navigation 和 Version Catalog。
|
||
- 配置 Gradle Wrapper、格式化、lint、单元测试和 CI。
|
||
- 建立 [系统架构](architecture.md)中的包结构和空 feature 边界。
|
||
- 将根 `AGENTS.md` 设计为短地图，指向本目录和验证命令。
|
||
- 增加 `verifyLocal` 聚合任务及基础 secret scan。
|
||
|
||
退出条件：
|
||
|
||
- Windows 上一条命令可执行格式、lint、单测和 debug 构建。
|
||
- CI 使用同一组命令。
|
||
- 空应用可在模拟器启动，导航到占位欢迎页。
|
||
- 没有生产服务密钥或真实内容。
|
||
|
||
## 3. P1：领域核心
|
||
|
||
目标：在纯 Kotlin 中完成并证明三枚铜币算法。
|
||
|
||
任务：
|
||
|
||
- 建立 `CoinSide`、`LineValue`、`Polarity`、`CastRound`、`CastResult`。
|
||
- 实现六轮输入校验和 `CastEngine`。
|
||
- 建立经过双重校验的 64 卦模式映射表。
|
||
- 实现之卦变换和动爻位置。
|
||
- 实现版本化序列化 DTO。
|
||
- 完成 8 种币面、4,096 种六爻、64 模式和已知夹具测试。
|
||
- 增加 domain 无 Android/网络依赖的架构门禁。
|
||
|
||
退出条件：
|
||
|
||
- [领域规则](domain-rules.md)全部被测试覆盖。
|
||
- 测试无随机、无网络、无系统时间依赖。
|
||
- `CastEngine` API 经评审后冻结为 `coin-v1`。
|
||
|
||
## 4. P2：内容数据管线
|
||
|
||
目标：建立可追踪、可校验、可发布的本地内容包。
|
||
|
||
任务：
|
||
|
||
- 决定原文版本、现代白话来源和授权。
|
||
- 实现 JSON schema、解析器和内容版本。
|
||
- 录入/导入 64 卦、卦辞、384 条爻辞及所需特殊文本。
|
||
- 建立来源清单、许可证清单和内容审核记录。
|
||
- 实现构建期完整性校验与映射交叉校验。
|
||
- 实现 `HexagramContentRepository` fake 与 assets 版本。
|
||
|
||
退出条件：
|
||
|
||
- 64 卦/384 爻数据完整、唯一且来源可追踪。
|
||
- 缺失、重复、非法顺序和错误映射测试均能失败。
|
||
- 内容负责人确认可再分发。
|
||
|
||
## 5. P3：核心用户流程与东方设计系统
|
||
|
||
目标：完成离线起念、六次录入和结果阅读。
|
||
|
||
任务：
|
||
|
||
- 实现颜色、字体、间距、形状和动画令牌。
|
||
- 实现卦象 `Canvas`、动爻标记和读屏语义。
|
||
- 实现首次说明、起念、投币和结果页面。
|
||
- 实现 `CastingSessionViewModel` 状态机及 SavedState 恢复。
|
||
- 支持前五轮返回修改、第六轮封印和明确重新起卦。
|
||
- 接入本地内容并区分原文/本地白话。
|
||
- 完成深浅主题、字体缩放、TalkBack、横屏和大屏适配。
|
||
|
||
退出条件：
|
||
|
||
- 飞行模式可以从起念走到完整结果。
|
||
- 已知夹具的屏幕卦象、名称、动爻和之卦一致。
|
||
- AI/网络代码尚未存在也不影响流程。
|
||
- [UX 与东方视觉](ux-design.md)检查表通过。
|
||
|
||
## 6. P4：本地解释与历史
|
||
|
||
目标：形成不依赖 AI 的完整 MVP。
|
||
|
||
任务：
|
||
|
||
- 实现版本化本地解释模板。
|
||
- 实现“可以试的一小步”的非裁决式结构。
|
||
- 实现 Room 历史、可选保存问题、详情和删除。
|
||
- 实现 DataStore 设置与同意版本基础设施。
|
||
- 完成 migration、删除、隐私和离线测试。
|
||
|
||
退出条件：
|
||
|
||
- 用户可选择不保存问题而保存卦象结果。
|
||
- 本地解释在无网络时可用。
|
||
- 删除行为与备份策略一致且经过验证。
|
||
- 此阶段已经是可发布的本地版候选。
|
||
|
||
## 7. P5：AI 解读
|
||
|
||
目标：在不扩大起卦权限的前提下增加可控 AI 解释。
|
||
|
||
前置阻塞：
|
||
|
||
- 模型提供商和后端部署方案确定；
|
||
- 隐私政策、数据保留和成本/限流规则确认；
|
||
- AI 安全用例集通过产品审核。
|
||
|
||
任务：
|
||
|
||
- 建立后端代理、认证、限流、超时和脱敏日志。
|
||
- 实现 `explanation-v1` 请求/响应 schema 与提示词版本。
|
||
- Android 实现同意、请求、取消、重试和本地降级。
|
||
- 对提示注入、高风险问题、非法输出和模型故障做测试。
|
||
- 增加远程功能开关；关闭 AI 时本地版仍完整。
|
||
|
||
退出条件：
|
||
|
||
- [AI 解释与安全](ai-safety.md)所有验收测试通过。
|
||
- APK 无生产模型密钥。
|
||
- 抓包显示只有用户明确动作触发请求，载荷与同意说明一致。
|
||
- 服务端故障不会改变或隐藏 `CastResult`。
|
||
|
||
## 8. P6：质量、发布与运营
|
||
|
||
贯穿所有阶段：
|
||
|
||
- 建立 CI、架构检查、内容校验、secret scan 和依赖许可证报告。
|
||
- 建立脱敏崩溃监控和最小匿名指标。
|
||
- 增加可复现 screenshot/accessibility 测试环境。
|
||
- 准备隐私政策、内容来源、免责声明和应用商店素材。
|
||
- 每次重复缺陷更新[失败记忆](failure-memory.md)和机械护栏。
|
||
- 定期清理未使用依赖、重复 helper、过期文档和 TODO。
|
||
|
||
发布条件完全遵循[质量门禁](quality-gates.md#6-发布门禁)。
|
||
|
||
## 9. 编码任务模板
|
||
|
||
后续任务应使用以下结构，减少代理猜测：
|
||
|
||
```markdown
|
||
## 目标
|
||
一个可验证的结果。
|
||
|
||
## 范围
|
||
- 允许修改：...
|
||
- 不在范围：...
|
||
|
||
## 需求
|
||
- FR-C-004
|
||
- NFR-DET-001
|
||
|
||
## 必读
|
||
- docs/domain-rules.md
|
||
- docs/architecture.md
|
||
|
||
## 验收
|
||
- Given/When/Then 场景
|
||
- 要运行的具体命令
|
||
|
||
## 风险
|
||
- 数据迁移 / 隐私 / 内容授权 / 无障碍 / 无
|
||
```
|
||
|
||
任务应尽量小到单次变更可完整验证，不以“大致完成页面”作为验收描述。
|
||
|
||
## 10. MVP 切分建议
|
||
|
||
最稳妥的发布顺序：
|
||
|
||
1. **内部算法版**：P0–P1，仅验证领域核心。
|
||
2. **离线体验版**：P2–P3，给测试用户完成起卦与阅读。
|
||
3. **本地正式候选**：P4，不依赖 AI 即可发布。
|
||
4. **AI 增强版**：P5，通过后由功能开关逐步开放。
|
||
|
||
这样 AI、后端或供应商选择不会阻塞核心产品，也不会迫使客户端把密钥和高风险逻辑提前塞入 APK。
|