"""Thư viện dùng chung ghi log chuẩn hóa cho toàn bộ hệ thống AutoPOE2.

Module này cung cấp cấu hình logger phân cấp chuẩn, định dạng đồng nhất
và các hàm tiện ích ghi nhận ngoại lệ không nuốt lỗi, tuân thủ nghiêm ngặt
quy tắc chống nuốt lỗi (Anti-Symptom Patching & Rule 16).
"""

import logging
import sys
import traceback
from typing import Optional

# Định dạng nhật ký chuẩn cho hệ sinh thái AutoPOE2
DEFAULT_LOG_FORMAT = "[%(asctime)s.%(msecs)03d] [%(levelname)s] [%(name)s]: %(message)s"
DEFAULT_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"


def get_logger(name: str = "AutoPOE2", level: int = logging.INFO) -> logging.Logger:
    """Khởi tạo hoặc trích xuất Logger phân cấp chuẩn cho module chỉ định.

    Tự động cấu hình StreamHandler xuất ra stdout với định dạng chuẩn mực nếu
    logger chưa có handler nào được đăng ký. Tránh trùng lặp handler khi gọi nhiều lần.

    Args:
        name: Tên của logger (thường là __name__ hoặc tên module nghiệp vụ).
        level: Cấp độ ghi nhận nhật ký (mặc định logging.INFO).

    Returns:
        logging.Logger: Đối tượng logger đã được cấu hình chuẩn.

    Example:
        >>> logger = get_logger("VisualWatcher")
        >>> logger.info("Khởi động hệ thống quan sát thành công.")
    """
    logger = logging.getLogger(name)
    logger.setLevel(level)

    if not logger.handlers:
        handler = logging.StreamHandler(sys.stdout)
        handler.setLevel(level)
        formatter = logging.Formatter(fmt=DEFAULT_LOG_FORMAT, datefmt=DEFAULT_DATE_FORMAT)
        handler.setFormatter(formatter)
        logger.addHandler(handler)

    return logger


def log_exception(
    logger: logging.Logger,
    context: str,
    exc: Optional[BaseException] = None,
    level: int = logging.ERROR,
) -> None:
    """Ghi nhận chi tiết ngoại lệ kèm ngữ cảnh và traceback đầy đủ.

    Hàm này được thiết kế để triệt tiêu hoàn toàn các khối 'except: pass' vô trách nhiệm,
    đảm bảo mọi ngoại lệ trong runtime đều được lưu vết chi tiết phục vụ điều tra nguyên
    nhân gốc rễ (Root Cause Analysis - Rule 8).

    Args:
        logger: Logger dùng để ghi nhận ngoại lệ.
        context: Chuỗi mô tả ngữ cảnh xảy ra lỗi (ví dụ: "Đọc cấu hình visual_tool thất bại").
        exc: Đối tượng ngoại lệ (nếu None, tự động trích xuất từ sys.exc_info()).
        level: Cấp độ log dùng để ghi nhận (mặc định logging.ERROR).

    Returns:
        None.

    Example:
        >>> try:
        ...     risky_operation()
        ... except Exception as e:
        ...     log_exception(logger, "Thực thi tác vụ mạo hiểm", e)
    """
    if exc is None:
        exc_type, exc_val, exc_tb = sys.exc_info()
        exc = exc_val

    if exc is not None:
        tb_str = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
        logger.log(level, f"[EXCEPTION] {context} - {type(exc).__name__}: {exc}\n{tb_str}")
    else:
        logger.log(level, f"[EXCEPTION] {context} - Không trích xuất được thông tin traceback.")