Portfolio Buddy 2 - 项目上下文
技术栈
- 前端: React 19, TypeScript, Vite
- UI: Tailwind CSS, shadcn/ui (仅颜色系统)
- 图表: Chart.js, react-chartjs-2, chartjs 插件 (zoom, annotation, date adapter)
- 状态管理: 纯 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: Metrics 接口中出现 1 次
已知错误
- Supabase 上传错误: 大文件上传时偶发 500 错误
- 在提交 9fb7fdb 中增强了错误处理
- 检查上传钩子中的错误处理
- 验证免费套餐的行限制是否未超出
近期新增功能
- 索提诺比率计算 (提交 258ba3a, 9f25040)
- 位置: 在 PortfolioSection.tsx 中内联实现 (第 133-158 行)
- 用户指定的无风险利率输入状态
- 使用 sqrt(365) 因子计算年化下行偏差
- 修正了方差计算 (除以总回报数,而不仅仅是负回报)
- 显示在投资组合统计部分 (第 535 行)
- 注意: 不在 dataUtils.ts 中 - 由于投资组合级别的上下文而保留在组件中
- 日期范围过滤 (提交 258ba3a)
- 按开始/结束日期过滤投资组合数据
- 在 usePortfolio 钩子中实现
- 高级多列排序 (useSorting 钩子)
- 按多个列排序并设置优先级
- 每列的自定义比较逻辑
架构约束
- 组件限制: 每个组件最多 200 行 (当前有 3 个组件违反)
- 钩子模式: 自定义钩子位于
/src/hooks/ - 工具模式: 纯函数位于
/src/utils/ - 类型安全: 严格 TypeScript,无
any类型 (技术债务中存在 15 处违规) - 状态管理: 仅使用纯 React 钩子 - 无 Zustand 或 TanStack Query
关键组件结构
src/
├── components/
│ ├── AnalyticsControls.tsx (切换 Metrics/Portfolio/Correlation 视图)
│ ├── ContractInput.tsx (合约乘数输入)
│ ├── CorrelationHeatmap.tsx (相关性热力图)
│ ├── CorrelationSection.tsx (相关性分析包装器)
│ ├── CustomTooltip.tsx (图表提示框)
│ ├── ErrorList.tsx (错误显示)
│ ├── Header.tsx (应用头部)
│ ├── MasterContractControl.tsx (将合约值应用于所有)
│ ├── MetricsTable.tsx (指标显示与选择)
│ ├── PortfolioSection.tsx (投资组合图表与分析 - 591 行!)
│ ├── SessionComplete.tsx (完成界面)
│ ├── 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:) → 向 main 发起 PR - 社区品牌: 5minfutures.com 交易社区;资产中的 Skool 徽标;嵌入的 GoHighLevel 表单
迁移上下文
从旧应用迁移 40 个功能 (已完成 90%)。详情请参考 migration-tracker 技能。