brainwave/docs/product-spec.md

产品规格

状态：MVP 方案基线 产品代号：Brainwave（正式名称：灵机） 原始输入：原始需求.txt

1. 产品定义

Brainwave 帮助用户把一件正在纠结的事放慢来看。应用保留三枚铜币、六次成卦、本卦、之卦和动爻的文化结构，但把输出定位为反思材料，而不是预测、命令或替代决策。

核心承诺：

1. 卦由用户的真实投币结果在本地确定。
2. AI 只解释已经确定的结果，无法参与、重算或改写起卦。
3. 用户在看到原始结果后，主动点击「解」才会触发解释。
4. 解释尽量落到一项现实、低风险、可撤销的小行动。
5. 应用不预测发财时间，不替用户决定辞职、分手、医疗、法律或投资行为。

2. 产品原则

原则	产品含义
人先于算法	用户亲手投币；应用只记录和计算
原文先于解释	先展示本卦、之卦、卦辞和动爻，再提供「解」
反思而非裁决	使用“可以观察/考虑”，不用“你必须/注定”
本地优先	无网络时仍可完成输入、起卦、查看本地内容
明示边界	AI 调用、数据发送、来源和失败状态都对用户可见
克制表达	东方文化氛围服务于阅读和节奏，不制造神秘权威

3. 目标用户与使用情境

主要用户是希望通过传统文化框架整理想法、但不希望被“算命结果”替代判断的中文 Android 用户。

典型情境：

• 在两个可行选择间犹豫，希望换一个角度观察。
• 情绪复杂时，先慢下来描述问题，再决定下一步。
• 对《易经》文化感兴趣，希望理解卦象和动爻的基本结构。
• 想保存一次反思过程，日后回看当时的判断与行动。

本产品不适合作为紧急求助、医疗诊断、法律意见、投资建议或人身安全决策工具。

4. MVP 用户流程

首次说明
   ↓
起念：写下纠结之事
   ↓
定法：确认“背=3、字=2”和由下而上
   ↓
投币：真实投三枚，逐次录入，共六次
   ↓
成卦：本地锁定本卦、之卦、动爻
   ↓
观象：查看卦名、卦辞、动爻原文/本地白话
   ↓
主动点击「解」
   ↓
本地解释或明确同意后调用 AI
   ↓
留下一项低风险、可撤销的小行动

用户可以在前五次录入期间返回修改；第六次确认后生成不可被 AI 修改的 CastResult。若要改变投币记录，必须明确选择“重新起卦”，旧结果不在原地静默变化。

5. 功能需求

5.1 起念

• FR-Q-001 应用允许用户输入当前纠结的问题，建议长度 1–200 个 Unicode 字符。
• FR-Q-002 问题字段必须有可见标签和隐私说明，不能仅使用占位文字。
• FR-Q-003 MVP 不要求账号、手机号或身份信息。
• FR-Q-004 问题是否在本地长期保存必须由首页说明、可见设置和当次操作共同控制；任何本地保存状态都不得被解释为上传授权。

5.2 投币与成卦

• FR-C-001 用户每轮录入三枚铜币的“字/背”，共六轮。
• FR-C-002 应用不提供随机、AI 或服务器代投功能。
• FR-C-003 每轮即时显示该爻的数值和阴阳/动静含义，但不得提前生成完整卦名来影响后续录入。
• FR-C-004 六爻按初爻至上爻、由下而上存储和绘制。
• FR-C-005 第六轮确认后，本地生成稳定、可序列化的 CastResult。
• FR-C-006 投币、求和、动爻变换和卦号映射必须符合领域规则。
• FR-C-007 进程重建或屏幕旋转不得悄悄丢失已确认的投币进度。

5.3 结果展示

• FR-R-001 结果页必须显示六条原始爻、本卦名称和编号。
• FR-R-002 有动爻时必须显示动爻位置、动爻文本和之卦；无动爻时明确显示“无动爻”。
• FR-R-003 动爻不能只靠颜色区分，还必须有文字或形状标记。
• FR-R-004 AI 解释加载失败不得影响原始结果和本地内容的展示。
• FR-R-005 本卦与之卦的内容必须来自版本明确、授权清晰的本地数据集。

5.4 解释

