# 專案概覽與目標

* 要打造一個 AI 語音助理，可以用電話打進來，或直接在瀏覽器裡對話
* 先示範「完全不用寫程式」就從雲端介面建立助理並接到電話號碼
* 接著示範給開發者看，如何用 React／JavaScript 在前端按一個按鈕就連到語音助理
* 再來說明如何從後端伺服器發出請求、控制語音助理，做到更完整的生產級整合
* 使用的服務是 Vy（Voice API），透過邀請連結註冊可拿到約 10 美元免費額度，不需輸入信用卡

# 使用場景：導入到申請表流程

* 真實場景是導入到一個付費導師計畫（Dev Launch）的申請流程
* 原本流程是長表單，要填年齡、程度、收入、是否願意投資、是否能馬上開始等多個欄位
* 很多人不想打字填長表單，更希望直接講電話或用說的
* 透過語音助理，可以改成用講的方式回答同樣問題，甚至額外追問表單沒設計到的資訊
* 語音助理會蒐集資料、判斷是否「合格」，前端再根據結果決定要導向預約頁、降階產品等

# Demo 流程重點

* 使用者在簡單 Landing Page 填寫姓名、電話、Email，按「開始通話」
* 頁面會接上語音助理，直接在瀏覽器裡通話，不需真的拿手機
* 助理會依腳本問一串問題：年齡、居住國家、月收入、是否能投資某個金額、程式程度、是否能即刻開始等
* 使用者回答後，助理會根據條件判斷是否適合這個計畫
* 通話結束後，前端會顯示「通話報告」，包含摘要與是否合格等資訊
* 可利用這些輸出在前端自動做後續導流或流程分支

# Vy 平台與帳號設定

* 到 Vy 網站註冊帳號，透過連結可取得免費額度
* 登入後進入 Dashboard，可以看到延遲、成本、選用模型等資訊

* 在側邊選單中進入 Assistants，按「Create new assistant」建立新的語音助理
* 建立時給助理命名，可選用範本（客服、遊戲 NPC、Q&A 等）或空白範本，範例使用空白

# 建立 Voice Assistant 基本流程

* 建立完成後即可在網頁上用「Talk with assistant」直接測試對話
* 也可以將助理綁定到電話號碼，讓使用者「打電話」進來（之後再設定）
* 主要要設定的項目包括：模型提供者、模型版本、溫度、情緒偵測、Prompt 等
* 所有設定修改完成後，需要按 Publish 才會生效

# 模型與語音設定

* 模型提供者可選多家，如 OpenAI、DeepSeek 等，範例使用 OpenAI
* 模型例子：選用類似 GPT-4o / GPT-4 Turbo cluster，平衡成本與延遲
* 溫度調低到約 0.3，使回答更穩定、較少亂跑
* 可選擇啟用情緒辨識，使助理依情緒更自然反應
* 語音提供者有多家選擇，範例使用 ElevenLabs 的「Nigel」語音
* 也可以輸入自訂 Voice ID，或從清單中挑選其他預設聲音

# 語音轉文字與音訊處理

* Transcriber 區塊用來設定語音轉文字的細節，範例採用預設值
* 啟用「背景降噪」，減少通話環境雜音對辨識品質的影響
* 啟用降噪後，成本與延遲不會顯著增加

# 工具、函式與結束通話邏輯

* 平台支援自訂工具與函式，讓助理在對話中觸發外部系統
* 可以連接到像 GoHighLevel、Make.com，或是自寫的程式（如查資料庫、建立紀錄等）
* 可以啟用「讓助理自行結束通話」的功能，並在 Prompt 中描述何時應該掛斷，以控制成本
* 若不啟用由助理掛斷，則由使用者手動結束通話

# 進階設定與錄音

* 進階設定中可選擇是否保留通話錄音，方便之後回放
* 啟用 Smart Endpointing，讓系統自動判斷使用者何時講完，而不用微調各種細節參數
* 這些設定主要是為了提升體驗與穩定性

# 訊息與 Webhook 設定

* Messaging 區塊可以設定要把通話相關事件送到哪裡（後端／前端）
* 可設定後端 Webhook URL，接收通話開始、結束、分析結果、錯誤等事件
* 前端也能透過客戶端事件取得通話中的資訊，用來更新 UI
* 可以選擇要傳哪些類型資料，例如逐步轉寫、結束報告等

# 通話結束分析與結構化輸出

* Analysis 區塊負責「通話結束後要做的事」
* 可設定「摘要 Prompt」，要求模型生成通話摘要
* 可設定「成功與否判斷 Prompt」，讓模型依條件判斷這通電話是否達成目標
* 最重要的是可以定義「結構化資料 Schema」，例如 JSON 格式
* 助理會在通話結束時依 Schema 輸出：例如是否合格、年齡、國家、收入區間、是否可以投資、是否能立即開始等
* 這些結構化資料可送到後端或前端，作為下一步自動流程的依據

# Prompt 設計與對話腳本
![Uploading file..._77ilahzt0]()

* 有兩大部分：第一句開場白（first message）、主系統 Prompt（系統說明與流程腳本）
* 開場白範例：說明「從哪裡打來」、「你先前申請了什麼」、「現在要開始申請流程」並問是否準備好
* 主 Prompt 裡描述助理的角色、語氣（溫暖、專業、不要像強硬業務）、對話節奏等
* 逐條列出需要詢問的問題：年齡、居住國家、收入水準、是否願意投資多少金額、程式能力、是否能立刻開始等等
* 在 Prompt 中明確描述「什麼條件算合格」，例如限定國家、最低收入、基礎程式能力要求等
* 對合格者要說的話、不合格者要說的話都事先寫好，讓助理按分支回覆
* 最後指示助理在問完所有必要問題後，簡短確認是否有其他問題，然後讓使用者自行結束通話
* 可在 Prompt 中使用變數占位（例如使用者名稱等），稍後從自家程式碼注入實際值

# 當前階段成果

* 到這一步為止，已在 Vy 介面完成助理建立、模型與語音選好、Prompt 寫好、分析邏輯設好
* 已可直接在 Vy 後台用「Talk with assistant」測試整個問答流程
* 後續步驟才會進到「接到實際電話」以及「用自家前端、後端程式碼來串接」

---
# 分析區塊的核心目的

* 分析區塊用來從通話內容中萃取真正有用的資訊
* 範例情境是用電話確認潛在客戶是否符合高價導師計畫資格
* 若符合資格就導向預約通話，不符合則導向低價課程或免費資源
* 通話結束後會呼叫 LLM 進行分析，因此分析結果會在通話結束後數秒才產生

# 設定摘要與結構化資料 Schema

* 摘要部分可以給簡單指示，例如「寫一個簡短通話摘要」，也可以加入更具體需求
* 成功與否（Success evaluation）在此案例中不是重點，重點是結構化資料
* 透過提示詞說明：會給一段與潛在客戶的通話轉錄，目的是評估是否符合資格
* 在提示中要求模型依照指定 Schema 給出輸出，並保持摘要簡潔
* 在 Schema 中可以為每個欄位設定名稱、類型（例如 Boolean、字串、enum）、描述與是否必填

# 結構化輸出欄位設計示例

