구글시트 예약 용량 계산 방법: 시간대별 남은 자리 자동 표시

// ===== 1단계: 장비 타입별 정원 설정 읽기 =====

// 여기만 본인 환경에 맞게 바꾸세요
const BOOK_CAPACITY_CONFIG = {                          // → 예약 용량 설정 모음
  SETTING_KEY_PREFIX: 'BOOK_CAPACITY_',                 // → SETTINGS 키 접두어
  DEFAULT_PER_HOUR: 2,                                  // → 설정 없을 때 기본 정원
  VALID_TYPES: ['CONTAINER', 'TRAILER']                 // → 허용 장비 종류
};                                                      // →

/**
 * 장비별 시간당 정원 조회
 * @param {string} equipType 장비 종류 (예: 'CONTAINER', 'TRAILER')
 * @return {number} 시간당 정원
 */
function BOOK_getCapacityForType_(equipType) {          // → 장비별 시간당 정원 조회
  if (!equipType) {                                     // → 장비 값이 비었는지 확인
    throw new Error('장비 종류가 비어 있습니다');        // → 오류로 중단
  }                                                     // →
  const upperType = String(equipType).toUpperCase();    // → 대문자로 정규화
  if (!BOOK_CAPACITY_CONFIG.VALID_TYPES.includes(upperType)) { // → 허용 목록 확인
    throw new Error('허용되지 않는 장비 종류: ' + equipType); // → 잘못된 값 거부
  }                                                     // →
  const settings = loadSettings_();                     // → 앞 편 SETTINGS 로딩 재사용
  const key = BOOK_CAPACITY_CONFIG.SETTING_KEY_PREFIX + upperType; // → SETTINGS 키 이름
  const raw = settings[key];                            // → 해당 키 값 읽기
  if (raw === undefined || raw === '') {                // → 값이 없으면
    return BOOK_CAPACITY_CONFIG.DEFAULT_PER_HOUR;       // → 기본 정원 반환
  }                                                     // →
  const capacity = Number(raw);                         // → 숫자로 변환
  // 정원은 '몇 대'라는 건수다. 2.5 는 통과시키면 안 된다 — isFinite 만 보면 통과한다.
  if (!Number.isSafeInteger(capacity) || capacity <= 0) { // → 1 이상의 정수만 허용
    throw new Error('정원은 1 이상의 정수여야 합니다: ' + raw); // → 설정 오류 알림
  }                                                     // →
  return capacity;                                      // → 정원 반환
}                                                       // →

/**
 * BOOK_getCapacityForType_ 동작 확인용 테스트 함수
 */
function BOOK_testGetCapacityForType_() {               // → 테스트용 함수
  const types = BOOK_CAPACITY_CONFIG.VALID_TYPES;       // → 허용 장비 목록
  const result = {};                                    // → 결과 저장 객체
  types.forEach(function(t) {                           // → 각 장비에 대해 반복
    result[t] = BOOK_getCapacityForType_(t);            // → 정원 조회
  });                                                   // →
  Logger.log(JSON.stringify(result));                   // → 결과를 로그에 출력
}                                                       // →

// ===== 2단계: 날짜별 시간·장비 사용량 집계 =====

// 여기만 본인 시트 구조에 맞게 바꾸세요
const BOOK_USAGE_CONFIG = {                             // → 사용량 계산 설정
  APPT_SHEET_NAME: 'APPT_MAIN',                         // → 예약 메인 시트 이름
  COL_DATE: 1,                                          // → 날짜 열 번호 (A=1)
  COL_TIME: 2,                                          // → 시간 열 번호 (B=2)
  COL_EQUIP_TYPE: 3                                     // → 장비 종류 열 번호 (C=3)
};                                                      // →

/**
 * 특정 날짜에 대해 시간대·장비별 예약 사용량을 계산
 * @param {Date} targetDate 기준 날짜(Date 객체)
 * @return {Object} {"HH:MM|장비": 사용건수} 형태의 객체
 */
