康和證券 AI 語音客服系統開發日誌

第一階段：專案初始化

2025-06-12

完成項目

1. 專案架構建立

建立三個獨立的專案資料夾：
- backend/ - API 伺服器
- admin-dashboard/ - 管理介面
- chat-widget/ - 聊天小工具

2. 後端設定 (backend/)

技術選擇：Node.js + Express + TypeScript

安裝的套件：

基礎：express, cors, dotenv
認證：jsonwebtoken, bcrypt
資料庫：pg (PostgreSQL)
檔案處理：multer, pdf-parse, mammoth
AI：@anthropic-ai/sdk

專案結構：

src/
├── routes/      # API 路由
├── services/    # 業務邏輯
├── models/      # 資料模型
├── middleware/  # 中介軟體
└── utils/       # 工具函數

資料庫設計：

建立完整的 PostgreSQL schema
包含 users、documents、conversations 等表格
支援全文搜尋功能
提供測試用種子資料

3. 管理介面設定 (admin-dashboard/)

技術選擇：Vue 3 + TypeScript + Vite
UI 框架：Element Plus
狀態管理：Pinia
路由：Vue Router 4
開發 Port：8080

4. 聊天小工具設定 (chat-widget/)

技術選擇：Vue 3 + TypeScript + Vite
建構方式：配置為 library 模式，產出單一 JS 檔案
開發 Port：8081

技術決策記錄

為什麼選擇 TypeScript

提供類型安全，減少執行時錯誤
更好的 IDE 支援和程式碼提示
適合團隊協作

為什麼選擇 PostgreSQL

支援 JSON 資料類型（適合儲存對話記錄）
內建全文搜尋功能
成熟穩定，效能優異

為什麼選擇 Element Plus

完整的企業級 UI 元件
良好的 Vue 3 支援
中文文檔友善

遇到的問題與解決方案

路徑問題

問題：使用相對路徑導致 cd 命令失敗

解決：改用絕對路徑，並正確處理空格

Git 配置

問題：CLAUDE.md 檔案衝突

解決：移除了 CLAUDE.md 檔案，配置了適當的 .gitignore

Git Commit

Commit ID: b5ce227
Message: feat: 初始化 AI 客服系統專案架構
變更： 46 個檔案變更，7431 行新增

測試檢查清單

後端伺服器可以啟動 (npm run dev)
管理介面可以啟動 (npm run dev)
聊天小工具可以啟動 (npm run dev)
資料庫 schema 可以執行
環境變數配置正確

第二階段：基本聊天功能原型

2025-06-12

開發策略調整

原計劃：先完成認證系統和文檔管理
調整後：優先實作聊天功能，讓使用者能快速測試
原因：提供立即可見的成果，提升開發體驗

完成項目

1. 後端聊天 API (`backend/src/routes/chat.ts`)

聊天訊息端點：`POST /api/chat/message`

接收訊息並返回模擬回應
使用暫時的 API key 驗證
預留 Anthropic API 整合位置（TODO 註解）

對話歷史端點：`GET /api/chat/conversations/:id`

目前返回空陣列
為未來功能預留介面

2. 聊天小工具 UI (`chat-widget/src/components/ChatWidget.vue`)

介面設計

浮動聊天按鈕（右下角）
可展開/收合的聊天視窗
iOS 風格的簡潔設計

功能實作

即時訊息發送和顯示
訪客/助理訊息區分
打字動畫效果
本地儲存對話資訊

響應式設計

桌面版：固定寬度 350px
手機版：全螢幕顯示

技術問題與解決

TypeScript 類型錯誤

問題：Express 中介軟體類型不匹配

解決：調整函數返回類型，使用 Promise<any>

缺少類型定義

問題：pg 模組缺少 TypeScript 類型

解決：安裝 @types/pg

測試結果

API 測試

# 健康檢查
curl http://localhost:3000/health
# 結果：{"status":"ok","timestamp":"2025-06-12T12:01:49.161Z","environment":"development"}

# 聊天 API
curl -X POST http://localhost:3000/api/chat/message \
  -H "Content-Type: application/json" \
  -H "x-api-key: test_api_key_development" \
  -d '{"message": "你好，這是測試"}'
# 結果：成功返回模擬回應

服務狀態

後端：Port 3000 ✅
聊天小工具：Port 8081 ✅
資料庫：連接失敗（預期行為）⚠️

Git Commit

Commit ID: 59bde57
Message: feat: 實作基本聊天功能原型 - 快速開發路徑

第三階段：Anthropic API 整合

2025-06-12

完成項目

1. AI 服務模組（`backend/src/services/ai.ts`）

建立完整的 AI 服務類別

封裝 Anthropic SDK 操作
支援普通聊天和串流聊天
實作 prompt 工程
完整的錯誤處理機制

主要功能

sendMessage(): 一次性完整回應
sendMessageStream(): 即時串流回應
estimateTokens(): Token 數量估算
自動重試和超時處理

2. 更新聊天路由

普通聊天端點：`POST /api/chat/message`

整合 AI 服務
返回完整回應和 token 使用資訊
支援對話 ID 和訪客 ID

