Skip to content

ntdat104/java-simple-securities

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
.mvn/wrapper
.mvn/wrapper
 
 
src
src
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
mvnw
mvnw
 
 
mvnw.cmd
mvnw.cmd
 
 
pom.xml
pom.xml
 
 

Repository files navigation

🧾 Software Requirements Specification (SRS)

For: Blockchain Digital Asset Exchange System

Version: 1.0
Date: 2025-10-23
Author: ChatGPT – Technical Analyst

1. Introduction

1.1 Purpose

Tài liệu này mô tả toàn bộ yêu cầu phần mềm của Hệ thống Sàn Giao Dịch Tài Sản Số Blockchain.
Mục tiêu là xây dựng một nền tảng an toàn, hiệu suất cao cho người dùng giao dịch các loại tài sản kỹ thuật số (crypto, token, futures, margin) trên nền blockchain.

Hệ thống cho phép:

  • Giao dịch Spot, Margin, Futures.
  • Gửi/rút tiền crypto.
  • Theo dõi danh mục, lịch sử giao dịch, lợi nhuận, quản trị rủi ro.
  • Hỗ trợ KYC/AML và 2FA.
  • Mở rộng tích hợp API, WebSocket, và Trading Bot.

1.2 Scope

Sàn giao dịch blockchain gồm 3 thành phần chính:

  1. Core Exchange Engine (Matching Engine) — xử lý khớp lệnh Spot, Margin, Futures.
  2. Wallet System — quản lý tài sản của người dùng (hot/cold wallet, lock/unlock).
  3. Web/API Gateway — cung cấp REST & WebSocket API cho giao diện web, mobile, và bot.

Các chức năng chính

  • Đăng ký / Đăng nhập / Xác thực hai lớp (2FA)
  • Quản lý ví (nạp, rút, chuyển nội bộ)
  • Đặt lệnh mua/bán Spot
  • Giao dịch Margin (đòn bẩy)
  • Giao dịch Futures (hợp đồng tương lai)
  • Quản lý sổ lệnh (Orderbook)
  • Ghi nhận giao dịch (Trade History)
  • Quản lý vị thế, thanh lý tự động (Liquidation)
  • Báo cáo và biểu đồ hiệu suất

1.3 Definitions, Acronyms, and Abbreviations

Thuật ngữ Mô tả
Spot Giao dịch mua/bán tài sản thực tại giá hiện tại
Margin Giao dịch sử dụng đòn bẩy, vay thêm tài sản
Futures Giao dịch hợp đồng tương lai có/không kỳ hạn
KYC Know Your Customer – xác minh danh tính
2FA Two-Factor Authentication
PnL Profit and Loss
Order Matching Cơ chế khớp lệnh tự động
Wallet Ví lưu trữ tài sản số của người dùng
API Gateway Cổng kết nối giữa client và backend service

1.4 References

  • IEEE Std 830-1998: Recommended Practice for Software Requirements Specification
  • Binance API Documentation
  • Coinbase Exchange Architecture Overview
  • OWASP Security Guidelines 2023

1.5 Overview

Phần còn lại của tài liệu gồm:

  • Phần 2: Tổng quan hệ thống
  • Phần 3: Yêu cầu chức năng
  • Phần 4: Yêu cầu phi chức năng
  • Phần 5: Kiến trúc và cơ sở dữ liệu

2. Overall Description

2.1 Product Perspective

Hệ thống được thiết kế theo kiến trúc Microservices:

  • Mỗi service hoạt động độc lập (User Service, Wallet Service, Order Service, Matching Engine, Market Data, API Gateway).
  • Dữ liệu được quản lý bằng PostgreSQL và Redis Cache.
  • Hỗ trợ Kafka để xử lý sự kiện giao dịch real-time.

Hệ thống con

Module Mô tả
User Service Đăng ký, đăng nhập, KYC, 2FA
Wallet Service Quản lý ví, nạp/rút, khóa/mở số dư
Order Service Quản lý lệnh giao dịch Spot / Margin / Futures
Matching Engine Khớp lệnh real-time
Risk Engine Quản lý margin, tính toán thanh lý
Market Data Service Cung cấp dữ liệu giá, biểu đồ
API Gateway REST + WebSocket API
Admin Panel Quản lý hệ thống và người dùng

