學生在決定研究方向或尋找指導老師時，往往不知道「有哪些可能的研究領域」或「哪些老師在做什麼研究」。 傳統做法是逐一瀏覽各系所網站，費時且難以跨校比較。
研究領域地圖提供兩段式探索：先從宏觀主題縮小範圍，再深入了解具體老師與論文。 結合 Uedu 自有資料與 OpenAlex 全球學術資料庫，讓學生的視野不受限於單一平台。
統計所有 opt-in 教師的研究關鍵字，以標籤雲呈現。支援跨教師論文搜尋（標題與摘要），以及依主題列出所有相關教師。
| 功能 | 資料來源 | 說明 |
|---|---|---|
| 主題標籤雲 | research_profiles.research_keywords | 依教師人數排序，顯示收新生人數 |
| 論文搜尋 | research_publications | LIKE 比對標題與摘要 |
| 依主題找老師 | research_keywords + research_bio | 不限 5 位，不做評分排序 |
每位 opt-in 教師擁有公開檔案頁（/advisor/profile/
研究領域地圖（/advisor/map）整合主題標籤雲、論文搜尋（雙 tab）、老師清單三個區塊。
Uedu 認證老師並非自動納入，而需教師主動填寫研究檔案並設定 is_recruiting=1。這是整個系統最核心的倫理設計：
is_recruiting 改為 0 即從推薦池移除，歷史檔案仍保留但不對學生顯示is_recruiting=1 額外加 1 分教師可在個人研究檔案填入 ORCID 後，點擊「從 ORCID 同步論文」。系統在背景執行：
https://pub.orcid.org/v3.0/<orcid>/works 取得作品清單put-code 批次查詢）teachers_publications 表，以 put_code 為 primary key 去重
對 429 / 503 / 網路錯誤自動以指數退避重試 3 次（_orcid_get_with_retry）。ORCID 只提供 metadata（標題、作者、年份、DOI），若需全文摘要仍需由教師手動補充或從 DOI 後續解析。
教師可在檔案頁手動隱藏特定論文（POST /api/advisor/publications/<id>/toggle_hidden），或刪除（DELETE /api/advisor/publications/<id>）。隱藏的論文不會出現於公開檔案與推薦結果，但保留紀錄供教師日後還原。
每日自動為論文產生 embedding（text-embedding-3-small），以 k-means 聚類後由 LLM 命名群集。
| 步驟 | 技術 |
|---|---|
| 1. 論文 embedding | OpenAI text-embedding-3-small（1536 維） |
| 2. 教師向量 | 該教師所有論文 embedding 的 L2-normalized 平均 |
| 3. 聚類 | scikit-learn KMeans（k = max(2, min(8, N//3))） |
| 4. 命名 | GPT-4o-mini 依群集代表論文標題生成標籤與描述 |
目前 recommend_potential_advisors 採用關鍵字 LIKE 比對，設計理念是「可解釋、可稽核」：
| 步驟 | 說明 |
|---|---|
| 1. 解析學生興趣詞彙 | 由 LLM 從對話擷取關鍵字（例如「EEG」「學習分析」） |
| 2. 關鍵字命中計分 | 對 research_keywords、research_bio 以 LIKE 比對，每命中一個關鍵字加 1 分 |
| 3. 收新生加分 | is_recruiting=1 額外 +1 分 |
| 4. 取 Top 5 | 依分數排序，回傳至多 5 位老師 |
| 5. 附命中理由 | 每位老師附「為什麼推薦」：具體列出命中的關鍵字 |
AI 助教回覆推薦結果時，結尾必須加上：「這只是初步建議，請主動讀論文後寫信與老師討論」。此為倫理守則中硬性要求，避免學生把 AI 推薦當成教師認可，也鼓勵真正的學術對話而非機械式媒合。
Phase 2 規劃：改用論文 embedding 做語意檢索，解決 LIKE 無法處理同義詞（「深度學習」vs.「neural networks」）的問題。詳細設計見 .claude/logs/advisor-match-proposal.md。
當 Uedu 自有資料不足（例如目前 opt-in 教師尚少）時，系統同步查詢 OpenAlex 全球學術資料庫（收錄 2.4 億+ 論文），目前限定五個國家的機構作者。
| 國家 | ISO Code |
|---|---|
| 台灣 | tw |
| 新加坡 | sg |
| 日本 | jp |
| 韓國 | kr |
| 中國 | cn |
注意：台灣（Taiwan, tw）與中國（China, cn）為兩個獨立國家。
查詢結果快取 7 天（external_papers_cache 表），避免重複呼叫 API。
在研究領域地圖的標籤雲或語意群集中，找到感興趣的研究方向
點擊主題，展開所有相關教師，查看其關鍵字、論文數、是否收新生
點擊教師姓名，進入公開檔案頁，閱讀研究自介與完整論文列表（含摘要）
讀完 1-2 篇論文摘要後，寫信與老師討論，讓老師知道你已做過功課
學生也可以在 ClassroomGPT 或 Aida 優學伴中直接用自然語言探索：
| 學生問 | AI 呼叫的工具 |
|---|---|
| 「Uedu 上有哪些研究主題？」 | list_advisor_research_topics |
| 「有哪些做學習分析的老師？」 | find_advisors_by_topic → search_external_papers（fallback） |
| 「最近有人做 EEG 教學的論文嗎？」 | search_advisor_papers → search_external_papers（fallback） |
| 「張家凱做哪些研究？」 | list_uedu_team_papers |
| 「想找專題指導老師」 | recommend_potential_advisors |
AI 會先搜 Uedu 內部資料，不足時自動查 OpenAlex 外部資料，並在回應中明確區分兩類來源。
| Endpoint | 說明 | 需登入 |
|---|---|---|
| GET /api/advisor/topics | 研究主題清單（依教師人數排序） | 否 |
| GET /api/advisor/search_papers?q=... | 搜尋 Uedu 認證老師論文 | 否 |
| GET /api/advisor/by_topic?topic=... | 依主題找老師 | 否 |
| GET /api/advisor/external_search?q=... | 搜尋 OpenAlex 外部論文 | 否 |
| GET /api/advisor/public_profile/{id} | 教師公開研究檔案 | 否 |
| GET /api/advisor/clusters | 語意研究群集清單 | 否 |
| GET /api/advisor/cluster/{id}/advisors | 群集底下的老師 | 否 |