"""
配置管理模块 — 公共模块 (Person E 可以先完成)

功能: 加载 YAML 配置，支持命令行覆盖和多配置合并。
"""

from __future__ import annotations

import logging
from pathlib import Path
from typing import Any, Optional

from omegaconf import OmegaConf, DictConfig

logger = logging.getLogger(__name__)


def load_config(config_path: str | Path) -> DictConfig:
    """
    加载 YAML 配置文件。

    TODO [Person E]: 实现以下逻辑:
    1. 使用 OmegaConf.load(config_path) 加载配置
    2. 验证配置完整性
    3. 返回 DictConfig 对象
    """
    raise NotImplementedError("TODO: Person E 实现 load_config")


def merge_configs(base_config: DictConfig, override_config: DictConfig) -> DictConfig:
    """
    合并配置 (override 覆盖 base)。

    TODO [Person E]:
    使用 OmegaConf.merge(base_config, override_config)
    """
    raise NotImplementedError("TODO: Person E 实现 merge_configs")


def config_from_cli(config_path: str, cli_args: list[str]) -> DictConfig:
    """
    从配置文件 + 命令行参数构建最终配置。

    TODO [Person E]:
    1. 加载 config_path
    2. 使用 OmegaConf.from_cli(cli_args) 解析命令行参数
    3. 合并并返回

    使用方式: python train.py --config configs/default.yaml training.lr=1e-4 model.nhead=16
    """
    raise NotImplementedError("TODO: Person E 实现 config_from_cli")