Financial Data (金融数据处理)

💰 核心理念: 金融数据是投资决策的基础，必须确保数据准确性、完整性和一致性。垃圾进，垃圾出。

🔴 第一原则：数据验证优先

❌ 错误做法: 直接导入数据，假设数据正确
✅ 正确做法: 导入 → 验证 → 清洗 → 再验证 → 存储

❌ 错误做法: "这是券商数据，应该没问题"
✅ 正确做法: 任何外部数据都要经过完整验证流程

When to Use This Skill

使用此技能当你需要：

• 从 IBKR、Gmail、Google Drive 导入交易数据
• 处理持仓快照数据
• 计算风险指标（VaR、回撤、夏普比率等）
• 数据清洗和格式转换
• 验证数据完整性和一致性
• 处理多币种数据转换

Not For / Boundaries

此技能不适用于：

• 实时行情数据获取（参考 api-integration skill）
• AI 分析和建议生成（参考 agent 相关代码）
• 数据库 schema 变更（参考 database-migration skill）

---

Quick Reference

🎯 数据处理工作流

数据源 → 获取原始数据 → 格式验证 → 数据清洗 → 业务验证 → 存储 → 确认
   ↓                                                    ↓
 IBKR/Gmail/Drive                                    失败 → 记录错误 → 人工处理

📋 数据导入前必问清单

问题	目的
1. 数据源是什么？	确定解析格式（XML/CSV/JSON）
2. 数据时间范围？	避免重复导入或遗漏
3. 币种是什么？	确定汇率转换需求
4. 有没有已存在的数据？	决定是覆盖还是增量更新
5. 数据量有多大？	评估是否需要分批处理

✅ 数据质量检查清单

检查项	说明	严重程度
必填字段完整	ticker, date, quantity 等	🔴 阻断
数值范围合理	价格 > 0, 数量 ≠ 0	🔴 阻断
日期格式正确	YYYY-MM-DD	🔴 阻断
币种有效	USD/HKD/CNY	🟡 警告
无重复记录	同一交易不重复	🟡 警告
数据连续性	无缺失日期	🟢 提示

---

数据源集成指南

1. IBKR Flex Query 导入

IBKR 是主要数据源，通过 Flex Query API 获取数据。

配置要求：

// 环境变量
VITE_CORS_PROXY_URL=https://your-proxy.workers.dev

// Flex Query 配置
const IB_TOKEN = "your_token";
const IB_QUERY_ID = "your_query_id";

数据获取流程：

1. 请求生成报表 (SendRequest)
2. 等待报表生成 (轮询 GetStatement)
3. 解析 XML 响应
4. 提取各类数据：
   - EquitySummaryByReportDateInBase → 账户摘要
   - OpenPosition → 持仓数据
   - Trade → 交易记录
   - ChangeInNAV → 净值变化
   - CashReportCurrency → 多币种现金

关键代码位置：

• client/src/services/ibkrFlexQuery.ts - IBKR 数据获取
• client/src/services/ibkrData.ts - IBKR 数据处理

2. Gmail 导入（交易确认邮件）

从券商确认邮件中提取交易数据。

支持的邮件格式：

• IBKR 交易确认
• 富途牛牛交易确认
• 老虎证券交易确认

解析流程：

1. 通过 Gmail API 获取邮件
2. 解析邮件正文（HTML/纯文本）
3. 使用正则表达式提取交易信息
4. 验证并格式化数据

3. Google Drive 导入（CSV/Excel）

从 Google Drive 导入历史数据文件。

支持的文件格式：

• CSV（推荐）
• Excel (.xlsx)

CSV 格式要求：

date,ticker,action,quantity,price,fee,currency,notes
2025-01-15,AAPL,BUY,100,185.50,1.00,USD,加仓
2025-01-16,AAPL,SELL,50,188.00,1.00,USD,止盈

---

数据验证规则

交易记录验证

// 必填字段验证
const requiredFields = ['date', 'ticker', 'action', 'quantity', 'price'];

// 数值范围验证
const validations = {
  price: (v: number) => v > 0,
  quantity: (v: number) => v !== 0,
  fee: (v: number) => v >= 0,
};

// 枚举值验证
const validActions = ['BUY', 'SELL', 'SHORT', 'COVER', 'DEPOSIT', 'WITHDRAW'];
const validCurrencies = ['USD', 'HKD', 'CNY'];
const validMarkets = ['US', 'HK', 'CN'];

持仓数据验证

