AlphaFuturesProMax/docs/06-前端组件文档.md

# 智能期货期权分析系统 - 前端组件文档

## 组件总览

| 组件名称 | 文件路径 | 功能描述 | 复杂度 |
|---------|---------|---------|--------|
| Navbar | `components/Navbar.tsx` | 顶部导航栏 | ⭐⭐ |
| MarketOverview | `components/MarketOverview.tsx` | 市场概览仪表盘 | ⭐⭐⭐ |
| HotEvents | `components/HotEvents.tsx` | 热点事件分析 | ⭐⭐⭐ |
| ProductCard | `components/ProductCard.tsx` | 品种卡片 | ⭐⭐ |
| ProductDetail | `components/ProductDetail.tsx` | 品种详情页 | ⭐⭐⭐⭐ |
| KLineChart | `components/KLineChart.tsx` | K线图表 | ⭐⭐⭐⭐⭐ |
| RiskAlerts | `components/RiskAlerts.tsx` | 风险提醒 | ⭐⭐ |

---

## Navbar 导航栏

### Props

```typescript
interface NavbarProps {
  activeTab: string;      // 当前激活的标签
  onTabChange: (tab: string) => void;  // 标签切换回调
}
```

### 功能特性

- 固定顶部导航
- 响应式设计（桌面/移动端）
- 实时时钟显示
- 滚动时添加阴影效果

### 使用示例

```tsx
import { Navbar } from '@/components/Navbar';

function App() {
  const [activeTab, setActiveTab] = useState('overview');
  
  return (
    <Navbar 
      activeTab={activeTab} 
      onTabChange={setActiveTab} 
    />
  );
}
```

---

## MarketOverview 市场概览

### Props

```typescript
interface MarketOverviewProps {
  data: MarketOverview;
}

interface MarketOverview {
  heatIndex: number;        // 市场热度指数
  heatChange: number;       // 热度变化
  upCount: number;          // 上涨品种数
  downCount: number;        // 下跌品种数
  capitalFlow: number;      // 资金流向
  volatilityIndex: number;  // 波动率指数
  volatilityChange: number; // 波动率变化
}
```

### 功能特性

- 数字滚动动画
- 迷你趋势图
- 涨跌颜色区分
- 卡片悬停效果

### 使用示例

```tsx
import { MarketOverviewPanel } from '@/components/MarketOverview';

const data = {
  heatIndex: 78.5,
  heatChange: 5.2,
  upCount: 156,
  downCount: 89,
  capitalFlow: 28.5,
  volatilityIndex: 23.8,
  volatilityChange: -1.2,
};

<MarketOverviewPanel data={data} />
```

---

## HotEvents 热点事件

### Props

```typescript
interface HotEventsProps {
  events: HotEvent[];
}

interface HotEvent {
  id: string;
  title: string;
  time: string;
  summary: string;
  affectedProducts: string[];
  impact: 'bullish' | 'bearish' | 'neutral';
  impactLevel: 1 | 2 | 3 | 4 | 5;
  analysis: string;
  risks: string[];
}
```

### 功能特性

- 事件列表与详情联动
- 影响等级星级显示
- 利多/利空标签
- 响应式布局

### 使用示例

```tsx
import { HotEventsPanel } from '@/components/HotEvents';

const events = [
  {
    id: '1',
    title: '地缘政治风险升级',
    time: '2025-03-02',
    summary: '美以袭伊朗，海上油阀被关',
    affectedProducts: ['原油', '黄金'],
    impact: 'bullish',
    impactLevel: 5,
    analysis: '地缘政治风险急剧升温...',
    risks: ['冲突升级', '供应中断'],
  },
];

<HotEventsPanel events={events} />
```

---

## ProductCard 品种卡片

### Props

```typescript
interface ProductCardProps {
  product: FuturesProduct;
  onClick?: () => void;
}

interface FuturesProduct {
  id: string;
  name: string;
  code: string;
  category: string;
  price: number;
  change: number;
  changePercent: number;
  trendScore: number;
  successRate: number;
  cycles: {
    m5: TrendDirection;
    m15: TrendDirection;
    m30: TrendDirection;
    m60: TrendDirection;
  };
  keyLevels: {
    resistance: number[];
    support: number[];
  };
  recommendation: 'long' | 'short' | 'wait';
  recommendationReason: string;
}
```

### 功能特性

- 多周期趋势标签
- 成功率进度条
- 关键点位显示
- 悬停放大效果

### 使用示例

```tsx
import { ProductCard } from '@/components/ProductCard';

const product = {
  id: '1',
  name: '原油',
  code: 'SC',
  price: 528.6,
  change: 12.1,
  changePercent: 2.35,
  // ... 其他字段
};

<ProductCard 
  product={product} 
  onClick={() => console.log('clicked')} 
/>
```

---

## ProductDetail 品种详情

### Props

```typescript
interface ProductDetailProps {
  product: FuturesProduct;
  onBack: () => void;
}
```

### 功能特性

- 周期切换（5/15/30/60分钟）
- K线图展示
- 技术指标汇总
- 交易建议
- 多周期一致性分析

### 子组件

#### PeriodButton

周期切换按钮

```typescript
interface PeriodButtonProps {
  label: string;
  isActive: boolean;
  onClick: () => void;
}
```

#### IndicatorCard

指标卡片

```typescript
interface IndicatorCardProps {
  title: string;
  value: string;
  status: string;
  signal?: 'positive' | 'negative' | 'neutral';
}
```

#### KeyLevelRow

关键点位行

