minglei/IntegrateDingTalkOA/src/main/java/com/example/integratedingtalkoa/util/TimeUtil.java

package com.example.integratedingtalkoa.util;

import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;

/**
 * 时间工具类。
 *
 * <p>提供当前时间、当前毫秒级时间戳、指定格式时间转时间戳、
 * 以及按天、月、年对时间戳进行加减计算的常用方法。</p>
 */
public final class TimeUtil {

    /**
     * 默认时间格式：yyyy-MM-dd HH:mm:ss。
     *
     * <p>注意：Java 中 HH 表示 24 小时制，hh 表示 12 小时制。
     * 为了兼容常见输入，本工具类对外说明仍按 yyyy-MM-dd hh:mm:ss 理解，
     * 实际推荐传入 24 小时制时间，例如 2026-08-04 11:03:51。</p>
     */
    private static final String DEFAULT_PATTERN = "yyyy-MM-dd HH:mm:ss";

    /**
     * 默认系统时区。
     */
    private static final ZoneId DEFAULT_ZONE_ID = ZoneId.systemDefault();

    /**
     * 默认时间格式化器。
     */
    private static final DateTimeFormatter DEFAULT_FORMATTER = DateTimeFormatter.ofPattern(DEFAULT_PATTERN);

    private TimeUtil() {
    }

    /**
     * 获取当前时间字符串。
     *
     * @return 当前时间，格式为 yyyy-MM-dd HH:mm:ss
     */
    public static String getCurrentTime() {
        return LocalDateTime.now().format(DEFAULT_FORMATTER);
    }

    /**
     * 获取当前毫秒级时间戳。
     *
     * @return 当前毫秒级时间戳
     */
    public static long getCurrentTimestamp() {
        return System.currentTimeMillis();
    }

    /**
     * 将 yyyy-MM-dd HH:mm:ss 格式的时间字符串转换为毫秒级时间戳。
     *
     * @param dateTime 时间字符串，例如 2026-08-04 11:03:51
     * @return 对应的毫秒级时间戳
     */
    public static long toTimestamp(String dateTime) {
        if (dateTime == null || dateTime.trim().length() == 0) {
            throw new IllegalArgumentException("时间字符串不能为空");
        }
        LocalDateTime localDateTime = LocalDateTime.parse(dateTime.trim(), DEFAULT_FORMATTER);
        return localDateTime.atZone(DEFAULT_ZONE_ID).toInstant().toEpochMilli();
    }

    /**
     * 将毫秒级时间戳转换为 yyyy-MM-dd HH:mm:ss 格式的时间字符串。
     *
     * @param timestampMillis 毫秒级时间戳
     * @return 时间字符串
     */
    public static String toDateTime(long timestampMillis) {
        return LocalDateTime.ofInstant(java.time.Instant.ofEpochMilli(timestampMillis), DEFAULT_ZONE_ID)
                .format(DEFAULT_FORMATTER);
    }

    /**
     * 时间戳增加指定天数。
     *
     * @param timestampMillis 毫秒级时间戳
     * @param days 增加的天数
     * @return 计算后的毫秒级时间戳
     */
    public static long plusDays(long timestampMillis, long days) {
        return LocalDateTime.ofInstant(java.time.Instant.ofEpochMilli(timestampMillis), DEFAULT_ZONE_ID)
                .plusDays(days)
                .atZone(DEFAULT_ZONE_ID)
                .toInstant()
                .toEpochMilli();
    }

    /**
     * 时间戳减少指定天数。
     *
     * @param timestampMillis 毫秒级时间戳
     * @param days 减少的天数
     * @return 计算后的毫秒级时间戳
     */
    public static long minusDays(long timestampMillis, long days) {
        return plusDays(timestampMillis, -days);
    }

    /**
     * 时间戳增加指定月数。
     *
     * @param timestampMillis 毫秒级时间戳
     * @param months 增加的月数
     * @return 计算后的毫秒级时间戳
     */
    public static long plusMonths(long timestampMillis, long months) {
        return LocalDateTime.ofInstant(java.time.Instant.ofEpochMilli(timestampMillis), DEFAULT_ZONE_ID)
                .plusMonths(months)
                .atZone(DEFAULT_ZONE_ID)
                .toInstant()
                .toEpochMilli();
    }

    /**
     * 时间戳减少指定月数。
     *
     * @param timestampMillis 毫秒级时间戳
     * @param months 减少的月数
     * @return 计算后的毫秒级时间戳
     */
    public static long minusMonths(long timestampMillis, long months) {
        return plusMonths(timestampMillis, -months);
    }

    /**
     * 时间戳增加指定年数。
     *
     * @param timestampMillis 毫秒级时间戳
     * @param years 增加的年数
     * @return 计算后的毫秒级时间戳
     */
    public static long plusYears(long timestampMillis, long years) {
        return LocalDateTime.ofInstant(java.time.Instant.ofEpochMilli(timestampMillis), DEFAULT_ZONE_ID)
                .plusYears(years)
                .atZone(DEFAULT_ZONE_ID)
                .toInstant()
                .toEpochMilli();
    }

    /**
     * 时间戳减少指定年数。
     *
     * @param timestampMillis 毫秒级时间戳
     * @param years 减少的年数
     * @return 计算后的毫秒级时间戳
     */
    public static long minusYears(long timestampMillis, long years) {
        return plusYears(timestampMillis, -years);
    }
}