feat: Phase 3 产品体验 + Phase 4 后端增强

## Phase 3: 产品体验

### 可访问性 (a11y)
- 全局 :focus-visible 焦点样式 + prefers-reduced-motion 降级
- 7 个组件补充 ARIA 属性 (aria-label, role, aria-pressed, aria-live)
- SettingsDrawer 完整 dialog/tab ARIA 语义 + useFocusTrap 焦点陷阱
- Canvas 区域 role="img" 标注

### 响应式布局
- 接入 useIsMobile/usePrefersReducedMotion hooks
- SettingsDrawer 移动端全宽 + 背景遮罩
- ControlPanel/TopHUD 响应式适配

### 主题系统
- VoiceInteractionPanel dark: 变体修复
- SettingsDrawer 主题切换按钮 (Sun/Moon)
- DigitalHumanViewer/ChatDock reduced motion 支持

## Phase 4: 后端增强

### 认证中间件
- AuthMiddleware 支持 X-API-Key header
- AUTH_ENABLED/API_KEYS 环境变量配置
- /health 和 / 免认证

### 会话持久化抽象
- SessionStore 抽象接口
- InMemorySessionStore (默认) + RedisSessionStore (可选)
- dialogue.py 重构，移除模块级全局变量

### Docker 化
- 多阶段 Dockerfile (node + python)
- nginx 反向代理 + supervisord 进程管理
- docker-compose.yml 含 Redis 服务

### WebSocket 骨架
- /ws endpoint + wsClient.ts (未接入主流程)

## 测试
- 前端: 118 测试通过
- 后端: 49 测试通过

Author: shijiashuai

.claude/settings.local.json

@@ -1,7 +1,8 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npx tsc:*)"
+      "Bash(npx tsc:*)",
+      "Bash(npx vitest:*)"
     ]
   }
 }

.dockerignore

@@ -0,0 +1,8 @@
+node_modules
+.git
+dist
+dist-*
+*.pyc
+__pycache__
+.env
+.claude

Dockerfile

