dudu 前端实现设计

目录

一、设计系统消费策略

设计系统位于 design/（tokens / React 组件 / UI kits / 品牌资产），是所有界面的唯一真相源。两类终端用不同方式消费：

设计系统硬规则（全端强制）

• 一屏最多一个蓝色主按钮，其余操作用 secondary / ghost
• 禁用渐变，纯色填充；单一品牌蓝，唯一例外色是微信品牌绿 #07C160（仅登录按钮）
• 识别浮层永远深色玻璃（light/dark 模式下不变）
• 图标只用 Lucide 线条（2px 圆头描边、currentColor），无 emoji、无 unicode 符号图标；例外：键帽字符 ⌘ ⇧ ⌫ ↵
• 文案：对用户称"你"、短句、微文案不带句号、提示语用"·"分隔；partial/final 等技术词不出现在 UI
• 动效三档 120/200/320ms、快入慢出；唯一循环动画是录音中的波形；无弹跳、无旋转、无视差
• 品牌名永远小写 dudu；中文写法"dudu 语音输入"或"嘟嘟语音输入"

二、设计令牌总表

来源 design/tokens/，此处摘录实现必需的关键值（完整以源文件为准）。

2.1 颜色（语义别名）

2.2 字体 / 间距 / 圆角 / 控件 / 动效

三、组件库与原生映射

React 组件（桌面端直接用）→ 移动端原生等价规格。文案全部内置于组件，移动端照抄。

3.1 核心组件速查

3.2 Waveform（波形）

• 条宽 3px、间距 3px、圆角 2px、currentColor；高度模式固定 12 值序列 [0.3,.55,.85,.45,.7,1,.4,.6,.25,.8,.5,.35] × height，最小 4px
• active 时 scaleY 0.35→1 交替动画 0.9s ease-in-out，逐条延迟 (i%6)*0.07s；这是全产品唯一循环动画，仅录音中出现
• 用法：浮层 bars=12 height=24 color=#7C9BFF；MicBar 录音态 bars=9 height=18 白色 95%

3.3 MicBar（麦克风条，移动端核心）

尺寸：高 56（--control-xl）、全宽、胶囊 999、15px/600 字重、图标线条 mic 20px；touch-action:none；移动端按压可缩 0.97（桌面无缩放）。

3.4 RecognitionOverlay（识别浮层）

• 宽 340、padding 14 18、圆角 14、--overlay-bg + blur(12px)、--shadow-overlay；入场淡入 + 上移 4px（200ms ease-out）
• 两态：listening（Waveform + mic 图标 + "聆听中…" 15px overlay-text-2）/ text（final 用 overlay-text 亮色，partial 用 overlay-text-2 灰色拼接其后，15px 行高 1.6）
• hint 右对齐 11px overlay-text-3："松开 ⌘⇧Space 完成输入"
• role="status" 无障碍播报

四、桌面端实现（Tauri 2）

4.1 技术栈与工程结构

desktop/
  src-tauri/            Rust：快捷键 / 音频采集 / WS / 注入 / 托盘 / 窗口管理
  src/                  React + Vite + TypeScript
    windows/
      overlay/          识别浮层窗口
      settings/         设置窗口
      login/            登录 / 购买窗口
      tray/             自绘托盘菜单窗口
    shared/             事件桥（tauri event ↔ React state）、API client
  package.json          依赖 @dudu/design（指向 ../design）

4.2 窗口清单与规格

4.3 首次启动流程

欢迎页 → 权限引导（macOS 辅助功能 + 麦克风，带系统设置深链）→ 微信扫码登录 → 试一试（示例输入框按住 ⌘⇧Space 说一句话）。Windows 无辅助功能步骤。

五、桌面端状态机与 Rust↔Web 事件

5.1 识别状态机（对照 OverlayDemo.jsx）

idle ──按下快捷键──▶ listening ──首个识别结果──▶ streaming ──松开──▶ idle
                      │ (浮层立即弹出"聆听中"，               │ final 注入焦点输入框
                      │  不等首个结果，420ms 内无结果保持)     │ 浮层淡出
                      └──松开(未出字)──▶ idle（不注入）

• partial 只进浮层不注入；final 句子级注入（句读处定稿，浮层中 final 亮色 + partial 灰色拼接）
• 松开时若有未定稿 partial，与 final 一并注入（committed = final + partial）
• 注入后浮层内容清空，准备下一次会话

5.2 Rust → Web 事件

5.3 Web → Rust 命令（invoke）

set_hotkey · set_mic_device / list_mic_devices · set_autostart · set_theme · open_url（更新下载页）· logout。设置持久化于本地（tauri-plugin-store），登录态 JWT 存系统钥匙串。

六、移动端键盘扩展（iOS / Android）

6.1 面板结构（自上而下，对照 KeyboardScreen.jsx）

面板底色 --surface-2 + 顶部 1px border-1；跟随系统 light/dark。

6.2 账户四态（工具条右侧文案 × MicBar 状态联动）

6.3 交互流程

