feat: 实现聊天取消功能，提升用户交互体验

- 在教练页面中添加用户取消发送或终止回复的能力 - 更新发送按钮状态，支持发送和取消状态切换 - 在流式回复中显示取消按钮，允许用户中断助手的生成 - 增强请求管理，添加请求序列号和有效性验证，防止延迟响应影响用户体验 - 优化错误处理，区分用户主动取消和网络错误，提升系统稳定性 - 更新相关文档，详细描述取消功能的实现和用户体验设计
2025-08-18 18:59:23 +08:00
parent 05a00236bc
commit d52981ab29
6 changed files with 1097 additions and 78 deletions
--- a/docs/cancel-chat-implementation.md
+++ b/docs/cancel-chat-implementation.md
@@ -0,0 +1,137 @@
+# 取消聊天功能实现文档
+
+## 功能概述
+
+为 AI 教练聊天界面添加了用户可以取消发送或终止回复的能力，参照业内最佳实践（如 ChatGPT、Claude 等）实现。
+
+## 主要功能
+
+### 1. 发送按钮状态切换
+- **发送状态**: 绿色背景，显示上箭头图标
+- **取消状态**: 红色背景 (#FF4444)，显示停止图标
+- 根据 `isSending` 或 `isStreaming` 状态自动切换
+
+### 2. 流式回复中的取消按钮
+- 在助手正在思考时显示"正在思考…"和取消按钮
+- 在助手正在输出文本时显示"停止生成"按钮
+- 取消按钮采用红色主题，与停止操作语义一致
+
+### 3. 取消逻辑处理
+- 调用 `streamAbortRef.current.abort()` 中断 XMLHttpRequest
+- 清理状态：`isSending`、`isStreaming`、`pendingAssistantIdRef`
+- 移除正在生成中的助手消息
+- 提供触觉反馈（Warning 类型）
+
+### 4. 错误处理优化
+- 区分用户主动取消和网络错误
+- 对于 AbortError 不进行错误提示和降级处理
+- 避免在取消操作后显示"请求失败"等错误信息
+
+## 技术实现
+
+### 关键函数
+
+```typescript
+function cancelCurrentRequest() {
+  // 中断流式请求
+  if (streamAbortRef.current) {
+    streamAbortRef.current.abort();
+    streamAbortRef.current = null;
+  }
+  
+  // 清理状态
+  setIsSending(false);
+  setIsStreaming(false);
+  
+  // 移除正在生成的消息
+  if (pendingAssistantIdRef.current) {
+    setMessages(prev => prev.filter(msg => msg.id !== pendingAssistantIdRef.current));
+    pendingAssistantIdRef.current = null;
+  }
+  
+  // 用户反馈
+  Haptics.notificationAsync(Haptics.NotificationFeedbackType.Warning);
+}
+```
+
+### UI 状态管理
+
+1. **发送按钮**:
+   - 背景色：发送时为主题色，取消时为红色
+   - 图标：发送时为上箭头，取消时为停止图标
+   - 禁用状态：只在无内容且非发送状态时禁用
+
+2. **流式消息气泡**:
+   - 思考阶段：显示"正在思考…"和取消按钮
+   - 输出阶段：在消息下方显示"停止生成"按钮
+
+### 边界情况处理
+
+1. **组件卸载**: 自动清理未完成的请求
+2. **新建会话**: 如果有进行中的请求，先取消再创建
+3. **切换历史会话**: 取消当前请求后再加载历史会话
+4. **多次点击**: 防止重复发送，支持随时取消
+
+## 用户体验设计
+
+### 视觉反馈
+- 按钮颜色变化（绿色→红色）
+- 图标变化（发送→停止）
+- 取消按钮采用一致的红色主题
+
+### 交互反馈
+- 触觉反馈：取消时提供 Warning 类型震动
+- 即时响应：点击取消后立即停止生成
+- 状态清理：取消后界面回到可输入状态
+
+### 语义化设计
+- "正在思考…" + "取消"：在等待响应阶段
+- "停止生成"：在文本输出阶段
+- 红色主题：与停止操作的通用语义保持一致
+
+## 业内最佳实践对比
+
+### ChatGPT
+- ✅ 发送按钮变为停止按钮
+- ✅ 红色停止图标
+- ✅ 即时响应
+
+### Claude
+- ✅ 流式输出过程中显示停止按钮
+- ✅ 取消后清理当前消息
+- ✅ 明确的视觉区分
+
+### 我们的实现
+- ✅ 发送/取消按钮一体化设计
+- ✅ 双重取消入口（发送按钮 + 消息内按钮）
+- ✅ 完整的状态管理和错误处理
+- ✅ 触觉反馈增强用户体验
+
+## 测试建议
+
+1. **基本功能测试**:
+   - 发送消息后立即点击取消
+   - 在流式输出过程中点击停止
+   - 连续发送多条消息并取消
+
+2. **边界情况测试**:
+   - 网络异常时的取消行为
+   - 快速切换会话时的状态清理
+   - 组件卸载时的资源清理
+
+3. **用户体验测试**:
+   - 按钮状态变化的流畅性
+   - 触觉反馈的适当性
+   - 界面响应的即时性
+
+## 总结
+
+本实现参照业内主流 AI 聊天应用的最佳实践，提供了完整的取消/终止功能，包括：
+
+- 直观的 UI 状态切换
+- 完善的取消逻辑处理
+- 良好的用户反馈机制
+- 健壮的错误处理
+- 一致的设计语言
+
+功能实现既保证了技术的正确性，也注重了用户体验的完整性。
--- a/docs/complete-cancel-solution.md
+++ b/docs/complete-cancel-solution.md
@@ -0,0 +1,234 @@
+# 完整取消功能解决方案
+
+## 问题诊断
+
+您遇到的问题确实需要前后端协作解决：
+
+1. **客户端问题**: XMLHttpRequest.abort() 只能终止网络传输，无法停止服务端处理
+2. **会话持久化问题**: 服务端可能已经开始处理并保存会话记录
+3. **延迟响应问题**: 服务端处理完成后，响应仍会到达客户端
+
+## 已实现的客户端增强方案
+
+### 1. 请求序列号机制
+```typescript
+// 防止延迟响应影响当前状态
+const requestSequenceRef = useRef<number>(0);
+const activeRequestIdRef = useRef<string | null>(null);
+
+function cancelCurrentRequest() {
+  // 增加序列号，使后续响应失效
+  requestSequenceRef.current += 1;
+  activeRequestIdRef.current = null;
+  
+  // 中断网络请求
+  streamAbortRef.current?.abort();
+  
+  // 清理状态和UI
+  setIsSending(false);
+  setIsStreaming(false);
+  // ...
+}
+```
+
+### 2. 请求有效性验证
+```typescript
+const isRequestValid = () => {
+  return activeRequestIdRef.current === requestId && 
+         requestSequenceRef.current === currentSequence;
+};
+
+// 在所有回调中验证
+const onChunk = (chunk: string) => {
+  if (!isRequestValid()) {
+    console.log('Ignoring chunk from invalidated request');
+    return;
+  }
+  // 处理chunk...
+};
+```
+
+### 3. 延迟会话ID生成
+```typescript
+// 修改前：立即生成会话ID
+function ensureConversationId(): string {
+  const cid = `mobile-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  setConversationId(cid); // 立即设置
+  return cid;
+}
+
+// 修改后：延迟生成，只在请求成功时设置
+function ensureConversationId(): string {
+  if (conversationId && conversationId.trim()) return conversationId;
+  return ''; // 返回空，让服务端生成
+}
+```
+
+### 4. 请求追踪机制
+```typescript
+// 在 api.ts 中添加请求ID
+const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+const requestHeaders = {
+  'Content-Type': 'application/json',
+  'X-Request-Id': requestId, // 用于服务端追踪
+  // ...
+};
+```
+
+## 需要服务端配合的方案
+
+### 方案1: 连接断开检测（推荐）
+
+**原理**: 服务端检测客户端连接状态，断开时停止处理
+
+```python
+# 服务端伪代码
+async def ai_chat_stream(request):
+    conversation_id = request.json.get('conversationId')
+    is_new_conversation = not conversation_id
+    
+    try:
+        # 检查客户端连接
+        if await request.is_disconnected():
+            return
+            
+        # 延迟创建会话记录
+        temp_conv_id = None
+        if is_new_conversation:
+            temp_conv_id = create_temp_conversation()
+            
+        async for chunk in ai_generate_stream():
+            # 每次生成前检查连接
+            if await request.is_disconnected():
+                if temp_conv_id:
+                    delete_temp_conversation(temp_conv_id)
+                return
+                
+            yield chunk
+            
+        # 只有成功完成才保存会话
+        if temp_conv_id:
+            save_permanent_conversation(temp_conv_id)
+            
+    except ClientDisconnectedError:
+        if temp_conv_id:
+            delete_temp_conversation(temp_conv_id)
+```
+
+**优点**: 
+- 自动检测，无需额外API
+- 资源清理及时
+- 实现相对简单
+
+### 方案2: 主动取消端点（备选）
+
+**原理**: 提供专门的取消API，客户端主动通知
+
+```python
+@app.post("/api/ai-coach/cancel")
+async def cancel_request(request):
+    request_id = request.json.get('requestId')
+    conversation_id = request.json.get('conversationId')
+    
+    # 标记请求取消
+    cancel_request_processing(request_id)
+    
+    # 清理临时会话
+    if is_temp_conversation(conversation_id):
+        delete_conversation(conversation_id)
+        
+    return {"status": "cancelled"}
+```
+
+**客户端调用**:
+```typescript
+function cancelCurrentRequest() {
+  // 现有逻辑...
+  
+  // 主动通知服务端
+  if (activeRequestIdRef.current) {
+    notifyServerCancel(conversationId, activeRequestIdRef.current);
+  }
+}
+
+async function notifyServerCancel(conversationId?: string, requestId?: string) {
+  try {
+    await api.post('/api/ai-coach/cancel', {
+      requestId,
+      conversationId
+    });
+  } catch (error) {
+    console.warn('Failed to notify server:', error);
+  }
+}
+```
+
+## 数据库设计建议
+
+```sql
+-- 会话状态管理
+CREATE TABLE conversations (
+    id VARCHAR(50) PRIMARY KEY,
+    user_id INT,
+    status ENUM('temp', 'active', 'cancelled') DEFAULT 'temp',
+    created_at TIMESTAMP,
+    confirmed_at TIMESTAMP NULL,
+    messages JSON,
+    INDEX idx_status_created (status, created_at)
+);
+
+-- 定期清理临时会话（防止内存泄漏）
+-- 可以用定时任务或在新请求时清理
+DELETE FROM conversations 
+WHERE status = 'temp' 
+AND created_at < NOW() - INTERVAL 10 MINUTE;
+```
+
+## 立即可用的解决方案
+
+### 当前已实现（无需服务端修改）
+
+客户端增强已经可以解决大部分问题：
+
+1. ✅ **防止延迟响应**: 请求序列号机制
+2. ✅ **严格状态管理**: 请求有效性验证  
+3. ✅ **延迟会话创建**: 避免空会话记录
+4. ✅ **即时UI反馈**: 取消后立即清理界面
+
+### 效果评估
+
+**改进前**:
+- 点击取消 → 网络中断 → 但服务端继续处理 → 稍后响应仍然到达
+- 会话记录已创建且保留
+
+**改进后**:
+- 点击取消 → 序列号增加 → 界面立即清理 → 延迟响应被忽略
+- 会话ID延迟生成，减少空记录
+
+### 推荐实施步骤
+
+**第一阶段（立即可用）**:
+1. ✅ 使用当前客户端增强方案
+2. 测试取消功能的改善效果
+
+**第二阶段（服务端配合）**:
+1. 实现连接断开检测
+2. 临时会话管理机制
+3. 完善资源清理
+
+**第三阶段（可选优化）**:
+1. 主动取消通知端点
+2. 数据库优化和定期清理
+3. 监控和日志完善
+
+## 测试验证
+
+建议测试以下场景：
+
+1. **快速取消**: 发送后立即点击取消
+2. **生成中取消**: 在AI回复过程中取消
+3. **网络异常**: 弱网环境下的取消行为
+4. **连续操作**: 快速发送多条消息并取消
+5. **状态恢复**: 取消后是否能正常发送新消息
+
+通过这个完整方案，可以显著改善取消功能的用户体验，即使在服务端暂未配合的情况下，客户端增强也能解决大部分问题。
--- a/docs/food-confirmation-implementation.md
+++ b/docs/food-confirmation-implementation.md
@@ -247,4 +247,90 @@ choiceButtonRecommended: {
 4. **错误处理**：完整的错误处理机制，确保用户体验流畅
 5. **性能优化**：避免不必要的重渲染，保持界面响应性

-这个实现完全符合API文档的要求，支持饮食记录的两阶段确认流程，并保持了与现有功能的兼容性。
+## 选择状态管理与用户体验优化
+
+### 防重复点击机制
+
+为了防止用户重复发送消息，实现了完善的状态管理：
+
+```typescript
+const [selectedChoices, setSelectedChoices] = useState<Record<string, string>>({});  // messageId -> choiceId
+const [pendingChoiceConfirmation, setPendingChoiceConfirmation] = useState<Record<string, boolean>>({});  // messageId -> loading
+```
+
+### 选择状态逻辑
+
+1. **状态检查**：点击前检查是否已选择
+2. **立即锁定**：点击后立即设置选中状态，防止重复点击
+3. **视觉反馈**：选中项显示特殊样式，其他选项变为禁用状态
+4. **加载指示**：发送过程中显示loading动画
+5. **错误恢复**：发送失败时重置状态，允许重新选择
+
+### UI状态展示
+
+- **正常状态**：常规样式，可点击
+- **推荐状态**：特殊边框和背景色，显示"推荐"标签
+- **选中状态**：深色边框，绿色背景，显示"已选择"标签
+- **禁用状态**：灰色透明，不可点击
+- **加载状态**：显示旋转加载动画
+
+### 触觉反馈
+
+- **选择时**：`Haptics.selectionAsync()` - 轻微选择反馈
+- **成功时**：`Haptics.NotificationFeedbackType.Success` - 成功通知
+- **失败时**：`Haptics.NotificationFeedbackType.Error` - 错误通知
+
+### 代码示例
+
+```typescript
+// 状态管理
+const isSelected = selectedChoices[item.id] === choice.id;
+const isAnySelected = selectedChoices[item.id] != null;
+const isPending = pendingChoiceConfirmation[item.id];
+const isDisabled = isAnySelected && !isSelected;
+
+// 点击处理
+onPress={() => {
+  if (!isDisabled && !isPending) {
+    Haptics.selectionAsync();
+    handleChoiceSelection(choice, item);
+  }
+}}
+
+// 选择处理逻辑
+async function handleChoiceSelection(choice: AiChoiceOption, message: ChatMessage) {
+  // 防重复检查
+  if (selectedChoices[message.id] != null) {
+    return;
+  }
+  
+  // 立即设置状态
+  setSelectedChoices(prev => ({ ...prev, [message.id]: choice.id }));
+  setPendingChoiceConfirmation(prev => ({ ...prev, [message.id]: true }));
+  
+  try {
+    // 发送确认
+    await sendStreamWithConfirmation(confirmationText, choice.id, confirmationData);
+    
+    // 成功反馈
+    setPendingChoiceConfirmation(prev => ({ ...prev, [message.id]: false }));
+    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+  } catch (e) {
+    // 失败时重置状态
+    setSelectedChoices(prev => {
+      const { [message.id]: _, ...rest } = prev;
+      return rest;
+    });
+    setPendingChoiceConfirmation(prev => {
+      const { [message.id]: _, ...rest } = prev;
+      return rest;
+    });
+    
+    // 错误反馈
+    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error);
+    Alert.alert('选择失败', e?.message || '选择失败，请重试');
+  }
+}
+```
+
+这个实现完全符合API文档的要求，支持饮食记录的两阶段确认流程，并保持了与现有功能的兼容性。同时提供了优秀的用户体验，包括防重复点击、状态反馈、触觉反馈等功能。
--- a/docs/server-side-cancel-support.md
+++ b/docs/server-side-cancel-support.md
@@ -0,0 +1,266 @@
+# 服务端取消支持方案
+
+## 问题分析
+
+当前取消功能的问题：
+1. 客户端 `XMLHttpRequest.abort()` 只能终止网络传输，无法停止服务端处理
+2. 服务端可能已经生成并保存了会话记录
+3. 延迟响应导致"取消"的内容稍后出现
+
+## 服务端需要支持的功能
+
+### 1. 请求中断检测
+
+**方案A：连接断开检测（推荐）**
+```python
+# 伪代码示例
+async def ai_chat_stream(request):
+    conversation_id = request.json.get('conversationId')
+    messages = request.json.get('messages', [])
+    
+    # 如果是新会话且客户端断开，不创建会话记录
+    is_new_conversation = not conversation_id
+    temp_conversation_id = None
+    
+    try:
+        # 检查客户端连接状态
+        if await request.is_disconnected():
+            print("Client disconnected before processing")
+            return
+            
+        # 只有在开始生成内容时才创建会话
+        if is_new_conversation:
+            temp_conversation_id = create_conversation()
+            
+        async for chunk in ai_generate_stream(messages):
+            # 每次生成前检查连接状态
+            if await request.is_disconnected():
+                print("Client disconnected during generation")
+                # 如果是新会话，删除临时创建的会话
+                if temp_conversation_id:
+                    delete_conversation(temp_conversation_id)
+                return
+                
+            yield chunk
+            
+        # 成功完成，保存会话
+        if temp_conversation_id:
+            save_conversation(temp_conversation_id, messages + [ai_response])
+            
+    except ClientDisconnectedError:
+        # 清理未完成的会话
+        if temp_conversation_id:
+            delete_conversation(temp_conversation_id)
+```
+
+**方案B：取消端点（备选）**
+```python
+# 添加专门的取消端点
+@app.post("/api/ai-coach/cancel")
+async def cancel_request(request):
+    request_id = request.json.get('requestId')
+    conversation_id = request.json.get('conversationId')
+    
+    # 标记请求为已取消
+    cancel_request_processing(request_id)
+    
+    # 如果会话是新创建的，删除它
+    if is_new_conversation(conversation_id):
+        delete_conversation(conversation_id)
+        
+    return {"status": "cancelled"}
+
+# 在主处理函数中检查取消状态
+async def ai_chat_stream(request):
+    request_id = request.headers.get('X-Request-Id')
+    
+    while generating:
+        if is_request_cancelled(request_id):
+            cleanup_and_exit()
+            return
+        # 继续处理...
+```
+
+### 2. 会话管理优化
+
+**延迟会话创建：**
+```python
+class ConversationManager:
+    def __init__(self):
+        self.temp_conversations = {}
+        
+    async def start_conversation(self, client_id):
+        """开始新会话，但不立即持久化"""
+        temp_id = f"temp_{uuid4()}"
+        self.temp_conversations[temp_id] = {
+            'client_id': client_id,
+            'messages': [],
+            'created_at': datetime.now(),
+            'confirmed': False
+        }
+        return temp_id
+        
+    async def confirm_conversation(self, temp_id, final_messages):
+        """确认会话并持久化"""
+        if temp_id in self.temp_conversations:
+            # 保存到数据库
+            real_id = self.save_to_database(final_messages)
+            del self.temp_conversations[temp_id]
+            return real_id
+            
+    async def cancel_conversation(self, temp_id):
+        """取消临时会话"""
+        if temp_id in self.temp_conversations:
+            del self.temp_conversations[temp_id]
+            return True
+        return False
+```
+
+### 3. 流式响应优化
+
+**分段提交策略：**
+```python
+async def ai_chat_stream(request):
+    try:
+        # 第一阶段：验证请求
+        if await request.is_disconnected():
+            return
+            
+        # 第二阶段：开始生成（创建临时会话）
+        temp_conv_id = await start_temp_conversation()
+        yield json.dumps({"temp_conversation_id": temp_conv_id})
+        
+        # 第三阶段：流式生成内容
+        full_response = ""
+        for chunk in ai_generate():
+            if await request.is_disconnected():
+                await cancel_temp_conversation(temp_conv_id)
+                return
+                
+            full_response += chunk
+            yield chunk
+            
+        # 第四阶段：确认并保存会话
+        final_conv_id = await confirm_conversation(temp_conv_id, full_response)
+        yield json.dumps({"final_conversation_id": final_conv_id})
+        
+    except ClientDisconnectedError:
+        await cancel_temp_conversation(temp_conv_id)
+```
+
+## 具体实现建议
+
+### 1. 服务端 API 修改
+
+**请求头支持：**
+```http
+POST /api/ai-coach/chat
+X-Request-Id: req_1234567890_abcdef
+Content-Type: application/json
+
+{
+  "conversationId": "existing_conv_id", // 可选，新会话时为空
+  "messages": [...],
+  "stream": true
+}
+```
+
+**响应头：**
+```http
+HTTP/1.1 200 OK
+X-Conversation-Id: mobile-1701234567-abcdef123
+X-Request-Id: req_1234567890_abcdef
+Content-Type: text/plain; charset=utf-8
+```
+
+### 2. 数据库设计优化
+
+**会话状态管理：**
+```sql
+CREATE TABLE conversations (
+    id VARCHAR(50) PRIMARY KEY,
+    user_id INT,
+    status ENUM('temp', 'active', 'cancelled') DEFAULT 'temp',
+    created_at TIMESTAMP,
+    confirmed_at TIMESTAMP NULL,
+    messages JSON,
+    INDEX idx_status_created (status, created_at)
+);
+
+-- 定期清理临时会话
+DELETE FROM conversations 
+WHERE status = 'temp' 
+AND created_at < NOW() - INTERVAL 10 MINUTE;
+```
+
+### 3. 客户端配合改进
+
+**添加请求ID头：**
+```typescript
+// 在 api.ts 中添加
+export function postTextStream(path: string, body: any, callbacks: TextStreamCallbacks, options: TextStreamOptions = {}) {
+  const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  
+  const requestHeaders: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'X-Request-Id': requestId,
+    ...(options.headers || {}),
+  };
+  
+  // ... 其余代码
+}
+```
+
+**主动取消通知（可选）：**
+```typescript
+async function notifyServerCancel(conversationId?: string, requestId?: string) {
+  try {
+    if (requestId) {
+      await api.post('/api/ai-coach/cancel', {
+        requestId,
+        conversationId
+      });
+    }
+  } catch (error) {
+    console.warn('Failed to notify server of cancellation:', error);
+  }
+}
+```
+
+## 完整取消流程
+
+### 客户端取消时：
+1. 增加请求序列号（防止延迟响应）
+2. 调用 `XMLHttpRequest.abort()`
+3. 清理本地状态
+4. （可选）通知服务端取消
+
+### 服务端检测到断开：
+1. 立即停止 AI 内容生成
+2. 检查会话状态（临时/已确认）
+3. 如果是临时会话，删除记录
+4. 清理相关资源
+
+### 防止延迟响应：
+1. 客户端使用请求序列号验证
+2. 服务端检查连接状态
+3. 分段式会话确认机制
+
+## 优先级建议
+
+**立即实现（高优先级）：**
+1. 客户端请求序列号验证 ✅ 已实现
+2. 延迟会话ID生成 ✅ 已实现  
+3. 客户端状态严格管理 ✅ 已实现
+
+**服务端配合（中优先级）：**
+1. 连接断开检测
+2. 临时会话管理
+3. 请求ID追踪
+
+**可选优化（低优先级）：**
+1. 主动取消通知端点
+2. 会话状态数据库优化
+3. 定期清理机制
+
+通过以上客户端和服务端的协作改进，可以彻底解决取消功能的问题，确保用户取消操作的即时性和有效性。