2.2 Product Functions (Overview)

  • User: đăng ký, đăng nhập, xác thực, bật 2FA.
  • Wallet: nạp/rút, chuyển nội bộ, kiểm tra số dư.
  • Market: xem sổ lệnh, lịch sử, biểu đồ giá.
  • Order: tạo, hủy, truy vấn lệnh.
  • Margin/Futures: mở/đóng vị thế, tính PnL, thanh lý.
  • Admin: quản lý token, thị trường, người dùng.

2.3 User Classes and Characteristics

Loại người dùng Mô tả Quyền hạn
Guest Người dùng chưa đăng ký Xem thông tin chung
Trader Người dùng có tài khoản đã KYC Giao dịch Spot, Margin, Futures
Admin Quản trị viên Quản lý hệ thống
System Bot Dịch vụ nội bộ Tự động khớp lệnh, quản lý rủi ro

2.4 Operating Environment

  • Backend: Java Spring Boot 3.x
  • Database: PostgreSQL 15, Redis 7
  • Message Queue: Apache Kafka
  • API: REST & WebSocket
  • Frontend: React.js / Next.js
  • Blockchain Nodes: Ethereum / BSC / Solana (qua RPC API)

2.5 Design and Implementation Constraints

  • Đáp ứng quy định KYC/AML quốc tế (FATF)
  • Bảo mật cấp ngân hàng (AES-256, RSA, HTTPS/TLS 1.3)
  • Dữ liệu giao dịch phải ghi log và không thể chỉnh sửa
  • Hỗ trợ khối lượng giao dịch cao (≥10.000 TPS)

2.6 User Documentation

  • User Manual (Web)
  • API Documentation (Swagger/OpenAPI 3.0)
  • Admin User Guide

3. Specific Requirements

3.1 Functional Requirements

3.1.1 User Management

  • FR-01: Người dùng có thể đăng ký bằng email/phone.
  • FR-02: Hệ thống gửi OTP xác minh.
  • FR-03: Người dùng có thể bật/tắt 2FA (Google Authenticator).
  • FR-04: Quản trị viên có thể khóa tài khoản người dùng.

3.1.2 Wallet Management

  • FR-05: Người dùng có thể nạp/rút token.
  • FR-06: Số dư ví phải được cập nhật theo thời gian thực.
  • FR-07: Hỗ trợ địa chỉ ví riêng cho mỗi token.
  • FR-08: Cho phép khóa/mở số dư khi lệnh giao dịch đang hoạt động.

3.1.3 Spot Trading

  • FR-09: Cho phép đặt lệnh Limit/Market.
  • FR-10: Khớp lệnh theo nguyên tắc “price-time priority”.
  • FR-11: Tự động cập nhật trạng thái lệnh (OPEN, FILLED, CANCELED).
  • FR-12: Lưu lịch sử giao dịch.

3.1.4 Margin Trading

  • FR-13: Người dùng có thể mở vị thế LONG/SHORT.
  • FR-14: Tính toán giá thanh lý tự động.
  • FR-15: Khi đạt ngưỡng thanh lý, hệ thống tự động tạo bản ghi liquidation.

3.1.5 Futures Trading

  • FR-16: Cho phép giao dịch hợp đồng PERPETUAL / QUARTERLY.
  • FR-17: Tính funding rate mỗi 8 giờ.
  • FR-18: Cập nhật vị thế, PnL real-time.

3.1.6 Market Data

  • FR-19: Cung cấp API lấy giá, order book, depth.
  • FR-20: Hỗ trợ WebSocket feed cho dữ liệu real-time.

3.1.7 Admin

  • FR-21: Quản lý danh sách token, thị trường.
  • FR-22: Theo dõi log giao dịch, cảnh báo bất thường.

3.2 Non-Functional Requirements