// 持仓一致性检查
function validatePositions(positions: Position[], transactions: Transaction[]) {
  // 1. 计算交易累计数量
  const calculatedQty = calculateFromTransactions(transactions);
  
  // 2. 与持仓数量对比
  for (const pos of positions) {
    const expected = calculatedQty[pos.ticker] || 0;
    if (pos.quantity !== expected) {
      console.warn(`持仓不一致: ${pos.ticker} 实际=${pos.quantity} 计算=${expected}`);
    }
  }
}

净值数据验证

// 净值连续性检查
function validateNetWorthHistory(records: NetWorthRecord[]) {
  const sorted = records.sort((a, b) => a.date.localeCompare(b.date));
  
  for (let i = 1; i < sorted.length; i++) {
    const prev = sorted[i - 1];
    const curr = sorted[i];
    
    // 检查日期连续性（工作日）
    const daysDiff = getBusinessDaysDiff(prev.date, curr.date);
    if (daysDiff > 1) {
      console.warn(`净值数据缺失: ${prev.date} 到 ${curr.date}`);
    }
    
    // 检查异常波动（单日变化超过 10%）
    const changePercent = (curr.netWorth - prev.netWorth) / prev.netWorth * 100;
    if (Math.abs(changePercent) > 10) {
      console.warn(`异常波动: ${curr.date} 变化 ${changePercent.toFixed(2)}%`);
    }
  }
}

---

数据清洗最佳实践

1. 股票代码标准化

// 统一股票代码格式
function normalizeSymbol(symbol: string, market: Market): string {
  switch (market) {
    case 'HK':
      // 港股：补齐到 5 位数字
      return symbol.replace(/^0+/, '').padStart(5, '0');
    case 'CN':
      // A股：保持 6 位数字
      return symbol.padStart(6, '0');
    case 'US':
    default:
      // 美股：大写字母
      return symbol.toUpperCase().replace(/[^A-Z]/g, '');
  }
}

2. 日期格式标准化

// 统一日期格式为 YYYY-MM-DD
function normalizeDate(dateStr: string): string {
  // 处理 IBKR 格式: 20250115
  if (/^\d{8}$/.test(dateStr)) {
    return `${dateStr.slice(0, 4)}-${dateStr.slice(4, 6)}-${dateStr.slice(6, 8)}`;
  }
  
  // 处理 MM/DD/YYYY 格式
  if (/^\d{1,2}\/\d{1,2}\/\d{4}$/.test(dateStr)) {
    const [m, d, y] = dateStr.split('/');
    return `${y}-${m.padStart(2, '0')}-${d.padStart(2, '0')}`;
  }
  
  // 已经是标准格式
  return dateStr;
}

3. 金额和汇率处理

// 汇率常量（应从实时数据获取）
const EXCHANGE_RATES = {
  USD_CNY: 7.04,
  HKD_CNY: 0.93,
};

// 转换为 CNY
function toCNY(amount: number, currency: Currency): number {
  switch (currency) {
    case 'USD':
      return amount * EXCHANGE_RATES.USD_CNY;
    case 'HKD':
      return amount * EXCHANGE_RATES.HKD_CNY;
    case 'CNY':
    default:
      return amount;
  }
}

4. 重复数据处理

// 交易记录去重
function deduplicateTransactions(transactions: Transaction[]): Transaction[] {
  const seen = new Set<string>();
  
  return transactions.filter(tx => {
    // 生成唯一键：日期 + 股票 + 动作 + 数量 + 价格
    const key = `${tx.date}_${tx.ticker}_${tx.action}_${tx.quantity}_${tx.price}`;
    
    if (seen.has(key)) {
      console.warn(`发现重复交易: ${key}`);
      return false;
    }
    
    seen.add(key);
    return true;
  });
}

---

风险指标计算

核心风险指标

指标	公式	说明
最大回撤	(峰值 - 谷值) / 峰值	历史最大亏损幅度
夏普比率	(收益率 - 无风险利率) / 波动率	风险调整后收益
VaR (95%)	历史分位数法	95% 置信度下的最大损失
胜率	盈利交易数 / 总交易数	交易成功率
盈亏比	平均盈利 / 平均亏损	风险回报比

计算示例

// 计算最大回撤
function calculateMaxDrawdown(netWorthHistory: number[]): {
  maxDrawdown: number;
  maxDrawdownPercent: number;
  peakDate: string;
  troughDate: string;
} {
  let peak = netWorthHistory[0];
  let maxDrawdown = 0;
  let maxDrawdownPercent = 0;
  
  for (const value of netWorthHistory) {
    if (value > peak) {
      peak = value;
    }
    
    const drawdown = peak - value;
    const drawdownPercent = drawdown / peak;
    
    if (drawdownPercent > maxDrawdownPercent) {
      maxDrawdown = drawdown;
      maxDrawdownPercent = drawdownPercent;
    }
  }
  
  return { maxDrawdown, maxDrawdownPercent, peakDate: '', troughDate: '' };
}

