MomentumLab/app/docs/03-技术架构.md

# A股智投分析平台 - 技术架构

## 一、整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                        前端层 (Frontend)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   React 18  │  │ TypeScript  │  │     Vite 构建       │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │Tailwind CSS │  │ shadcn/ui   │  │    Recharts 图表    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        API 网关层                            │
│              (Nginx / AWS API Gateway / 阿里云)              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        后端层 (Backend)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Node.js    │  │   Python    │  │   WebSocket 服务    │  │
│  │  Express    │  │   FastAPI   │  │   (Socket.io)       │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        数据层 (Data)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   MySQL     │  │    Redis    │  │   外部数据接口      │  │
│  │  (主存储)   │  │   (缓存)    │  │  (AKShare/Tushare)  │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## 二、前端架构

### 2.1 技术选型

| 技术 | 版本 | 用途 |
|-----|------|------|
| React | 18.x | UI框架 |
| TypeScript | 5.x | 类型系统 |
| Vite | 5.x | 构建工具 |
| Tailwind CSS | 3.x | 样式框架 |
| shadcn/ui | latest | UI组件库 |
| Recharts | 2.x | 图表库 |
| Framer Motion | 11.x | 动画库 |
| Lucide React | latest | 图标库 |

### 2.2 目录结构

```
src/
├── components/          # 公共组件
│   ├── Navbar.tsx       # 导航栏
│   ├── CandlestickChart.tsx  # K线蜡烛图
│   ├── StockDetailModal.tsx  # 个股详情弹窗
│   ├── SectorDetailModal.tsx # 版块详情弹窗
│   └── Footer.tsx       # 页脚
│
├── sections/            # 页面区块组件
│   ├── MarketOverview.tsx      # 市场概览
│   ├── MomentumSectors.tsx     # 动量版块
│   ├── HighLowStocks.tsx       # 新高新低
│   ├── PriceDistribution.tsx   # 涨跌分布
│   └── MomentumRecommendation.tsx  # 动量推荐
│
├── services/            # 数据服务层
│   └── stockData.ts     # 股票数据服务
│
├── types/               # TypeScript类型定义
│   └── index.ts         # 类型定义
│
├── hooks/               # 自定义React Hooks
│   └── useStockData.ts  # 股票数据Hook
│
├── utils/               # 工具函数
│   └── format.ts        # 格式化函数
│
├── App.tsx              # 主应用组件
├── main.tsx             # 应用入口
└── index.css            # 全局样式
```

### 2.3 组件设计原则

1. **单一职责**: 每个组件只负责一个功能
2. **可复用性**: 公共组件抽离，提高复用
3. **类型安全**: 使用TypeScript严格类型检查
4. **性能优化**: 使用useMemo、useCallback优化渲染

### 2.4 状态管理

当前使用React内置状态管理：
- `useState`: 组件内部状态
- `useEffect`: 副作用处理
- `useContext`: 跨组件状态（待实现）

未来可考虑：
- Zustand: 轻量级状态管理
- Redux Toolkit: 复杂状态管理

## 三、后端架构（待实现）

### 3.1 技术选型方案

#### 方案一: Node.js + Express
```javascript
// 技术栈
- Node.js 20.x
- Express 4.x
- TypeScript 5.x
- Prisma ORM
- Socket.io (WebSocket)
```

#### 方案二: Python + FastAPI
```python
# 技术栈
- Python 3.11
- FastAPI
- SQLAlchemy
- WebSockets
- Celery (定时任务)
```

### 3.2 目录结构

```
backend/
├── src/
│   ├── controllers/     # 控制器层
│   │   ├── stockController.ts
│   │   ├── sectorController.ts
│   │   └── userController.ts
│   │
│   ├── services/        # 业务逻辑层
│   │   ├── stockService.ts
│   │   ├── sectorService.ts
│   │   └── dataSyncService.ts
│   │
│   ├── models/          # 数据模型层
│   │   ├── Stock.ts
│   │   ├── Sector.ts
│   │   └── User.ts
│   │
│   ├── routes/          # 路由定义
│   │   ├── stockRoutes.ts
│   │   ├── sectorRoutes.ts
│   │   └── userRoutes.ts
│   │
│   ├── middleware/      # 中间件
│   │   ├── auth.ts
│   │   ├── errorHandler.ts
│   │   └── rateLimiter.ts
│   │
│   ├── utils/           # 工具函数
│   │   ├── logger.ts
│   │   ├── validator.ts
│   │   └── formatter.ts
│   │
│   ├── config/          # 配置文件
│   │   ├── database.ts
│   │   ├── redis.ts
│   │   └── constants.ts
│   │
│   ├── websocket/       # WebSocket服务
│   │   └── stockSocket.ts
│   │
│   └── app.ts           # 应用入口
│
├── prisma/              # Prisma ORM
│   └── schema.prisma
│
├── tests/               # 测试文件
├── Dockerfile
├── docker-compose.yml
└── package.json
```

