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)
- 分析風險指標與績效(夏普比率、索提諾比率、最大回撤等)
- 透過 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:1 處,用於 Metrics 介面
已知錯誤
- Supabase 上傳錯誤:大型上傳時偶發 500 錯誤
- 已在提交 9fb7fdb 中增強錯誤處理
- 檢查上傳 hook 中的錯誤處理
- 確認免費方案未超過資料列限制
近期新增功能
- 索提諾比率計算(提交 258ba3a、9f25040)
- 位置:在 PortfolioSection.tsx 中內聯實作(第 133-158 行)
- 無風險利率輸入狀態,使用者可指定無風險利率
- 使用 sqrt(365) 因子計算年化下行偏離度
- 修正變異數計算(除以總收益率,而非僅負值)
- 顯示於投資組合統計區域(第 535 行)
- 注意:不在 dataUtils.ts 中 - 因投資組合層級上下文保留在元件內
- 日期範圍篩選(提交 258ba3a)
- 按開始/結束日期篩選投資組合資料
- 在 usePortfolio hook 中實作
- 進階多欄排序(useSorting hook)
- 依優先級對多個欄位排序
- 每欄自訂比較邏輯
架構約束
- 元件限制:每個元件最多 200 行(目前有 3 個元件違規)
- Hook 模式:自訂 Hook 置於
/src/hooks/ - 工具模式:純函數置於
/src/utils/ - 型別安全:嚴格 TypeScript,不使用
any型別(目前有 15 處技術債務違規) - 狀態管理:僅使用純 React Hook - 不使用 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:僅色彩權杖 — CSS 變數在
src/index.css中,未安裝實際的 shadcn 元件。日後可透過npx shadcn@latest add button等指令新增 - Git 工作流程:功能分支 →
git checkout -b feature/name→ 常規提交(feat:、fix:、chore:)→ PR 至 main - 社群品牌:5minfutures.com 交易社群;資產中的 Skool 標誌;內嵌 GoHighLevel 表單
遷移上下文
從舊應用程式遷移 40 項功能(已完成 90%)。詳細資訊請參閱 migration-tracker 技能。