TK-FB-Project/api.hyungi.net/utils/dateUtils.js

/**
 * 날짜/시간 유틸리티 함수
 *
 * 중요: 이 프로젝트는 한국(Asia/Seoul, UTC+9) 시간대 기준으로 운영됩니다.
 * DB에 저장되는 비즈니스 날짜(report_date, session_date 등)는 반드시 한국 시간 기준이어야 합니다.
 *
 * @author TK-FB-Project
 * @since 2026-02-03
 */

const KOREA_TIMEZONE_OFFSET = 9; // UTC+9

/**
 * 한국 시간(KST) 기준 현재 Date 객체 반환
 * @returns {Date} 한국 시간 기준 Date 객체
 */
function getKoreaDate() {
  const now = new Date();
  return new Date(now.getTime() + (KOREA_TIMEZONE_OFFSET * 60 * 60 * 1000));
}

/**
 * 한국 시간(KST) 기준 현재 날짜 문자열 반환
 * @returns {string} 'YYYY-MM-DD' 형식
 */
function getKoreaDateString() {
  const koreaDate = getKoreaDate();
  const year = koreaDate.getUTCFullYear();
  const month = String(koreaDate.getUTCMonth() + 1).padStart(2, '0');
  const day = String(koreaDate.getUTCDate()).padStart(2, '0');
  return `${year}-${month}-${day}`;
}

/**
 * 한국 시간(KST) 기준 현재 datetime 문자열 반환
 * @returns {string} 'YYYY-MM-DD HH:mm:ss' 형식 (MySQL DATETIME 호환)
 */
function getKoreaDatetime() {
  const koreaDate = getKoreaDate();
  const year = koreaDate.getUTCFullYear();
  const month = String(koreaDate.getUTCMonth() + 1).padStart(2, '0');
  const day = String(koreaDate.getUTCDate()).padStart(2, '0');
  const hours = String(koreaDate.getUTCHours()).padStart(2, '0');
  const minutes = String(koreaDate.getUTCMinutes()).padStart(2, '0');
  const seconds = String(koreaDate.getUTCSeconds()).padStart(2, '0');
  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
}

/**
 * 한국 시간(KST) 기준 현재 시간 문자열 반환
 * @returns {string} 'HH:mm:ss' 형식
 */
function getKoreaTimeString() {
  const koreaDate = getKoreaDate();
  const hours = String(koreaDate.getUTCHours()).padStart(2, '0');
  const minutes = String(koreaDate.getUTCMinutes()).padStart(2, '0');
  const seconds = String(koreaDate.getUTCSeconds()).padStart(2, '0');
  return `${hours}:${minutes}:${seconds}`;
}

/**
 * UTC Date를 한국 시간 datetime 문자열로 변환
 * @param {Date} date - UTC 기준 Date 객체
 * @returns {string} 'YYYY-MM-DD HH:mm:ss' 형식
 */
function toKoreaDatetime(date) {
  if (!date) return null;
  const koreaDate = new Date(date.getTime() + (KOREA_TIMEZONE_OFFSET * 60 * 60 * 1000));
  const year = koreaDate.getUTCFullYear();
  const month = String(koreaDate.getUTCMonth() + 1).padStart(2, '0');
  const day = String(koreaDate.getUTCDate()).padStart(2, '0');
  const hours = String(koreaDate.getUTCHours()).padStart(2, '0');
  const minutes = String(koreaDate.getUTCMinutes()).padStart(2, '0');
  const seconds = String(koreaDate.getUTCSeconds()).padStart(2, '0');
  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
}

/**
 * UTC Date를 한국 날짜 문자열로 변환
 * @param {Date} date - UTC 기준 Date 객체
 * @returns {string} 'YYYY-MM-DD' 형식
 */
function toKoreaDateString(date) {
  if (!date) return null;
  const koreaDate = new Date(date.getTime() + (KOREA_TIMEZONE_OFFSET * 60 * 60 * 1000));
  const year = koreaDate.getUTCFullYear();
  const month = String(koreaDate.getUTCMonth() + 1).padStart(2, '0');
  const day = String(koreaDate.getUTCDate()).padStart(2, '0');
  return `${year}-${month}-${day}`;
}

/**
 * 한국 시간 datetime 문자열을 Date 객체로 변환
 * @param {string} koreaDatetimeStr - 'YYYY-MM-DD HH:mm:ss' 형식
 * @returns {Date} UTC 기준 Date 객체
 */
function fromKoreaDatetime(koreaDatetimeStr) {
  if (!koreaDatetimeStr) return null;
  // 한국 시간 문자열을 UTC로 변환
  const date = new Date(koreaDatetimeStr + '+09:00');
  return date;
}

/**
 * 연도 반환 (한국 시간 기준)
 * @returns {number} 현재 연도
 */
function getKoreaYear() {
  return getKoreaDate().getUTCFullYear();
}

/**
 * 월 반환 (한국 시간 기준, 1-12)
 * @returns {number} 현재 월 (1-12)
 */
function getKoreaMonth() {
  return getKoreaDate().getUTCMonth() + 1;
}

module.exports = {
  KOREA_TIMEZONE_OFFSET,
  getKoreaDate,
  getKoreaDateString,
  getKoreaDatetime,
  getKoreaTimeString,
  toKoreaDatetime,
  toKoreaDateString,
  fromKoreaDatetime,
  getKoreaYear,
  getKoreaMonth,
};