* 設定欄位如：是否有程式開發經驗（Boolean），並透過描述明確定義 true / false 判準
* 加入補充欄位如「coding_experience_extra_details」用於補充文字說明
* 月收入欄位設為 enum，列出收入區間選項，方便固定輸出值並利於後端使用
* 在 enum 中加入「not_provided」選項，以處理使用者拒絕提供收入的情況
* 其他欄位包括 country、age、is_qualified、ready_to_start 等評估相關資訊
* 由於單層最多只能有 10 個欄位，可建立 object 欄位來嵌套更多資料
* 以 contact_details 物件包住 first_name、last_name、phone_number、email 等聯絡資訊，節省欄位名額

# 實際測試一通資格審核電話

* 啟動助理後，助理自我介紹並說明是用來評估是否適合加入導師計畫
* 問使用者年齡與所在國家，例如：24 歲、住在澳洲
* 詢問月收入或收入區間，使用者可選擇不透露
* 說明導師計畫需要投入 2000–4000 美金，確認對方是否願意投資
* 使用者覺得金額過高，助理保持同理心，仍繼續了解狀況
* 詢問目前程式程度，使用者表示是完全新手
* 助理根據條件判斷該計畫只適合已有紮實基礎的人，告知目前不適合
* 提出可以改推薦免費或入門資源，若使用者拒絕則結束通話並祝福

# 在後台檢視通話紀錄與分析結果

* 通話結束後，在 Logs 中可看到錄音檔與完整逐字稿
* 在 Analysis 分頁中可以看到依 Schema 填好的結構化資料欄位
* 範例結果包含 country、coding_experience、ready_to_start、monthly_income、is_qualified 等欄位
* 依輸出可清楚得知：沒開發經驗、不準備投入金額、不符合資格等狀態
* 同一區塊也會顯示由模型生成的通話摘要，方便快速瀏覽重點
* 可查看此通話消耗的成本金額，方便追蹤每通電話的費用
* Logs 中還能檢視所有對話訊息細節與助理設定相關資訊

# 將語音助理綁定到實體電話號碼

* 在 Phone numbers 頁面可以申請最多 10 組免費電話號碼（目前限美國與加拿大區碼）
* 建立號碼時可選擇區碼並命名，例如命名為 main
* 將某個電話號碼綁定到指定的語音助理（例如改綁到 tutorial 助理）
* 綁定後即可用實體手機撥打該號碼，助理會自動接聽並開始對話
* 可設定備援電話號碼，若 AI 號碼失敗可轉接到真人電話
* 可設定 outbound 電話號碼，讓助理主動撥出電話而不是被動接聽
* 通話同樣會進入 Logs 與 Analysis，可用於後續分析與自動化流程

# 整體系統架構與流程說明

* 使用者先造訪前端 Landing Page（例如導師計畫申請頁），按下「Apply now」
* 前端顯示表單與「電話申請」選項，使用者選擇電話申請後輸入姓名、電話、Email 等資訊
* 前端提示使用者即將接到 AI 電話，通話可以發生在實體手機或網頁內通話介面
* AI 助理撥打電話或接通網頁通話，與使用者對話並依問題逐步評估資格
* 通話結束後，前端可顯示通話摘要、是否合格、下一步動作等結果
* 助理根據 is_qualified 結果決定導向：若合格則跳轉到預約通話頁面，不合格則導向低價產品或免費資源頁
* 後端伺服器負責與 AI 助理直接溝通，可讀取通話分析結果與 Logs
* 後端可接收完整 call report，依結果執行後續流程，例如寫入資料庫、發送 Email、觸發自動化工作流等
* 若使用者未接電話，可擴充為讓助理留言語音或簡訊，作為後續跟進的一部分

---

# 初始化 React + Vite 專案

* 使用 `npm create vite@latest` 建立專案，專案名稱為 `frontend`
* 選擇框架為 React，語言使用 JavaScript 而非 TypeScript
* `cd frontend` 後執行 `npm install` 安裝依賴
* 之後透過 `npm run dev` 啟動前端開發伺服器

# 安裝 Vapi Web SDK 與環境變數設定

* 依官方文件安裝 Web SDK：`npm install @vapi-ai/web`
* 在專案根目錄建立 `.env` 檔案
* 定義前端用的環境變數（需以 `VITE_` 開頭）：
* `VITE_VAPI_API_KEY`：前端專用（Public）API Key
* `VITE_ASSISTANT_ID`：在 Vy 後台某個 Assistant 的 ID
* 到 Vy Dashboard 的 API Keys 頁面取得 Public API Key（前端只用 Public，不用 Private）
* 到 Assistants 頁面找到目標 Assistant，複製其 ID 填入 `.env`

# 清理預設檔案與結構

* 刪除 `src/assets` 資料夾與內含 React logo 等預設資源
* 刪除 `App.css`，不再使用預設樣式
* 將 `App.jsx` 清空，只保留元件骨架與 `useState` import，從零開始寫 UI

# 建立 AI 控制模組（ai.js）

* 在 `src` 目錄建立 `ai.js` 檔案
* 匯入 SDK：`import Vapi from '@vapi-ai/web'`
* 從環境變數讀取金鑰與 Assistant ID：
* `const apiKey = import.meta.env.VITE_VAPI_API_KEY`
* `const assistantId = import.meta.env.VITE_ASSISTANT_ID`
* 建立並匯出單一 Vapi 實例：`export const vapi = new Vapi(apiKey)`
* 匯出啟動語音助理的函式 `startAssistant`：
* 非同步函式，接收 `firstName`、`lastName`、`email`、`phone` 四個參數
* 呼叫 `vapi.start(assistantId, { assistantOverrides: { variables: { firstName, lastName, email, phone } } })`
* 透過 `assistantOverrides.variables` 將表單資料傳給後端語音助理，用於 Prompt 變數與分析輸出
* 匯出停止語音助理的函式 `stopAssistant`，內部只呼叫 `vapi.stop()`

# 官方文件與進階覆寫說明

* 官方 Web SDK 文件示範兩種使用方式：
* 使用既有 Assistant ID 啟動既有設定
* 直接在程式碼中傳入完整 Assistant 設定 JSON（不使用 Dashboard 預設設定）
* `assistantOverrides` 可以覆寫幾乎所有配置，例如：
* 是否錄音、轉寫設定、模型、語音設定等
* SDK 也支援發送「背景訊息」給助理，用於動態更新上下文或指令

# 在 App.jsx 測試啟動語音助理

* 在 `App.jsx` 匯入：`vapi`、`startAssistant`、`stopAssistant` 自 `./ai`
* 匯入 `useEffect` 以便在元件載入時測試啟動
* 用 `useEffect` 搭配空依賴陣列，在首次渲染時呼叫 `startAssistant()` 測試是否能連線與開麥
* 開啟 `npm run dev`，瀏覽器載入後會自動啟動語音助理並開始對話
* 確認無誤後，移除這段 `useEffect` 測試程式，避免每次載入就自動撥通

# 加入樣式與狀態管理

* 在 `index.css` 貼入事先寫好的樣式（表單、按鈕、波形、容器布局等）
* 在 `App.jsx` 新增多個 `useState` 管理前端狀態：
* `started`：通話是否已啟動
* `loading`：是否正在啟動或處理中
* `assistantIsSpeaking`：助理是否目前正在說話
* `volumeLevel`：目前音量數值，用於畫出波形動畫
* `callId`：通話 ID，之後用來查詢結果或報告
* `loadingResult`：是否正在載入通話結果
* 表單欄位狀態：`firstName`、`lastName`、`phoneNumber`、`email`
* 暫時設定 `const showForm = true`，先強制顯示表單區塊

