# A股智投 - 技术规格文档

---

## 1. 组件清单

### shadcn/ui 组件
| 组件 | 用途 |
|------|------|
| Card | 数据卡片容器 |
| Button | 各类按钮 |
| Input | 搜索输入框 |
| Select | 数据源选择器 |
| Tabs | 页面标签切换 |
| Table | 股票列表展示 |
| Badge | 状态标签 |
| Switch | 实时订阅开关 |
| Dialog | 确认弹窗 |
| Tooltip | 悬浮提示 |
| Separator | 分割线 |
| Skeleton | 加载占位 |

### 第三方组件
| 组件 | 来源 | 用途 |
|------|------|------|
| Recharts | npm | 图表绘制 |
| react-tsparticles | npm | 背景粒子效果 |

### 自定义组件
| 组件 | 用途 |
|------|------|
| GaugeChart | 情绪指标仪表盘 |
| Treemap | 版块热力图 |
| AnimatedNumber | 数字滚动动画 |
| StockCard | 股票信息卡片 |
| SentimentMeter | 情绪指示器 |
| PriceChangeBar | 涨跌幅分布柱状图 |
| MomentumList | 动量排名列表 |
| NewsFeed | 新闻资讯流 |
| DataSourceSelector | 数据源选择器 |

---

## 2. 动画实现方案

| 动画 | 库 | 实现方式 | 复杂度 |
|------|------|----------|--------|
| 页面加载淡入 | Framer Motion | AnimatePresence + motion.div | 中 |
| 卡片依次入场 | Framer Motion | staggerChildren + variants | 中 |
| 数字滚动 | 自定义Hook | useCountUp + requestAnimationFrame | 中 |
| 仪表盘指针 | Framer Motion | animate + rotate | 中 |
| 图表数据更新 | Recharts | animationDuration | 低 |
| 表格行悬浮 | CSS/Tailwind | hover:bg-white/5 | 低 |
| 卡片悬浮 | CSS/Tailwind | hover:border-white/20 | 低 |
| 标签页切换 | Framer Motion | layoutId + motion.div | 中 |
| 实时数据脉冲 | CSS | animate-pulse | 低 |
| 背景粒子 | react-tsparticles | 配置粒子参数 | 高 |

---

## 3. 项目文件结构

```
app/
├── src/
│   ├── components/
│   │   ├── ui/              # shadcn/ui 组件
│   │   ├── charts/          # 图表组件
│   │   │   ├── GaugeChart.tsx
│   │   │   ├── Treemap.tsx
│   │   │   ├── PriceDistribution.tsx
│   │   │   └── SentimentTrend.tsx
│   │   ├── common/          # 通用组件
│   │   │   ├── AnimatedNumber.tsx
│   │   │   ├── StockCard.tsx
│   │   │   ├── Header.tsx
│   │   │   └── Footer.tsx
│   │   └── sections/        # 页面区块
│   │       ├── MarketOverview.tsx
│   │       ├── SentimentIndicator.tsx
│   │       ├── MomentumAnalysis.tsx
│   │       ├── HighLowStocks.tsx
│   │       ├── PriceChangeDistribution.tsx
│   │       ├── StockAnalysis.tsx
│   │       ├── SentimentAnalysis.tsx
│   │       └── DataSourcePanel.tsx
│   ├── hooks/               # 自定义Hooks
│   │   ├── useCountUp.ts
│   │   ├── useRealtime.ts
│   │   ├── useStockData.ts
│   │   └── useSentiment.ts
│   ├── lib/                 # 工具函数
│   │   ├── utils.ts
│   │   ├── mockData.ts
│   │   └── formatters.ts
│   ├── types/               # TypeScript类型
│   │   └── index.ts
│   ├── pages/               # 页面
│   │   ├── Dashboard.tsx    # 大盘分析首页
│   │   └── StockDetail.tsx  # 个股分析页
│   ├── App.tsx
│   ├── main.tsx
│   └── index.css
├── public/
├── index.html
├── tailwind.config.js
├── vite.config.ts
└── package.json
```

---

## 4. 依赖清单