function BOOK_getTimeUsageForDateCore_(targetDate) {    // → 날짜별 시간대 사용량 계산
  if (!(targetDate instanceof Date)) {                  // → 날짜 타입 확인
    throw new Error('Date 객체를 넘겨야 합니다');       // → 잘못된 입력 거부
  }                                                     // →
  const sheet = SpreadsheetApp                          // →
    .getActive()                                        // → 현재 스프레드시트
    .getSheetByName(BOOK_USAGE_CONFIG.APPT_SHEET_NAME); // → 예약 시트 가져오기
  if (!sheet) {                                         // → 시트 유무 확인
    throw new Error('예약 시트를 찾을 수 없습니다');   // → 설정 오류
  }                                                     // →
  const lastRow = sheet.getLastRow();                   // → 마지막 데이터 행 번호
  if (lastRow < 2) {                                    // → 헤더만 있는 경우
    return {};                                          // → 빈 결과 반환
  }                                                     // →
  const height = lastRow - 1;                           // → 데이터 행 개수
  // 필요한 열까지만 읽도록 width 조정 (실무에 맞게 최소화 권장)
  const width = BOOK_USAGE_CONFIG.COL_EQUIP_TYPE;       // → 읽을 열 개수
  const range = sheet.getRange(2, 1, height, width);    // → 2행부터 마지막 행까지
  const values = range.getValues();                     // → 한 번에 읽기
  const ymdTarget = APPT_ymd_(targetDate);              // → 기준 날짜 문자열
  const usage = {};                                     // → 결과 저장용 객체
  const badRows = [];                                   // → 셀 수 없었던 행 번호

  values.forEach(function(row, i) {                     // → 각 행 반복
    const rowNumber = i + 2;                            // → 실제 시트 행 번호
    const rowDate = row[BOOK_USAGE_CONFIG.COL_DATE - 1]; // → 날짜 셀
    const rowTime = row[BOOK_USAGE_CONFIG.COL_TIME - 1]; // → 시간 셀
    const equipType = row[BOOK_USAGE_CONFIG.COL_EQUIP_TYPE - 1]; // → 장비 종류 셀

    if (!rowDate && !rowTime && !equipType) {           // → 세 칸이 모두 빈 행
      return;                                           // → 진짜 빈 줄만 건너뛴다
    }                                                   // →
    // 여기서부터는 **조용히 넘기지 않는다.** 못 센 행은 사용량에서 빠지고,
    // 그러면 '자리가 남았다'로 계산돼 정원 초과 예약을 그대로 허용한다.
    if (!(rowDate instanceof Date) || !(rowTime instanceof Date)) { // → 텍스트로 저장된 행
      badRows.push(rowNumber);                          // → 기록해 두고
      return;                                           // → 이 행은 셀 수 없다
    }                                                   // →
    const upperType = String(equipType).toUpperCase();  // → 장비 대문자로
    if (!BOOK_CAPACITY_CONFIG.VALID_TYPES.includes(upperType)) { // → 허용 목록 밖 장비
      badRows.push(rowNumber);                          // → 이것도 못 센 행이다
      return;                                           // →
    }                                                   // →
    const ymd = APPT_ymd_(rowDate);                     // → 행의 날짜 문자열
    if (ymd !== ymdTarget) {                            // → 다른 날짜면
      return;                                           // → 건너뜀 (정상)
    }                                                   // →
    const hm = APPT_hm_(rowTime);                       // → HH:MM 문자열
    const key = hm + '|' + upperType;                   // → 시간+장비 조합 키
    if (!usage[key]) {                                  // → 처음 등장하면
      usage[key] = 0;                                   // → 0으로 초기화
    }                                                   // →
    usage[key] += 1;                                    // → 예약 1건 추가
  });                                                   // →

  if (badRows.length > 0) {                             // → 못 센 행이 하나라도 있으면
    throw new Error(                                    // → 숫자를 믿을 수 없으므로 멈춘다
      '셀 수 없는 예약 행이 있습니다(행 ' + badRows.slice(0, 10).join(', ') + '). ' +
      '날짜·시간이 텍스트로 저장됐거나 장비 종류가 허용 목록 밖입니다. ' +
      '이 행을 빼고 세면 자리가 남은 것으로 계산돼 정원 초과 예약을 허용하게 됩니다. ' +
      '기본 5편의 APPT_normalizeDateFormats() 로 정리한 뒤 다시 실행하세요.'
    );                                                  // →
  }                                                     // →

  return usage;                                         // → 시간·장비별 사용량 반환
}                                                       // →