Mã Yêu cầu Mô tả
NFR-01 Hiệu năng Hỗ trợ ≥10.000 giao dịch/giây
NFR-02 Bảo mật Mã hóa AES-256, 2FA, chống SQL Injection
NFR-03 Tính sẵn sàng Uptime ≥ 99.9%
NFR-04 Khả năng mở rộng Hỗ trợ scale ngang theo microservices
NFR-05 Khả năng khôi phục Recovery time < 5 phút
NFR-06 Logging & Auditing Ghi log mọi thay đổi giao dịch
NFR-07 Dễ sử dụng Giao diện trực quan, thân thiện
NFR-08 Tuân thủ KYC/AML, GDPR, ISO 27001

4. System Architecture Overview

flowchart LR
    subgraph Frontend
        A1[Web Client] -->|REST/WebSocket| GW[API Gateway]
        A2[Mobile App] -->|REST| GW
    end

    subgraph Backend
        GW --> USR[User Service]
        GW --> WAL[Wallet Service]
        GW --> ORD[Order Service]
        ORD --> ENG[Matching Engine]
        ENG --> MQ[(Kafka Queue)]
        MQ --> RISK[Risk Engine]
        RISK --> DB[(PostgreSQL)]
        WAL --> DB
        USR --> DB
    end

    subgraph Blockchain
        NODE1[ETH Node]
        NODE2[BSC Node]
        WAL --> NODE1
        WAL --> NODE2
    end

    subgraph Admin
        ADM[Admin Panel] --> GW
    end
Loading

5. Database Design Overview (Expanded)

5.1 Core Tables

1. users

Field Type Key Description
id BIGSERIAL PK ID người dùng
email VARCHAR(255) UNIQUE Email người dùng
password_hash VARCHAR(255) Mã băm mật khẩu
full_name VARCHAR(255) Tên đầy đủ
phone_number VARCHAR(20) Số điện thoại
kyc_status SMALLINT 0 = Not Verified, 1 = Verified
two_fa_enabled BOOLEAN Trạng thái 2FA
status SMALLINT 1 = Active, 2 = Inactive
created_at TIMESTAMP Thời gian tạo
updated_at TIMESTAMP Thời gian cập nhật

2. wallet

Field Type Key Description
id BIGSERIAL PK ID ví
user_id BIGINT FK → users.id Chủ sở hữu ví
token_id BIGINT FK → token.id Token tương ứng
address VARCHAR(255) Địa chỉ blockchain
balance DECIMAL(36,18) Số dư khả dụng
locked_balance DECIMAL(36,18) Số dư bị khóa
created_at TIMESTAMP Thời gian tạo
updated_at TIMESTAMP Thời gian cập nhật

3. token

Field Type Key Description
id BIGSERIAL PK ID token
symbol VARCHAR(20) UNIQUE Ký hiệu token (BTC, ETH, USDT, v.v.)
name VARCHAR(100) Tên token
network VARCHAR(50) Mạng blockchain (Ethereum, BSC, Solana, v.v.)
contract_address VARCHAR(255) Địa chỉ hợp đồng token
decimals INT Số chữ số thập phân
status SMALLINT 1 = Active, 0 = Inactive

4. market

Field Type Key Description
id BIGSERIAL PK ID thị trường
base_token_id BIGINT FK → token.id Token gốc (VD: BTC)
quote_token_id BIGINT FK → token.id Token định giá (VD: USDT)
symbol VARCHAR(20) UNIQUE Ký hiệu thị trường (BTCUSDT)
min_order_size DECIMAL(18,8) Kích thước lệnh tối thiểu
price_precision INT Số chữ số sau dấu thập phân giá
status SMALLINT 1 = Active, 0 = Inactive

5. orders

Field Type Key Description
id BIGSERIAL PK ID lệnh
user_id BIGINT FK → users.id Người tạo lệnh
market_id BIGINT FK → market.id Thị trường
side VARCHAR(4) BUY / SELL
type VARCHAR(10) LIMIT / MARKET
price DECIMAL(36,18) Giá đặt lệnh
quantity DECIMAL(36,18) Số lượng
filled_quantity DECIMAL(36,18) Số lượng đã khớp
status VARCHAR(20) OPEN / FILLED / CANCELED
created_at TIMESTAMP Thời gian tạo
updated_at TIMESTAMP Thời gian cập nhật