• FR-E-001 结果锁定且原始内容已经可见后，才显示可用的「解」操作。
• FR-E-002 用户可以选择本地解释；AI 是可选增强，不是完成流程的前提。
• FR-E-003 第一次发送给 AI 前，必须说明会发送哪些内容并获得明确同意。
• FR-E-004 AI 输出必须符合AI 解释与安全的结构和语言边界。
• FR-E-005 解释必须将本卦、之卦和动爻视为输入事实，不得重新生成或纠正它们。
• FR-E-006 最终行动建议必须低风险、可撤销、有限时，并保留“不采取行动”的选项。

5.5 历史记录

• FR-H-001 历史记录属于 MVP 后半段能力；核心起卦不依赖它。
• FR-H-002 设置提供“自动保存完整记录”总开关，以及问题原文、解读全文和行动记录三个内容开关；四项默认开启，总开关关闭时内容开关同步停用。
• FR-H-003 删除记录必须可撤销或经过确认。
• FR-H-004 历史记录保存在应用私有存储中，并默认排除 Android Auto Backup、设备迁移数据提取和云备份；未来导出、备份或同步必须单独设计并获得明确选择。
• FR-H-005 第六爻确认并锁定结果后，若自动保存开启，应用必须立即创建历史会话；未完成草稿不得进入长期历史。自动保存关闭时，结果页仍提供“保存本次”。
• FR-H-006 自动保存的完整记录包含可复核起卦快照，并按内容开关保存问题原文、当次解读全文和行动记录；设置默认值均为开启。
• FR-H-007 首页必须持续说明“起卦与历史默认保存在本机，不主动上传。只有你选择 AI 解读时，本次所需内容才会发送。”并提供设置入口；结果页必须显示当次保存状态，并允许“本次不保存/删除本次记录”。
• FR-H-008 当次稍后生成的本地或 AI 解读必须按设置关联到同一会话；重新解读不得静默覆盖既有解读，必须新增版本或由用户明确确认替换。自动保存不能触发或授权 AI 请求。

6. 非功能需求

• NFR-OFF-001 写问题、录入、起卦、查看本地卦辞在飞行模式下可用。
• NFR-DET-001 相同的六次投币输入和同一数据版本必须产生完全相同的本卦、动爻和之卦。
• NFR-SEC-001 开发者 AI 密钥不得进入 APK、源码仓库或客户端日志。
• NFR-PRI-001 问题文本、解释全文和模型请求不得写入分析埋点或崩溃日志。
• NFR-PRI-002 Room 历史数据库及其辅助文件不得进入系统自动备份、设备迁移或任何未单独授权的云端副本。
• NFR-A11Y-001 正文对比度至少 4.5:1；交互目标至少 48×48dp；支持系统字体缩放和读屏。
• NFR-PERF-001 本地起卦为纯内存同步计算，用户确认后应即时完成，不显示伪加载动画。
• NFR-RES-001 旋转、切后台和可恢复的进程重建后保留当前流程状态。
• NFR-I18N-001 首版以简体中文为基线，所有用户文案从资源文件读取，不硬编码在 Composable 中。

7. MVP 非目标

• 自动、摇手机或 AI 随机起卦。
• 根据日期、位置、设备传感器或用户画像改变卦象。
• 社区、排行榜、连续签到、灵验率或“改善运势”机制。
• 付费解锁“更准”结果、制造焦虑的倒计时或重复付费抽取。
• 医疗、法律、投资、博彩、婚恋或职业决定的确定性建议。
• 用 AI 自动决定应该读取哪一爻或隐藏用户已经得到的动爻。
• 首版账号体系、云同步和社交分享图生成。

8. 成功标准

MVP 可以交付的最低条件：

1. 新用户不阅读帮助也能正确完成六次录入。
2. 所有 4,096 种六爻数值组合均能确定本卦和之卦，且满足领域不变量。
3. 断网时完整完成本地流程。
4. AI 被禁用、超时或返回非法内容时，原始结果仍然完整且可阅读。
5. 用户能清楚分辨“经典/本地内容”“AI 解释”和“建议行动”。
6. 无障碍检查覆盖投币控件、卦象、动爻和长文阅读。
7. 64 卦及爻辞内容通过完整性、来源和授权门禁。
8. 默认设置下完成起卦会生成一条仅在本机的完整记录；用户可以全局关闭、当次退出、单条删除或清空全部，且这些操作不会触发网络请求。

需求与验证方式的对应关系见质量门禁。