/**
 * BOOK_getTimeUsageForDateCore_ 동작 확인용 테스트 함수
 */
function BOOK_testGetTimeUsageForDateCore_() {          // → 테스트용 함수
  const today = new Date();                             // → 오늘 날짜
  const usage = BOOK_getTimeUsageForDateCore_(today);   // → 사용량 계산
  Logger.log(JSON.stringify(usage));                    // → 결과 로그 출력
}                                                       // →

// ===== 3단계: 개별 슬롯(시간+장비) 남은 자리 계산 =====

/**
 * 한 슬롯(날짜+시간+장비)의 사용량·정원·남은 자리 계산
 * @param {Date} slotDate 예약 날짜(Date, 날짜 부분만 사용)
 * @param {Date} slotTime 예약 시간(Date, 시간·분 부분 사용)
 * @param {string} equipType 장비 종류
 * @return {Object} {time, equipType, used, capacity, remaining}
 */
function BOOK_getSeqUsageForSlotCore_(slotDate, slotTime, equipType) { // → 한 슬롯 사용·남은 자리 계산
  if (!(slotDate instanceof Date) || !(slotTime instanceof Date)) {   // → 날짜·시간 타입 확인
    throw new Error('날짜와 시간은 Date 타입이어야 합니다');         // → 잘못된 입력 거부
  }                                                                   // →
  const upperType = String(equipType).toUpperCase();                  // → 장비 대문자
  if (!BOOK_CAPACITY_CONFIG.VALID_TYPES.includes(upperType)) {        // → 허용 장비 확인
    throw new Error('허용되지 않는 장비 종류: ' + equipType);         // → 오류 알림
  }                                                                   // →
  const usageByKey = BOOK_getTimeUsageForDateCore_(slotDate);         // → 해당 날짜 전체 사용량
  const hm = APPT_hm_(slotTime);                                      // → HH:MM 문자열
  const key = hm + '|' + upperType;                                   // → 시간+장비 키
  const used = usageByKey[key] || 0;                                  // → 이미 사용된 수량
  const capacity = BOOK_getCapacityForType_(upperType);               // → 정원 조회
  const remaining = Math.max(capacity - used, 0);                     // → 남은 자리 (음수 방지)
  return {                                                            // → 결과 객체 반환
    time: hm,                                                         // → 시간 문자열
    equipType: upperType,                                             // → 장비 종류
    used: used,                                                       // → 사용 수량
    capacity: capacity,                                               // → 정원
    remaining: remaining                                              // → 남은 자리
  };                                                                  // →
}                                                                     // →

/**
 * BOOK_getSeqUsageForSlotCore_ 동작 확인용 테스트 함수
 */
function BOOK_testGetSeqUsageForSlotCore_() {                         // → 테스트용 함수
  const today = new Date();                                           // → 오늘 날짜
  const time = new Date(                                              // → 08:00 시간 객체
    today.getFullYear(),                                              // →
    today.getMonth(),                                                 // →
    today.getDate(),                                                  // →
    8, 0, 0                                                           // →
  );                                                                  // →
  const info = BOOK_getSeqUsageForSlotCore_(today, time, 'CONTAINER'); // → 08:00 컨테이너 정보
  Logger.log(JSON.stringify(info));                                   // → 결과 로그 출력
}                                                                     // →

// ===== 4단계: 정원 초과 방지를 위한 Lock 적용 패턴 (예시) =====

/**
 * 예시: 단일 예약 저장 로직 (정원 체크 + Lock)
 * 실제 환경에 맞게 시트명·열 구조 등을 수정해서 사용하세요.
 * @param {Object} payload {date, time, equipType, shipper, memo ...}
 * @return {Object} {ok: boolean, message: string}
 */
