

PHẦN MỀM QUẢN LÝ THIẾT BỊ MẠNG
Network Device Management System

ĐẶC TẢ PHẦN MỀM
Software Specification Document




	
	





















	
Công Nghệ 


	•	Tổng Quan Hệ Thống
Phần mềm Quản Lý Thiết Bị Mạng (Network Device Management System – NDMS) là hệ thống fullstack phụ việc kiểm tra, giám sát, quản lý tập trung các thiết bị mạng trong tổ chức. Hệ thống tích hợp bản đồ số để trực quan hóa vị trí và trạng thái thiết bị theo thời gian thực. 
	•	Tính năng cốt lõi:  
	•	Hiển thị thông tin và trạng thái thiết bị trự quan trên bản đồ
	•	Tìm kiếm, lọc thiết bị theo thông tin không gian (Vùng Bản Đồ) và thuộc tính (loại, trạng thái, IP)
	•	Giám sát trạng thái thiết bị thời gian thực qua Ping và SNMP (Hai phương thức)
	•	Lưu trữ và hiển thị lịch sử trạng thái 
	•	Cảnh báo tự động khi thiết bị down qua giao diện web hoặc email
	•	Công Nghệ và Kiến Trúc Tổng Thể

Postgresql
Database
Flask Python
Backend APIs
Reactjs
Frontend Web



	Kiến Trúc Tổng Thể: 



















	






	•	Quản Lý Danh mục loại thiết bị (DeviceType)
	•	Mô tả chức năng 
Module Device Type cho phép người dùng quản lý danh mục các loại thiết bị mạng được hỗ trợ trong hệ thống. Mỗi loại thiết bị có tên, mô tả, icon đại diện và màu sắc hiển thị trên bản đồ. Dữ liệu danh mục này là nền tảng cho module Device – Mỗi thiết bị muốn quản lý phải nằm trong danh mục loại thiết bị này. 
	•	Loại thiết bị hỗ trợ: Máy Trạm (WorkStation), Switch, Router, Máy Tính, Điện thoại, ….
	•	Mỗi loại có icon và màu sắc riêng – Dùng để hiển thị trên bản đồ 
	•	Không được xóa loại thiết đang được gán cho thiết bị nào đó (FK)
	•	Mô tả quy trình
Luồng Quản lý danh mục thiết bị: + Truy cập trang quản lý -> Danh mục loại thiết bị
+ Thêm loại thiết bị mới: Nhập Tên, Mô Tả, Chọn icon (Upload SVG/ PNG), chọn màu sắc mặc định
+ Hệ thống validate: Tên không trùng lặp (UNIQUE), icon đúng định dạng

	•	Giải Pháp & Công Nghệ
+ Lưu icon dưới dạng URL (Upload lên S3-compatible storage hoặc server static file)+ Api danh sách trả về không phân trang -> Hiển thị dưới dạng dropdown để người dùng có thể chọn 

	•	CSDL 
DeviceType
Name
Type
Nullable
ID
UUID
False
Name
VARCHAR(100)
False
Description
TEXT
True
IconUrl
VARCHAR(512)
True
Color
VARCHAR(7)
False
SortOrder
SMALLINT
False
IsActive
BOOLEAN
False
Created
TIMESTAMPTZ
False
Modified
TIMESTAMPTZ
False







	•	API
API
METHOD
ROUTES
Danh Sách
GET
/device-types
/device-types/{DeviceTypeId}
Thêm Mới
POST
/device-types
Cập Nhật
PUT
/device-types/{deviceTypeId}
Xóa
DELETE
/device-types/{deviceTypeId}

*Không cho phép xóa khi còn thiết bị thuộc loại này 






	•	Quản Lý Thiết Bị (Device) -> một device type có nhiều device khác nhau
	•	Mô Tả Chức Năng
