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

// 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

# 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

-- 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