from datetime import datetime, timedelta


def 取本月结束时间(时间字符串: str | None = None) -> str | None:
    """返回指定日期所在月份的结束时间。

    功能说明:
        - 这个函数用于把某个日期定位到它所在月份的最后一天，并返回当天的 ``23:59:59``。
        - 适合做月报截止时间、月度订单查询截止时间、账单周期结束时间。
        - 支持传入日期和完整时间两种格式。
        - 输入格式不正确时，函数返回 ``None``。

    Args:
        时间字符串: ``YYYY-MM-DD`` 或 ``YYYY-MM-DD HH:MM:SS`` 格式的日期时间字符串。

    Returns:
        成功时返回月末时间字符串；失败时返回 ``None``。
    """
    try:
        if 时间字符串 is None:
            日期对象 = datetime.now().date()
        else:
            时间字符串 = 时间字符串.strip()
            if len(时间字符串) == 10:
                日期对象 = datetime.strptime(时间字符串, "%Y-%m-%d").date()
            else:
                日期对象 = datetime.strptime(时间字符串, "%Y-%m-%d %H:%M:%S").date()

        if 日期对象.month == 12:
            下月月初 = 日期对象.replace(year=日期对象.year + 1, month=1, day=1)
        else:
            下月月初 = 日期对象.replace(month=日期对象.month + 1, day=1)

        月结束日期 = 下月月初 - timedelta(days=1)
        return f"{月结束日期} 23:59:59"
    except Exception:
        return None


if __name__ == "__main__":
    print("===== 示例1：传入日期，取当月结束时间 =====")
    print("结果:", 取本月结束时间("2026-03-20"))

    print("\n===== 示例2：传入完整时间，取当月结束时间 =====")
    print("结果:", 取本月结束时间("2026-03-20 18:30:45"))

    print("\n===== 示例3：不传参数，取当前月份结束时间 =====")
    print("结果:", 取本月结束时间())

    print("\n===== 示例4：闰年的 2 月结束时间 =====")
    print("结果:", 取本月结束时间("2024-02-10"))

    print("\n===== 示例5：输入错误格式 =====")
    print("结果:", 取本月结束时间("2026/03/20"))

    print("\n===== 示例6：应用场景-生成月账单统计截止时间 =====")
    账单日期 = "2026-12-08 11:20:00"
    print("账单统计截止:", 取本月结束时间(账单日期))
