# 前端 UX 改进分析计划

## 问题概述

对 void-chat 前端代码进行了全面分析，涵盖页面路由、聊天组件、共享UI组件、状态管理、CSS样式、工具库等6大模块。以下按优先级整理待改进项。

---

## 🔴 P0 — 关键体验问题（影响核心功能使用）

### 1. 消息输入无草稿持久化
- **问题**: 用户刷新或断开连接时，正在输入的消息丢失
- **位置**: `MessageInput.tsx`, `PrivateChat.tsx`
- **建议**: 基于 localStorage 实现自动保存草稿，按 roomId 分隔

### 2. WebSocket 断连无用户反馈
- **问题**: 连接丢失时仅内部状态变化，用户看不到明确的"连接已断开/正在重连"提示；重连失败后仅显示通用 toast
- **位置**: `useBaseWebSocket.ts` (lines 77, 107, 110)
- **建议**: 在聊天界面顶部显示持续性连接状态条（非 toast），包含重连倒计时和重试次数；恢复连接后显示"已恢复"成功提示

### 3. 消息发送无确认反馈
- **问题**: 发送消息后无"发送中/已发送/失败"状态指示，用户不确定消息是否到达服务器
- **位置**: `useMessageComposer.ts`, `chatStore.ts`
- **建议**: 实现乐观更新——消息立即追加到列表（带 pending 状态），收到服务器确认后更新；失败时显示重试按钮

### 4. 移动端触控目标过小
- **问题**: 多个按钮触控面积不足 44×44px（iOS/Android 最低推荐值）
  - `.icon-btn`: padding 6px ≈ 20×20px
  - `.msg-action-btn`: padding 4px×10px ≈ 20×22px
  - `.modal-close-btn`: padding 2px×6px ≈ 14×14px
  - `.kick-btn`: padding 3px ≈ 13×13px
  - `.dm-btn`: padding 4px ≈ 16×16px
- **位置**: `responsive.css`, `messages.css`, `modals.css`, `sidebar.css`
- **建议**: 为移动端增加 `min-width/min-height: 44px` 或增大 padding

### 5. 移动端消息操作按钮不可见
- **问题**: 编辑/删除等操作按钮仅 hover 时显示，触屏设备无 hover
- **位置**: `MessageItem.tsx`, `messages.css`
- **建议**: 移动端改为长按菜单或在消息右侧显示 "⋯" 更多按钮

### 6. 应用初始化无加载状态
- **问题**: `checkAuth()` 执行期间无 loading UI，用户可能看到页面闪跳（先显示错误页面再重定向）
- **位置**: `App.tsx` (lines 24-26)
- **建议**: 添加全屏 loading 指示器，auth check 完成前不渲染路由

### 7. 无错误边界
- **问题**: 任何组件渲染错误都会导致白屏，无 fallback UI
- **位置**: `App.tsx`
- **建议**: 在 Routes 外层添加 React ErrorBoundary，提供友好的错误页面和重试按钮

---

## 🟠 P1 — 重要体验改进（影响使用效率）

### 8. Emoji 选择器功能缺失
- **问题**: 仅 31 个固定 emoji，无搜索、无分类、无最近使用、无键盘导航、无肤色变体
- **位置**: `EmojiPicker.tsx`, `emojis.ts`
- **建议**: 扩展 emoji 数据集，添加搜索过滤、分类标签页、最近使用记录、键盘方向键导航

### 9. Toast 通知体验不足
- **问题**: 固定 4 秒消失无法定制（错误类信息消失太快）；无手动关闭按钮；无堆叠逻辑（多条可能重叠）；无 aria-live 无障碍支持
- **位置**: `Toast.tsx`, `uiStore.ts` (line 75)
- **建议**: 错误类 toast 延长到 8 秒或需手动关闭；添加关闭按钮和堆叠排队；添加 `role="alert"` 和 `aria-live`

### 10. 表单验证反馈缺失（全局性问题）
- **问题**: 所有表单（登录/注册/创建房间/编辑资料）均仅在提交时验证，无实时反馈
  - 密码不匹配只有提交后才提示
  - 房间容量范围无即时校验
  - 缺少字段级 required/optional 标记
- **位置**: `AuthPage.tsx`, `CreateRoomDialog.tsx`, `EditRoomDialog.tsx`, `ProfileModal.tsx`
- **建议**: 添加 inline 实时校验提示、字段必填标记、字符计数器