```typescript
interface KeyLevelRowProps {
  label: string;
  value: number;
  type: 'resistance' | 'support';
}
```

### 使用示例

```tsx
import { ProductDetail } from '@/components/ProductDetail';

<ProductDetail 
  product={product} 
  onBack={() => setSelectedProduct(null)} 
/>
```

---

## KLineChart K线图表

### Props

```typescript
interface KLineChartProps {
  klineData: KLineData[];      // K线数据
  macdData: MACDData[];        // MACD数据
  resistance: number[];        // 压力位数组
  support: number[];           // 支撑位数组
  height?: number;             // 图表高度，默认500
}

interface KLineData {
  time: string;
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
}

interface MACDData {
  time: string;
  dif: number;
  dea: number;
  macd: number;
}
```

### 功能特性

- 三图联动（K线+成交量+MACD）
- 鼠标悬停十字光标
- 压力位/支撑位标注
- 移动平均线（MA5/MA10/MA20）
- 数据缩放与平移
- 自定义Tooltip

### ECharts配置

图表使用ECharts实现，主要配置包括：

```typescript
const option: echarts.EChartsOption = {
  // 三个grid分别对应K线、成交量、MACD
  grid: [
    { top: '5%', height: '50%' },    // K线
    { top: '58%', height: '15%' },   // 成交量
    { top: '76%', height: '18%' },   // MACD
  ],
  
  // 三个x轴联动
  xAxis: [
    { type: 'category', gridIndex: 0 },
    { type: 'category', gridIndex: 1 },
    { type: 'category', gridIndex: 2 },
  ],
  
  // 三个y轴
  yAxis: [
    { scale: true, gridIndex: 0 },
    { scale: true, gridIndex: 1 },
    { scale: true, gridIndex: 2 },
  ],
  
  // 数据系列
  series: [
    { type: 'candlestick', name: 'K线' },
    { type: 'line', name: 'MA5' },
    { type: 'line', name: 'MA10' },
    { type: 'line', name: 'MA20' },
    { type: 'bar', name: '成交量' },
    { type: 'bar', name: 'MACD' },
    { type: 'line', name: 'DIF' },
    { type: 'line', name: 'DEA' },
  ],
};
```

### 使用示例

```tsx
import { KLineChart } from '@/components/KLineChart';

const klineData = [
  { time: '2025-03-03T10:00:00Z', open: 525, high: 528, low: 524, close: 527, volume: 12580 },
  // ... 更多数据
];

const macdData = [
  { time: '2025-03-03T10:00:00Z', dif: 0.52, dea: 0.41, macd: 0.22 },
  // ... 更多数据
];

<KLineChart
  klineData={klineData}
  macdData={macdData}
  resistance={[535, 542]}
  support={[518, 510]}
  height={500}
/>
```

---

## RiskAlerts 风险提醒

### Props

```typescript
interface RiskAlertsProps {
  alerts: RiskAlert[];
}

interface RiskAlert {
  id: string;
  title: string;
  affectedProducts: string[];
  riskLevel: 'high' | 'medium' | 'low';
  description: string;
  suggestion: string;
  time: string;
}
```

### 功能特性

- 风险等级颜色区分
- 影响品种标签
- 操作建议显示

### 使用示例

```tsx
import { RiskAlertsPanel } from '@/components/RiskAlerts';

const alerts = [
  {
    id: '1',
    title: '中东地缘风险急剧升温',
    affectedProducts: ['原油', '黄金'],
    riskLevel: 'high',
    description: '美以与伊朗冲突升级',
    suggestion: '控制仓位，设置止损',
    time: '2025-03-02 14:30',
  },
];

<RiskAlertsPanel alerts={alerts} />
```

---

## 自定义Hooks

### useMarketData

市场数据订阅Hook（待实现）

```typescript
function useMarketData(symbols: string[]) {
  const [data, setData] = useState<Map<string, TickData>>(new Map());
  
  useEffect(() => {
    // WebSocket连接
    const ws = new WebSocket('wss://api.example.com/ws');
    
    ws.onmessage = (event) => {
      const tick = JSON.parse(event.data);
      setData(prev => new Map(prev).set(tick.symbol, tick));
    };
    
    return () => ws.close();
  }, [symbols]);
  
  return data;
}
```

### useKLineData

K线数据获取Hook（待实现）

```typescript
function useKLineData(symbol: string, period: string) {
  const [data, setData] = useState<KLineData[]>([]);
  const [loading, setLoading] = useState(false);
  
  useEffect(() => {
    setLoading(true);
    fetch(`/api/v1/products/${symbol}/kline?period=${period}`)
      .then(res => res.json())
      .then(result => {
        setData(result.data);
        setLoading(false);
      });
  }, [symbol, period]);
  
  return { data, loading };
}
```

---

## 样式规范

### Tailwind自定义配置

```javascript
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        background: '#09090b',
        primary: '#7dd75a',
        secondary: '#0d5d1b',
        accent: '#e6e6e6',
        up: '#7dd75a',
        down: '#ef4444',
        neutral: '#a1a1aa',
        warning: '#f59e0b',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
};
```

### 常用样式组合

```css
/* 卡片样式 */
.card {
  @apply p-4 rounded-xl border border-[#27272a] bg-[#0d0d10];
}

/* 悬停效果 */
.card-hover {
  @apply hover:border-[#7dd75a]/50 transition-all duration-300;
}

/* 上涨文字 */
.text-up {
  @apply text-[#7dd75a];
}

/* 下跌文字 */
.text-down {
  @apply text-[#ef4444];
}
```