brainwave/docs/product-spec.md

# 产品规格

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

## 1. 产品定义

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

核心承诺：

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

## 2. 产品原则

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

## 3. 目标用户与使用情境

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

典型情境：

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

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

## 4. MVP 用户流程

```text
首次说明
   ↓
起念：写下纠结之事
   ↓
定法：确认“背=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** 投币、求和、动爻变换和卦号映射必须符合[领域规则](domain-rules.md)。
- **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 解释与安全](ai-safety.md)的结构和语言边界。
- **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. 默认设置下完成起卦会生成一条仅在本机的完整记录；用户可以全局关闭、当次退出、单条删除或清空全部，且这些操作不会触发网络请求。

需求与验证方式的对应关系见[质量门禁](quality-gates.md#4-需求追踪矩阵)。