# 註冊 Vapi 事件監聽（call / speech / volume / message）

* 在 `useEffect` 中使用 `vapi.on(...)` 註冊各種事件
* `call-start`：
* 將 `loading` 設為 false
* 將 `started` 設為 true
* `call-end`：
* 將 `started` 設為 false
* 將 `loading` 設為 false，避免卡在載入狀態
* `speech-start`：
* 每次助理開始說話時觸發
* 將 `assistantIsSpeaking` 設為 true
* `speech-end`：
* 助理每次說完一句時觸發
* 將 `assistantIsSpeaking` 設為 false
* `volume-level`：
* 帶入 `level` 參數
* 將 `volumeLevel` 更新為目前音量，用來驅動波形動畫 UI
* `message`（選用）：
* 每次有訊息事件觸發時拿到 `message`
* 可 `console.log(message)`，用於顯示即時逐字稿或除錯

# 建立使用者表單 UI

* 在 `App.jsx` 回傳 JSX 結構，最外層使用 `.app-container` 容器
* 使用 `showForm && (...)` 條件渲染表單區塊
* 表單區塊內容：
* 標題 `<h1>` 顯示「Contact details」等文字
* 多個輸入欄位：First name、Last name、Phone number、Email 等
* 輸入欄位使用：
* `type="text"` 或適當類型
* `placeholder` 顯示欄位名稱
* `value` 綁到對應的 state（例如 `firstName`）
* `className="input-field"` 使用預先定義的樣式
* `onChange={handleInputChange(setFirstName)}` 這種寫法來更新狀態
* 實作 `handleInputChange` 工具函式：
* 接收一個 Setter，例如 `setFirstName`
* 回傳一個事件處理函式 `event => setter(event.target.value)`
* 透過這個工具函式，所有輸入欄位可以共用相同 onChange 模式，減少重複程式碼

---

# 建立聯絡資料表單欄位

* 從「名字」欄位複製結構，依序改成「姓氏」、「Email」、「電話」四個欄位
* 每個欄位各自綁定 state：firstName / setFirstName、lastName / setLastName、email / setEmail、phoneNumber / setPhoneNumber
* Email 欄位 input type 設為 `email`，電話欄位設為 `tel`，其餘欄位使用一般文字輸入
* 完成後得到一個包含姓名、Email、電話的基本聯絡表單

# 表單送出按鈕與欄位檢查

* 在 form 內加入按鈕，文字例如「Start application call」
* 按鈕 onClick 綁定 `handleStart` 函式，初期可先定義為空函式避免錯誤
* 使用 `allFieldsFilled = firstName && lastName && email && phoneNumber` 判斷是否全部填寫
* 按鈕的 disabled 綁定 `!allFieldsFilled`，確保所有欄位填完才能啟動通話
* 手動輸入測試資料可確認按鈕啟用與否，驗證表單邏輯正常

# 開始與結束通話的核心流程

* `handleStart` 設為 async，進入時先設定 loading 為 true
* 呼叫 `startAssistant`，傳入 firstName、lastName、email、phoneNumber 等參數啟動語音助理通話
* 從回傳結果中取得通話 ID（例如 `data.id`），並以 state `callId` 保存，供後續查詢通話分析結果使用
* `handleStop` 呼叫 `stopAssistant` 結束通話，之後再補上「取得通話結果並顯示」的邏輯
* 整體由 `handleStart` 負責啟動與記錄通話，由 `handleStop` 負責結束與清理狀態

# 控制畫面：表單、載入中與通話中顯示

* `showForm` 條件為「非 loading、尚未開始助理、未載入結果、沒有 callResult」，只在初始階段顯示表單
* loading 或載入結果時不顯示表單，改顯示一個帶有 `loading` class 的載入指示區塊
* 開始通話後隱藏表單，改顯示通話相關 UI（例如音量條、助理狀態、掛斷按鈕）
* 通話結束後預計改為顯示通話結果，而不是再出現表單

# VolumeLevel：音量視覺化元件

* VolumeLevel 元件接收 volume 參數，內部預設 `numBars = 10` 代表 10 個音量條
* 透過 `Array.from({ length: numBars })` 產生多個 bar 元素
* 每個 bar 的 className 包含 `volume-bar`，並依「索引 / numBars 是否小於 volume」決定是否加上 `active`
* CSS 依 `volume-bar` 和 `volume-bar active` 決定顯示樣式，形成動態的音量高低效果

# AssistantSpeechIndicator：助理說話狀態顯示

* AssistantSpeechIndicator 元件接收 `isSpeaking` 布林值判斷助理是否正在說話
* 外層 div 使用 `assistant-speech-indicator` class 包住整個狀態區塊
* 內部狀態 div className 組成 `speech-indicator speaking` 或 `speech-indicator not-speaking`
* 顯示文字例如「Assistant speaking」或「Assistant not speaking」，樣式交由 CSS 控制

# ActiveCallDetails：整合視覺化與掛斷操作

* ActiveCallDetails 元件接收 `assistantIsSpeaking`、`volumeLevel`、`endCallCallback` 三個參數
* 內部先渲染 AssistantSpeechIndicator 顯示助理目前說話狀態
* 接著渲染 VolumeLevel 顯示即時音量條變化
* 底部放置「End call」按鈕，onClick 綁定 `endCallCallback`，讓使用者可以結束通話
* 作為通話進行階段的主視覺與控制區塊

# 在主頁中整合通話 UI 與流程

* 在 App 中匯入 ActiveCallDetails，並以 `started && <ActiveCallDetails ... />` 方式條件渲染
* 將追蹤助理說話狀態的 state 傳給 `assistantIsSpeaking`，音量狀態傳給 `volumeLevel`
* 將 `handleStop` 傳入 `endCallCallback` 讓「End call」按鈕真正觸發結束通話流程
* 實際操作流程為：填好表單 → 按下「Start application call」→ 顯示載入動畫 → 接到 AI 通話並顯示波形與狀態 → 按下「End call」結束並回到初始畫面

# 前端完成度與尚未處理的部分

* 目前前端已能發起通話、顯示助理說話狀態與音量視覺化、並提供結束通話按鈕
* 前端尚未取得與顯示「通話分析結果」，例如是否符合資格、結構化欄位、通話摘要與完整轉錄
* 對於單純客戶支援用途目前功能已足夠，但無法根據通話內容自動執行後續動作
* 若要根據通話結果做決策（如導向預約頁或其他方案），需要接上後端取得分析資料並在前端顯示與處理

---

# 後端伺服器目的與角色

* 建立獨立的 Python Backend 來安全存取語音助理的「通話紀錄與結構化輸出」
* 前端只負責發起通話與顯示結果，不直接接觸敏感資料或後端 API key
* 後端負責：根據前端傳來的 call ID，向 Vy API 查詢完整通話詳情（包含分析與結構化資料）
* 避免任何人從前端隨意查詢所有通話紀錄，降低敏感資訊外洩風險

# Backend 專案初始化與依賴

* 在專案中建立 `backend` 資料夾，作為後端專案目錄
* 在 `backend` 內建立 `requirements.txt`，列出依賴：
* `requests`、`Flask`、`python-dotenv`、`Flask-Cors`
* 建立 `main.py` 作為主程式檔
* 建立 `.env` 檔案，定義 `VAPI_API_KEY`（這裡使用「後端私鑰」）

# 後端 API Key 設定