@@ -0,0 +1,29 @@
+# Stage 1: Build frontend
+FROM node:18-alpine AS frontend-builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Stage 2: Production
+FROM python:3.12-slim
+WORKDIR /app
+
+# Install nginx
+RUN apt-get update && apt-get install -y --no-install-recommends nginx supervisor && rm -rf /var/lib/apt/lists/*
+
+# Backend setup
+COPY server/requirements.txt /app/server/
+RUN pip install --no-cache-dir -r /app/server/requirements.txt
+COPY server/ /app/server/
+
+# Frontend built assets
+COPY --from=frontend-builder /app/dist /usr/share/nginx/html
+
+# Config files
+COPY docker/nginx.conf /etc/nginx/sites-available/default
+COPY docker/supervisord.conf /etc/supervisor/conf.d/metahuman.conf
+
+EXPOSE 80
+CMD ["supervisord", "-n"]

docker-compose.yml

@@ -0,0 +1,36 @@
+version: "3.8"
+
+services:
+  app:
+    build: .
+    ports:
+      - "3000:80"
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
+      - OPENAI_MODEL=${OPENAI_MODEL:-gpt-4o-mini}
+      - LLM_PROVIDER=${LLM_PROVIDER:-openai}
+      - TTS_PROVIDER=${TTS_PROVIDER:-edge}
+      - AUTH_ENABLED=${AUTH_ENABLED:-false}
+      - API_KEYS=${API_KEYS:-}
+      - REDIS_URL=redis://redis:6379/0
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+    volumes:
+      - redis_data:/data
+    restart: unless-stopped
+
+volumes:
+  redis_data:

docker/nginx.conf

@@ -0,0 +1,30 @@
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /v1/ {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 300s;
+    }
+
+    location /health {
+        proxy_pass http://127.0.0.1:8000;
+    }
+
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+}

docker/supervisord.conf

@@ -0,0 +1,24 @@
+[supervisord]
+nodaemon=true
+logfile=/dev/null
+logfile_maxbytes=0
+
+[program:nginx]
+command=nginx -g "daemon off;"
+autostart=true
+autorestart=true
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+
+[program:backend]
+command=uvicorn app.main:app --host 127.0.0.1 --port 8000
+directory=/app/server
+autostart=true
+autorestart=true
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+environment=PYTHONUNBUFFERED="1"

docs/architecture.md

@@ -89,3 +89,51 @@ UI 层尽量“只读 store + 调用高层 action”，避免直接操作底层
 1. `visionService` 获取视频帧并运行推理
 2. `visionMapper` 输出简化状态（emotion、nod/shake 等）
 3. 页面/引擎应用到数字人表现（表情与动作）
+
+## 5. 当前架构评估
+
+- 优点
+  - 已经形成 `page -> hooks -> orchestrator/service -> store` 的基本分层，`AdvancedDigitalHumanPage` 比早期版本更薄。
+  - 前端对后端断连有 fallback，适合 Demo/SDK 场景。
+  - 3D、语音、视觉、对话四条主能力链路已经能独立演进。
+- 当前主要问题
+  - 聊天消息生命周期分散在 hook、orchestrator、store 三处，容易出现占位消息、流式结束、错误清理不同步。
+  - 传输层当前同时存在普通 HTTP、SSE、预研 WebSocket，但还没有统一的 transport 抽象。
+  - UI store 同时承载渲染态、会话态、系统态，后续复杂度继续上升时会增加无关重渲染和状态耦合。
+  - 视觉、语音、3D 渲染都偏浏览器能力驱动，缺少统一的健康状态和性能观测面板。
+
+## 6. 后续技术路线图
+
+### Phase 1: 稳定交互主链路
+
+- 收敛消息生命周期：用户消息、助手占位、流式 token、结束态、错误态由同一条消息状态流管理。
+- 补齐流式聊天测试：重点覆盖并发请求、占位消息清理、fallback、TTS 失败。
+- 清理高频路径上的无效订阅，优先优化聊天区、HUD、控制面板的 store 订阅方式。
+
+### Phase 2: 统一实时传输层
+
+- 抽象 `chat transport` 接口，屏蔽 `POST /v1/chat`、`SSE /v1/chat/stream`、`WebSocket /ws` 的差异。
+- 默认保留 SSE，WebSocket 作为增强模式接入，不把页面逻辑和具体传输协议绑定。
+- 给 transport 增加连接态、重连策略、超时和 server capability 探测。
+- 支持通过 `VITE_CHAT_TRANSPORT=http|sse|websocket` 切换策略，便于灰度验证。
+
+### Phase 3: 拆分状态域
+
+- 将当前 store 按 `session/chat`、`avatar/runtime`、`system/connection` 三个域拆分。
+- 减少 3D 渲染状态和聊天 UI 状态的相互影响，降低页面级组件重渲染。
+- 将可序列化状态和不可序列化运行时对象彻底分开。
+
+### Phase 4: 体验与性能优化
+
+- Viewer 根据设备能力动态调节粒子数、阴影、DPR 和后处理开关。
+- 为聊天区、设置面板、模型加载过程补充 skeleton/placeholder，减少跳变感。
+- 增加前端性能埋点：首屏加载、模型加载耗时、首 token 时间、完整回复时间。
+
+## 7. 本轮已落地优化
+
+- 修复流式聊天占位消息 `id` 不一致导致的消息不更新问题。
+- 修复流式结束回调重复触发问题，避免 UI 状态重复收尾。
+- 聊天气泡在流式开始但尚未收到 token 时，展示明确的生成态文案。
+- 聊天 hook 改为 selector 订阅，减少因 store 全量订阅带来的额外重渲染。
+- 新增统一 `chat transport` 抽象，并让 orchestrator 改为依赖 transport 而不是直接依赖具体协议实现。
+- 修复流式降级到 fallback 时丢失 `connectionStatus/error` 的问题。

docs/development.md

@@ -40,6 +40,9 @@ npm run preview
   - 说明：后端地址
   - 本地开发：`http://localhost:8000`
   - GitHub Pages 生产环境：`https://<your-render-service>.onrender.com`
+- `VITE_CHAT_TRANSPORT`
+  - 可选；`http`、`sse`、`websocket`
+  - 默认：`auto`（当前优先走 SSE）
 
 ## 3. 后端（FastAPI）
 

index.html

@@ -1,5 +1,5 @@
 <!doctype html>
-<html lang="en">
+<html lang="en" class="dark">
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />

server/.env.example

@@ -26,3 +26,7 @@ CORS_ALLOW_ORIGINS=https://lessup.github.io
 
 # Logging
 LOG_LEVEL=INFO
+
+# Auth (disabled by default)
+AUTH_ENABLED=false
+API_KEYS=