# SPECIFICATION: ỨNG DỤNG THEO DÕI BIẾN ĐỘNG GIÁ CHỨNG KHOÁN MBS

### 1. TỔNG QUAN DỰ ÁN

#### 1.1 Mục tiêu

Xây dựng ứng dụng web/mobile theo dõi biến động giá chứng khoán theo thời gian thực từ sàn chứng khoán MB Securities (MBS), cung cấp công cụ phân tích và cảnh báo cho nhà đầu tư.

#### 1.2 Phạm vi

* **Nguồn dữ liệu**: Sàn chứng khoán MBS (mbs.com.vn) + các nguồn dữ liệu thị trường VN (VnDirect, SSI, Vietstock)
* **Thị trường**: HOSE, HNX, UPCOM
* **Loại chứng khoán**: Cổ phiếu, ETF, Chứng quyền, Trái phiếu doanh nghiệp

***

### 2. KIẾN TRÚC HỆ THỐNG

plain Copy

```
┌─────────────────────────────────────────────────────────────┐
│                    CLIENT LAYER                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Web App    │  │  Mobile App  │  │  Extension   │      │
│  │  (React/Vue) │  │(React Native)│  │   (Chrome)   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────┬────────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────────┐
│                   API GATEWAY                               │
│         (Rate Limiting, Authentication, Routing)            │
└────────────────────┬────────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
┌──────────────┐ ┌──────────┐ ┌──────────────┐
│  Data Sync   │ │  Realtime│ │  Historical  │
│   Service    │ │  Service │ │   Service    │
└──────┬───────┘ └────┬─────┘ └──────┬───────┘
       │              │              │
       └──────────────┼──────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│              DATA SOURCES                                   │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │ MBS WebSocket│ │  VnStock API │ │  SSI FC API  │        │
│  │  (Primary)   │ │  (Fallback)  │ │  (Backup)    │        │
│  └──────────────┘ └──────────────┘ └──────────────┘        │
└─────────────────────────────────────────────────────────────┘
```

***

### 3. CHỨC NĂNG CHÍNH (FUNCTIONAL REQUIREMENTS)

#### 3.1 Dashboard Tổng Quan Thị Trường

Table

| ID    | Chức năng              | Mô tả                                                     | Priority |
| ----- | ---------------------- | --------------------------------------------------------- | -------- |
| F-001 | Bảng giá trực tuyến    | Hiển thị bảng giá HOSE/HNX/UPCOM với tốc độ cập nhật < 1s | P0       |
| F-002 | Chỉ số thị trường      | VN-Index, HNX-Index, VN30, VNMidCap, VNSmallCap           | P0       |
| F-003 | Top movers             | Top tăng/giảm/giao dịch nhiều nhất                        | P0       |
| F-004 | Heatmap thị trường     | Màu sắc thể hiện độ rộng thị trường                       | P1       |
| F-005 | Thanh khoản thị trường | Tổng khối lượng, giá trị giao dịch                        | P1       |

#### 3.2 Theo Dõi Cổ Phiếu Chi Tiết

Table

| ID    | Chức năng                      | Mô tả                                             | Priority |
| ----- | ------------------------------ | ------------------------------------------------- | -------- |
| F-006 | Biểu đồ nến (Candlestick)      | Khung thời gian: 1m, 5m, 15m, 30m, 1H, 1D, 1W, 1M | P0       |
| F-007 | Bảng giá đặt lệnh (Order Book) | Hiển thị 10 mức giá mua/bán tốt nhất              | P0       |
| F-008 | Lịch sử giao dịch (Tape)       | Danh sách giao dịch khớp lệnh real-time           | P0       |
| F-009 | Thông tin cơ bản               | Vốn hóa, EPS, P/E, P/B, ROE, ROA                  | P1       |
| F-010 | So sánh cổ phiếu               | So sánh 2-5 mã trên cùng biểu đồ                  | P1       |

#### 3.3 Hệ Thống Cảnh Báo (Alert System)

Table

| ID    | Chức năng            | Mô tả                                            | Priority |
| ----- | -------------------- | ------------------------------------------------ | -------- |
| F-011 | Cảnh báo giá         | Khi giá chạm ngưỡng (>, <, =) giá định trước     | P0       |
| F-012 | Cảnh báo biến động % | Khi thay đổi % vượt ngưỡng trong khung thời gian | P0       |
| F-013 | Cảnh báo khối lượng  | Khi khối lượng giao dịch vượt ngưỡng             | P1       |
| F-014 | Cảnh báo breakout    | Khi phá vỡ đỉnh/đáy trong N phiên                | P2       |
| F-015 | Thông báo đa kênh    | Web push, Email, Telegram, SMS                   | P1       |

#### 3.4 Quản Lý Danh Mục Đầu Tư

Table