### 11. 搜索面板 UX 欠缺
- **问题**: 必须手动按 Enter 才搜索（无实时搜索）；无结果分页；点击结果跳转后搜索面板仍然打开遮挡视线；搜索结果缺少键盘导航（↑↓）
- **位置**: `SearchPanel.tsx`
- **建议**: 添加防抖实时搜索；结果项点击后自动收起面板或半透明化；支持键盘导航

### 12. 私信体验不完整
- **问题**:
  - 无已读标记（仅关闭时才发 mark_read，阅读中不标记）
  - 无输入中指示器（主聊天有，私信没有）
  - 手动滚动用三重 `requestAnimationFrame`（性能隐患）
  - 私信不支持 @mention 和 emoji 快捷插入
  - 无法删除/归档旧对话
- **位置**: `PrivateChat.tsx`
- **建议**: 查看消息时即标记已读；复用主聊天的 typing indicator；使用虚拟列表替代手动滚动；共享输入组件能力

### 13. Markdown 渲染缺失功能
- **问题**: 链接无 `target="_blank"`（用户点击后离开聊天）；无代码块复制按钮；无语法高亮
- **位置**: `lib/markdown.ts`
- **建议**: 配置 marked renderer 为链接添加 `target="_blank" rel="noopener noreferrer"`；代码块添加复制按钮；考虑集成轻量语法高亮

### 14. 空状态/加载状态处理不足
- **问题**: 多处缺少有意义的空状态提示
  - "No Rooms Available" 无引导操作（如"立即创建一个"）
  - "No Private Conversations Yet" 无开始对话入口
  - 房间加载中无骨架屏
  - 私信列表无 loading 指示器
- **位置**: `LobbyPage.tsx`, `MailboxPage.tsx`, `ChatPage.tsx`, `chatStore.ts`
- **建议**: 所有空状态添加引导 CTA；loading 使用骨架屏而非纯文字

### 15. 文件上传无进度指示
- **问题**: 上传仅显示 "Uploading..." 文字，无进度条或百分比
- **位置**: `MessageInputBar.tsx` (lines 82-87)
- **建议**: 使用 XMLHttpRequest 或 fetch + ReadableStream 实现上传进度条

### 16. Admin 面板缺少分页和排序
- **问题**: 用户列表一次性渲染全部（千级用户时性能问题）；无表头排序；无批量操作
- **位置**: `AdminUserManagementTab.tsx` (lines 210-305)
- **建议**: 实现分页或虚拟滚动；添加表头排序（用户名/注册时间/角色）；添加多选批量禁用/禁言

### 17. Admin 角色变更无确认对话框
- **问题**: 角色变更立即执行，无二次确认（disable/mute 有确认，role 没有）
- **位置**: `AdminUserManagementTab.tsx` (lines 60-79)
- **建议**: 添加确认对话框，防止意外操作

---

## 🟡 P2 — 体验优化（提升精致感）

### 18. 键盘快捷键和无障碍
- **问题**:
  - 搜索输入框 `outline: none` 导致键盘焦点不可见
  - 多个按钮缺少 focus-visible 样式（emoji-btn, kick-btn, dm-btn）
  - Admin tab panel 缺少 `role="tabpanel"`
  - 未读 badge 缺少 aria-label（屏幕阅读器无法感知）
  - 缺少全局快捷键帮助（如 `?` 弹出快捷键列表）
- **位置**: CSS 多处, `AdminPage.tsx`, `LobbyPage.tsx`, `ChatView.tsx`
- **建议**: 修复所有 `outline: none`；补全 focus-visible 样式；添加 ARIA 角色和标签

### 19. TypingIndicator 过渡生硬
- **问题**: 输入中指示器突然出现/消失，无动画过渡；用户断连后可能残留"正在输入"状态
- **位置**: `TypingIndicator.tsx`
- **建议**: 添加 fade-in/fade-out 动画；客户端设置输入状态超时自动清除

### 20. 图片查看器体验
- **问题**: 占位尺寸硬编码 800×600 导致加载时视觉跳动；图片加载期间无 loading 指示；alt 文本使用通用 "Shared image"
- **位置**: `ImageViewer.tsx`, `MessageContent.tsx`
- **建议**: 使用实际比例占位；添加加载动画；生成有意义的 alt 文本

### 21. Matrix Rain 移动端电池消耗
- **问题**: 即使标签页不可见时也持续运行动画，不响应 Page Visibility API
- **位置**: `MatrixRain.tsx`
- **建议**: 监听 `document.visibilitychange`，标签页隐藏时暂停 canvas 动画

