brainwave/docs/prototype.md

移动端交互原型

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

1. 原型目的

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

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

2. 交付范围

原型已经覆盖：

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

本轮不包含：

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

3. 运行方式

在仓库根目录运行：

python -m http.server 4173 --bind 127.0.0.1

然后访问：

http://127.0.0.1:4173/prototype/

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

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

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 序号映射，用于验证交互结果；生产实现仍必须按领域规则在纯 Kotlin 中重建并穷举测试，不能复制前端代码当作权威领域实现。
• 已确认的爻可逐步撤销；进入结果后本次结果不可被 AI 改写。

5.2 结果阅读

信息优先级固定为：

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

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

5.3 AI 调用门

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

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

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

5.4 首页与历史

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

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

6. 视觉系统

视觉遵循 ADR-006：

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

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

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

7. 原型截图

关键状态截图位于 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 前，需要用户明确反馈或确认：

• “纸、墨、朱砂、留白”的整体气质；
• 工作名只作占位，不把“一问”直接视为正式名称；
• 三枚硬币圆形切换控件与结果阅读层级；
• 本地/AI 选择、同意门和非裁决式行动语气；
• 产品已确认历史默认本机自动保存、可全局关闭和当次退出（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。