| ID    | Chức năng          | Mô tả                                     | Priority |
| ----- | ------------------ | ----------------------------------------- | -------- |
| F-016 | Tạo danh mục ảo    | Theo dõi nhiều danh mục với tên tùy chỉnh | P1       |
| F-017 | Nhập giao dịch     | Ghi nhận mua/bán với giá, số lượng, ngày  | P1       |
| F-018 | Tính P\&L          | Lãi/lỗ thực tế và unrealized P\&L         | P1       |
| F-019 | Phân tích danh mục | Tỷ trọng ngành, biểu đồ phân bổ           | P2       |
| F-020 | Export báo cáo     | PDF/Excel báo cáo danh mục                | P2       |

***

### 4. YÊU CẦU KỸ THUẬT (TECHNICAL REQUIREMENTS)

#### 4.1 Data Sources & APIs

**4.1.1 Nguồn chính: MBS WebSocket**

JavaScript Copy

```javascript
// WebSocket Endpoint (giả định dựa trên cấu trúc s24.mbs.com.vn)
wss://realtime.mbs.com.vn/ws/market-data

// Subscription Message
{
  "action": "subscribe",
  "channels": ["price", "orderbook", "trade"],
  "symbols": ["VNM", "VIC", "HPG"],
  "frequency": "realtime"
}

// Response Format
{
  "type": "price_update",
  "symbol": "VNM",
  "data": {
    "lastPrice": 78500,
    "change": 1200,
    "changePercent": 1.55,
    "volume": 1250000,
    "bid": 78400,
    "ask": 78600,
    "timestamp": "2024-01-15T09:45:23.123Z"
  }
}
```

**4.1.2 Nguồn dự phòng: VnStock API**

Python Copy

```python
# Sử dụng thư viện vnstock cho dữ liệu lịch sử
from vnstock import Vnstock

stock = Vnstock().stock(symbol='VNM', source='VCI')
df = stock.quote.history(start='2024-01-01', end='2024-01-15')
```

**4.1.3 Nguồn dự phòng 2: SSI FC API**

* **Base URL**: `https://fc-data.ssi.com.vn/`
* **Streaming**: WebSocket cho dữ liệu real-time
* **Documentation**: Yêu cầu tài khoản SSI để truy cập

#### 4.2 Công Nghệ Sử Dụng

Table

| Layer            | Công nghệ                        | Lý do chọn                    |
| ---------------- | -------------------------------- | ----------------------------- |
| Frontend         | Next.js 14 + TypeScript          | SSR, performance, type safety |
| State Management | Zustand + React Query            | Lightweight, caching tốt      |
| Charts           | Lightweight Charts (TradingView) | Chuyên dụng tài chính, nhẹ    |
| Backend          | Node.js + Fastify                | Hiệu năng cao, WebSocket tốt  |
| Database         | TimescaleDB (PostgreSQL)         | Time-series data, query nhanh |
| Cache            | Redis                            | Real-time data, session       |
| Message Queue    | Redis Pub/Sub                    | Phân phối dữ liệu real-time   |
| Hosting          | Vercel (FE) + AWS EC2 (BE)       | Scalable, cost-effective      |

#### 4.3 Database Schema

sql Copy

```sql
-- Bảng giá real-time
CREATE TABLE stock_prices (
    symbol VARCHAR(10) NOT NULL,
    timestamp TIMESTAMPTZ NOT NULL,
    open DECIMAL(12,2),
    high DECIMAL(12,2),
    low DECIMAL(12,2),
    close DECIMAL(12,2),
    volume BIGINT,
    value BIGINT,
    bid_price DECIMAL(12,2)[],
    bid_volume BIGINT[],
    ask_price DECIMAL(12,2)[],
    ask_volume BIGINT[],
    PRIMARY KEY (symbol, timestamp)
);

-- Bảng giao dịch (tape)
CREATE TABLE trades (
    id BIGSERIAL,
    symbol VARCHAR(10) NOT NULL,
    timestamp TIMESTAMPTZ NOT NULL,
    price DECIMAL(12,2),
    volume BIGINT,
    side CHAR(1), -- 'B'uy or 'S'ell
    match_type VARCHAR(10) -- 'LO', 'MP', 'ATC', etc.
);

-- Bảng cảnh báo
CREATE TABLE alerts (
    id UUID PRIMARY KEY,
    user_id UUID NOT NULL,
    symbol VARCHAR(10) NOT NULL,
    condition_type VARCHAR(20), -- 'PRICE_ABOVE', 'PRICE_BELOW', 'CHANGE_PERCENT'
    threshold DECIMAL(12,4),
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    triggered_at TIMESTAMPTZ,
    notification_channels JSONB -- ['web', 'email', 'telegram']
);

-- Index cho query nhanh
CREATE INDEX idx_prices_symbol_time ON stock_prices(symbol, timestamp DESC);
CREATE INDEX idx_trades_symbol_time ON trades(symbol, timestamp DESC);
```

***

### 5. GIAO DIỆN NGƯỜI DÙNG (UI/UX)

#### 5.1 Wireframe Chính

plain Copy