function BOOK_saveSingleBooking_(payload) {
  // 1) 입력 검증 (간단 예시)
  if (!payload || !payload.date || !payload.time || !payload.equipType) {
    return { ok: false, message: '필수 입력값이 누락되었습니다.' };
  }

  // '2026-08-03' 을 new Date() 에 그대로 넣으면 UTC 자정으로 읽혀 하루가 밀리고,
  // '09:00' 은 아예 Invalid Date 가 된다. 기본 5편 도우미로 검증한 뒤 직접 만든다.
  let slotDate;
  let slotTime;
  try {
    const ymdText = APPT_ymd_(payload.date);            // 형식·실재 날짜까지 검증
    const hmText = APPT_hm_(payload.time);              // '09:00' 도 안전하게 읽는다
    const dp = ymdText.split('-');
    const tp = hmText.split(':');
    slotDate = new Date(Number(dp[0]), Number(dp[1]) - 1, Number(dp[2]));
    slotTime = new Date(1899, 11, 30, Number(tp[0]), Number(tp[1]));
  } catch (e) {
    return { ok: false, message: '날짜·시간 형식이 올바르지 않습니다: ' + e.message };
  }
  const equipType = String(payload.equipType).toUpperCase();

  // 2) 스크립트 잠금 획득
  const lock = LockService.getScriptLock();
  try {
    lock.waitLock(30 * 1000); // 최대 30초 대기 (실무 환경에 맞게 조정)

    // 3) 잠금이 잡힌 상태에서 최신 남은 자리 계산
    const slotInfo = BOOK_getSeqUsageForSlotCore_(slotDate, slotTime, equipType);
    if (slotInfo.remaining <= 0) {
      return {
        ok: false,
        message: Utilities.formatString(
          '[정원 초과] %s %s %s 시간대는 정원이 이미 가득 찼습니다.',
          APPT_ymd_(slotDate),
          slotInfo.time,
          equipType
        )
      };
    }

    // 4) 남은 자리가 1개 이상이면 실제 저장
    const sheet = SpreadsheetApp
      .getActive()
      .getSheetByName(BOOK_USAGE_CONFIG.APPT_SHEET_NAME);

    if (!sheet) {
      return { ok: false, message: '예약 시트를 찾을 수 없습니다.' };
    }

    // 예시: 마지막 행 뒤에 예약 한 줄 추가 (열 구조는 프로젝트별로 맞추세요)
    const lastRow = sheet.getLastRow();
    const newRow = lastRow + 1;

    // A: 날짜, B: 시간, C: 장비, D: 화주, E: 메모 라는 가정
    // 열마다 따로 쓰면 중간에 오류가 났을 때 **반만 채워진 행**이 남는다.
    // 한 줄을 배열로 만들어 setValues 한 번에 쓴다.
    const rowValues = [
      slotDate,                                   // A: 날짜
      slotTime,                                   // B: 시간
      equipType,                                  // C: 장비
      payload.shipper || '',                      // D: 화주
      payload.memo || ''                          // E: 메모
    ];
    sheet.getRange(newRow, 1, 1, rowValues.length).setValues([rowValues]);
    sheet.getRange(newRow, BOOK_USAGE_CONFIG.COL_DATE).setNumberFormat('yyyy-MM-dd');
    sheet.getRange(newRow, BOOK_USAGE_CONFIG.COL_TIME).setNumberFormat('HH:mm');

    return {
      ok: true,
      message: Utilities.formatString(
        '%s %s %s 예약이 저장되었습니다. (남은 자리: %d → %d)',
        APPT_ymd_(slotDate),
        slotInfo.time,
        equipType,
        slotInfo.remaining,
        slotInfo.remaining - 1
      )
    };
  } catch (e) {
    // 개발자/운영자 확인용 로그
    console.error('BOOK_saveSingleBooking_ 오류:', e);
    return { ok: false, message: '예약 저장 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.' };
  } finally {
    // 5) 잠금 해제
    try {
      lock.releaseLock();
    } catch (e) {
      // releaseLock 실패는 보통 치명적이지 않으므로 조용히 로그만 남김
      console.warn('Lock release 실패:', e);
    }
  }
}