### 22. CSS 层级和性能问题
- **问题**:
  - `noise-overlay` z-index: 9999 过高
  - modal(1000) vs sidebar(1001) z-index 可能冲突
  - noise 动画 0.2s infinite（每秒 40+ 帧重绘）影响低端设备
  - 多处 `backdrop-filter: blur()` 在低端设备卡顿
  - 滚动条样式不一致（部分隐藏、部分自定义、部分原生）
- **位置**: `effects.css`, `responsive.css`, `modals.css`
- **建议**: 统一 z-index 层级体系（用 CSS 变量）；移动端禁用 noise 动画；统一滚动条策略

### 23. 响应式断点不足
- **问题**: 仅一个 768px 断点，缺少 480px（小手机）、1024px（平板）、1440px（大桌面）
- **位置**: `responsive.css`
- **建议**: 至少增加 480px 和 1024px 两个断点

### 24. 低对比度文本可能不符 WCAG AA
- **问题**: `--color-text-muted: #2d5f3a` 在深色背景上对比度约 35%，可能不满足 WCAG AA 4.5:1 最低要求
- **位置**: `tokens.css`
- **建议**: 提高 muted 文本亮度；`.role-badge` 9px 字号也需增大到至少 11px

### 25. HTML 缺少 PWA/SEO 基础
- **问题**: 无 favicon、无 `<meta name="description">`、无 `<meta name="theme-color">`、无 PWA manifest、无 Open Graph 标签
- **位置**: `index.html`
- **建议**: 添加基础 meta 标签和 favicon

### 26. 密码房间交互细节
- **问题**: 密码输入无显示/隐藏切换；回车键不能提交；私有房间可不设密码就创建
- **位置**: `RoomPasswordModal.tsx`, `CreateRoomDialog.tsx`
- **建议**: 添加密码可见性切换；表单支持 Enter 提交；私有房间强制要求密码

### 27. 本地化问题
- **问题**: `ProfileModal.tsx` line 36 硬编码中文 "头像上传失败"，与其他英文错误提示不一致
- **位置**: `ProfileModal.tsx`
- **建议**: 替换为英文或建立统一的 i18n 机制

### 28. UserCard 的 DOM 操作反模式
- **问题**: 直接操作 DOM 的 `Object.getOwnPropertyDescriptor` 方式在 textarea 中插入 mention，不符合 React 范式
- **位置**: `UserCard.tsx` (lines 115-129)
- **建议**: 使用 React ref 和 state 驱动的方式插入

### 29. Mention 下拉框缺少键盘确认和关闭
- **问题**: 高亮项无法用 Enter/Space 选择（仅支持点击）；无 Escape 关闭；无点击外部关闭
- **位置**: `MentionDropdown.tsx`
- **建议**: 支持 Enter 确认选择、Escape 关闭、点击外部关闭

### 30. 邀请链接管理 UX
- **问题**: 创建后显示邀请码但无自动复制提示；列表仅显示截断预览；单条邀请无复制按钮
- **位置**: `AdminControlTab.tsx`
- **建议**: 创建后自动复制到剪贴板并提示；每条邀请添加复制按钮

---

## 改进优先级总览

| 优先级 | 编号 | 改进项 | 影响范围 |
|--------|------|--------|---------|
| 🔴 P0 | 1 | 消息草稿持久化 | 所有聊天场景 |
| 🔴 P0 | 2 | WebSocket 断连反馈 | 所有聊天场景 |
| 🔴 P0 | 3 | 消息发送确认状态 | 所有聊天场景 |
| 🔴 P0 | 4 | 移动端触控目标 | 移动端全局 |
| 🔴 P0 | 5 | 移动端消息操作 | 移动端聊天 |
| 🔴 P0 | 6 | 初始化加载状态 | 所有页面 |
| 🔴 P0 | 7 | 错误边界 | 所有页面 |
| 🟠 P1 | 8 | Emoji 选择器 | 聊天输入 |
| 🟠 P1 | 9 | Toast 通知改进 | 全局 |
| 🟠 P1 | 10 | 表单验证反馈 | 所有表单 |
| 🟠 P1 | 11 | 搜索面板 UX | 聊天搜索 |
| 🟠 P1 | 12 | 私信体验完善 | 私信 |
| 🟠 P1 | 13 | Markdown 渲染增强 | 消息展示 |
| 🟠 P1 | 14 | 空状态/加载状态 | 多处 |
| 🟠 P1 | 15 | 文件上传进度 | 文件上传 |
| 🟠 P1 | 16 | Admin 分页排序 | 管理面板 |
| 🟠 P1 | 17 | Admin 角色确认 | 管理面板 |
| 🟡 P2 | 18-30 | 见上文详细列表 | 各模块 |