* 到 Vy Dashboard → API Keys 頁面
* 這次使用的是「Private / Backend API Key」，權限較高
* 將 Private Key 貼到 `backend/.env` 裡的 `VAPI_API_KEY`
* 不在影片或程式碼中顯示 Private Key，避免洩漏

# Python 虛擬環境與套件安裝

* 在 VS Code 開新 Terminal，切到專案根目錄後再進入 `backend`
* 建立虛擬環境：`python -m venv venv`
* Windows 啟用：`venv\Scripts\activate`
* macOS / Linux 啟用：`source venv/bin/activate`
* 啟用後執行：`pip install -r requirements.txt` 安裝所有依賴
* 下次重開機後要再啟用虛擬環境才能使用已裝的套件

# 查詢單一通話 API（呼叫 Vy 官方 API）

* 在 `main.py` 中匯入：`os`、`requests`、`load_dotenv`
* 呼叫 `load_dotenv()` 載入 `.env` 中的 `VAPI_API_KEY`
* 寫函式 `fetch_call_details(call_id)` 用來打 Vy 的 Get Call API
* API URL 格式：`https://api.vapi.ai/call/{call_id}`（實際以官方文件為準）
* 在 headers 裡設置 `Authorization: Bearer <VAPI_API_KEY>`
* 用 `requests.get(url, headers=headers)` 送出請求
* 以 `response.json()` 回傳 JSON 格式結果

# Flask 應用與 CORS 設定

* 建立 Flask app：`app = Flask(__name__)`
* 匯入 `Flask`、`jsonify`、`request` 以及 `Flask-Cors` 的 `CORS`
* 用 `CORS(app)` 包住 app，允許前端網頁以 AJAX 呼叫此後端 API
* 目的：避免前端向不同網域或不同 port 的後端發請求時遇到 CORS 錯誤

# /call-details API 路由設計

* 建立路由：`@app.route("/call-details", methods=["GET"])`
* 寫處理函式 `get_call_details()`
* 從 query string 讀取 `callId`：`call_id = request.args.get("callId")`
* 若 `callId` 缺失：
* 回傳 `jsonify({"error": "callId is required"}), 400`（Bad Request）
* 若 `callId` 存在：
* 呼叫 `fetch_call_details(call_id)` 向 Vy 取得完整通話資訊

# 從 Vy 回應中擷取重要欄位

* 接收 `response = fetch_call_details(call_id)` 的 JSON 物件
* 可 `print(response)` 方便開發時檢查返回格式
* 主要關注欄位：
* `summary = response.get("summary")`
* `analysis = response.get("analysis")`（結構化資料、成功與否判斷等）
* 後端回傳給前端：
* `return jsonify({"analysis": analysis, "summary": summary}), 200`

# 錯誤處理與例外情況

* 使用 `try...except Exception as e` 包住對 Vy API 的呼叫
* 若發生錯誤（API 掛掉、callId 無效、網路問題等）
* 回傳 `jsonify({"error": str(e)}), 500`（Internal Server Error）
* 讓前端可以根據錯誤訊息做相對應的 UI 顯示

# 啟動 Flask 後端伺服器

* 在檔案底部加入：
* `if __name__ == "__main__": app.run(debug=True)`
* 執行：`python main.py` 啟動後端伺服器
* 預設在 `http://127.0.0.1:5000` 或類似位址提供 API 服務

# 手動測試 /call-details API

* 在瀏覽器輸入：`http://127.0.0.1:5000/call-details?callId=1234`
* 若 `callId` 是假的或格式錯誤，後端會：
* 回傳 `{"analysis": null, "summary": null}` 或錯誤訊息
* 若未帶 `callId`，則回傳：
* `{"error": "callId is required"}`，HTTP 狀態碼 400
* 確認路由運作無誤後，即可在前端整合此 API

# 前後端資料流整體流程

* 通話開始與結束都由前端透過 Vapi Web SDK 控制
* 通話結束時，前端持有這通電話的 `callId`
* 前端呼叫自家後端 `/call-details?callId=...`
* 後端用 Private API Key 向 Vy 官方 API 查詢該通話詳細資訊
* 後端擷取 `summary` 與 `analysis` 等關鍵欄位後回傳給前端
* 前端顯示「結束報告」、判斷是否合格、或依結果導向下一步流程

---

# 在 Vite 前端設定 Proxy 解決 CORS

* 在前端設定檔中加入 server.proxy 設定，將以 /call-details 開頭的請求轉發到後端伺服器
* 目標網址指向本機後端服務埠 5000
* 啟用變更來源設定，讓請求看起來像是直接發給後端
* 在開發模式下關閉憑證檢查以避免本機 https / http 設定造成錯誤
* 目的：前端呼叫 /call-details 時，實際會送到後端 API，而不會觸發瀏覽器的跨網域限制

# 在前端輪詢取得通話分析結果

* 新增 getCallDetails 函式，用來從後端取回單一通話的分析結果
* 設定輪詢間隔（例如 3 秒），持續重複請求直到分析完成
* 每次請求會帶上 callId 查詢對應那一通通話的分析資料
* 收到回應後將資料轉成 JSON，並檢查是否已包含分析結果與摘要
* 若尚未產出分析與摘要，使用計時器延遲一段時間後再次呼叫 getCallDetails

# 管理載入狀態與錯誤處理

* 呼叫 getCallDetails 前先將「載入結果中」的狀態設定為 true
* 一旦成功取得完整分析資料，將其儲存在前端狀態中，並把「載入結果中」改為 false
* 若請求或解析 JSON 過程中發生錯誤，會進入錯誤處理區塊
* 錯誤處理可簡單顯示錯誤訊息，方便除錯輪詢流程

# 在結束通話後觸發分析查詢

* 結束通話時的處理函式除呼叫停止助理外，也會呼叫 getCallDetails
* 通話一結束就開始輪詢後端，直到 LLM 分析完通話轉錄並產生結果
* 這樣使用者結束通話後，過幾秒就能在前端介面看到「這通通話的判定與摘要」

# 在畫面上顯示「資格判定」與摘要

* 當「正在載入結果」狀態為 true 時，在畫面顯示「正在載入通話資訊」之類提示文字
* 當不再載入且 callResult 有值時，顯示一個區塊用來展示分析結果
* 顯示是否合格：從 callResult 裡的分析資料中讀取結構化欄位（例如是否合格）
* 顯示摘要：從 callResult 裡的 summary 欄位呈現整通通話的總結
* 透過瀏覽器主控台可以看到完整的分析物件，包括結構化欄位與聯絡資料等

# 修正 JSON 與 Proxy 設定問題

* 一開始出現「解析 JSON 失敗」與 Proxy 錯誤，是因為目標網址誤用 https 而後端實際為 http
* 將 proxy 目標中的 https 改成 http 後，請求才能正常通過開發用 Proxy 並取得正確回應
* 修正後再次測試通話，結束後輪詢即可順利拿到分析結果與摘要

# 改善語音合成模型與聲音自然度

* 針對語音不自然的問題，改換文字轉語音供應商的模型版本（例如較新的 turbo 模型）
* 手動指定更自然的 voice id，使說話語調與口音更接近真人對話
* 更新語音設定並重新發布助理後，再次測試通話即可聽到更自然的語音回應
* 最終完成整體流程：前端表單與通話 UI、後端代理與分析、結構化結果顯示，以及自然的語音互動

