brainwave/docs/prototype.md

移动端交互原型

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

1. 原型目的

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

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

2. 交付范围

原型已经覆盖：

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

本轮不包含：

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

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

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

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

截图是 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 与最大字体测试。