Module Device là phần trung tâm của hệ thống – quản lý toàn bộ các thông tin các thiết bị mạng cần giám sát. Mỗi thiết bị có đầy đủ thông tin nhận dạng, vị trí địa lý (tọa độ cần hiển thị trên bản đồ, thông tin kết nối mạng(IP/Port), và giao thức giám sát được áp dụng. 
	•	Mỗi thiết bị bắt buộc thuộc một DeviceType đã được định nghĩa
	•	Tọa độ Iat/Ing nhập bằng cách click trực tiếp trên bản đồ Leaflet min trong form thêm thiết bị 
	•	Sau khi tạo, APScheduler tự động thêm job Ping/SNMP cho thiết bị theo MonitorConfig
	•	Trạng thái hiện tại (CurrentStatus) được tính từ bản ghi mới nhất trong bảng DeviceStatus
	•	Hỗ trợ upload hình ảnh đại diện riêng cho từng thiết bị


	•	Mô Tả Quy Trình
Luồng thêm mới thiết bị: 
+ Người dùng truy cập danh sách -> Thêm Mới thiết bị
+ Điền thông tin thiết bị: Device Type, Mô Tả, Ip Address, Màu Sắc, Avatar. 
+ Validate: IP hợp lệ (regex IPv4/IPv6), tên không trùng, Iat, Ing
+ Lưu vào bảng devices
+ APSscheduler.add_job() tự động được gọi – Thêm job Ping hoặc SNMP theo MonitorConfig mặc định
+ Thiết bị xuất hiện ngay trên Leafet map với trạng thái Unknow
+ Ping worker chạy lần đầu theo interval cấu hình -> Cập nhật trạng thái Up hoặc Down 


	•	Giải Pháp & Công Nghệ

	•	Tọa độ lưu FLOAT8
	•	Khi thiết bị di rời vật lí: Bấm vào sửa Iat/Ing trên form sửa -> Marker tự dịch chuyển trên map 
	•	Avatar upload : Upload qua S3 cloud để lưu trữ


	•	CSDL
Device Type
Name
Type
Nullable
ID
UUID
False
DeviceTypeId
UUID
False
Name
VARCHAR(200)
False
Description
TEXT
True
IpAddress
VARCHAR(45)
False
Port
INTERGER
True
Latitude
FLOAT8
False
Longitude
FLOAT8
False
Color
VARCHAR(7)
False
AvatarUrl
VARCHAR(512)
True
IsActivc
BOOLEAN
True
Created
TIMESTAMPTZ
False
Modified
TIMESTAMPTZ
False

	•	API
Device
API
Method
Routes
Danh sách
GET
/devices
/devices/{DeviceId}
Cập Nhật
PUT
/devices/{DeviceId}
Xóa
DELETE
/devices/{DeviceId}
Upload Avatar
POST
/devices/{DeviceId}/avatar


	•	Cấu Hình Giám Sát (MonitorConfig)
	•	Mô tả chức năng
Module MonitorConfig quản lý cấu hình phương thức và tần suất kiểm tra trạng thái cho từng thiết bị. Mỗi thiết bị có một bản cấu hình riêng — xác định dùng Ping (ICMP qua icmplib) hay SNMP (qua pysnmp), tần suất kiểm tra (interval), timeout, và các tham số giao thức cụ thể. Toàn bộ xử lý diễn ra trong Python, không phụ thuộc service bên ngoài.

•	Ping (ICMP): dùng icmplib — async_ping() — kiểm tra kết nối cơ bản, đo RTT và packet loss
•	SNMP: dùng pysnmp — get_cmd() — lấy thông tin chi tiết qua OID (sysName, sysUpTime, ifNumber,...)
•	Hai phương thức có thể bật đồng thời — APScheduler tạo 2 job độc lập cho cùng 1 thiết bị
•	Interval cấu hình per-device — thiết bị quan trọng: 30s/lần, thiết bị ít quan trọng: 5 phút/lần
•	Thay đổi config → APScheduler.reschedule_job() cập nhật ngay, không cần restart service

APSscheduler ở đây chính là thư viện Python chạy trong bộ nhớ (RAM) của backend. Dữ liệu để APScheduler biết "cần làm gì, bao lâu 1 lần" → lấy từ bảng MonitorConfig khi app khởi động.

	•	Mô tả quy trình
Luồng cấu hình monitoring cho thiết bị: 
+ Vào trang chi tiết thiết bị -> Cấu hình giám sát
+ Chọn phương thức: Ping, SNMP hoặc cả hai 
+ Cấu hình ping: Số packet(Count), timeout(giây), interval kiểm tra(giây)
+ Cấu hình SNMP: Community String, SNMP Version(v2c/v3), PORT, Danh sách OID tùy chỉnh
+ Lưu config vào DB -> Gọi APSscheduler.add_job() hoặc reschedule_job() tức thì
+ Worker chạy theo interval mới từ chu kỳ tiếp theo   

	•	Giải pháp và công nghệ 
	•	Ping Worker – icmplib: async_ping(address, count, timeout, privileged=False)
	•	





	•	CSDL
MonitorConfig
Name
Type
Nullable
ID
UUID
False
DeviceId
UUID
False
EnablePing
BOOLEAN
False
PingCount
SMALLINT
False
PingTimeout
SMALLINT
False
PingInterval
INTEGER
False
EnableSnmp
BOOLEAN
False
SnmpVersion
VARCHAR(5)
True
SnmpCommunity
VARCHAR(256)
True
SnmpPort
INTEGER
True
SnmpInterval
INTEGER
True
SnmpTimeout
SMALLINT
True
SnmpCustomOids
JSONB
True
Created
TIMESTAMPTZ
False
Modified
TIMESTAMPTZ
False


	•	API
API
METHOD
ROUTES
Lấy config của thiết bị
GET
devices/{DeviceId}/monitor-config
Tạo hoặc cập nhật config
PUT
devices/{DevicesId}/monitor-config
TEST kết nối 
POST
devices/{DevicesId}/monitor-config/test

	•	Lịch sử trạng thái thiết bị(DeviceStatus)
	•	Mô tả chức năng
Module DeviceStatus lưu trữ kết quả của từng lần Ping/SNMP Worker chạy. Đây là dữ liệu time-series — volume tăng nhanh, cần tối ưu lưu trữ và query. Dữ liệu phục vụ: hiển thị trạng thái realtime trên Leaflet map (bản ghi mới nhất), vẽ biểu đồ response time (Recharts), tính SLA uptime %, và là cơ sở để phát hiện ngưỡng cảnh báo.

	•	Mỗi lần Ping Worker chạy → 1 bản ghi mới với status, RTT, packet loss, timestamp
	•	Mỗi lần SNMP Worker chạy → 1 bản ghi mới với status, dữ liệu OID dạng JSONB
	•	WebSocket broadcast ngay sau khi lưu — frontend nhận status mới trong vòng < 1 giây
	•	Chiến lược change-only: chỉ lưu khi status thay đổi so với lần trước — giảm volume đáng kể




	•	Mô tả quy trình
Luồng ghi lịch sử trạng thái – Chạy tự động bởi Worker:
	•	APSscheduler kích hoạt job theo interval đã cấu hình trong MonitorConfig
	•	Ping Worker: gọi async_ping(ip, count, timeout, privileged=False) → nhận kết quả
	•	Đánh giá trạng thái: is_alive=True -> up, is_alive=False -> down
	•	SNMP Worker: gọi get_cmd() cho từng OID trong SnmpCustomOids -> Nhận giá trị 
	•	Đánh giá: Lấy được sysName -> up; timeout/error -> down
	•	Lưu bản ghi mới vào bảng device_status(Timescale DB) kèm CheckedAt = now(UTC)
	•	WebSocket gọi ws_manager.broadcast ({type:'device_status', device_id, status, rtt_ms})
	•	Kiểm tra AlertConfig: đếm fail liên tiếp -> Nếu vượt FailThreshold -> Gọi Alert Worker

	•	Giải pháp và công nghệ 
	•	TimeScaleDB hypertable trên cột CheckedAt – partition tự động theo thời gian, query time- range nhanh
	•	Retention policy: tự động xóa dữ liệu cũ hơn 90 ngày ( Cấu hình qua TimescaleDb policy)
	•	Composite index: (DeviceId, CheckedAt DESC) – query lịch sử theo thiết bị trang range
	•	API time-bucket: group dữ liệu theo 5m/1h/1d tùy range request – dùng TimescaleDB time_bucket()
	•	Change detection: so sánh với bản ghi gần nhất, chỉ lưu khi status thay đổi hoặc RTT thay đổi >20%
	•	CSDL
Name
Type
Nullable
ID
BIGSERIAL
False
DeviceId
UUID
False
Status
VARCHAR(20)
False
Method
VARCHAR(10)
False
ResponseTimeMs
FLOAT8
True
PacketLoss
FLOAT8
True
SnmpData
JSONB
True
Detail
TEXT
True
CheckedAt
TIMESTAMPTZ
False


	•	API
API
Method
Routes
Lịch sử theo thiết bị 
-Filter:
+ DateFrom, DateTo(datetime)
+ Status(up/down/degraded)
+ Method(ping,snmp)
+ Bucket(5m/1h/1d)
-Paging: Page + Size
GET
- devices/{DeviceId}/status/history
- devices/{DeviceId}/status/latest
-> Trả về bản ghi status mới nhất
Trạng thái tất cả các thiết bị
GET
-devices/status/current
Trả về map: {deviceId: {status, checkedAt, responseMs}}





	•	Cảnh báo (Alert)
	•	Mô tả chức năng
Module Alert gồm hai phần: AlertConfig (cấu hình ngưỡng và kênh cảnh báo device và AlertLog( Lịch sử các sự cố phát sinh). Hệ Thống tự động phát cảnh báo khi Ping/SNMP Worker phát hiện thiết bị vi phạm ngưỡng – thông báo qua WebSocket toast trên giao diện web và email HTML qua STMP ( thư viện của Python smtplib + Jinja2 )

	•	Mô tả quy trình
Luồng phát hiện và gửi cảnh báo – được gọi bởi Ping/SNMP Worker:
	•	Worker phát hiện thiết bị trả về status = down → gọi check_and_alert(device_id)
	•	Đếm số lần fail liên tiếp: query bản ghi gần nhất trong DeviceStatus cho đến khi gặp status != down
	•	So sánh với AlertConfig.FailThreshold — nếu fail_count < threshold → không làm gì
	•	Kiểm tra cooldown: lấy AlertLog gần nhất, tính elapsed = now - triggered_at (phút)
	•	Nếu elapsed < CooldownMinutes → bỏ qua, không gửi lại (tránh spam)
	•	Tạo bản ghi AlertLog mới (status: active)
	•	Nếu NotifyWeb=True: gọi ws_manager.broadcast() — tất cả client nhận toast đỏ
	•	Nếu NotifyEmail=True và EmailRecipients không rỗng: gọi send_alert_email() qua smtplib
	•	Khi thiết bị up lại: Worker tự động cập nhật AlertLog.ResolvedAt, AlertLog.Status = resolved

	•	Giải pháp và công nghệ
	•	Email: smtplib chuẩn Python — hỗ trợ SMTP_SSL, cấu hình host/port/user/pass qua .env
	•	HTML Email template: Jinja2 (pip install jinja2) — render template với context {device, alert}
	•	Web alert payload: {type:'alert', device_id, device_name, ip, status, message, triggered_at}

	•	CSDL
AlertConfig
Name
Type
Nullable
ID
UUID
False
DeviceId
UUID
False
IsEnabled
BOOLEAN
False
FailThreshold
SMALLINT
False
CooldownMinutes
INTEGER
False
NotifyWeb
BOOLEAN
False
NotifyEmail
BOOLEAN
False
EmailRecipients
TEXT[]
True
Created
TIMESTAMPTZ
False
Modified
TIMESTAMPTZ
False

AlertLog
Name
Type
Nullable
ID
BIGSERIAL
False
DeviceId
UUID
False
AlertType
VARCHAR(50)
False
Status
VARCHAR(20)
False
Message
TEXT
False
TriggeredAt
TIMESTAMPTZ
False
ResolvedAt
TIMESTAMPTZ
True
AckBy
UUID
True
AckAt
TIMESTAMPTZ
True
EmailSent
BOOLEAN
False
EmailSentAt
TIMESTAMPTZ
True


	•	API
AlertConfig

API
Method
Routes
Lấy cấu hình cảnh báo 
GET
-devices/{DeviceId}/alert-config
Tạo hoặc cập nhật cấu hình
PUT
- devices/{DeviceId}/alert-config
Test gửi email thử
POST
- devices/{DeviceId}/alert-config/test-email


		AlertLog

API
Method
Routes
Danh sách cảnh báo
- Paging: Page + Size
- SortBy:
+ TriggeredAt
+ Status
- FilterBy:
+ DeviceId
+ AlertType
+ Status (active/resolved)
+ DateFrom, DateTo
+ EmailSent	
GET
	•	alerts
	•	devices/{DeviceId}/alerts
Acknowledge cảnh báo
PATCH
	•	alerts/{AlertId}/acknowledge
Đánh dấu đã giải quyết
PATCH
	•	alerts/{AlertId}/resolve
Thống kê
GET
	•	alerts/summary
        Trả về : {totalActive, resolvedToday, topDevices}