1. 按住麦克风条 → 进 recording：开始采集 + WS 推流；宿主输入框边框变 1.5px accent（视觉锚定目标）
2. 识别中：partial 文本条流式刷新（final 亮 + partial 灰）；partial 不进宿主输入框
3. 松开 → committed（final + 未定稿 partial）经 iOS textDocumentProxy.insertText / Android currentInputConnection.commitText 上屏；状态复位
4. 上滑取消：手指上移超过阈值（48pt）松开 → 丢弃本次结果，不上屏
5. 功能键：，。 直接 insertText；退格 deleteBackward；发送 = 宿主 return key

6.4 平台实现要点

6.5 iOS 录音主路径结论（1A spike 真机实证，14D 落地）

键盘扩展进程内无法录音：即使"允许完全访问"开启，AVAudioSession setActive/start 在扩展进程内直接报 CoreAudio 错误 2003329396 —— iOS 平台硬限制，与权限无关。因此 iOS 语音主路径采用预留的 deep link 降级方案：

1. 键盘 MicBar 改为"按一下 · 去 dudu 说话"，经 extensionContext.open 打开 dudu://dictate（主 App 全屏听写页，深色玻璃 overlay 风格）
2. 主 App 进程录音推流：AVAudioEngine 采集 → AVAudioConverter 重采样 16kHz/16bit/mono → 100ms/3200B 分帧 → WSS /v1/asr/stream，partial/final 流式显示（final 亮 / partial 灰）
3. 松开定稿：committed 文本复制到剪贴板 + 写 App Group pending_text（120s 有效）双保险，提示"已复制 · 回到原 App 粘贴"
4. 用户手动切回原 App（iOS 无"自动跳回上一 App"的公开 API，键盘扩展也无法携带可跳回的 return 上下文）→ dudu 键盘 viewWillAppear 检出未过期 pending_text，textDocumentProxy.insertText 自动上屏并在工具条短暂显示"已上屏"；过期则用户手动粘贴剪贴板兜底

七、移动端主 App 四屏（对照 AppScreens.jsx）

八、反馈问题（v1.1 新增）

用户在客户端内直接反馈问题或建议，支持文字 + 图片，可选附带诊断信息。入口：桌面设置窗口"帮助"分组、移动端"我的"页列表行；键盘扩展内不放入口（保持键盘极简）。

8.1 表单规格（桌面 / 移动一致）

8.2 交互与实现

• 提交走 POST /v1/feedback（multipart/form-data，需登录；未登录时入口处提示先登录）
• 图片在客户端先压缩到长边 ≤2000px 再上传（缩短上传时间）；上传进度复用 ProgressBar
• 桌面端反馈窗口独立于设置窗口（420px），关闭不影响设置；移动端为普通推入页面
• 限频由服务端控制（每用户 10 条/天），超限时 toast 提示"今天反馈次数已达上限"

九、客户端打点（v1.1 新增）

目的：量化响应时间（对照延迟目标）与关键链路质量，驱动体验改进。隐私底线：任何事件不携带识别文本与音频。

9.1 指标清单

公共维度（每条自动附带）：device_id（客户端首次启动生成的匿名 UUID，与账号无关）、platform、app_version、os_version、client_ts。

9.2 上报机制

• 本地 JSONL 队列：满 20 条 或 60s 或冷启动时批量 POST /v1/metrics/batch（gzip）
• 失败指数退避重试；本地队列上限 1000 条，超出丢最旧；上报失败不影响任何功能
• 接口允许匿名（登录前的 onboarding 漏斗也要收）；登录后自动带上 user_id
• 性能事件 MVP 全量上报（量小），后续可服务端下发采样率

9.3 各端实现位置

十、UI 状态 ↔ 后端接口对照

前端每个动态数据点都有明确来源（接口详见 backend-architecture.html）：

十一、100% 还原核查清单（验收标准）

1. 所有颜色 / 字号 / 间距 / 圆角 / 阴影 / 动效值只来自令牌，无硬编码（移动端来自生成的 Theme 文件）
2. 一屏一个蓝色主按钮；secondary/ghost 用于其余操作
3. 全局无渐变；唯一例外色为微信绿 #07C160（仅登录按钮）
4. 识别浮层在 light/dark 下均为深色玻璃（--overlay-bg + blur12）且 focusable:false
5. 图标全部 Lucide 2px 线条 currentColor；UI 无 emoji；键帽字符 ⌘⇧⌫↵ 仅在 Kbd/HotkeyCombo
6. 文案抽样核查：用"你"、微文案无句号、"·"分隔提示、半角数字 + 空格（472 / 600 分钟、00:04）、无 partial/final 字样
7. MicBar 四态视觉与文案逐字对照 MicBar.jsx；浮层两态对照 RecognitionOverlay.jsx
8. 波形是唯一循环动画且仅录音中出现；prefers-reduced-motion 下停止
9. 焦点环仅键盘聚焦显示（:focus-visible）
10. light/dark 切换全界面无遗漏（含键盘面板、设置、主 App）；桌面"跟随系统"实时响应
11. 对照 ui_kits 演示页（design/ui_kits/desktop/index.html、mobile/index.html）逐屏截图比对