```
┌─────────────────────────────────────────────────────────────────┐
│  [Logo]  Dashboard  Watchlist  Screener  Alerts  [🔍] [👤] [⚙️] │
├─────────────────────────────────────────────────────────────────┤
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  VN-Index: 1,245.67 ▲12.5 (+1.02%)  |  KLGD: 890.5 tỷ    │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────┐  ┌─────────────────────────────────┐  │
│  │   [Biểu đồ nến       │  │  Bảng giá trực tuyến           │  │
│  │    VNM - 1 ngày]     │  │  ─────────────────────────────  │  │
│  │                      │  │  Mã    Giá   +/-   KL    Tổng KL│  │
│  │  [Toolbar chart]     │  │  VNM  78.5  ▲1.2  125K   1.2M   │  │
│  │                      │  │  VIC  95.2  ▼0.5   89K   890K   │  │
│  │                      │  │  HPG  24.8  ▲0.3  456K   5.6M   │  │
│  └──────────────────────┘  │  ...                            │  │
│  ┌──────────────────────┐  └─────────────────────────────────┘  │
│  │  Order Book (VNM)    │  ┌─────────────────────────────────┐  │
│  │  Giá mua    KL       │  │  Top Movers                     │  │
│  │  78.6      15,400    │  │  🚀 Tăng mạnh: ACB +5.2%        │  │
│  │  78.5      28,500    │  │  📉 Giảm mạnh: GAS -3.1%        │  │
│  │  ...                 │  │  🔥 Khớp nhiều: HPG (56 tỷ)     │  │
│  │  ─────────────────   │  └─────────────────────────────────┘  │
│  │  Giá bán    KL       │                                       │
│  │  78.7      12,300    │                                       │
│  │  ...                 │                                       │
│  └──────────────────────┘                                       │
└─────────────────────────────────────────────────────────────────┘
```

#### 5.2 Responsive Breakpoints

* **Desktop**: 1440px+ (multi-panel layout)
* **Tablet**: 768px-1439px (2-column layout)
* **Mobile**: <768px (single column, tab navigation)

***

### 6. HIỆU NĂNG & BẢO MẬT

#### 6.1 Yêu Cầu Hiện Năng

Table

| Chỉ số             | Yêu cầu                 | Cách đo                    |
| ------------------ | ----------------------- | -------------------------- |
| Latency dữ liệu    | < 500ms từ sàn đến user | WebSocket timestamp diff   |
| Time to First Byte | < 100ms                 | Lighthouse/Performance API |
| Frame rate         | 60fps khi scroll/chart  | Chrome DevTools            |
| Concurrent users   | 10,000+                 | Load testing (k6)          |

#### 6.2 Bảo Mật

* **Authentication**: JWT với refresh token rotation
* **Rate Limiting**: 100 requests/minute cho API, 10 connections/IP cho WebSocket
* **Data Validation**: Zod schema validation cho mọi input
* **CORS**: Whitelist domain cụ thể
* **HTTPS/WSS**: Bắt buộc cho mọi connection

***

### 7. LỘ TRÌNH PHÁT TRIỂN (ROADMAP)

#### Phase 1: MVP (4 tuần)

* \[ ] Kết nối WebSocket MBS lấy dữ liệu real-time
* \[ ] Dashboard cơ bản (bảng giá, biểu đồ đơn giản)
* \[ ] Danh sách theo dõi (watchlist) local storage

#### Phase 2: Core Features (4 tuần)

* \[ ] Hệ thống cảnh báo giá
* \[ ] Biểu đồ nến nâng cao (indicators cơ bản)
* \[ ] User authentication & cloud watchlist

#### Phase 3: Advanced (4 tuần)

* \[ ] Quản lý danh mục đầu tư với P\&L
* \[ ] Phân tích kỹ thuật (RSI, MACD, MA)
* \[ ] Mobile app (React Native)

#### Phase 4: Scale (Ongoing)

* \[ ] Machine learning dự đoán xu hướng
* \[ ] Tích hợp tin tức & sentiment analysis
* \[ ] Social features (chia sẻ danh mục)

***

### 8. RỦI RO & GIẢI PHÁP

Table

| Rủi ro                  | Mức độ     | Giải pháp                                                         |
| ----------------------- | ---------- | ----------------------------------------------------------------- |
| MBS không có public API | Cao        | Web scraping + reverse engineering WebSocket, có fallback sources |
| Delay dữ liệu           | Trung bình | Multi-source aggregation, hiển thị timestamp và độ trễ            |
| Rate limiting từ nguồn  | Trung bình | Cache aggressive, exponential backoff                             |
| Dữ liệu không chính xác | Cao        | Cross-validation giữa nhiều nguồn, disclaimer rõ ràng             |

***

### 9. TÀI LIỆU THAM KHẢO

* API Stock VN - apistockvn.robotstock.info.vn
* SSI FC API Documentation - fc-data.ssi.com.vn
* VnStock Python Library - Thinh Vu

***

Bạn có muốn tôi chi tiết hóa thêm phần nào không? Ví dụ:

* **API Integration** chi tiết với code mẫu
* **Database Schema** đầy đủ với migration scripts
* **UI/UX Design** với Figma wireframes chi tiết
* **DevOps** với Docker, CI/CD pipeline