brainwave/docs/prototype.md

# 移动端交互原型

> 状态：高保真候选 v0.3；核心 v0.1 已确认，首页、问卦簿与默认本机保存流程已实现并待视觉复核
> 基准视口：360 × 792 CSS px（对应当前目标手机的紧凑竖屏体验）
> 实现位置：[`prototype/`](../prototype/)

## 1. 原型目的

在初始化 Android 工程前，先用可点击原型确认最容易返工的产品决策：信息层级、六次录入方式、结果阅读顺序、AI 同意门和东方文化表达。原型确认后，P3 的 Compose 页面应复用这里的设计令牌和状态契约，而不是重新发明流程。

v0.3 截图仍保留当时的视觉工作名“一问”，不得当作当前产品文案。正式产品名已由 [ADR-014](decisions.md#adr-014正式-android-身份与最低版本) 确认为“灵机”；应用图标与商店素材仍见 [TBD-001](decisions.md#未决问题)，P3 固化正式页面前须刷新原型品牌文案。

## 2. 交付范围

原型已经覆盖：

- 欢迎与方法说明；
- 首次欢迎与回访首页两种状态；
- 首页唯一主操作、“最近一次”和问卦簿次级入口；
- 开放式问题输入，以及明确的“不写具体内容”入口；
- 三枚硬币逐枚录入、字/背计值、六轮 bottom-up 进度和撤销上一爻；
- 本地确定性计算本卦、之卦和全部动爻；
- 有动爻与无动爻两种结果布局；
- 经典原文、本地白话和动爻的来源标签；
- “解”的本地/AI 两种分支；
- AI 发送范围说明、逐次同意、加载、成功、失败和本地降级；
- 首页本机保存/AI 发送边界说明与保存设置入口；
- 默认开启的完整记录自动保存、总开关与三个内容开关；
- 结果保存状态、当次不保存、自动保存关闭后的“保存本次”和解读关联反馈；
- 问卦簿列表、空状态、记录详情、单条删除和清空全部确认；
- 减少动态效果、键盘焦点、语义标签和最小触控目标。

本轮不包含：

- Android/Compose 生产代码；
- 深色主题、平板和横屏定稿；
- Room 真实持久化、历史迁移和系统 backup/data-extraction 配置；
- 真实 AI 请求、账户、服务端或持久化；
- 完整 64 卦授权内容包；
- 正式名称、图标、字体授权和商店视觉。

## 3. 运行方式

在仓库根目录运行：

```powershell
python -m http.server 4173 --bind 127.0.0.1
```

然后访问：

```text
http://127.0.0.1:4173/prototype/
```

原型无构建步骤、无第三方前端依赖，也不会发起外部网络请求。浏览器刷新会清空本次会话，这符合“评审原型”而非生产存储的定位。

服务保持运行时，重新生成截图并执行浏览器门禁：

```powershell
node prototype\capture.mjs
```

脚本使用本机 Chrome/Edge 的 DevTools 协议，不安装 npm 依赖。可通过任务专用环境变量 `BRAINWAVE_PROTOTYPE_URL` 指向不同的本地服务地址。

## 4. 评审入口

正常入口可以完整点击。为稳定复现截图，还提供只用于评审的查询参数：

| 状态 | URL | 评审重点 |
|---|---|---|
| 欢迎 | `?view=welcome` | 第一印象、文化气质、产品边界 |
| 起念 | `?view=question` | 输入层级、隐私提示、跳过入口 |
| 第三爻录入 | `?view=casting` | 手动录入、计值可见性、进度 |
| 有动爻结果 | `?view=result` | 复 24 → 坤 2、初爻动、内容顺序 |
| 无动爻结果 | `?view=static` | 乾 1、不出现之卦 |
| AI 同意 | `?view=consent` | 发送范围与明确同意 |
| AI 解读 | `?view=explanation` | 来源标签、非裁决语言、行动收束 |
| 本地解读 | `?view=local` | 离线分支与来源区分 |
| AI 失败 | `?view=error` | 结果保留、重试和本地降级 |
| 回访首页 | `?view=home` | 单一主操作、最近一次、问卦簿入口 |
| 回访首页空态 | `?view=home-empty` | 无记录时不显示空功能宫格 |
| 问卦簿 | `?view=history` | 倒序列表、问题/解释保存状态 |
| 问卦簿空态 | `?view=history-empty` | 空态说明与开始入口 |
| 历史详情 | `?view=history-detail` | 起卦快照、版本和已保存内容 |
| 保存设置默认态 | `?view=settings` | 四个开关默认开启、本机与备份边界 |
| 保存设置关闭态 | `?view=settings-off` | 总开关关闭、内容开关保留值并停用 |
| 本次未保存结果 | `?view=result-not-saved` | 未保存原因和“保存本次”恢复路径 |
| 删除确认 | `?view=delete` | 级联删除范围和再次确认 |
| 清空全部确认 | `?view=clear-all` | 全量删除范围、设置保持不变 |

这些参数只设置初始预览状态，不属于 Android 正式版路由。

## 5. 交互与领域契约

### 5.1 起卦

- 用户必须亲自投币并逐枚录入；页面没有随机、摇一摇或 AI 代投入口。
- 字记 2，背记 3；每轮三枚硬币全部有值后才能确认。
- 六轮按初爻到上爻记录，界面以“从下往上”明确提示。
- 6 为老阴、7 为少阳、8 为少阴、9 为老阳，6/9 标为动爻。
- 原型包含完整 64 卦 King Wen 序号映射，用于验证交互结果；生产实现仍必须按[领域规则](domain-rules.md)在纯 Kotlin 中重建并穷举测试，不能复制前端代码当作权威领域实现。
- 已确认的爻可逐步撤销；进入结果后本次结果不可被 AI 改写。

### 5.2 结果阅读

信息优先级固定为：

1. 本卦、之卦和动爻；
2. 用户本次所问；
3. 经典原文；
4. 本地白话；
5. 动爻文本与提示；
6. 用户主动点击“解”后的扩展解释。

无动爻时只显示本卦和“卦象稳定”提示，不虚构之卦。多动爻时必须透明保留全部变化位置。

### 5.3 AI 调用门

原型中的 AI 加载是本地模拟，不会调用模型。正式流程必须维持以下顺序：

```text
本地结果已展示
  → 用户点击「解」
  → 用户选择 AI
  → 页面说明确切发送字段
  → 用户勾选并确认
  → 才允许发起一次请求
```

失败状态不得隐藏或重算卦象，必须同时提供本地解释和重试入口。

### 5.4 首页与历史

- 首次欢迎页继续保持单一“开始”操作；有历史的回访首页使用更紧凑的开场，并在主操作之后展示最近一次。
- 首页不显示空的未来功能卡片。扩展区只渲染已上线入口；至少出现 3 个同级长期功能后才重新评估底部导航。
- 首页显示：“起卦与历史默认保存在本机，不主动上传。只有你选择 AI 解读时，本次所需内容才会发送。”并提供“管理保存设置”。
- 第六爻锁定后默认自动创建本机会话；结果页显示保存状态，并支持“本次不保存/删除本次记录”。总开关关闭时显示“本次未保存”和“保存本次”。
- 设置页提供默认开启的总开关、问题原文、解读全文和行动记录开关；总开关关闭时其余控制同步停用。清空全部必须二次确认。
- 本地或 AI 解读按设置加入同一会话；自动保存与 AI 同意完全独立，保存过程不得产生网络调用。
- 问卦簿中的演示记录只存在内存。刷新会恢复预览夹具，不能把原型行为误称为 Room 已实现。
- 删除必须经过确认；正式版级联删除会话、解释和行动记录。

这些状态在原型中使用内存模拟，刷新后恢复预览夹具；它们定义 Compose 的交互契约，但不代表 Room、DataStore 或备份排除已经实现。

## 6. 视觉系统

视觉遵循 [ADR-006](decisions.md#adr-006东方文化采用内容优先的纸墨朱砂设计)：

| 令牌 | 值 | 用途 |
|---|---|---|
| `paper` | `#F7F2E8` | 页面底色 |
| `surface` | `#FFFDF7` | 阅读卡片与弹层 |
| `ink` | `#1F1B16` | 标题、卦象和主要正文 |
| `ink-soft` | `#655E55` | 次级正文 |
| `cinnabar` | `#8C2F2B` | 主操作、动爻和关键提示 |
| `ochre` | `#765D3E` | 辅助标签和次级动作 |
| `outline` | `#B9AEA0` | 分隔和控件边界 |

标题和文化文本优先使用系统可用的中文宋体/衬线字体，控件与说明使用中文黑体/无衬线字体。正式 Android 版本必须决定可再分发字体或采用平台字体回退，不能把本机字体直接打包。

文化感来自排版、阅读节奏、卦象结构和克制的朱砂强调，不使用龙凤祥云、伪古印章、金色发光、正文毛笔字或抽卡式动效。

## 7. 原型截图

关键状态截图位于 [`prototype/screenshots/`](../prototype/screenshots/)，命名按用户旅程排序：

1. `01-welcome.png`
2. `02-question.png`
3. `03-casting.png`
4. `04-result-moving.png`
5. `05-result-static.png`
6. `06-ai-consent.png`
7. `07-ai-explanation.png`
8. `08-ai-error.png`
9. `09-home-returning.png`
10. `10-home-empty.png`
11. `11-history-list.png`
12. `12-history-empty.png`
13. `13-history-detail.png`
14. `14-settings-default.png`
15. `15-delete-confirm.png`
16. `16-settings-off.png`
17. `17-result-not-saved.png`
18. `18-clear-all-confirm.png`

目录中的 `14-save-record.png` 与 `16-save-with-explanation.png` 是 v0.2 手动保存流程的历史评审证据，当前截图脚本不再生成，不能用于 v0.3 验收。

截图是 360 CSS px 宽度的评审证据，不是应用商店素材。

## 8. 验收清单

进入 Android P0/P3 前，需要用户明确反馈或确认：

- [x] “纸、墨、朱砂、留白”的整体气质；
- [x] 工作名只作占位，不把“一问”直接视为正式名称；
- [x] 三枚硬币圆形切换控件与结果阅读层级；
- [x] 本地/AI 选择、同意门和非裁决式行动语气；
- [x] 产品已确认历史默认本机自动保存、可全局关闭和当次退出（ADR-012）；
- [ ] 回访首页的“最近一次 / 问卦簿”层级是否保持了主流程焦点；
- [ ] v0.3 首页告知、默认开启设置、结果保存状态、当次退出和清空全部是否足够清楚；
- [ ] 问卦簿列表、空态、详情和删除确认是否适合进入 Compose 实现；
- [ ] 是否在下一轮原型加入深色主题或更大字号状态。

未确认项应继续停留在原型层修改；不应提前固化为 Compose 生产页面。

## 9. 向 Android 实现的映射

| 原型概念 | Compose 目标 |
|---|---|
| CSS 颜色/间距/圆角令牌 | `MaterialTheme` 扩展与 design token |
| `welcome/question/casting/result` | Navigation destination + 状态驱动页面 |
| `home/history/history-detail` | 顶层首页 + Room `Flow` 驱动的列表/详情 |
| 三枚硬币控件 | 具备明确 semantics 的 48dp+ Compose 控件 |
| 六爻图 | Canvas 绘制 + 完整读屏描述 |
| 底部选择/同意层 | Material 3 modal bottom sheet/dialog |
| 本地/AI/错误来源标签 | sealed UI state，不以颜色作为唯一提示 |
| `prefers-reduced-motion` | 系统动画缩放/无障碍偏好适配 |
| 保存状态/设置/删除确认 | `HistorySavePolicy` 状态驱动 UI + 事务保存/级联删除用例 |

Compose 实现必须从 `CastResult` 渲染，不能在 UI 层复制 King Wen 映射或根据文本猜测卦象。

## 10. 本轮验证记录

- `node --check prototype/app.js`：通过。
- `node --check prototype/capture.mjs`：通过。
- `node prototype/capture.mjs`：通过；十八个状态完成 360px 截图与浏览器审计。
- `git diff --check`：通过。
- Chromium 360 × 792：核心流程、首页、历史、保存设置、自动保存/未保存状态、删除与清空确认均已渲染。
- 已知夹具 `9,8,8,8,8,8`：显示复 24 → 坤 2，初爻动。
- 静态夹具 `7,7,7,7,7,7`：显示乾 1，无动爻且无之卦。
- 浏览器控制台错误：0；运行时异常：0；外部请求：0；模型调用：0。
- 首页只有 1 个主流程开始按钮且没有底部导航；问卦簿演示列表为 3 条，删除确认后为 2 条。
- 四个保存开关默认开启；关闭总开关后三个内容开关保留值并停用。
- 结果默认显示自动保存状态；“本次不保存”删除当次记录后可重新“保存本次”，且不会改变全局设置。
- AI 解读生成后显示“解读已加入本次记录”；保存、设置、历史与删除流程产生的外部请求均为 0。
- 清空全部会删除三条演示记录、保留自动保存设置，并返回可操作的设置页。
- 375×812、430×932 与 792×360：无水平溢出，主内容可达；回访首页前进/返回恢复正确。
- `prefers-reduced-motion: reduce`：页面动效压缩至近零时长。
- 新增成功、危险和次级文字组合的对比度均不低于 4.97:1。
- 十八个状态的未命名按钮、低于 48px 的按钮触控目标、过小开关/复选框标签：均为 0。

原型验证不能替代 P1 的 4,096 组合领域测试，也不能替代 Android 真机、TalkBack 与最大字体测试。v0.3 已满足 ADR-012 的原型门禁，但仍需用户完成视觉复核后才能映射到 Compose。