// 计算夏普比率
function calculateSharpeRatio(
  returns: number[],
  riskFreeRate: number = 0.02
): number {
  const avgReturn = returns.reduce((a, b) => a + b, 0) / returns.length;
  const variance = returns.reduce((sum, r) => sum + Math.pow(r - avgReturn, 2), 0) / returns.length;
  const stdDev = Math.sqrt(variance);
  
  // 年化
  const annualizedReturn = avgReturn * 252;
  const annualizedStdDev = stdDev * Math.sqrt(252);
  
  return (annualizedReturn - riskFreeRate) / annualizedStdDev;
}

---

数据库表结构

详细的数据库 schema 定义请参考：

• references/data-schemas.md - 完整的数据结构定义

核心表概览

表名	用途	主键
transactions	交易记录	uuid
stock_positions	股票持仓快照	bigserial
option_positions	期权持仓快照	bigserial
dashboard_snapshots	每日驾驶舱快照	bigserial
risk_metrics	风险指标	bigserial
watchlist	观察列表	uuid

---

Examples

Example 1: 从 IBKR 导入数据

Input: "需要从 IBKR 导入最新的交易和持仓数据"

Steps:

1. 调用 fetchIBKRFlexQuery() 获取数据
2. 验证返回的数据完整性
3. 调用 syncIBKRToSupabase() 同步到数据库
4. 验证同步结果

Expected Output:

import { syncIBKRToSupabase } from '@/services/ibkrFlexQuery';

const result = await syncIBKRToSupabase(true, (stage, progress) => {
  console.log(`[${progress}%] ${stage}`);
});

if (result.success) {
  console.log('同步成功:', result.data);
} else {
  console.error('同步失败:', result.message);
}

Example 2: 验证持仓数据一致性

Input: "检查持仓数据是否与交易记录一致"

Steps:

1. 获取所有交易记录
2. 计算每个股票的累计持仓
3. 与当前持仓对比
4. 输出差异报告

Expected Output:

// 获取数据
const transactions = await getTransactions();
const positions = await getPositions();

// 计算预期持仓
const expectedPositions = calculatePositionsFromTransactions(transactions);

// 对比
for (const pos of positions) {
  const expected = expectedPositions[pos.ticker] || 0;
  if (pos.quantity !== expected) {
    console.warn(`❌ ${pos.ticker}: 实际=${pos.quantity}, 预期=${expected}`);
  } else {
    console.log(`✅ ${pos.ticker}: ${pos.quantity}`);
  }
}

Example 3: 计算风险指标

Input: "计算最近 30 天的风险指标"

Steps:

1. 获取净值历史数据
2. 计算日收益率
3. 计算各项风险指标
4. 存储到 risk_metrics 表

Expected Output:

// 获取净值数据
const netWorthHistory = await getNetWorthHistory(30);

// 计算日收益率
const returns = calculateDailyReturns(netWorthHistory);

// 计算风险指标
const metrics = {
  maxDrawdown: calculateMaxDrawdown(netWorthHistory),
  sharpeRatio: calculateSharpeRatio(returns),
  var95: calculateVaR(returns, 0.95),
  volatility: calculateVolatility(returns),
};

// 存储
await saveRiskMetrics(metrics);

---

常见问题处理

Q1: IBKR 数据获取失败

可能原因：

1. Token 过期
2. CORS 代理不可用
3. 网络问题

解决方案：

// 1. 检查 Token 有效性
// 登录 IBKR 账户管理 → 报表 → Flex Queries → 检查 Token

// 2. 尝试备用代理
const FALLBACK_PROXIES = [
  'https://corsproxy.io/?',
  'https://api.allorigins.win/raw?url=',
];

// 3. 增加重试次数和超时时间

Q2: 数据重复导入

解决方案：

// 使用 upsert 而非 insert
const { error } = await supabase
  .from('transactions')
  .upsert(transactions, {
    onConflict: 'date,ticker,action,quantity,price',
    ignoreDuplicates: true
  });

Q3: 汇率数据不准确

解决方案：

// 1. 使用实时汇率 API
const rates = await fetchExchangeRates();

// 2. 或使用 IBKR 提供的汇率
const fxRate = trade.fxRateToBase;

---

References

• references/data-schemas.md: 完整的数据结构定义
• references/validation-rules.md: 数据验证规则详解
• references/import-templates.md: 数据导入模板

---

Maintenance

• Sources: 项目实际代码, IBKR API 文档, 金融数据处理最佳实践
• Last Updated: 2025-01-01
• Known Limits:
  • IBKR Flex Query 有请求频率限制
  • 历史数据导入需要手动触发
  • 汇率数据可能有延迟