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)
- 分析风险指标和绩效(Sharpe, 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 错误
- 在提交 9fb7fdb 中增强了错误处理
- 检查上传钩子中的错误处理
- 验证免费层的行数限制是否未超出
最近添加的功能
- Sortino 比率计算(提交 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 (切换指标/投资组合/相关视图)
│ ├── 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 技能。