---
# Terminology
* 語音助理（Voice Assistant）：透過語音與使用者互動、回答問題或執行任務的智慧系統
* 語音 API（Voice API）：提供開發者呼叫語音相關功能（通話、合成、辨識）的程式介面
* 大型語言模型（Large Language Model, LLM）：能理解與產生自然語言文字的 AI 模型
* 提示詞工程（Prompt Engineering）：設計與微調輸入文字來控制模型行為的技術
* 延遲時間（Latency）：從發出請求到收到回應所花費的時間
* 語音轉文字（Speech-to-Text, STT）：把人說的話轉成文字的技術
* 文字轉語音（Text-to-Speech, TTS）：把文字內容轉換成可聽語音的技術
* 溫度參數（Temperature）：控制模型輸出隨機性與創造性高低的設定值
* 情緒偵測（Emotion Detection）：從語音或文字判斷說話者情緒狀態的技術
* 背景降噪（Background Denoising）：去除通話或錄音中的環境雜音處理
* 語音模型提供商（Model Provider）：提供 AI 模型服務的公司或平台
* 集群服務（Cluster）：由多台伺服器組成、用來分擔模型運算負載的架構
* 前端應用程式（Frontend Application）：在瀏覽器中與使用者互動的畫面與程式碼
* 後端伺服器（Backend Server）：處理商業邏輯、資料庫與外部 API 呼叫的伺服器程式
* Webhook（Web Hook）：事件發生時主動把資料送到指定網址的回呼機制
* JSON 結構（JSON Schema）：定義 JSON 資料欄位格式與型別的規範
* 結構化資料輸出（Structured Output）：依固定欄位格式輸出的資料，方便程式解析
* 通話報告（Call Report）：通話結束後產生的摘要與分析結果文件
* 通話成功率評估（Call Success Evaluation）：判斷一次通話是否達成預期目標的過程
* 函式工具（Tool / Function）：模型在對話中可呼叫的外部功能或程式
* 自訂工具整合（Custom Tool Integration）：把自己寫的程式功能接入語音助理供其呼叫
* 事件回呼 URL（Callback URL）：用來接收平台推送事件資料的伺服器網址
* 響應串流（Streaming Response）：在資料尚未全部產生前，邊產生邊回傳的傳輸方式
* 通話錄音（Call Recording）：將通話語音內容存檔以便回放或分析
* 分析管線（Analysis Pipeline）：通話結束後一系列自動分析與處理的流程
* 使用者資格篩選（Lead Qualification）：評估使用者是否符合產品或服務條件的流程
* 申請流程自動化（Application Automation）：用系統自動收集與審核申請資料的做法
* 表單替代方案（Form Replacement）：用對話或語音流程代替傳統線上表單
* 入口頁面（Landing Page）：用來導入訪客並推動單一行動的網頁
* 互動式對話流程（Interactive Flow）：依使用者回答即時調整後續問題的對話設計
* 文字客製提示（Custom Prompt）：根據特定業務需求撰寫的模型指令文字
* 知識庫（Knowledge Base）：存放產品或公司相關資訊供模型查詢的資料集合
* 聊天上下文（Conversation Context）：目前與過去對話中可用來判斷狀況的所有資訊
* 狀態管理（State Management）：在對話過程中記錄與更新使用者相關資料的方式
* 呼叫路由（Call Routing）：根據條件把來電導向不同助理或流程的機制
* 自動結束通話（Auto Hangup）：由系統判斷並主動掛斷電話的功能
* 智慧端點偵測（Smart Endpointing）：自動偵測使用者何時說完話再開始回應的技術
* 參數調校（Parameter Tuning）：調整模型與語音系統各種設定以優化效果的過程
* 試用額度（Free Credit）：新用戶註冊後可免費使用的一定金額或使用量
* 音訊串流（Audio Streaming）：連續傳送語音資料到伺服器或從伺服器接收語音資料
* API 金鑰（API Key）：用來驗證身分並授權使用 API 的密鑰
* 回應模板（Response Template）：預先設計好的回覆句型或訊息結構
* 使用者屬性（User Attributes）：例如年齡、國家、收入等用於判斷與客製化的欄位
* 資料後處理（Post-processing）：對模型或語音輸出再進一步整理與修正的步驟
* 事件日誌（Event Log）：記錄系統在對話和通話中產生的各種事件與狀態
* 通話流程設計（Call Flow Design）：規劃通話中問題順序與決策分支的工作
* A/B 測試（A/B Testing）：比較兩種不同設定或提示詞效果的實驗方法
* 生產環境部署（Production Deployment）：將系統正式上線給真實使用者使用的過程
* 體驗優化（Experience Optimization）：持續調整系統以提升使用者互動感受與效率
* 轉換率（Conversion Rate）：從進入流程的使用者中，實際完成目標行為的比例
* 通話分析（Call Analysis）：對一通電話的內容做整理與判斷，找出重點與結果
* 結構化輸出（Structured Output）：用固定欄位與格式，把模型的答案變成規律的資料
* 結構化資料綱要（Structured Data Schema）：事先定義好「有哪些欄位、型別是什麼」的規則
* 欄位描述（Field Description）：用文字說明每個欄位代表什麼，要填什麼內容
* 布林值（Boolean）：只有「真」或「假」兩種可能的資料型別
* 列舉型別（Enumeration）：先列出幾個固定選項，只能從裡面選一個或幾個
* 必填欄位（Mandatory Field）：一定要有值的欄位，不能留白
* 巢狀物件（Nested Object）：在一個欄位裡面再放一個「小物件」，裡面還有更多欄位
* 聯絡資訊物件（Contact Details Object）：把姓名、電話、Email 等聯絡資料打包在同一個物件裡
* 月收入區間（Monthly Income Range）：用「收入落在哪個範圍」來描述一個人的月收入
* 資格評估（Eligibility Evaluation）：判斷對方符不符合某個專案或課程的條件
* 合格判定（Qualification Decision）：最後決定對方是「合格」還是「不合格」
* 潛在客戶（Prospect）：還沒成交，但有可能會成為客戶的人
* 資格審核通話（Qualification Call）：專門用來檢查對方適不適合的電話訪談
* 成功評估（Success Evaluation）：判斷這次通話有沒有達到預期目標的步驟
* 通話摘要（Call Summary）：用幾句話快速說明這通電話發生了什麼
* 超時設定（Timeout Setting）：設定最多等多久，超過時間就停止或放棄
* LLM 呼叫（LLM Invocation）：把文字丟給大型語言模型，請它運算並回覆的動作
* 通話文字稿（Call Transcription）：把電話講話內容完整變成文字的紀錄
* 響應綱要（Response Schema）：限制模型輸出必須符合的一組欄位與格式規則
* 欄位驗證（Field Validation）：檢查欄位裡填的值有沒有符合規定
* 枚舉選項（Enum Options）：列舉型別裡可以被選擇的那幾個固定值
* 預設選項（Default Option）：在沒特別指定時，自動使用的選項
* 未提供標記（Not Provided Flag）：用來表示使用者沒有提供這一項資訊的值
* 分析日誌（Analysis Logs）：記錄通話、分析與模型輸出細節的系統紀錄
* 通話成本（Call Cost）：這通電話在 API 與服務上實際花掉的金額
* 助理設定（Assistant Configuration）：調整語音助理行為與規則的各種設定
* 語音助理（Voice Assistant）：用聲音跟人對話的 AI 助理
* 電話號碼綁定（Phone Number Binding）：把一個電話號碼指定給某個助理或專案使用
* 回撥電話（Callback）：系統主動打電話給使用者，而不是等使用者先打進來
* 備援電話（Fallback Number）：主號碼失敗時，改打到的備用電話號碼
* 外呼電話（Outbound Call）：由系統主動撥出去的電話，而不是接聽進來的電話
* 來電路由（Call Routing）：控制來電要被導到哪個助理或哪個人員的流程
* 電話語音流程（Call Flow）：一通電話中問題、回答與分支路線的完整順序
* 銷售漏斗（Sales Funnel）：從認識你到成交，中間一層一層篩選與轉化的流程圖
* 低單價產品（Low-ticket Offer）：價格較低、比較容易入手的產品或課程
* 向下銷售（Downsell）：原本商品太貴時，改推薦價格更低的方案
* 著陸頁（Landing Page）：使用者點廣告或連結後，第一個看到的介紹頁面
* 申請表單（Application Form）：讓使用者填資料、申請加入某個計畫的表單
* 合格線索（Qualified Lead）：經過評估後，確定值得進一步跟進的潛在客戶
* 不合格線索（Unqualified Lead）：不符合條件，不適合繼續銷售流程的潛在客戶
* 呼叫報告（Call Report）：整理一通或多通電話結果與重點的報告資料
* 後端伺服器（Backend Server）：在伺服器上處理權杖、資料儲存與邏輯的程式
* 前端整合（Frontend Integration）：把 AI 助理與分析功能接到網頁或 App 上
* 系統架構圖（System Architecture Diagram）：畫出前端、後端與助理之間關係的圖
* 元件泳道圖（Swimlane Diagram）：用多條「泳道」分開不同角色在流程中的動作的流程圖
* 助理觸發（Assistant Trigger）：某個事件讓 AI 助理開始行動的那個動作
* 事件驅動流程（Event-driven Flow）：由「事件」帶動下一步要做什麼的系統設計方式
* 後端通知（Backend Notification）：把通話結果或分析資料送回後端的訊息
* 自動化後續動作（Automated Follow-up）：根據通話結果自動寄信、導頁或安排下一步的流程
* 程式碼編輯器（Code Editor）：用來撰寫與編輯程式碼的軟體工具
* VS Code 整合開發環境（VS Code IDE）：一套常用來開發前端與後端程式的免費編輯器
* React 前端框架（React Framework）：用來建立互動式使用者介面的 JavaScript 函式庫
* Vite 建置工具（Vite Build Tool）：幫助快速啟動與打包前端專案的開發工具
* npm 封包管理器（npm Package Manager）：用來安裝與管理 JavaScript 套件的系統
* 專案腳手架（Project Scaffold）：自動幫你生出基本專案結構的起始模板
* 相依套件安裝（Dependency Installation）：把專案需要用到的外部套件下載到本機的過程
* 前端開發伺服器（Dev Server）：在本機跑起來，用來即時預覽網頁變化的伺服器
* 前端 SDK（Frontend SDK）：讓前端程式方便呼叫某個服務功能的一組程式庫
* 網頁 SDK（Web SDK）：專門設計給瀏覽器環境使用的開發工具套件
* 官方文件（Official Documentation）：由產品或服務官方提供的使用說明與教學
* 環境設定檔（Env File）：用來存放專案機密或設定值的文字檔案
* 環境變數前綴（Env Prefix）：為了安全與規則，環境變數名稱需要加上的固定開頭字串
* 公開 API 金鑰（Public API Key）：可以放在前端使用、權限較小的識別金鑰
* 私密 API 金鑰（Private API Key）：只能放在後端、權限較大的機密金鑰
* 助理識別碼（Assistant ID）：用來指定啟動哪一個語音助理的唯一代碼
* 模組匯入（Import Statement）：把別的檔案或套件中的程式碼載入進來使用的語法
* 模組匯出（Export Statement）：把檔案中的函式或變數公開給其他檔案使用的語法
* 實例化物件（Object Instantiation）：用 new 關鍵字建立一個物件實體的動作
* 非同步函式（Async Function）：可以等待外部操作完成再繼續執行的函式
* Await 關鍵字（Await Keyword）：在非同步函式中，用來等待結果回來的語法
* 回傳 Promise（Return Promise）：表示這個函式會在未來某個時間點才給出結果
* 函式參數（Function Parameters）：呼叫函式時傳進去、讓函式使用的資料
* 前端表單資料（Frontend Form Data）：使用者在網頁上輸入的文字與資料集合
* 狀態管理 Hook（State Hook）：在 React 中用來記錄與更新畫面狀態的工具
* useEffect Hook（useEffect Hook）：在特定時機自動執行程式碼的 React 工具
* 相依陣列（Dependency Array）：告訴 useEffect 在哪些變數改變時才需要重新執行
* 事件監聽器（Event Listener）：當特定事件發生時，自動呼叫某個函式的機制
* 通話開始事件（Call Start Event）：語音通話一開始時觸發的系統事件
* 通話結束事件（Call End Event）：語音通話完全結束時觸發的系統事件
* 語音開始事件（Speech Start Event）：助理開始說話當下觸發的事件
* 語音結束事件（Speech End Event）：助理一句話說完時觸發的事件
* 音量變化事件（Volume Level Event）：音量高低變化時持續回報數值的事件
* 回呼函式（Callback Function）：被當成參數傳入，之後由系統在適當時機呼叫的函式
* 音量等級數值（Volume Level Value）：用數字表示當前聲音大小的資料
* 即時轉寫訊息（Live Transcript Message）：通話中即時產生的文字內容訊息
* 表單輸入欄位（Form Input Field）：讓使用者在網頁上輸入資料的小方框
* 佔位文字（Placeholder Text）：顯示在輸入框裡、提示要填什麼的淡色文字
* OnChange 事件處理（OnChange Handler）：在輸入內容改變時被呼叫來更新狀態的函式
* 事件物件（Event Object）：描述這次事件細節的資料，例如從哪個輸入框來
* 目標值（Target Value）：事件中實際輸入的文字內容值
* CSS 樣式表（CSS Stylesheet）：用來控制網頁外觀排版與顏色的設定檔
* 樣式類別名稱（CSS Class Name）：套在元素上讓它使用特定 CSS 樣式的名稱
* 版面容器（Layout Container）：用來包住其他元件、控制整體排版的外層區塊
* 輸入驗證（Input Validation）：檢查使用者輸入是否符合格式或必填規則的過程
* 載入狀態（Loading State）：表示系統正在處理中、尚未完成的畫面狀態
* 通話進行中狀態（Call Started State）：代表目前語音通話正在進行的布林值狀態
* 助理說話狀態（Assistant Speaking State）：代表現在是助理在說話中的布林值狀態
* 通話結果物件（Call Result Object）：用來存放這次通話分析與摘要結果的資料結構
* GitHub 原始碼倉庫（GitHub Repository）：用來存放與分享專案程式碼的線上空間
* 表單元件（Form Component）：用來收集使用者輸入資料的 React 元件
* 輸入框（Input Field）：讓使用者輸入文字或數字的欄位
* 電子郵件欄位（Email Field）：專門用來輸入 Email 並可自動做基本格式檢查的欄位
* 電話欄位（Telephone Field）：用來輸入電話號碼的輸入欄位
* onClick 處理函式（onClick Handler）：按鈕被點擊時要執行的函式
* handleStart 函式（handleStart Function）：在使用者按下開始通話時負責啟動助理的函式
* 非同步函式（Async Function）：可以搭配 await 等待非同步操作完成的函式
* await 關鍵字（await Keyword）：在非同步函式中等待 Promise 結果的語法
* 狀態鉤子（useState Hook）：在 React 中用來宣告與更新元件狀態的工具
* 效果鉤子（useEffect Hook）：在狀態或屬性改變時執行副作用程式碼的工具
* 載入狀態（Loading State）：表示目前系統正在處理中、尚未完成的狀態標記
* 送出按鈕（Submit Button）：用來觸發送出表單或啟動流程的按鈕
* 停用按鈕（Disabled Button）：暫時無法被點擊的按鈕狀態
* 表單驗證（Form Validation）：檢查欄位是否都有填寫或格式正確的過程
* 前端邏輯（Frontend Logic）：在瀏覽器端負責處理 UI 與互動的程式邏輯
* 聯絡資料表單（Contact Details Form）：用來收集姓名、Email、電話等基本資料的表單
* 應用程式通話（Application Call）：專門用來進行申請流程的語音通話
* 語音助理介面（Voice Assistant Interface）：顯示語音助理狀態、文字與控制的畫面
* 活動通話細節元件（Active Call Details Component）：顯示正在通話時狀態與按鈕的 React 元件
* 語音音量條（Volume Bars）：用多條長條顯示目前音量高低的視覺元素
* 音量等級（Volume Level）：用 0–1 或多格刻度表示的當前音量大小
* 助理發話指示器（Assistant Speech Indicator）：顯示助理目前是否正在說話的標示
* End Call 按鈕（End Call Button）：用來結束目前通話的按鈕
* 回呼函式（Callback Function）：當某事件發生時被呼叫執行的函式
* 陣列生成（Array.from）：用來依指定長度或來源建立新陣列的 JavaScript 函式
* 展開運算子（Spread Operator）：用 ... 展開陣列或物件內容的語法
* 條件渲染（Conditional Rendering）：依狀態決定要不要在畫面上顯示某個元件
* 三元運算子（Ternary Operator）：用 `條件 ? A : B` 寫成一行的條件判斷
* 類別名稱（Class Name）：指定給 HTML 元素，用來套用 CSS 樣式的名稱
* CSS 動畫（CSS Animation）：用 CSS 讓元素產生動態效果的技術
* 波形視覺化（Waveform Visualization）：把音訊以波形或條狀圖方式呈現出來的畫面
* 呼叫識別碼（Call ID）：用來唯一識別一通通話的 ID 值
* 結束通話處理（Handle Stop）：在使用者結束通話時負責停止助理與更新狀態的函式
* 語音助理狀態（Assistant State）：描述助理目前是閒置、通話中或結束等狀態的資料
* 結構化輸出結果（Structured Output Result）：從後端取得、符合預先定義欄位格式的分析結果
* 通話後分析（Post-call Analysis）：通話結束後對內容與結果做整理與判斷的流程
* 後端 API 呼叫（Backend API Call）：從前端向伺服器發出請求取得或送出資料的動作
* 開始助理函式（startAssistant Function）：向後端請求啟動語音助理與通話的函式
* 停止助理函式（stopAssistant Function）：通知後端停止目前語音助理通話的函式
* 假資料（Dummy Data）：用來測試或示範的隨意資料，不是真實使用者資訊
* 視覺化元件（Visualization Component）：專門負責呈現圖形或指示狀態的 UI 元件
* 通話流程控制（Call Flow Control）：管理通話開始、進行、結束各階段的邏輯
* 前端路由返回（Frontend Navigation Back）：通話結束後把使用者導回原本畫面或首頁的動作
* 使用者體驗（User Experience, UX）：使用者實際操作系統時感受到的整體順暢度與舒適度
* 按鈕樣式（Button Styling）：針對按鈕外觀做顏色、大小、圓角等設計的 CSS 設定
* 活動/非活動狀態（Active/Inactive State）：用來區分元件目前是否啟用或運作中的標記
* 錯誤訊息（Error Message）：在流程出錯時顯示給開發者或使用者看的問題說明
* 主題樣式表（Theme Stylesheet）：集中定義按鈕、背景、字體等整體風格的 CSS 檔
* 狀態旗標（State Flag）：用布林值記錄某個狀態是否成立的變數
* 前端元件庫（Component Library）：收集一組常用 UI 元件，方便在專案中重複使用的套件或設計系統
* 虛擬環境（Virtual Environment）：在專案中建立獨立的 Python 執行空間，隔離不同專案的套件與版本
* 相依套件（Dependencies）：程式運作時所需安裝的外部函式庫或套件集合
* 需求檔（requirements.txt）：列出專案所有相依套件與版本給 pip 安裝用的檔案
* 環境變數檔（.env File）：用來存放 API 金鑰等敏感設定、不直接寫在程式碼裡的檔案
* 私密金鑰（Private Key）：只能在後端保存、權限較高的機密 API 金鑰
* HTTP 要求（HTTP Request）：從用戶端送到伺服器的一筆網路請求
* HTTP 回應（HTTP Response）：伺服器處理完請求後回傳給用戶端的資料
* GET 請求（GET Request）：用來向伺服器「讀取」資料的一種 HTTP 方法
* 授權標頭（Authorization Header）：在 HTTP 請求中夾帶身分驗證資訊的標頭欄位
* 持有人權杖（Bearer Token）：以「Bearer XXX」形式附在授權標頭，用來驗證使用者或服務身分的字串
* 狀態碼（Status Code）：描述 HTTP 請求結果的三位數代碼（如 200、400、500）
* JSON 物件（JSON Object）：用鍵值對方式表示資料的文字格式，常用於 API 傳輸
* JSON 解析（JSON Parsing）：把 JSON 字串轉換為程式內可操作的資料結構的過程
* API 端點（API Endpoint）：對外提供服務的特定 URL 路徑
* 呼叫識別碼（Call ID）：用來唯一標示某一次語音通話記錄的 ID
* 通話紀錄（Call Log）：保存一通通話相關所有細節與訊息的資料
* 結構化輸出（Structured Output）：依固定欄位格式輸出的資料，方便前端或系統使用
* 錯誤處理（Error Handling）：在程式遇到錯誤時，優雅處理而不是直接崩潰的做法
* 異常捕捉（Exception Handling）：用 try/except 把執行時錯誤攔下來並做相對應處理
* 日誌輸出（Logging）：在後端持續記錄執行狀態與錯誤訊息，方便除錯與追蹤
* 代理伺服器（Proxy Server）：代替前端向外部服務發送請求、轉傳結果的中間伺服器
* 跨來源資源共用（CORS）：瀏覽器規範，限制與控制不同網域之間發送請求的安全機制
* Flask 框架（Flask Framework）：輕量級的 Python 網頁與 API 伺服器框架
* 路由裝飾器（Route Decorator）：用來標記某個函式對應哪一個 URL 路徑與方法的語法
* 路由處理函式（Route Handler）：實際處理特定 URL 請求邏輯的後端函式
* JSON 回應（JSON Response）：伺服器以 JSON 格式回傳給前端的資料
* 查詢參數（Query Parameter）：URL 中「?」後面用來傳遞額外參數的 key=value 配對
* 請求參數解析（Request Args Parsing）：從查詢參數中把需要的值取出來的過程
* 伺服器啟動（Server Run）：讓後端程式開始監聽某個埠號並接受請求的動作
* 偵錯模式（Debug Mode）：在開發時提供更詳細錯誤訊息與自動重啟功能的模式
* Python 請求套件（requests Library）：Python 中用來發送 HTTP 請求的常用套件
* 作業系統模組（os Module）：Python 中用來存取環境變數與檔案路徑等作業系統功能的模組
* 環境載入工具（python-dotenv）：專門用來載入 .env 檔案內容到環境變數的工具套件
* 伺服器 SDK（Server SDK）：提供後端使用者更方便操作 API 的官方程式庫
* API 參考文件（API Reference）：列出所有可用端點、參數與回應格式的技術文件
* 通話成本資訊（Call Cost Information）：描述某一次語音通話所產生費用的資料
* 分析結果（Analysis Result）：對通話內容進行 AI 分析後產生的結論與結構化資料
* 成功評估（Success Evaluation）：判定這次通話是否達成預期目的的評量結果
* 通話摘要（Call Summary）：對整通通話內容做簡短敘述與重點整理的文字
* 前後端分離架構（Frontend-Backend Separation）：前端與後端獨立開發、以 API 溝通的系統設計方式
* 安全性權限控制（Security Permissions）：限制哪些操作與資料只有授權方可以存取的機制
* 機密資訊保護（Sensitive Data Protection）：避免用戶資料與金鑰在前端或公開環境外洩的做法
* HTTP 查詢字串（Query String）：URL 中攜帶查詢參數的一整段文字部分
* 內部伺服器錯誤（Internal Server Error）：伺服器端發生未預期問題時回傳的 500 狀態碼
* 錯誤訊息回傳（Error Message Response）：在 API 回應中附帶描述錯誤原因的文字或欄位
* 參數驗證（Parameter Validation）：檢查請求中是否帶有必要的欄位與正確格式的過程
* API 呼叫流程（API Call Flow）：從前端發送請求、後端轉呼外部服務再回傳結果的整體步驟
* 伺服器埠號（Server Port）：用來區分同一台機器上不同網路服務的數字編號
* 本機開發環境（Local Development Environment）：在自己電腦上啟動伺服器與前端進行開發測試的環境
* 回傳格式設計（Response Schema Design）：規劃 API 回應中欄位名稱與資料結構的設計工作
* 跨來源資源共用（CORS, Cross-Origin Resource Sharing）：瀏覽器規則，限制前端向不同網域發送請求，避免安全問題
* 反向代理（Proxy）：由前端伺服器代替使用者把請求轉發到後端伺服器的中介層
* 開發伺服器（Dev Server）：在開發階段提供熱重載與本機預覽的伺服器
* 目標伺服器（Target Server）：代理要把請求真正轉送到的後端位址
* 更改來源標頭（Change Origin）：在代理時修改 HTTP Origin 標頭成為目標伺服器的網域
* 不安全連線（Insecure Connection）：未驗證憑證或未加密的 HTTP/SSL 連線
* HTTP 通訊協定（HTTP Protocol）：網頁用來傳輸請求與回應的應用層協定
* HTTPS 通訊協定（HTTPS Protocol）：在 HTTP 上加上 TLS/SSL 加密的安全通訊協定
* API 端點（API Endpoint）：後端提供服務的具體 URL 路徑
* 呼叫詳情路由（Call Details Route）：專門用來查詢單一通話詳細資訊的 API 路徑
* 前後端通訊（Frontend-Backend Communication）：瀏覽器與伺服器之間交換資料的過程
* 查詢字串參數（Query String Parameter）：URL 中 `?key=value` 形式附加的參數
* 呼叫識別碼（Call ID）：用來唯一識別每一通語音通話的 ID 值
* 週期輪詢（Periodic Polling）：固定間隔反覆向後端詢問最新狀態的技巧
* 輪詢間隔（Polling Interval）：兩次輪詢請求之間等待的時間長度
* 後處理分析（Post-call Analysis）：通話結束後，由模型分析通話內容的階段
* 結構化分析資料（Structured Analysis Data）：以固定欄位與型別呈現的分析結果資料
* JSON 回應（JSON Response）：後端以 JSON 格式回傳的資料物件
* JSON 解析（JSON Parsing）：把字串形式的 JSON 轉成可操作物件的過程
* 非同步請求（Asynchronous Request）：不會阻塞主執行緒、完成後再回報結果的網路請求
* Promise 鏈（Promise Chain）：連續使用 `then` 來依序處理非同步結果的寫法
* then 回呼（then Callback）：在 Promise 成功時被呼叫、處理回傳資料的函式
* catch 錯誤處理（catch Error Handling）：在 Promise 失敗時捕捉錯誤並處理的機制
* 設定逾時（setTimeout）：指定延遲一段時間後再執行某段程式碼的函式
* 遞迴呼叫（Recursive Call）：函式在自己內部再次呼叫自己的寫法
* 結構化資料欄位（Structured Data Field）：在 schema 中定義好的單一屬性欄位
* 合格旗標（Qualified Flag）：記錄使用者是否通過資格審核的布林欄位
* 摘要欄位（Summary Field）：儲存整通通話簡短文字摘要的欄位
* 結構化回應物件（Structured Response Object）：包含分析結果與摘要的完整 JSON 物件
* 載入結果狀態（Loading Result State）：代表目前正在等待後端分析結果的 UI 狀態標記
* 代理錯誤（Proxy Error）：前端代理請求時，轉發或連線失敗產生的錯誤
* 非預期 JSON 結尾（Unexpected End of JSON）：表示伺服器回傳的 JSON 資料不完整或壞掉的錯誤
* 主控台輸出（Console Logging）：用 `console.log` 在瀏覽器開發工具中印出偵錯資訊
* 開發模式設定（Development Configuration）：只在開發階段使用的 Vite 或建置工具設定
* 生產模式部署（Production Deployment）：把應用程式部署到正式環境讓真實使用者使用
* 結構化輸出欄位（Structured Output Field）：在 AI 分析設定裡定義要輸出的單一欄位
* 聯絡資訊欄位（Contact Fields）：像姓名、Email、電話等用來聯絡使用者的欄位
* 後端分析服務（Backend Analysis Service）：負責根據通話紀錄進行 LLM 分析的伺服器端程式
* 自動重試機制（Auto-Retry Mechanism）：在結果尚未準備好時，自動再次嘗試請求資料的流程
* 呼叫結果物件（Call Result Object）：前端儲存某通通話完整結果的狀態物件
* 狀態驅動 UI（State-driven UI）：依照 React 狀態變化自動更新畫面的設計方式
* 錯誤提示（Error Alert）：在畫面上用警示或彈窗呈現錯誤訊息的做法
* 語音提供者（Voice Provider）：像 11Labs 這類提供 TTS 語音服務的第三方平台
* 語音模型（Voice Model）：負責產生語音的特定模型版本設定
* 語音樣式 ID（Voice ID）：指定要使用哪一種聲音風格的識別字串
* 模型版本（Model Version）：同一服務下，不同世代或性能設定的模型編號
* 語音自然度（Speech Naturalness）：衡量語音聽起來像真人程度的品質指標
* 後端 webhook（Backend Webhook）：由外部服務主動回呼到你伺服器的通知端點
* 事件驅動整合（Event-driven Integration）：以事件（如通話結束）觸發後端邏輯的整合方式