# 移动端交互原型

> 状态：高保真候选 v0.1，待用户视觉与流程确认
> 基准视口：360 × 792 CSS px（对应当前目标手机的紧凑竖屏体验）
> 实现位置：[`prototype/`](../prototype/)

## 1. 原型目的

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

本轮使用“一问”作为视觉工作名。它不构成正式命名决定；正式名称、应用图标和商店素材仍是 [TBD-001](decisions.md#未决问题)。

## 2. 交付范围

原型已经覆盖：

- 欢迎与方法说明；
- 开放式问题输入，以及明确的“不写具体内容”入口；
- 三枚硬币逐枚录入、字/背计值、六轮 bottom-up 进度和撤销上一爻；
- 本地确定性计算本卦、之卦和全部动爻；
- 有动爻与无动爻两种结果布局；
- 经典原文、本地白话和动爻的来源标签；
- “解”的本地/AI 两种分支；
- AI 发送范围说明、逐次同意、加载、成功、失败和本地降级；
- 减少动态效果、键盘焦点、语义标签和最小触控目标。

本轮不包含：

- Android/Compose 生产代码；
- 深色主题、平板和横屏定稿；
- 历史记录与设置页面；
- 真实 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` | 结果保留、重试和本地降级 |

这些参数只设置初始预览状态，不属于 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
  → 页面说明确切发送字段
  → 用户勾选并确认
  → 才允许发起一次请求
```

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

## 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`

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

## 8. 验收清单

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

- [ ] “纸、墨、朱砂、留白”的整体气质是否合适；
- [ ] 工作名只作占位，不把“一问”直接视为正式名称；
- [ ] 三枚硬币用圆形切换控件录入是否容易理解；
- [ ] 结果页先卦象、后原文/白话、再点击“解”的层级是否合适；
- [ ] 本地解读与 AI 解读的选择、同意和来源标签是否足够清楚；
- [ ] “可以试的一小步”的非预测、非裁决语气是否符合定位；
- [ ] 是否需要在下一轮原型加入历史记录、深色主题或更大字号状态。

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

## 9. 向 Android 实现的映射

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

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：欢迎、起念、录入、有/无动爻结果、AI 同意、成功与失败状态已渲染。
- 已知夹具 `9,8,8,8,8,8`：显示复 24 → 坤 2，初爻动。
- 静态夹具 `7,7,7,7,7,7`：显示乾 1，无动爻且无之卦。
- 浏览器控制台错误：0；运行时异常：0；外部请求：0；模型调用：0。
- 八个状态的未命名按钮、低于 48px 的按钮触控目标、过小复选框标签：均为 0。

原型验证不能替代 P1 的 4,096 组合领域测试，也不能替代 Android 真机、TalkBack 与最大字体测试。