brainwave/docs/decisions.md

架构决策与未决问题

状态：持续维护 规则：已接受决定不得被实现者静默推翻；变更需新增记录并说明迁移影响

决策状态

• Accepted：当前实现必须遵守。
• Proposed：有推荐默认值，但仍允许产品确认前调整。
• Superseded：已被后续决策替代，保留历史原因。
• Rejected：明确不采用，避免重复讨论。

ADR-001：使用原生 Android Kotlin + Jetpack Compose

• 状态：Accepted
• 日期：2026-08-04
• 决定：Android 首版采用 Kotlin、Jetpack Compose、Material 3 和单 Activity。
• 原因：产品只要求 Android；Compose 支持自定义主题、Canvas 卦象、状态驱动界面、无障碍和自适应布局，且符合官方新应用方向。
• 后果：不建立 Flutter、React Native 或 WebView 双栈；UI 测试使用 Compose 工具链。

ADR-002：以官方单模块 Architecture Template 为骨架

• 状态：Accepted
• 日期：2026-08-04
• 决定：从 android/architecture-templates 的 base 分支起步，保留单 Gradle module，按层和 feature 分包。
• 原因：模板包含 Compose、Room、Hilt、ViewModel、Navigation、Flow 和测试基础；MVP 规模不足以抵消多模块复杂度。
• 后果：满足系统架构后才能提出多模块 ADR。

ADR-003：起卦是本地确定性纯领域逻辑

• 状态：Accepted
• 日期：2026-08-04
• 决定：CastEngine 为纯 Kotlin，无随机、时间、网络、存储和问题文本依赖。
• 原因：原始需求明确 AI 不参与起卦；纯函数最容易穷举验证和复现。
• 后果：任何“个性化卦象”“AI 校正”“服务器起卦”均违反架构。

ADR-004：用户真实投币并手动录入

• 状态：Accepted
• 日期：2026-08-04
• 决定：MVP 不提供随机起卦、摇手机起卦或 AI 代投；每轮录入三枚“字/背”。
• 原因：保留用户亲手完成过程的产品核心，并避免将流程游戏化。
• 后果：可以改进录入控件，但不能增加默认随机按钮。

ADR-005：固定 coin-v1 计值和 bottom-up 顺序

• 状态：Accepted
• 日期：2026-08-04
• 决定：字=2、背=3；第一次为初爻；6/9 动、7/8 静；数据标准顺序 bottom-up。
• 原因：传统资料在币面称呼上并不完全一致，项目需要可见且可复现的单一约定。
• 后果：界面始终显示计值；改变约定必须增加方法版本，不能修改旧记录。

ADR-006：东方文化采用内容优先的纸墨朱砂设计

• 状态：Accepted
• 日期：2026-08-04
• 决定：以暖纸、墨色、克制朱砂、宋/黑体搭配和留白建立文化气质，同时保留原生 Android 交互语义。
• 原因：流程和文字比装饰符号更能表达文化，也更利于阅读和无障碍。
• 后果：拒绝龙凤祥云、金色发光、正文毛笔字、旋转太极和抽卡式动效。

ADR-007：本地内容是核心，AI 是可关闭增强

• 状态：Accepted
• 日期：2026-08-04
• 决定：64 卦、卦辞、爻辞和基础解释本地可用；AI 通过独立接口和功能开关接入。
• 原因：核心流程要离线可靠，模型故障和成本不能阻塞产品。
• 后果：P4 本地版可独立发布；AI 关闭时 UI 不能出现断裂占位。

ADR-008：正式 AI 密钥只放后端

• 状态：Accepted
• 日期：2026-08-04
• 决定：正式版经自有后端代理模型服务，不将开发者密钥打入 APK。
• 原因：客户端秘密可以被提取；后端也承担限流、schema 校验、安全策略和版本控制。
• 后果：没有后端之前只实现本地版或 mock，不用临时硬编码密钥“先跑起来”。

ADR-009：历史记录采用明确保存、本机优先

• 状态：Proposed
• 日期：2026-08-04
• 决定：用户完成后明确保存才进入 Room；保存时可不保留问题原文；默认无账号和云同步。
• 原因：问题可能高度敏感，自动永久保存不是安全默认值。
• 后果：历史功能不能成为完成起卦的前置条件。

ADR-010：多动爻全部透明展示

• 状态：Accepted
• 日期：2026-08-04
• 决定：显示所有实际动爻及其文本，不采用未经产品确认的规则隐藏或只选一条“主爻”。
• 原因：不同解释传统存在差异，产品不应把一种裁决算法伪装成唯一事实。
• 后果：AI 可以组织内容，但输入和界面保留全部动爻。

未决问题

ID	问题	推荐默认	阻塞阶段
TBD-001	正式产品名与应用图标	Brainwave 仅作代码代号	P0 商店配置
TBD-002	application ID	使用组织所有的反向域名	P0
TBD-003	minSdk	26；创建工程时复核覆盖率和依赖要求	P0
TBD-004	问题是否允许留空	允许选择“不写具体内容”，但需显式操作	P3
TBD-005	经典原文、现代白话的版本与授权	自有白话 + 可核验公版原文	P2，发布阻塞
TBD-006	乾用九、坤用六是否纳入 MVP	内容具备时展示	P2/P3
TBD-007	历史是否默认保存卦象	默认不保存，完成后询问	P4
TBD-008	Android Auto Backup 是否包含历史	默认排除敏感历史，待隐私评审	P4
TBD-009	AI 模型供应商与自有后端	供应商无关接口；先交付本地版	P5
TBD-010	服务端问题/回复保留期	最小化且明确披露，优先不持久化正文	P5，发布阻塞
TBD-011	高风险本地资源表覆盖地区	首发市场确认后维护，不让模型编号码	P5
TBD-012	架构检查工具	选择维护活跃工具或小型自定义测试	P0/P1

新增决策模板

## ADR-NNN：标题

- 状态：Proposed | Accepted | Superseded | Rejected
- 日期：YYYY-MM-DD
- 关联：需求、issue 或旧 ADR
- 决定：一句可执行结论
- 原因：为什么现在这样选择
- 备选：认真考虑过什么
- 后果：实现、迁移、测试和文档影响
- 复审条件：何时重新评估

不要直接改写旧 ADR 来隐藏历史。需要反转时新增 ADR，并把旧记录标为 Superseded by ADR-NNN。