feat(backend): 完成模塊一投資人格分析 (Upload API + MBTI Profiler)

[meatmeateater]

📘 模塊一：投資人格分析 (Investment Profiler) 整合指南

檔案說明：本文檔旨在協助前端開發者與團隊成員理解如何對接「投資人格分析」模塊。
功能概述：本模塊包含 交易文件上傳、隨機問卷生成 與 雙重人格分析 (MBTI) 功能。

---

1. 🚀 前端調用與整合流程 (Frontend Integration)

整個業務流程由兩個部分組成：文件上傳 (API) 與 Agent 對話 (Tool Calling)。

步驟 A：交易紀錄上傳 (Upload API)

前端需提供一個上傳按鈕，將用戶的 .csv 或 .xlsx 文件傳送到後端，並獲取後端回傳的絕對路徑。

• Endpoint: POST /api/upload
• Content-Type: multipart/form-data
• 參數 (Body):
  • file: (Binary) 用戶選擇的檔案。

前端請求範例 (JS/TS)

const formData = new FormData();
formData.append("file", fileInput.files[0]);

try {
  const response = await fetch("http://localhost:8000/api/upload", {
    method: "POST",
    body: formData,
  });

  const data = await response.json();
  
  // ⚠️ 關鍵：請保存 data.file_path，這將用於後續 Agent 分析
  console.log("File Path:", data.file_path); 
  
} catch (error) {
  console.error("Upload failed", error);
}

成功回應 (Response)

{
 "status": "success",
 "file_path": "D:\\projects\\spark-ai-demo\\apps\\server\\uploads\\trade_history.csv",
 "filename": "trade_history.csv",
 "message": "上傳成功！..."
}

---

步驟 B：Agent 交互流程 (Agent Interaction)

本模塊透過 Agent 自動調用工具來完成，前端只需負責渲染 UI 與傳遞訊息。

1. 觸發問卷 (Get Questions)

當用戶說：「幫我分析投資人格」時，Agent 會調用工具 generate_investment_quiz。

• Agent 行為: 返回 8 道題目 (JSON 格式)。
• 前端任務: 監聽 Tool Output，將題目渲染為問卷 UI。
• 題目結構範例:

[
 {
   "id": "EI_01",
   "dimension": "EI",
   "question": "在交易群組中，你的活躍程度是？",
   "options": {
     "A": "非常活躍，喜歡分享觀點",
     "B": "潛水居多，默默觀察"
   }
 },
 ... (共8題)
]

2. 提交分析 (Submit Analysis)

當用戶填完問卷並上傳文件後，前端需將資訊整理成 Prompt 發送給 Agent。

• 前端發送的 Prompt 範本:

  「我已完成問卷與上傳。
  交易文件路徑：{file_path} (來自步驟 A 的回應)
  問卷回答數據：{JSON.stringify(user_answers)}」

• 回答數據格式 (user_answers):

{
 "EI_01": "A",
 "SN_02": "B",
 "TF_01": "A"
 // 格式支援 "A" 或 "A: 選項文字"
}

• Agent 行為: 自動調用 analyze_user_profile 工具，進行運算並輸出最終 MBTI 分析報告。

---

2. 📝 代碼變更履歷 (Changelog)

為了實現此功能，我們在後端 (apps/server) 進行了以下修改與新增：

🟢 新增/修改的核心檔案

檔案路徑	類型	作用說明
apps/server/main.py	修改	新增 /api/upload 接口。負責將前端上傳的交易文件儲存至 uploads/ 目錄，並回傳絕對路徑供 Python Tool 讀取。
.../skills/investment_profiler/tools.py	新增	定義 Agent 工具： 1. generate_investment_quiz: 隨機抽取 8 題問卷。 2. analyze_user_profile: 接收路徑與回答，執行核心分析。
.../skills/investment_profiler/core/performance.py	新增	硬指標運算引擎。基於 QuantStats 與 Pandas，計算夏普率、回撤等數據。支援 Excel 與多種 CSV 格式 (含雜訊 Header)。
.../skills/investment_profiler/core/questionnaire.py	新增	軟指標計分引擎。負責解析用戶的 A/B 回答，計算 MBTI 四個維度的得分並生成自述報告。
.../skills/investment_profiler/data/question_bank.py	新增	題庫資料。包含 16 道經過設計的 MBTI 投資心理題，資料結構已清洗 (移除選項中的暗示性標籤)。

⚙️ 設定配置變更

檔案路徑	說明
.../skills/investment_profiler/__init__.py	導出 tools 列表，使系統能識別新工具。
.../skills/registry.py	將 investment_profiler 註冊到全局 SKILL_REGISTRY。

---

3. 💡 補充說明 (Technical Notes)

1. 題目隨機性機制

• 題庫總共有 16 題。
• 每次調用 generate_investment_quiz，後端會從每個維度 (EI / SN / TF / JP) 隨機抽取 2 題。
• 前端獲得的永遠是 8 題 的隨機題目，無需處理隨機邏輯。

2. 交易文件兼容性

目前的 PerformanceEngine 已針對常見交易所格式優化：

• ✅ 標準 CSV/Excel: 第一行是標題。
• ✅ 交易所流水單: (如 AssetChangeDetails...) 能自動識別 UID: 等雜訊並跳過前幾行。
• ✅ 必要欄位: 需包含「時間 (Time/Date)」與「損益 (Profit/Change/Amount)」。

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spark-ai-demo-web	Error		Jan 30, 2026 2:46pm