Device

backend/modules/monitor_config/schemas.py

@@ -0,0 +1,164 @@
+# pyrefly: ignore [missing-import]
+from marshmallow import Schema, fields, validate
+
+# ============================================
+# SCHEMAS: Validate dữ liệu đầu vào cho Monitor Config
+# ============================================
+# Luồng đi: Client gửi JSON body → Controller nhận → Schema validate → Service xử lý
+# Nếu dữ liệu không hợp lệ → Marshmallow ném ValidationError → Global handler trả 400
+# ============================================
+
+# Danh sách các SNMP version hệ thống hỗ trợ
+VALID_SNMP_VERSIONS = ["v1", "v2c", "v3"]
+
+
+class UpdateMonitorConfigSchema(Schema):
+    """
+    Schema để validate dữ liệu khi cập nhật cấu hình giám sát.
+    Tất cả các trường đều optional vì người dùng có thể chỉ cập nhật một phần.
+    
+    Ví dụ request body:
+    {
+        "enable_ping": true,
+        "ping_interval": 30,
+        "enable_snmp": true,
+        "snmp_community": "public",
+        "snmp_version": "v2c"
+    }
+    """
+
+    # ─── Cấu hình Ping (ICMP) ────────────────────────
+    enable_ping = fields.Boolean(required=False)
+
+    ping_count = fields.Integer(
+        required=False,
+        validate=validate.Range(min=1, max=10)
+        # Số lượng gói tin ping gửi mỗi lần kiểm tra
+        # min=1: ít nhất 1 gói, max=10: tránh gửi quá nhiều gây tải mạng
+    )
+
+    ping_timeout = fields.Integer(
+        required=False,
+        validate=validate.Range(min=1, max=30)
+        # Thời gian chờ phản hồi tối đa (giây)
+        # Nếu thiết bị không phản hồi trong khoảng này → coi như timeout
+    )
+
+    ping_interval = fields.Integer(
+        required=False,
+        validate=validate.Range(min=5, max=86400)
+        # Tần suất kiểm tra (giây): min=5s (thiết bị quan trọng), max=86400s (1 ngày)
+        # APScheduler sẽ chạy job Ping theo interval này
+    )
+
+    # ─── Cấu hình SNMP ───────────────────────────────
+    enable_snmp = fields.Boolean(required=False)
+
+    snmp_version = fields.String(
+        required=False,
+        allow_none=True,
+        validate=validate.OneOf(VALID_SNMP_VERSIONS)
+        # Chỉ chấp nhận: "v1", "v2c", "v3"
+    )
+
+    snmp_community = fields.String(
+        required=False,
+        allow_none=True,
+        validate=validate.Length(max=256)
+        # Community string dùng để xác thực SNMP (ví dụ: "public", "private")
+    )
+
+    snmp_port = fields.Integer(
+        required=False,
+        allow_none=True,
+        validate=validate.Range(min=1, max=65535)
+        # Port SNMP mặc định là 161, nhưng cho phép tùy chỉnh
+    )
+
+    snmp_interval = fields.Integer(
+        required=False,
+        allow_none=True,
+        validate=validate.Range(min=5, max=86400)
+        # Tần suất kiểm tra SNMP (giây), tương tự ping_interval
+    )
+
+    snmp_timeout = fields.Integer(
+        required=False,
+        allow_none=True,
+        validate=validate.Range(min=1, max=30)
+        # Thời gian chờ phản hồi SNMP tối đa (giây)
+    )
+
+    snmp_custom_oids = fields.Dict(
+        required=False,
+        allow_none=True
+        # Danh sách OID tùy chỉnh dưới dạng JSON object
+        # Ví dụ: {"sysName": "1.3.6.1.2.1.1.5.0", "ifNumber": "1.3.6.1.2.1.2.1.0"}
+        # Lưu vào PostgreSQL dưới dạng JSONB
+    )
+
+
+class TestConnectionSchema(Schema):
+    """
+    Schema để validate dữ liệu khi người dùng bấm nút "Test kết nối".
+    Cho phép test trước khi lưu cấu hình — client truyền lên cấu hình tạm để test.
+    
+    Luồng đi:
+    1. Người dùng nhập cấu hình trên giao diện (chưa bấm Lưu)
+    2. Bấm nút "Test" → Client gửi POST /api/devices/{id}/monitor-config/test
+    3. Server nhận cấu hình tạm → Chạy Ping/SNMP test ngay lập tức
+    4. Trả kết quả (Up/Down, RTT, chi tiết) → Hiển thị trên giao diện
+    5. Nếu OK → Người dùng mới bấm "Lưu" để PUT cập nhật cấu hình thực
+    """
+
+    # Test ping hay snmp?
+    test_ping = fields.Boolean(
+        required=False,
+        load_default=True
+        # Mặc định test ping
+    )
+
+    test_snmp = fields.Boolean(
+        required=False,
+        load_default=False
+    )
+
+    # ─── Tham số Ping (dùng cho test) ─────────────────
+    ping_count = fields.Integer(
+        required=False,
+        load_default=3,
+        validate=validate.Range(min=1, max=10)
+    )
+
+    ping_timeout = fields.Integer(
+        required=False,
+        load_default=5,
+        validate=validate.Range(min=1, max=30)
+    )
+
+    # ─── Tham số SNMP (dùng cho test) ─────────────────
+    snmp_version = fields.String(
+        required=False,
+        allow_none=True,
+        validate=validate.OneOf(VALID_SNMP_VERSIONS)
+    )
+
+    snmp_community = fields.String(
+        required=False,
+        allow_none=True,
+        validate=validate.Length(max=256)
+    )
+
+    snmp_port = fields.Integer(
+        required=False,
+        allow_none=True,
+        load_default=161,
+        validate=validate.Range(min=1, max=65535)
+    )
+
+    snmp_timeout = fields.Integer(
+        required=False,
+        allow_none=True,
+        load_default=5,
+        validate=validate.Range(min=1, max=30)
+    )