串流聊天端點：`POST /api/chat/message/stream`

使用 Server-Sent Events (SSE)
即時傳送文字片段
適合長回應和更好的用戶體驗

技術細節

使用的技術

Anthropic TypeScript SDK (@anthropic-ai/sdk)
Claude 3.5 Sonnet 模型（最新版）
Server-Sent Events 用於串流

錯誤處理

API key 驗證
速率限制處理（429 錯誤）
網路錯誤自動重試
友善的錯誤訊息

成本控制措施

Max tokens 限制為 1024
Token 使用追蹤
建議實作快取機制

使用方式

1. 設定 API Key：

# 在 backend/.env 檔案中
ANTHROPIC_API_KEY=your-api-key-here

2. 測試 API：

cd backend
node test-api.js

3. 在聊天小工具中測試：

訪問 http://localhost:8081
輸入問題測試 AI 回應

已知限制

尚未實作對話歷史

每次對話都是獨立的
需要資料庫支援

沒有文檔搜尋

AI 只能根據 prompt 回答
無法參考上傳的文檔

基本的 prompt

可以根據業務需求優化
加入更多公司特定資訊

第四階段：修復關鍵問題

2025-06-12

修復的問題

1. ConversationId 格式不匹配

問題：前端生成 conv-timestamp 格式，後端驗證要求 UUID
症狀：第二則訊息會失敗（400 Bad Request）
解決：將驗證從 .isUUID() 改為 .isString()
影響檔案：backend/src/routes/chat.ts

2. 對話無記憶

問題：每則訊息都是獨立的，AI 無法記住之前的對話
原因：conversationHistory 永遠是空的
解決：實作 in-memory 對話儲存

const conversationStore = new Map<string, Array<{ role, content }>>();

限制：

重啟後端會遺失所有對話
最多保留 20 則訊息（10 輪對話）
不同視窗間無法共享

3. CORS 動態埠號問題

問題：Widget 可能在 8081 或 8082，但 CORS 只允許固定埠號
解決：開發環境允許所有 http://localhost:*
影響檔案：backend/src/index.ts

技術決策

為什麼用 Map 而非資料庫？

快速開發，立即見效
避免 PostgreSQL 設定複雜度
適合開發測試階段

為什麼限制 20 則訊息？

防止記憶體無限增長
Claude API token 限制
保持對話相關性

測試確認

✅ 多則訊息連續發送正常
✅ AI 能記住之前的對話內容
✅ 不同埠號的 Widget 都能連接
✅ 錯誤訊息更詳細易懂

下一步優化建議

持久化對話

整合 PostgreSQL
實作對話 CRUD API
支援對話歷史查詢

改善 ConversationId

使用真正的 UUID（安裝 uuid 套件）
統一前後端格式
支援對話恢復

優化記憶體管理

實作 LRU 快取
定期清理過期對話
監控記憶體使用

Git Commit

Commit ID: 379fbbc
Message: feat: 完成 Anthropic API 整合並修復關鍵問題

完成項目

1. 專案架構建立

2. 後端設定 (backend/)

3. 管理介面設定 (admin-dashboard/)

4. 聊天小工具設定 (chat-widget/)

技術決策記錄

為什麼選擇 TypeScript

為什麼選擇 PostgreSQL

為什麼選擇 Element Plus

遇到的問題與解決方案

路徑問題

Git 配置

Git Commit

測試檢查清單

開發策略調整

完成項目

1. 後端聊天 API (backend/src/routes/chat.ts)

聊天訊息端點：POST /api/chat/message

對話歷史端點：GET /api/chat/conversations/:id

2. 聊天小工具 UI (chat-widget/src/components/ChatWidget.vue)

介面設計

功能實作

響應式設計

技術問題與解決

TypeScript 類型錯誤

缺少類型定義

測試結果

API 測試

服務狀態

Git Commit

完成項目

1. AI 服務模組（backend/src/services/ai.ts）

建立完整的 AI 服務類別

主要功能

2. 更新聊天路由

普通聊天端點：POST /api/chat/message

串流聊天端點：POST /api/chat/message/stream

技術細節

使用的技術

錯誤處理

成本控制措施

使用方式

1. 設定 API Key：

2. 測試 API：

3. 在聊天小工具中測試：

已知限制

尚未實作對話歷史

沒有文檔搜尋

基本的 prompt

修復的問題

1. ConversationId 格式不匹配

2. 對話無記憶

3. CORS 動態埠號問題

技術決策

為什麼用 Map 而非資料庫？

為什麼限制 20 則訊息？

測試確認

下一步優化建議

持久化對話

改善 ConversationId

優化記憶體管理

Git Commit

開發環境資訊

1. 後端聊天 API (`backend/src/routes/chat.ts`)

聊天訊息端點：`POST /api/chat/message`

對話歷史端點：`GET /api/chat/conversations/:id`

2. 聊天小工具 UI (`chat-widget/src/components/ChatWidget.vue`)

1. AI 服務模組（`backend/src/services/ai.ts`）

普通聊天端點：`POST /api/chat/message`

串流聊天端點：`POST /api/chat/message/stream`