6. trade

Field Type Key Description
id BIGSERIAL PK ID giao dịch
buy_order_id BIGINT FK → orders.id Lệnh mua
sell_order_id BIGINT FK → orders.id Lệnh bán
price DECIMAL(36,18) Giá khớp
quantity DECIMAL(36,18) Số lượng khớp
fee DECIMAL(36,18) Phí giao dịch
trade_time TIMESTAMP Thời gian giao dịch

5.2 Margin & Futures Extension Tables

7. margin_position

Field Type Key Description
id BIGSERIAL PK ID vị thế
user_id BIGINT FK → users.id Chủ vị thế
market_id BIGINT FK → market.id Thị trường
side VARCHAR(5) LONG / SHORT
leverage DECIMAL(5,2) Đòn bẩy (x2, x5, x10, v.v.)
entry_price DECIMAL(36,18) Giá vào lệnh
liquidation_price DECIMAL(36,18) Giá thanh lý
margin_amount DECIMAL(36,18) Số tiền ký quỹ
unrealized_pnl DECIMAL(36,18) Lãi/lỗ chưa thực hiện
status VARCHAR(20) OPEN / CLOSED / LIQUIDATED
created_at TIMESTAMP Thời gian mở vị thế
updated_at TIMESTAMP Thời gian cập nhật

8. liquidation

Field Type Key Description
id BIGSERIAL PK ID thanh lý
position_id BIGINT FK → margin_position.id Vị thế bị thanh lý
user_id BIGINT FK → users.id Người dùng bị thanh lý
liquidation_price DECIMAL(36,18) Giá thanh lý
executed_at TIMESTAMP Thời gian thanh lý
reason VARCHAR(255) Nguyên nhân (Margin Call / Forced)

9. futures_contract

Field Type Key Description
id BIGSERIAL PK ID hợp đồng tương lai
market_id BIGINT FK → market.id Thị trường tương ứng
type VARCHAR(20) PERPETUAL / QUARTERLY
funding_rate DECIMAL(10,8) Funding rate hiện tại
next_funding_time TIMESTAMP Thời điểm funding tiếp theo
maintenance_margin_rate DECIMAL(10,8) Tỷ lệ margin duy trì
status SMALLINT 1 = Active, 0 = Inactive

10. audit_log

Field Type Key Description
id BIGSERIAL PK ID log
user_id BIGINT FK → users.id Người thực hiện
action VARCHAR(255) Hành động (CREATE_ORDER, WITHDRAW, LOGIN, v.v.)
ip_address VARCHAR(50) Địa chỉ IP
device VARCHAR(100) Thiết bị truy cập
timestamp TIMESTAMP Thời điểm ghi log

5.3 Database Relationships Diagram (Simplified)

erDiagram
    USERS ||--o{ WALLET : owns
    USERS ||--o{ ORDERS : places
    USERS ||--o{ MARGIN_POSITION : holds
    USERS ||--o{ LIQUIDATION : affected
    USERS ||--o{ AUDIT_LOG : logs

    WALLET }o--|| TOKEN : contains
    MARKET }o--|| TOKEN : uses
    ORDERS }o--|| MARKET : trades_on
    TRADE }o--|| ORDERS : executes
    MARGIN_POSITION }o--|| MARKET : based_on
    LIQUIDATION }o--|| MARGIN_POSITION : terminates
    FUTURES_CONTRACT }o--|| MARKET : derived_from
Loading

6. Appendices

6.1 Future Enhancements

  • Tích hợp staking/lending module
  • API cho Trading Bot
  • On-chain proof-of-reserve

6.2 Security Considerations

  • Xác thực JWT cho API
  • Mã hóa private key ví người dùng (AES-256)
  • Bảo vệ chống DDoS, CSRF

6.3 Assumptions and Dependencies

  • Blockchain node luôn sẵn sàng
  • Giao dịch crypto có thể bị delay tùy mạng lưới

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages