NetworkDeviceManagementSystem/backend/modules/monitor_config/schemas.py

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