docs: add Android app implementation harness
This commit is contained in:
QiuSW
@@ -0,0 +1,143 @@
|
||||
# 产品规格
|
||||
|
||||
> 状态：MVP 方案基线
|
||||
> 产品代号：Brainwave（正式名称 TBD）
|
||||
> 原始输入：[原始需求.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** 未获得单独授权时，历史记录只保存在应用私有存储中。
|
||||
|
||||
## 6. 非功能需求
|
||||
|
||||
- **NFR-OFF-001** 写问题、录入、起卦、查看本地卦辞在飞行模式下可用。
|
||||
- **NFR-DET-001** 相同的六次投币输入和同一数据版本必须产生完全相同的本卦、动爻和之卦。
|
||||
- **NFR-SEC-001** 开发者 AI 密钥不得进入 APK、源码仓库或客户端日志。
|
||||
- **NFR-PRI-001** 问题文本、解释全文和模型请求不得写入分析埋点或崩溃日志。
|
||||
- **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 卦及爻辞内容通过完整性、来源和授权门禁。
|
||||
|
||||
需求与验证方式的对应关系见[质量门禁](quality-gates.md#4-需求追踪矩阵)。
|
||||
Reference in New Issue
Block a user