Task_Reporter/openspec/changes/archive/2025-12-08-fix-chat-ux-issues/tasks.md

Tasks: Fix Chat UX Issues

Phase 1: 發文者顯示名稱

T-1.1: 後端 Schema 新增 sender_display_name

• 在 MessageResponse schema 新增 sender_display_name: Optional[str] 欄位
• 在 MessageBroadcast schema 新增 sender_display_name: Optional[str] 欄位

T-1.2: 後端 Service 查詢加入 User JOIN

• 修改 MessageService.get_messages() 使用 LEFT JOIN 取得 display_name
• 新增 MessageService.get_display_name() helper 方法
• 修改 MessageService.search_messages() 使用 LEFT JOIN 取得 display_name

T-1.3: WebSocket 廣播包含 display_name

• 修改 WebSocket MESSAGE handler 查詢並包含 sender_display_name
• 修改 WebSocket EDIT_MESSAGE handler 包含 sender_display_name
• 修改 REST API create_message 端點包含 sender_display_name

T-1.4: 前端顯示 display_name

• 更新 Message 型別定義包含 sender_display_name 欄位
• 更新 MessageBroadcast 型別定義包含 sender_display_name 欄位
• 修改 RoomDetail.tsx 顯示 sender_display_name || sender_id
• 修改 useWebSocket.ts 傳遞 sender_display_name

Phase 2: 統一時區為 GMT+8

T-2.1: 建立時間格式化工具

• 建立 frontend/src/utils/datetime.ts
• 實作 formatDateTimeGMT8(date) 函數
• 實作 formatTimeGMT8(date) 函數
• 實作 formatMessageTime(date) 函數 (智慧顯示)
• 實作 formatRelativeTimeGMT8(date) 函數 (相對時間)

T-2.2: 套用到所有時間顯示

• RoomDetail.tsx - 訊息時間改用 formatMessageTime
• RoomList.tsx - 最後活動時間改用 formatRelativeTimeGMT8

Phase 3: AI 報告生成問題修復

T-3.1: 後端 DIFY 健康檢查

• 在 dify_client.py 新增 test_connection() 方法
• 新增 HealthCheckResponse schema
• 新增 GET /api/reports/health 端點檢查 DIFY 狀態
• 啟動時檢查 DIFY_API_KEY 並記錄警告
• 在 main.py 註冊 health_router

T-3.2: 改善錯誤處理與顯示

• 確保 background task 錯誤正確寫入 report.error_message (已存在)
• WebSocket 廣播失敗狀態時包含具體錯誤 (已存在)

T-3.3: 前端輪詢機制

• 修改 useReports.ts 新增 useReportPolling() hook
• 新增 useGenerateReportWithPolling() hook
• 修改 RoomDetail.tsx 實作輪詢邏輯
• 顯示各階段進度訊息 (準備中 → 收集資料 → AI 生成 → 組裝文件)
• 失敗時顯示錯誤訊息給使用者

T-3.4: 報告下載中文檔名修復

• 修改 router.py download_report 使用 RFC 5987 編碼處理中文檔名
• 使用 urllib.parse.quote() 對檔名進行 URL 編碼
• 提供 ASCII fallback 檔名相容舊版客戶端

Phase 4: 測試與驗證

T-4.1: 測試發文者顯示

• 測試新訊息 WebSocket 廣播包含 display_name
• 測試歷史訊息 API 回傳包含 display_name
• 測試未知使用者 (不在 users 表) fallback 顯示 sender_id

T-4.2: 測試時區顯示

• 測試訊息時間顯示為台灣時間
• 測試跨日訊息時間正確

T-4.3: 測試 AI 報告

• 測試 DIFY_API_KEY 未設定時的錯誤訊息
• 測試報告生成完整流程
• 測試生成失敗時的錯誤顯示
• 測試報告下載中文檔名正確顯示