Portfolio Buddy 2 - 專案上下文
技術棧
- 前端:React 19、TypeScript、Vite
- UI:Tailwind CSS、shadcn/ui(僅使用色彩系統)
- 圖表:Chart.js、react-chartjs-2、chartjs 插件(縮放、註釋、日期適配器)
- 狀態管理:純 React(useState、useMemo、useCallback)
- 資料工具:date-fns 用於日期操作
- 後端:Supabase(PostgreSQL)
- 部署:Cloudflare Pages
專案目的
專為投資人與期貨交易者打造的投資組合分析工具,功能包括:
- 比較交易策略與基準資產(SPY、GLD)
- 計算資產間的相關矩陣(Spearman 與 Pearson)
- 分析風險指標與績效(夏普比率、Sortino 比率、最大回撤等)
- 透過 CSV 上傳交易資料並視覺化結果
- 應用合約乘數調整期貨交易的指標
- 按日期範圍篩選資料以進行特定時期分析
已知問題與技術債務
當前技術債務
-
未使用的相依套件:已安裝 Recharts(11.5KB)但從未匯入
- 應從 package.json 中移除
- 目前使用 Chart.js 替代
-
元件過大:違反 200 行標準
- PortfolioSection.tsx(591 行)→ 需要重構為子元件
- App.tsx(351 行)→ 將區塊抽出為元件
- MetricsTable.tsx(242 行)→ 已改善但仍超過限制
-
TypeScript 違規:15 處使用
any型別- usePortfolio.ts:交易/指標型別中有 11 處
- useMetrics.ts:排序比較中有 4 處
- dataUtils.ts:Metrics 介面中有 1 處
已知錯誤
- Supabase 上傳錯誤:大檔案上傳時偶發 500 錯誤
- 已在 commit 9fb7fdb 中加強錯誤處理
- 檢查上傳 hooks 中的錯誤處理邏輯
- 確認免費方案的行數限制是否未超過
近期新增功能
- Sortino 比率計算(commits 258ba3a, 9f25040)
- 位置:直接在 PortfolioSection.tsx 中實作(第 133-158 行)
- 無風險利率輸入狀態,供使用者指定無風險利率
- 使用 sqrt(365) 因子計算年化下行風險
- 修正變異數計算(除以總報酬數,而非僅負報酬)
- 顯示於投資組合統計區塊(第 535 行)
- 注意:不在 dataUtils.ts 中 - 因需投資組合層級上下文而保留在元件中
- 日期範圍篩選(commit 258ba3a)
- 依據開始/結束日期篩選投資組合資料
- 在 usePortfolio hook 中實作
- 進階多欄排序(useSorting hook)
- 依據優先級對多個欄位排序
- 每個欄位提供自訂比較邏輯
架構約束
- 元件限制:每個元件最多 200 行(目前有 3 個元件違規)
- Hook 模式:自訂 hooks 放在
/src/hooks/ - 工具函式模式:純函式放在
/src/utils/ - 型別安全:嚴格的 TypeScript,禁止使用
any型別(目前有 15 處違規視為技術債務) - 狀態管理:僅使用純 React hooks - 不使用 Zustand 或 TanStack Query
主要元件結構
src/
├── components/
│ ├── AnalyticsControls.tsx (切換指標/投資組合/相關性檢視)
│ ├── ContractInput.tsx (合約乘數輸入)
│ ├── CorrelationHeatmap.tsx (相關性熱力圖視覺化)
│ ├── CorrelationSection.tsx (相關性分析包裝器)
│ ├── CustomTooltip.tsx (圖表工具提示)
│ ├── ErrorList.tsx (錯誤顯示)
│ ├── Header.tsx (應用程式標頭)
│ ├── MasterContractControl.tsx (對所有項目套用合約價值)
│ ├── MetricsTable.tsx (指標顯示與選擇)
│ ├── PortfolioSection.tsx (投資組合圖表與分析 - 591 行!)
│ ├── SessionComplete.tsx (完成 UI)
│ ├── SortableHeader.tsx (表格標頭含排序指示器)
│ ├── UploadedFilesList.tsx (已上傳檔案清單)
│ └── UploadSection.tsx (檔案上傳至 Supabase)
├── hooks/
│ ├── useContractMultipliers.ts (管理合約乘數)
│ ├── useMetrics.ts (計算交易指標)
│ ├── usePortfolio.ts (投資組合資料與日期篩選)
│ └── useSorting.ts (進階多欄排序)
└── utils/
└── dataUtils.ts (指標計算、CSV 解析、相關性分析)
關鍵慣例
- 路徑別名:
@/對應src/— 所有內部匯入請使用此別名 - shadcn-ui:僅使用色彩 token — CSS 變數定義在
src/index.css,未實際安裝 shadcn 元件。可透過npx shadcn@latest add button等方式後續新增 - Git 工作流程:功能分支 →
git checkout -b feature/name→ 常規提交(feat:、fix:、chore:)→ 向 main 發送 PR - 社群品牌:5minfutures.com 交易社群;assets 中的 Skool 標誌;嵌入的 GoHighLevel 表單
遷移上下文
從舊應用程式遷移 40 個功能(已完成 90%)。詳細資訊請參閱 migration-tracker 技能。