## 四、数据库设计

### 4.1 MySQL 表结构

```sql
-- 股票基本信息表
CREATE TABLE stocks (
    id INT PRIMARY KEY AUTO_INCREMENT,
    code VARCHAR(10) NOT NULL COMMENT '股票代码',
    name VARCHAR(50) NOT NULL COMMENT '股票名称',
    industry VARCHAR(50) COMMENT '所属行业',
    market VARCHAR(10) COMMENT '所属市场(沪市/深市)',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_code (code),
    INDEX idx_industry (industry)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 版块信息表
CREATE TABLE sectors (
    id INT PRIMARY KEY AUTO_INCREMENT,
    code VARCHAR(10) NOT NULL COMMENT '版块代码',
    name VARCHAR(50) NOT NULL COMMENT '版块名称',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_code (code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 股票与版块关联表
CREATE TABLE stock_sectors (
    stock_code VARCHAR(10) NOT NULL,
    sector_code VARCHAR(10) NOT NULL,
    PRIMARY KEY (stock_code, sector_code),
    FOREIGN KEY (stock_code) REFERENCES stocks(code),
    FOREIGN KEY (sector_code) REFERENCES sectors(code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 实时行情表
CREATE TABLE stock_quotes (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    stock_code VARCHAR(10) NOT NULL,
    price DECIMAL(10, 2) NOT NULL COMMENT '当前价格',
    open DECIMAL(10, 2) COMMENT '开盘价',
    high DECIMAL(10, 2) COMMENT '最高价',
    low DECIMAL(10, 2) COMMENT '最低价',
    pre_close DECIMAL(10, 2) COMMENT '昨收',
    volume BIGINT COMMENT '成交量',
    turnover BIGINT COMMENT '成交额',
    change_percent DECIMAL(5, 2) COMMENT '涨跌幅',
    quote_time TIMESTAMP NOT NULL,
    INDEX idx_code_time (stock_code, quote_time),
    INDEX idx_time (quote_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- K线数据表
CREATE TABLE kline_data (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    stock_code VARCHAR(10) NOT NULL,
    period VARCHAR(10) NOT NULL COMMENT '周期(day/week/month)',
    date DATE NOT NULL,
    open DECIMAL(10, 2) NOT NULL,
    high DECIMAL(10, 2) NOT NULL,
    low DECIMAL(10, 2) NOT NULL,
    close DECIMAL(10, 2) NOT NULL,
    volume BIGINT NOT NULL,
    ma5 DECIMAL(10, 2),
    ma10 DECIMAL(10, 2),
    ma20 DECIMAL(10, 2),
    ma30 DECIMAL(10, 2),
    ma60 DECIMAL(10, 2),
    UNIQUE KEY uk_code_period_date (stock_code, period, date),
    INDEX idx_date (date)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 版块行情表
CREATE TABLE sector_quotes (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    sector_code VARCHAR(10) NOT NULL,
    change_percent DECIMAL(5, 2) COMMENT '涨跌幅',
    momentum_score DECIMAL(5, 2) COMMENT '动量分数',
    rank INT COMMENT '排名',
    volume BIGINT COMMENT '成交量',
    turnover BIGINT COMMENT '成交额',
    quote_time TIMESTAMP NOT NULL,
    INDEX idx_code_time (sector_code, quote_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 用户表
CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 用户自选股表
CREATE TABLE user_favorites (
    user_id INT NOT NULL,
    stock_code VARCHAR(10) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (user_id, stock_code),
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (stock_code) REFERENCES stocks(code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### 4.2 Redis 缓存设计

```
# 实时行情缓存 (TTL: 60秒)
stock:quote:{stock_code} -> Hash

# 版块行情缓存 (TTL: 60秒)
sector:quote:{sector_code} -> Hash

# K线数据缓存 (TTL: 300秒)
kline:{stock_code}:{period} -> Sorted Set

# 搜索缓存 (TTL: 300秒)
search:{keyword} -> List

# 用户会话 (TTL: 86400秒)
session:{session_id} -> Hash