### 核心依赖
```json
{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.20.0",
    "framer-motion": "^10.16.0",
    "recharts": "^2.10.0",
    "lucide-react": "^0.294.0",
    "date-fns": "^2.30.0",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "tailwind-merge": "^2.0.0"
  }
}
```

### 开发依赖
```json
{
  "devDependencies": {
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "@vitejs/plugin-react": "^4.2.0",
    "typescript": "^5.3.0",
    "vite": "^5.0.0",
    "tailwindcss": "^3.4.0",
    "autoprefixer": "^10.4.0",
    "postcss": "^8.4.0"
  }
}
```

---

## 5. 数据结构

### 股票基本信息
```typescript
interface Stock {
  code: string;           // 股票代码
  name: string;           // 股票名称
  price: number;          // 当前价格
  change: number;         // 涨跌额
  changePercent: number;  // 涨跌幅%
  volume: number;         // 成交量
  marketCap: number;      // 市值
  industry: string;       // 所属行业
}
```

### 市场概况
```typescript
interface MarketOverview {
  upCount: number;        // 上涨家数
  downCount: number;      // 下跌家数
  flatCount: number;      // 平盘家数
  limitUpCount: number;   // 涨停家数
  limitDownCount: number; // 跌停家数
  updateTime: string;     // 更新时间
}
```

### 情绪指标
```typescript
interface SentimentData {
  value: number;          // 0-100
  label: string;          // 状态标签
  description: string;    // 描述
}
```

### 动量数据
```typescript
interface MomentumData {
  sector: string;         // 版块名称
  changePercent: number;  // 涨跌幅
  momentum: number;       // 动量值
  stocks: Stock[];        // 包含股票
}
```

### AI分析结果
```typescript
interface AIAnalysis {
  stockCode: string;
  insights: string;       // 关键洞察
  recommendation: 'buy' | 'sell' | 'hold';
  trend: 'up' | 'down' | 'sideways';
  targetPrice: {
    idealBuy: number;
    secondBuy: number;
    stopLoss: number;
    takeProfit: number;
  };
  confidence: number;     // 置信度
}
```

---

## 6. 实时订阅设计

### WebSocket连接
- 连接地址: `wss://api.example.com/realtime`
- 心跳间隔: 30秒
- 重连策略: 指数退避

### 订阅主题
```typescript
enum SubscribeTopic {
  MARKET_OVERVIEW = 'market_overview',
  STOCK_PRICE = 'stock_price',
  SENTIMENT = 'sentiment',
  MOMENTUM = 'momentum',
  NEWS = 'news'
}
```

### 消息格式
```typescript
interface WSMessage {
  topic: SubscribeTopic;
  data: any;
  timestamp: number;
}
```

---

## 7. 多数据源设计

### 数据源接口
```typescript
interface DataSource {
  id: string;
  name: string;
  icon: string;
  isAvailable: boolean;
}

const dataSources: DataSource[] = [
  { id: 'eastmoney', name: '东方财富', icon: 'eastmoney', isAvailable: true },
  { id: 'ths', name: '同花顺', icon: 'ths', isAvailable: true },
  { id: 'xueqiu', name: '雪球', icon: 'xueqiu', isAvailable: true },
  { id: 'tencent', name: '腾讯财经', icon: 'tencent', isAvailable: true },
];
```

### 数据适配器模式
```typescript
interface DataAdapter {
  fetchMarketOverview(): Promise<MarketOverview>;
  fetchStockDetail(code: string): Promise<Stock>;
  fetchMomentumData(): Promise<MomentumData[]>;
  fetchSentiment(): Promise<SentimentData>;
}
```

---

## 8. 性能优化

### 策略
1. **虚拟滚动**: 长列表使用虚拟滚动
2. **数据缓存**: React Query缓存请求结果
3. **防抖节流**: 搜索输入防抖，滚动事件节流
4. **懒加载**: 图表组件懒加载
5. **代码分割**: 路由级别代码分割

### 指标
- 首屏加载: < 2s
- 交互响应: < 100ms
- 动画帧率: 60fps