import calendar


def 取某季度结束时间(年份: int, 季度: int) -> str | None:
    """返回指定年份和季度的结束时间。

    功能说明:
        - 这个函数用于直接指定“某一年第几季度”，然后得到这个季度结束的时刻。
        - 季度只能填写 ``1``、``2``、``3``、``4``。
        - 如果年份或季度不合法，函数返回 ``None``。

    Args:
        年份: 要查询的年份。
        季度: 要查询的季度。

    Returns:
        成功时返回季度结束时间；失败时返回 ``None``。
    """
    try:
        年份 = int(年份)
        季度 = int(季度)
        if 年份 <= 0 or 季度 not in (1, 2, 3, 4):
            return None
        结束月份 = 季度 * 3
        月末天数 = calendar.monthrange(年份, 结束月份)[1]
        return f"{年份:04}-{结束月份:02}-{月末天数:02} 23:59:59"
    except Exception:
        return None


if __name__ == "__main__":
    print("===== 示例1：取 2026 年第 1 季度结束时间 =====")
    print("结果:", 取某季度结束时间(2026, 1))

    print("\n===== 示例2：取 2026 年第 3 季度结束时间 =====")
    print("结果:", 取某季度结束时间(2026, 3))

    print("\n===== 示例3：传入字符串参数 =====")
    print("结果:", 取某季度结束时间("2024", "4"))

    print("\n===== 示例4：季度超出范围 =====")
    print("结果:", 取某季度结束时间(2026, 5))

    print("\n===== 示例5：年份不合法 =====")
    print("结果:", 取某季度结束时间(0, 1))

    print("\n===== 示例6：应用场景-生成历史季度查询截止时间 =====")
    print("查询结束:", 取某季度结束时间(2025, 2))