# 热门股票排行 (TTL: 300秒)
hot:stocks -> Sorted Set

# 涨跌幅分布 (TTL: 60秒)
price:distribution -> Hash
```

## 五、API 设计规范

### 5.1 接口规范

```
Base URL: https://api.aguzhitou.com/v1

请求格式:
- Content-Type: application/json
- Authorization: Bearer {token}

响应格式:
{
    "code": 200,
    "message": "success",
    "data": { ... }
}

错误码:
- 200: 成功
- 400: 请求参数错误
- 401: 未授权
- 403: 禁止访问
- 404: 资源不存在
- 500: 服务器错误
```

### 5.2 接口列表

详见 [04-API接口文档.md](./04-API接口文档.md)

## 六、部署架构

### 6.1 生产环境

```
                    ┌─────────────┐
                    │   用户      │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  CDN加速    │
                    │ (静态资源)  │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐    │    ┌───────▼───────┐
       │  Nginx      │    │    │   Nginx       │
       │ (负载均衡)  │    │    │ (负载均衡)    │
       └──────┬──────┘    │    └───────┬───────┘
              │           │            │
       ┌──────┴───────────┴────────────┴──────┐
       │                                       │
       │         Kubernetes Cluster            │
       │  ┌─────────┐  ┌─────────┐            │
       │  │ Frontend│  │ Frontend│            │
       │  │ Pod x3  │  │ Pod x3  │            │
       │  └────┬────┘  └────┬────┘            │
       │       └────────────┘                 │
       │              │                       │
       │  ┌───────────┴───────────┐           │
       │  │      Backend          │           │
       │  │      Pod x3           │           │
       │  └───────────┬───────────┘           │
       │              │                       │
       │  ┌───────────┴───────────┐           │
       │  │      WebSocket        │           │
       │  │      Pod x2           │           │
       │  └───────────────────────┘           │
       │                                       │
       └───────────────────────────────────────┘
                           │
       ┌───────────────────┼───────────────────┐
       │                   │                   │
┌──────▼──────┐   ┌───────▼────────┐  ┌──────▼──────┐
│   MySQL     │   │     Redis      │  │  外部API    │
│  (主从集群)  │   │   (Cluster)    │  │ (AKShare等) │
└─────────────┘   └────────────────┘  └─────────────┘
```

### 6.2 Docker 部署

```dockerfile
# Dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["node", "dist/server.js"]
```

```yaml
# docker-compose.yml
version: '3.8'

services:
  frontend:
    build: ./frontend
    ports:
      - "80:80"
    depends_on:
      - backend

  backend:
    build: ./backend
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=mysql://user:pass@mysql:3306/aguzhitou
      - REDIS_URL=redis://redis:6379
    depends_on:
      - mysql
      - redis

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=rootpass
      - MYSQL_DATABASE=aguzhitou
    volumes:
      - mysql_data:/var/lib/mysql

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

volumes:
  mysql_data:
  redis_data:
```

## 七、性能优化

### 7.1 前端优化
- 代码分割 (Code Splitting)
- 懒加载 (Lazy Loading)
- 图片优化 (WebP格式)
- 缓存策略 (Service Worker)
- CDN加速

### 7.2 后端优化
- 数据库索引优化
- Redis缓存
- 接口限流
- 连接池
- 异步处理

### 7.3 监控
- 前端性能监控 (Web Vitals)
- 后端APM (New Relic / Sentry)
- 日志收集 (ELK Stack)
- 告警通知

## 八、安全规范

### 8.1 前端安全
- XSS防护
- CSRF防护
- HTTPS强制
- Content Security Policy

### 8.2 后端安全
- 接口鉴权 (JWT)
- 参数校验
- SQL注入防护
- 敏感信息加密
- 访问日志

## 九、开发规范

### 9.1 代码规范
- ESLint + Prettier
- Git Commit 规范
- 代码审查 (Code Review)
- 单元测试覆盖率 > 80%

### 9.2 Git 工作流
```
main (生产分支)
  ↑
develop (开发分支)
  ↑
feature/* (功能分支)
  ↑
hotfix/* (紧急修复)
```

## 十、技术债务

| 问题 | 优先级 | 解决方案 |
|-----|-------|---------|
| 缺少后端API | 高 | 开发Node.js/Python后端 |
| 使用模拟数据 | 高 | 接入真实数据源 |
| 缺少用户系统 | 中 | 开发登录注册功能 |
| 缺少测试 | 中 | 补充单元测试和E2E测试 |
| 缺少CI/CD | 低 | 配置GitHub Actions |