교사 김민기(민기쌤) 연수 아카이브 | 민기.한국

충청북도교육청 AI 레벨업 (성찰) 연수

Sun, 06 Sep 2026 05:15:01 GMT

충청북도교육청 AI 레벨업 (성찰) 연수

강사: 교사 김민기(민기쌤)
일시: 2026-11-06
장소: 한국교원대학교

충청북도교육청 교사를 위한 AI 레벨업 - 성찰 단계 연수입니다.

강의 자료

[제공용] 1~3차시-최종수정본.pdf

충남온수업 미래교육배움터 제미나이, 챗GPT

Thu, 17 Sep 2026 05:55:43 GMT

충남온수업 미래교육배움터 제미나이, 챗GPT

강사: 교사 김민기(민기쌤)
일시: 2026-09-17
장소: 충청남도교육청 교육연수원

강의 자료

2026년도 일부개정 학교폭력 사안처리 가이드북(단면).pdf

ChatGPT로 이미지 만들기

웹캠으로 찍은 교사 사진을 이모티콘 세트로 만들기

첨부한 내 사진을 참고하여 교사가 수업 자료, 학급 안내, 온라인 게시판에서 사용할 수 있는 이모티콘 세트를 만들어 줘.

사진 속 사람의 얼굴 특징, 헤어스타일, 안경 여부, 전체적인 인상을 최대한 유지해 줘. 실제 사진을 그대로 복제한 느낌보다는 깔끔하고 친근한 2D 캐릭터 일러스트 스타일로 표현해 줘.

한 화면에 동일한 인물의 이모티콘 9개를 3×3 배열로 배치해 줘.

표정과 동작은 다음과 같이 구성해 줘.
1. 엄지손가락을 들며 잘했어요
2. 두 손을 모으며 감사합니다
3. 손가락으로 앞을 가리키며 여기를 보세요
4. 놀란 표정
5. 웃으며 박수치는 모습
6. 고민하는 표정
7. 힘내라는 의미로 주먹을 쥔 모습
8. 조용히 하라는 의미로 검지를 입 앞에 댄 모습
9. 손을 흔들며 인사하는 모습

교실에서 학생에게 보여 주기 적절한 표정으로 만들어 줘.
과도하게 귀엽거나 유아용 캐릭터처럼 표현하지 말고, 중고등학교 교사가 사용하기 좋은 단정한 느낌으로 만들어 줘.

각 이모티콘의 얼굴 비율, 옷, 헤어스타일, 그림체를 완전히 통일해 줘.
배경은 투명하게 처리해 줘.
말풍선과 글자는 넣지 마.
각 캐릭터 주변에는 충분한 여백을 두어 나중에 하나씩 잘라 사용할 수 있게 만들어 줘.

모의고사나 시험지용 흑백 삽화 만들기

지필평가 시험지에 사용할 교육용 삽화를 만들어 줘.

장면:
교실에서 교사 한 명과 중학생 한 명이 대화하고 있다.
교사는 학생을 바라보며 설명하고 있고, 학생은 교사의 말을 들은 뒤 대답한다.

표현 방식:
간결한 선화 스타일. 완전한 흑백.
회색 음영과 색채는 최소화하고 흰 배경을 유지할 것.
굵고 명확한 검은 선을 사용할 것.
가는 선이나 복잡한 질감은 피할 것.
복사기와 학교용 갱지에 인쇄했을 때도 인물과 사물이 명확히 구별되게 할 것.

구성:
등장인물은 필요한 사람만 배치할 것.
배경에는 책상과 칠판 정도만 최소한으로 표현할 것.
장식용 소품, 포스터, 창밖 풍경, 책 제목 등 문항 이해와 관계없는 요소는 넣지 말 것.
인물의 표정도 과장하지 말 것.
그림 자체가 정답에 대한 추가 단서를 제공해서는 안 된다.

중요:
그림 안에는 어떠한 한글, 영어, 숫자, 기호도 넣지 말 것.
말풍선은 비워 둘 것.
텍스트는 시험지 편집 과정에서 별도로 삽입할 예정이다.
이미지만 생성할 것.

가로형 삽화로 만들고, A4 시험지의 절반 폭 정도에 배치했을 때 선명하게 보이도록 단순하고 명확하게 구성해 줘.

학교 행사 포스터 만들기

학교 행사 포스터를 만들어 줘.

행사명:
함께 만드는 존중의 학교

대상:
중학생

목적:
학교폭력 예방과 존중하는 언어생활을 학생들에게 안내하는 교내 게시용 포스터.

전체 분위기:
중학생에게 유치해 보이지 않으면서 밝고 친근한 교육 포스터.
공공기관이나 교육청 캠페인 자료처럼 단정하고 신뢰감 있는 디자인.
지나치게 화려한 광고 디자인은 피할 것.

레이아웃:
맨 위에 행사명이 가장 크게 보이도록 구성.
중앙에 핵심 일러스트.
아래쪽에는 행사 날짜, 장소, 안내 내용.

A3 세로형 포스터 비율.
멀리서 보아도 중심 이미지가 명확하게 인식되게 만들어 줘.
인쇄했을 때 지나치게 어두워지지 않도록 흰색 계열의 여백을 충분히 확보해 줘.

행사에 대한 정보:
- 행사명: 「말 한마디가 학교를 바꿉니다」 존중 언어 실천 행사
- 학생들이 일상에서 사용하는 말을 돌아보고, 친구에게 존중과 배려가 담긴 표현을 직접 전달하는 학교폭력 예방 행사입니다.
- 운영은 점심시간과 등교시간을 활용해 1일 행사로 진행합니다. 학생에게 작은 카드 한 장을 나누어 주고, 친구에게 전하고 싶은 존중의 말을 적게 합니다. 예를 들면 “네가 있어서 우리 반이 더 편해”, “지난번에 도와줘서 고마워”, “내가 장난으로 했던 말이 불편했다면 미안해”처럼 구체적인 표현을 쓰도록 안내합니다.
- 작성한 카드는 친구에게 직접 전달하거나 중앙현관에 설치한 「존중의 말 게시판」에 붙입니다. 학생회가 참여해 좋은 표현 일부를 선정하고 점심시간 방송이나 학교 게시판을 통해 소개합니다.

충남교육청 AI 에듀테크 활용 역량강화 연수

Sat, 12 Sep 2026 00:17:57 GMT

충남교육청 AI 에듀테크 활용 역량강화 연수

강사: 교사 김민기(민기쌤)
일시: 2026-09-12
장소: 캠코인재개발원

강의 자료

생기부 점검

Code.gs

// =================================================================
// [0] 초기 설정 및 메뉴
// =================================================================

var MAX_STUDENT_ROWS_ = 40;

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('민기쌤 생기부 도우미')
    .addItem('🚀 사이드바 열기', 'openSidebar')
    .addToUi();
}

function renderView_(viewName, viewData) {
  var template = HtmlService.createTemplateFromFile('Sidebar');

  template.initialView = viewName || 'sidebar';
  template.initialDataJson = JSON.stringify(viewData || {});

  return template.evaluate();
}

function openSidebar() {
  ensureBannedWordSheet_();

  var html = renderView_('sidebar')
    .setTitle('민기쌤 생기부 맞춤법 도우미')
    .setWidth(300);

  SpreadsheetApp.getUi().showSidebar(html);
}

function openSpellCheckViewer() {
  assertSelectionWithinLimit_();

  var html = renderView_('spellcheck')
    .setWidth(1000)
    .setHeight(700);

  SpreadsheetApp.getUi().showModelessDialog(
    html,
    '📝 Bareun 맞춤법 검사 및 수정'
  );
}

function openFormatCheckViewer(options) {
  var normalizedOptions = normalizeFormatOptions_(options);

  if (!hasAnyFormatOption_(normalizedOptions)) {
    throw new Error('형식 검사 항목을 하나 이상 선택해 주세요.');
  }

  assertSelectionWithinLimit_();

  var html = renderView_('format', normalizedOptions)
    .setWidth(1000)
    .setHeight(700);

  SpreadsheetApp.getUi().showModelessDialog(
    html,
    '🔎 생기부 형식 검사'
  );
}


// =================================================================
// [1] 선택 영역 공통 처리 및 40명 제한
// =================================================================

function getSelectedTextCells_() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  var sheet = spreadsheet.getActiveSheet();
  var range = sheet.getActiveRange();

  if (!range) {
    throw new Error('선택된 셀이 없습니다.');
  }

  var values = range.getValues();

  var startRow = range.getRow();
  var startCol = range.getColumn();

  var rows = [];
  var nonEmptyRowIndexes = {};

  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[i].length; j++) {
      var value = values[i][j];

      if (value === null || value === undefined) {
        continue;
      }

      var text = String(value);

      if (text.trim() === '') {
        continue;
      }

      // 내용이 있는 행 하나를 학생 1명으로 계산
      nonEmptyRowIndexes[i] = true;

      rows.push({
        sheetName: sheet.getName(),
        row: startRow + i,
        col: startCol + j,
        original: text
      });
    }
  }

  var studentCount = Object.keys(nonEmptyRowIndexes).length;

  if (studentCount > MAX_STUDENT_ROWS_) {
    throw new Error(
      '한 번에 최대 ' +
      MAX_STUDENT_ROWS_ +
      '명까지만 검사할 수 있습니다. 현재 선택 영역에는 내용이 있는 행이 ' +
      studentCount +
      '개 있습니다.'
    );
  }

  return {
    rows: rows,
    studentCount: studentCount
  };
}

function assertSelectionWithinLimit_() {
  var selected = getSelectedTextCells_();

  if (selected.rows.length === 0) {
    throw new Error('선택 영역에 검사할 내용이 없습니다.');
  }

  return selected;
}


// =================================================================
// [2] Bareun API 키 및 UI 설정
// =================================================================

function getBareunUserProperties_() {
  ensureBannedWordSheet_();

  var props = PropertiesService.getUserProperties();

  var currentPolicy = 'BAREUN_ONLY_KEYS_V3';
  var previousPolicy = props.getProperty('API_KEY_POLICY_VERSION');

  if (previousPolicy !== currentPolicy) {
    var allowedProperties = {
      UI_STATE: true,
      API_KEY_POLICY_VERSION: true
    };

    if (
      previousPolicy === 'USER_SUPPLIED_KEYS_V1' ||
      previousPolicy === 'BAREUN_ONLY_KEYS_V1' ||
      previousPolicy === 'BAREUN_ONLY_KEYS_V2'
    ) {
      allowedProperties.USER_BAREUN_KEY = true;
    }

    Object.keys(props.getProperties()).forEach(function(propertyName) {
      if (!allowedProperties[propertyName]) {
        props.deleteProperty(propertyName);
      }
    });

    var previousUiState = {};

    try {
      previousUiState = JSON.parse(
        props.getProperty('UI_STATE') || '{}'
      );
    } catch (e) {
      previousUiState = {};
    }

    var currentUiState = {};

    ['card-api', 'sub-api-settings', 'card-util'].forEach(function(id) {
      if (previousUiState[id]) {
        currentUiState[id] = true;
      }
    });

    props.setProperty(
      'UI_STATE',
      JSON.stringify(currentUiState)
    );

    props.setProperty(
      'API_KEY_POLICY_VERSION',
      currentPolicy
    );
  }

  return props;
}

function saveUserBareunKey(bareunKey) {
  var props = getBareunUserProperties_();

  var cleanBareunKey = String(
    bareunKey || ''
  ).trim();

  if (!cleanBareunKey) {
    throw new Error(
      'Bareun API 키를 입력해 주세요. 이 도우미는 API 키를 제공하지 않습니다.'
    );
  }

  props.setProperty(
    'USER_BAREUN_KEY',
    cleanBareunKey
  );

  return {
    hasBareun: true
  };
}

function checkUserBareunStatus() {
  var props = getBareunUserProperties_();

  return {
    hasBareun: !!props.getProperty('USER_BAREUN_KEY')
  };
}

function clearUserBareunKey() {
  var props = getBareunUserProperties_();

  props.deleteProperty(
    'USER_BAREUN_KEY'
  );

  return {
    hasBareun: false
  };
}

function getBareunKey() {
  var key = getBareunUserProperties_()
    .getProperty('USER_BAREUN_KEY');

  if (!key) {
    throw new Error(
      'Bareun API 키가 없습니다. 사이드바 상단에서 등록해 주세요.'
    );
  }

  return key;
}


// =================================================================
// [3] Bareun 맞춤법 검사
// =================================================================

function getSelectedDataForSpellCheck() {
  var selected = assertSelectionWithinLimit_();

  return selected.rows;
}

function getBareunCorrection(text) {
  var userKey = getBareunKey();

  return callBareunApi(
    text,
    userKey
  );
}

function callBareunApi(text, userKey) {
  var url =
    'https://api.bareun.ai/bareun.RevisionService/CorrectError';

  var options = {
    method: 'post',
    contentType: 'application/json',

    headers: {
      'api-key': userKey
    },

    muteHttpExceptions: true,

    payload: JSON.stringify({
      document: {
        content: text,
        language: 'ko-KR'
      },

      encoding_type: 'UTF16'
    })
  };

  var response = UrlFetchApp.fetch(
    url,
    options
  );

  var responseCode =
    response.getResponseCode();

  var responseText =
    response.getContentText();

  if (responseCode !== 200) {
    return {
      error:
        'Bareun API 오류: ' +
        responseCode
    };
  }

  var result;

  try {
    result = JSON.parse(
      responseText
    );
  } catch (e) {
    return {
      error:
        'Bareun API 응답을 해석하지 못했습니다.'
    };
  }

  return {
    revised:
      result.revised || text,

    helps:
      result.helps || {},

    rawBlocks:
      result.revisedBlocks ||
      result.revised_blocks ||
      [],

    error: null
  };
}


// =================================================================
// [4] 검사 결과 시트 반영
// =================================================================

function applySpellCheckResults(updates) {
  if (!Array.isArray(updates)) {
    throw new Error(
      '적용할 데이터 형식이 올바르지 않습니다.'
    );
  }

  var spreadsheet =
    SpreadsheetApp.getActiveSpreadsheet();

  updates.forEach(function(item) {
    var sheet =
      spreadsheet.getSheetByName(
        item.sheetName
      );

    if (!sheet) {
      throw new Error(
        '검사한 시트를 찾을 수 없습니다: ' +
        item.sheetName
      );
    }

    sheet
      .getRange(
        item.row,
        item.col
      )
      .setValue(
        item.text
      );
  });

  return updates.length;
}


// =================================================================
// [5] 기재 금지어 관리
// =================================================================

var BANNED_WORD_SHEET_NAME_ =
  '기재금지어관리';

var BANNED_WORD_HEADERS_ = [
  '번호',
  '기재 금지어'
];

var LEGACY_BANNED_WORD_HEADERS_ = [
  '유형',
  '기재 금지어',
  '대체 표현'
];

var ONE_COLUMN_BANNED_WORD_HEADERS_ = [
  '기재 금지어'
];

function getLegacyBannedWordList_() {
  var saved =
    PropertiesService
      .getUserProperties()
      .getProperty(
        'BANNED_WORDS_DB'
      );

  if (!saved) {
    return getDefaultBannedList_();
  }

  try {
    var parsed =
      JSON.parse(saved);

    if (!Array.isArray(parsed)) {
      return getDefaultBannedList_();
    }

    return parsed
      .map(function(item) {
        return String(
          item && item.k || ''
        ).trim();
      })
      .filter(function(keyword) {
        return keyword !== '';
      });

  } catch (e) {
    return getDefaultBannedList_();
  }
}

function initializeBannedWordSheet_(sheet, list) {
  sheet
    .getRange(
      1,
      1,
      1,
      BANNED_WORD_HEADERS_.length
    )
    .setValues([
      BANNED_WORD_HEADERS_
    ])
    .setBackground('#fce8e6')
    .setFontColor('#a50e0e')
    .setFontWeight('bold')
    .setHorizontalAlignment('center');

  var rows =
    list.map(
      function(keyword, index) {
        return [
          index + 1,
          keyword
        ];
      }
    );

  if (rows.length > 0) {
    sheet
      .getRange(
        2,
        1,
        rows.length,
        2
      )
      .setValues(
        rows
      );
  }

  sheet.setFrozenRows(1);
  sheet.setColumnWidth(1, 60);
  sheet.setColumnWidth(2, 260);
  sheet.setTabColor('#d93025');
}

function migrateLegacyBannedWordSheet_(sheet) {
  var lastColumn =
    sheet.getLastColumn();

  var legacyColumn;
  var clearColumns;

  if (
    lastColumn >= 3 &&
    sheet
      .getRange(
        1,
        1,
        1,
        3
      )
      .getDisplayValues()[0]
      .join('|') ===
      LEGACY_BANNED_WORD_HEADERS_.join('|')
  ) {
    legacyColumn = 2;
    clearColumns = 3;

  } else if (
    sheet
      .getRange(
        1,
        1,
        1,
        1
      )
      .getDisplayValues()[0][0] ===
      ONE_COLUMN_BANNED_WORD_HEADERS_[0]
  ) {
    legacyColumn = 1;
    clearColumns = 1;

  } else {
    return false;
  }

  var lastRow =
    sheet.getLastRow();

  var keywords =
    lastRow < 2
      ? []
      : sheet
          .getRange(
            2,
            legacyColumn,
            lastRow - 1,
            1
          )
          .getDisplayValues()
          .map(function(row) {
            return String(
              row[0] || ''
            ).trim();
          })
          .filter(function(keyword) {
            return keyword !== '';
          });

  var clearRows =
    Math.max(
      sheet.getLastRow(),
      1
    );

  sheet
    .getRange(
      1,
      1,
      clearRows,
      clearColumns
    )
    .clearContent();

  initializeBannedWordSheet_(
    sheet,
    keywords
  );

  return true;
}

function ensureBannedWordSheet_() {
  var spreadsheet =
    SpreadsheetApp.getActiveSpreadsheet();

  if (!spreadsheet) {
    throw new Error(
      '활성 스프레드시트를 찾을 수 없습니다.'
    );
  }

  var originalSheet =
    spreadsheet.getActiveSheet();

  var originalRange =
    spreadsheet.getActiveRange();

  var lock =
    LockService.getDocumentLock() ||
    LockService.getScriptLock();

  lock.waitLock(30000);

  var sheet;

  try {
    sheet =
      spreadsheet.getSheetByName(
        BANNED_WORD_SHEET_NAME_
      );

    if (!sheet) {
      sheet =
        spreadsheet.insertSheet(
          BANNED_WORD_SHEET_NAME_
        );

      initializeBannedWordSheet_(
        sheet,
        getLegacyBannedWordList_()
      );

    } else {
      migrateLegacyBannedWordSheet_(
        sheet
      );
    }

    PropertiesService
      .getUserProperties()
      .deleteProperty(
        'BANNED_WORDS_DB'
      );

    return sheet;

  } finally {
    if (
      originalSheet &&
      sheet &&
      originalSheet.getSheetId() !==
        sheet.getSheetId()
    ) {
      spreadsheet.setActiveSheet(
        originalSheet
      );

      if (originalRange) {
        spreadsheet.setActiveRange(
          originalRange
        );
      }
    }

    lock.releaseLock();
  }
}

function openBannedWordManagementSheet() {
  var sheet =
    ensureBannedWordSheet_();

  sheet.activate();

  sheet
    .getRange('A1')
    .activate();

  return sheet.getName();
}

function getDefaultBannedList_() {
  return [
    'MBTI',
    '커리어넷',
    '메이저맵',
    '패들렛',
    '띵커벨',
    '알로',
    '미리캔버스',
    '망고보드',
    '유튜버',
    '유튜브',
    '넷플릭스',
    '왓챠',
    '티빙',
    '네이버 폼',
    '구글 폼',
    'OECD',
    'UN',
    '유네스코',
    'WTO',
    'WHO',
    '그린피스',
    '앰네스티',
    'IMF',
    '인스타그램',
    '페이스북',
    '카카오톡',
    '네이버',
    '구글',
    '클래스 카드',
    '구글 클래스룸',
    '게더타운',
    '제페토',
    '아이패드',
    '갤럭시 탭',
    '비트코인',
    'TED',
    '반크',
    'TOEIC',
    'TOEFL',
    'TEPS',
    '대회',
    '수상',
    '한자능력검정'
  ];
}

function getBannedWordList_() {
  var sheet =
    ensureBannedWordSheet_();

  var header =
    sheet
      .getRange(
        1,
        1,
        1,
        2
      )
      .getDisplayValues()[0];

  if (
    header.join('|') !==
    BANNED_WORD_HEADERS_.join('|')
  ) {
    throw new Error(
      '기재금지어관리 시트의 1행은 "번호 | 기재 금지어" 순서여야 합니다.'
    );
  }

  var lastRow =
    sheet.getLastRow();

  if (lastRow < 2) {
    return [];
  }

  var values =
    sheet
      .getRange(
        2,
        1,
        lastRow - 1,
        2
      )
      .getDisplayValues();

  var seen = {};
  var list = [];

  values.forEach(
    function(row, index) {
      var rowNumber =
        index + 2;

      var number =
        String(
          row[0] || ''
        ).trim();

      var keyword =
        String(
          row[1] || ''
        ).trim();

      if (!number && !keyword) {
        return;
      }

      if (!/^[1-9]\d*$/.test(number)) {
        throw new Error(
          '기재금지어관리 시트 ' +
          rowNumber +
          '행의 번호(A열)는 1 이상의 정수여야 합니다.'
        );
      }

      if (!keyword) {
        throw new Error(
          '기재금지어관리 시트 ' +
          rowNumber +
          '행의 기재 금지어(B열)를 입력해 주세요.'
        );
      }

      var duplicateKey =
        normalizeBannedWord_(
          keyword
        );

      if (seen[duplicateKey]) {
        throw new Error(
          '기재금지어관리 시트 ' +
          rowNumber +
          '행의 기재 금지어가 ' +
          seen[duplicateKey] +
          '행과 중복됩니다: ' +
          keyword
        );
      }

      seen[duplicateKey] =
        rowNumber;

      list.push(
        keyword
      );
    }
  );

  return list;
}

function escapeRegExp_(value) {
  return String(value)
    .replace(
      /[.*+?^${}()|[\]\\]/g,
      '\\$&'
    );
}

function normalizeBannedWord_(value) {
  return String(value || '')
    .replace(/\s+/g, '')
    .toLocaleLowerCase();
}

function buildWhitespaceInsensitivePattern_(keyword) {
  var compact =
    normalizeBannedWord_(
      keyword
    );

  if (!compact) {
    throw new Error(
      '비어 있는 기재 금지어는 검사할 수 없습니다.'
    );
  }

  return compact
    .split('')
    .map(function(character) {
      return escapeRegExp_(
        character
      );
    })
    .join('[\\s\\u00A0]*');
}

function createBannedMatcher_(list) {
  if (
    !list ||
    list.length === 0
  ) {
    return null;
  }

  var sorted =
    list
      .slice()
      .sort(
        function(a, b) {
          return (
            normalizeBannedWord_(b).length -
            normalizeBannedWord_(a).length
          );
        }
      );

  var canonical = {};

  sorted.forEach(
    function(keyword) {
      canonical[
        normalizeBannedWord_(keyword)
      ] = keyword;
    }
  );

  var pattern =
    new RegExp(
      '(' +
      sorted
        .map(
          buildWhitespaceInsensitivePattern_
        )
        .join('|') +
      ')',
      'gi'
    );

  return {
    pattern: pattern,
    canonical: canonical
  };
}

function findBannedMatches_(text, matcher) {
  if (!matcher) {
    return {
      matches: [],
      counts: {}
    };
  }

  var matches = [];
  var counts = {};

  matcher.pattern.lastIndex = 0;

  var match;

  while (
    (match =
      matcher.pattern.exec(
        text
      )) !== null
  ) {
    var normalized =
      normalizeBannedWord_(
        match[0]
      );

    var keyword =
      matcher.canonical[
        normalized
      ];

    if (keyword) {
      matches.push({
        keyword: keyword,
        start: match.index,
        end:
          match.index +
          match[0].length
      });

      counts[keyword] =
        (counts[keyword] || 0) + 1;
    }

    // 혹시라도 길이 0인 정규식 일치가 생기는 경우 무한 반복 방지
    if (match[0].length === 0) {
      matcher.pattern.lastIndex++;
    }
  }

  matcher.pattern.lastIndex = 0;

  return {
    matches: matches,
    counts: counts
  };
}


// =================================================================
// [6] 형식 검사 옵션
// =================================================================

function normalizeFormatOptions_(options) {
  options = options || {};

  return {
    quotes: !!options.quotes,
    banned: !!options.banned,
    spaces: !!options.spaces,
    parentheses: !!options.parentheses
  };
}

function hasAnyFormatOption_(options) {
  return (
    options.quotes ||
    options.banned ||
    options.spaces ||
    options.parentheses
  );
}


// =================================================================
// [7] 소괄호 쌍 검사
// =================================================================

function analyzeParentheses_(text) {
  var stack = [];

  var unmatchedOpen = [];
  var unmatchedClose = [];

  for (
    var i = 0;
    i < text.length;
    i++
  ) {
    var character =
      text.charAt(i);

    if (character === '(') {
      stack.push(i);

    } else if (
      character === ')'
    ) {
      if (stack.length > 0) {
        stack.pop();

      } else {
        unmatchedClose.push(i);
      }
    }
  }

  while (
    stack.length > 0
  ) {
    unmatchedOpen.push(
      stack.pop()
    );
  }

  unmatchedOpen.sort(
    function(a, b) {
      return a - b;
    }
  );

  return {
    balanced:
      unmatchedOpen.length === 0 &&
      unmatchedClose.length === 0,

    unmatchedOpen:
      unmatchedOpen,

    unmatchedClose:
      unmatchedClose
  };
}


// =================================================================
// [8] 통합 형식 검사
// =================================================================

function runFormatCheck(options) {
  var normalizedOptions =
    normalizeFormatOptions_(
      options
    );

  if (
    !hasAnyFormatOption_(
      normalizedOptions
    )
  ) {
    throw new Error(
      '형식 검사 항목을 하나 이상 선택해 주세요.'
    );
  }

  var selected =
    assertSelectionWithinLimit_();

  var bannedMatcher = null;

  if (
    normalizedOptions.banned
  ) {
    bannedMatcher =
      createBannedMatcher_(
        getBannedWordList_()
      );
  }

  var results = [];

  selected.rows.forEach(
    function(item) {
      var original =
        item.original;

      // 형식 검사는 자동 수정하지 않음
      // 오른쪽 수정안도 항상 원문 그대로 시작
      var suggested =
        original;

      var issues = [];
      var ranges = [];

      // -------------------------------------------------------------
      // 1. 따옴표 통일 검사
      // -------------------------------------------------------------

      if (
        normalizedOptions.quotes
      ) {
        var quoteCount = 0;

        for (
          var q = 0;
          q < original.length;
          q++
        ) {
          var quoteChar =
            original.charAt(q);

          if (
            quoteChar === '‘' ||
            quoteChar === '’' ||
            quoteChar === '“' ||
            quoteChar === '”'
          ) {
            quoteCount++;

            ranges.push({
              start: q,
              end: q + 1,
              type: 'quotes'
            });
          }
        }

        if (quoteCount > 0) {
          issues.push({
            type: 'quotes',
            title: '따옴표 통일',
            message:
              '둥근 따옴표 ' +
              quoteCount +
              '개가 발견되었습니다. 하이라이팅된 부분을 확인한 뒤 수정안에서 직접 고쳐 주세요.'
          });
        }
      }


      // -------------------------------------------------------------
      // 2. 스페이스바 실수 검사
      // 일반 공백이 2칸 이상 연속된 경우
      // -------------------------------------------------------------

      if (
        normalizedOptions.spaces
      ) {
        var spaceRegex =
          / {2,}/g;

        var spaceMatches = [];
        var spaceMatch;

        while (
          (spaceMatch =
            spaceRegex.exec(
              original
            )) !== null
        ) {
          spaceMatches.push({
            start:
              spaceMatch.index,

            end:
              spaceMatch.index +
              spaceMatch[0].length,

            length:
              spaceMatch[0].length
          });

          if (
            spaceMatch[0].length === 0
          ) {
            spaceRegex.lastIndex++;
          }
        }

        if (
          spaceMatches.length > 0
        ) {
          spaceMatches.forEach(
            function(matchInfo) {
              ranges.push({
                start:
                  matchInfo.start,

                end:
                  matchInfo.end,

                type:
                  'spaces'
              });
            }
          );

          issues.push({
            type: 'spaces',
            title: '스페이스바 실수',
            message:
              '두 칸 이상 연속된 공백이 ' +
              spaceMatches.length +
              '곳 발견되었습니다. 하이라이팅된 부분을 확인한 뒤 수정안에서 직접 고쳐 주세요.'
          });
        }
      }


      // -------------------------------------------------------------
      // 3. 기재 금지어 검사
      // -------------------------------------------------------------

      if (
        normalizedOptions.banned &&
        bannedMatcher
      ) {
        var bannedResult =
          findBannedMatches_(
            original,
            bannedMatcher
          );

        bannedResult.matches.forEach(
          function(matchInfo) {
            ranges.push({
              start:
                matchInfo.start,

              end:
                matchInfo.end,

              type:
                'banned'
            });
          }
        );

        Object.keys(
          bannedResult.counts
        ).forEach(
          function(keyword) {
            var count =
              bannedResult.counts[
                keyword
              ];

            issues.push({
              type:
                'banned',

              title:
                '기재 금지어',

              message:
                '"' +
                keyword +
                '"이(가) ' +
                count +
                '회 발견되었습니다. 하이라이팅된 부분을 확인한 뒤 수정안에서 문맥에 맞게 직접 고쳐 주세요.'
            });
          }
        );
      }


      // -------------------------------------------------------------
      // 4. 소괄호 쌍 검사
      // 개수뿐 아니라 등장 순서까지 검사
      // -------------------------------------------------------------

      if (
        normalizedOptions.parentheses
      ) {
        var parenResult =
          analyzeParentheses_(
            original
          );

        if (
          !parenResult.balanced
        ) {
          parenResult.unmatchedOpen.forEach(
            function(position) {
              ranges.push({
                start:
                  position,

                end:
                  position + 1,

                type:
                  'parentheses'
              });
            }
          );

          parenResult.unmatchedClose.forEach(
            function(position) {
              ranges.push({
                start:
                  position,

                end:
                  position + 1,

                type:
                  'parentheses'
              });
            }
          );

          var parenthesisMessages = [];

          if (
            parenResult.unmatchedOpen.length > 0
          ) {
            parenthesisMessages.push(
              '짝이 없는 여는 괄호 ( ' +
              parenResult.unmatchedOpen.length +
              '개'
            );
          }

          if (
            parenResult.unmatchedClose.length > 0
          ) {
            parenthesisMessages.push(
              '짝이 없는 닫는 괄호 ) ' +
              parenResult.unmatchedClose.length +
              '개'
            );
          }

          issues.push({
            type:
              'parentheses',

            title:
              '괄호 쌍 검사',

            message:
              parenthesisMessages.join(
                ', '
              ) +
              '가 발견되었습니다. 빨간색으로 표시된 괄호를 확인한 뒤 수정안에서 직접 고쳐 주세요.'
          });
        }
      }


      // 문제 있는 셀만 결과 창에 표시
      if (
        issues.length > 0
      ) {
        results.push({
          sheetName:
            item.sheetName,

          row:
            item.row,

          col:
            item.col,

          original:
            original,

          // 자동 수정 없이 원문 그대로
          suggested:
            suggested,

          issues:
            issues,

          ranges:
            ranges
        });
      }
    }
  );

  return {
    studentCount:
      selected.studentCount,

    checkedCellCount:
      selected.rows.length,

    issueCellCount:
      results.length,

    rows:
      results,

    options:
      normalizedOptions
  };
}


// =================================================================
// [9] 호환용 기재 금지어 검사 함수
// 기존 코드에서 이 함수를 직접 호출하는 경우를 대비
// =================================================================

function runBannedWordCheck() {
  var result =
    runFormatCheck({
      quotes: false,
      banned: true,
      spaces: false,
      parentheses: false
    });

  return result.rows;
}


// =================================================================
// [10] UI 상태 저장 및 불러오기
// =================================================================

function saveUiState(
  cardId,
  isExpanded
) {
  var props =
    PropertiesService
      .getUserProperties();

  var state = {};

  try {
    state =
      JSON.parse(
        props.getProperty(
          'UI_STATE'
        ) || '{}'
      );

  } catch (e) {
    state = {};
  }

  state[cardId] =
    isExpanded;

  props.setProperty(
    'UI_STATE',
    JSON.stringify(
      state
    )
  );
}

function getUiState() {
  var props =
    PropertiesService
      .getUserProperties();

  try {
    return JSON.parse(
      props.getProperty(
        'UI_STATE'
      ) || '{}'
    );

  } catch (e) {
    return {};
  }
}

Sidebar.html


= 0 ? initialView : "sidebar"; ?>







  

  

  

  





  

    

      
        🔑 Bareun API 키 설정
      

      
        expand_more
      

    


    

      

        

          
            내 Bareun API 키
          

          
            expand_more
          

        


        

          
            ⌛ API 키 설정 확인 중...
          


          

            


            
              Bareun API 키
            


            


            


            

          
        
      
    
  


  

    

      
        📝 선택 영역 검사
      

      
        expand_more
      

    


    

      


      


      

        
          형식 검사 항목
        


        
          

          
            따옴표 통일 (' ")
          
        


        
          

          
            기재 금지어 검사
          
        


        
          

          
            스페이스바 실수 검사
          
        


        
          

          
            괄호 쌍 검사
          
        

      


      


      
        한 번에 최대 40명까지 검사할 수 있습니다.

      


      
        기재금지어관리 시트 열기
      

    
  


  











  

  

  

  


  





  

    
      
        fact_check
      

      맞춤법 검사 및 수정
    


    

      
        
          원본 오류
        
      

      
        
          수정 제안
        
      

    
  


  

    

      

      
        데이터를 불러오는 중입니다...
      

    


    

  


  

    


    

  


  











  

  

  


  





  

    
      
        rule
      

      형식 검사 및 수정
    


    
      검사 준비 중...
    

  


  

    

      

      
        형식을 검사하는 중입니다...

석림중학교 교직원 연수

Wed, 09 Sep 2026 06:39:22 GMT

석림중학교 교직원 연수

강사: 교사 김민기(민기쌤)
일시: 2026-09-09
장소: 서산석림중학교

강의 자료

[강의] 앱스스크립트.pptx

바른 API

Code.gs

// =================================================================
// [0] 초기 설정 및 메뉴
// =================================================================

function onOpen() {
  SpreadsheetApp.getUi().createMenu('민기쌤 생기부 도우미')
      .addItem('🚀 사이드바 열기', 'openSidebar') 
      .addToUi();
}

function renderView_(viewName) {
  var template = HtmlService.createTemplateFromFile('Sidebar');
  template.initialView = viewName || 'sidebar';
  return template.evaluate();
}

function openSidebar() {
  ensureBannedWordSheet_();
  var html = renderView_('sidebar')
      .setTitle('민기쌤 생기부 맞춤법 도우미')
      .setWidth(300); 
  SpreadsheetApp.getUi().showSidebar(html);
}

function openSpellCheckViewer() {
  var html = renderView_('spellcheck')
      .setWidth(1000) 
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '📝 Bareun 맞춤법 검사 및 수정');
}

function openBannedWordViewer() {
  var html = renderView_('banned')
      .setWidth(1000)
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '🚫 기재 금지어 점검');
}

// =================================================================
// [1] Bareun API 키 및 UI 설정
// =================================================================

function getBareunUserProperties_() {
  ensureBannedWordSheet_();
  var props = PropertiesService.getUserProperties();
  var currentPolicy = 'BAREUN_ONLY_KEYS_V3';
  var previousPolicy = props.getProperty('API_KEY_POLICY_VERSION');

  // 정책 변경 시 현재 기능에서 쓰지 않는 예전 사용자 설정을 한 번 정리합니다.
  if (previousPolicy !== currentPolicy) {
    var allowedProperties = {
      UI_STATE: true,
      API_KEY_POLICY_VERSION: true
    };
    // 바로 이전 사용자 입력형 정책에서 저장한 키만 보존합니다.
    if (previousPolicy === 'USER_SUPPLIED_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V2') {
      allowedProperties.USER_BAREUN_KEY = true;
    }
    Object.keys(props.getProperties()).forEach(function(propertyName) {
      if (!allowedProperties[propertyName]) props.deleteProperty(propertyName);
    });

    var previousUiState = {};
    try {
      previousUiState = JSON.parse(props.getProperty('UI_STATE') || '{}');
    } catch (e) {
      previousUiState = {};
    }
    var currentUiState = {};
    ['card-api', 'sub-api-settings', 'card-util'].forEach(function(id) {
      if (previousUiState[id]) currentUiState[id] = true;
    });
    props.setProperty('UI_STATE', JSON.stringify(currentUiState));
    props.setProperty('API_KEY_POLICY_VERSION', currentPolicy);
  }

  return props;
}

function saveUserBareunKey(bareunKey) {
  var props = getBareunUserProperties_();
  var cleanBareunKey = String(bareunKey || '').trim();

  if (!cleanBareunKey) {
    throw new Error('Bareun API 키를 입력해 주세요. 이 도우미는 API 키를 제공하지 않습니다.');
  }

  props.setProperty('USER_BAREUN_KEY', cleanBareunKey);
  return { hasBareun: true };
}

function checkUserBareunStatus() {
  var props = getBareunUserProperties_();
  return { hasBareun: !!props.getProperty('USER_BAREUN_KEY') };
}

function clearUserBareunKey() {
  var props = getBareunUserProperties_();
  props.deleteProperty('USER_BAREUN_KEY');
  return { hasBareun: false };
}

function getBareunKey() {
  var key = getBareunUserProperties_().getProperty('USER_BAREUN_KEY');
  if (!key) throw new Error("Bareun API 키가 없습니다. 사이드바 상단에서 등록해주세요.");
  return key;
}

// =================================================================
// [2] Bareun 맞춤법 검사
// =================================================================

function getSelectedDataForSpellCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");
  var rows = [];
  var startRow = range.getRow();
  var startCol = range.getColumn();
  var values = range.getValues();
  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var text = values[i][j].toString();
      if (text.trim() !== "") {
        rows.push({ sheetName: sheetName, row: startRow + i, col: startCol + j, original: text });
      }
    }
  }
  return rows;
}

function getBareunCorrection(text) {
  var userKey = getBareunKey();
  var result = callBareunApi(text, userKey); 
  return result; 
}

function applySpellCheckResults(updates) {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  updates.forEach(function(item) {
    var sheet = spreadsheet.getSheetByName(item.sheetName);
    if (!sheet) throw new Error('검사한 시트를 찾을 수 없습니다: ' + item.sheetName);
    sheet.getRange(item.row, item.col).setValue(item.text);
  });
  return updates.length;
}

function callBareunApi(text, userKey) {
  var url = "https://api.bareun.ai/bareun.RevisionService/CorrectError";
  var options = {
    "method": "post", "contentType": "application/json", "headers": { "api-key": userKey }, "muteHttpExceptions": true,
    "payload": JSON.stringify({ "document": { "content": text, "language": "ko-KR" }, "encoding_type": "UTF16" })
  };
  var response = UrlFetchApp.fetch(url, options);
  var result = JSON.parse(response.getContentText());
  
  if (response.getResponseCode() !== 200) {
    return { error: "API 오류: " + response.getResponseCode() };
  }
  return { revised: result.revised, helps: result.helps || {}, rawBlocks: result.revisedBlocks || result.revised_blocks || [], error: null };
}

// =================================================================
// [3] 기재 금지어 관리
// =================================================================

var BANNED_WORD_SHEET_NAME_ = '기재금지어관리';
var BANNED_WORD_HEADERS_ = ['번호', '기재 금지어'];
var LEGACY_BANNED_WORD_HEADERS_ = ['유형', '기재 금지어', '대체 표현'];
var ONE_COLUMN_BANNED_WORD_HEADERS_ = ['기재 금지어'];

function getLegacyBannedWordList_() {
  var saved = PropertiesService.getUserProperties().getProperty('BANNED_WORDS_DB');
  if (!saved) return getDefaultBannedList_();

  try {
    var parsed = JSON.parse(saved);
    if (!Array.isArray(parsed)) return getDefaultBannedList_();
    return parsed
      .map(function(item) {
        return String(item && item.k || '').trim();
      })
      .filter(function(keyword) { return keyword !== ''; });
  } catch (e) {
    return getDefaultBannedList_();
  }
}

function initializeBannedWordSheet_(sheet, list) {
  sheet.getRange(1, 1, 1, BANNED_WORD_HEADERS_.length)
    .setValues([BANNED_WORD_HEADERS_])
    .setBackground('#fce8e6')
    .setFontColor('#a50e0e')
    .setFontWeight('bold')
    .setHorizontalAlignment('center');

  var rows = list.map(function(keyword, index) {
    return [index + 1, keyword];
  });
  if (rows.length > 0) sheet.getRange(2, 1, rows.length, 2).setValues(rows);

  sheet.setFrozenRows(1);
  sheet.setColumnWidth(1, 60);
  sheet.setColumnWidth(2, 260);
  sheet.setTabColor('#d93025');
}

function migrateLegacyBannedWordSheet_(sheet) {
  var lastColumn = sheet.getLastColumn();
  var legacyColumn;
  var clearColumns;

  if (lastColumn >= 3 && sheet.getRange(1, 1, 1, 3).getDisplayValues()[0].join('|') === LEGACY_BANNED_WORD_HEADERS_.join('|')) {
    legacyColumn = 2;
    clearColumns = 3;
  } else if (sheet.getRange(1, 1, 1, 1).getDisplayValues()[0][0] === ONE_COLUMN_BANNED_WORD_HEADERS_[0]) {
    legacyColumn = 1;
    clearColumns = 1;
  } else {
    return false;
  }

  var lastRow = sheet.getLastRow();
  var keywords = lastRow < 2 ? [] : sheet.getRange(2, legacyColumn, lastRow - 1, 1)
    .getDisplayValues()
    .map(function(row) { return String(row[0] || '').trim(); })
    .filter(function(keyword) { return keyword !== ''; });

  var clearRows = Math.max(sheet.getLastRow(), 1);
  sheet.getRange(1, 1, clearRows, clearColumns).clearContent();
  initializeBannedWordSheet_(sheet, keywords);
  return true;
}

function ensureBannedWordSheet_() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  if (!spreadsheet) throw new Error('활성 스프레드시트를 찾을 수 없습니다.');

  var originalSheet = spreadsheet.getActiveSheet();
  var originalRange = spreadsheet.getActiveRange();
  var lock = LockService.getDocumentLock() || LockService.getScriptLock();
  lock.waitLock(30000);

  var sheet;
  try {
    sheet = spreadsheet.getSheetByName(BANNED_WORD_SHEET_NAME_);
    if (!sheet) {
      sheet = spreadsheet.insertSheet(BANNED_WORD_SHEET_NAME_);
      initializeBannedWordSheet_(sheet, getLegacyBannedWordList_());
    } else {
      // 이전 형식은 금지어만 보존하여 번호·기재금지어 두 열 목록으로 안전하게 바꿉니다.
      migrateLegacyBannedWordSheet_(sheet);
    }

    // 시트로 옮긴 뒤 예전 사용자별 저장값은 더 이상 별도 원본으로 남기지 않습니다.
    PropertiesService.getUserProperties().deleteProperty('BANNED_WORDS_DB');
    return sheet;
  } finally {
    if (originalSheet && sheet && originalSheet.getSheetId() !== sheet.getSheetId()) {
      spreadsheet.setActiveSheet(originalSheet);
      if (originalRange) spreadsheet.setActiveRange(originalRange);
    }
    lock.releaseLock();
  }
}

function openBannedWordManagementSheet() {
  var sheet = ensureBannedWordSheet_();
  sheet.activate();
  sheet.getRange('A1').activate();
  return sheet.getName();
}

function getDefaultBannedList_() {
  return [
    "MBTI", "커리어넷", "메이저맵", "패들렛", "띵커벨", "알로",
    "미리캔버스", "망고보드", "유튜버", "유튜브", "넷플릭스", "왓챠",
    "티빙", "네이버 폼", "구글 폼", "OECD", "UN", "유네스코", "WTO",
    "WHO", "그린피스", "앰네스티", "IMF", "인스타그램", "페이스북",
    "카카오톡", "네이버", "구글", "클래스 카드", "구글 클래스룸", "게더타운",
    "제페토", "아이패드", "갤럭시 탭", "비트코인", "TED", "반크", "TOEIC",
    "TOEFL", "TEPS", "대회", "수상", "한자능력검정"
  ];
}

function getBannedWordList_() {
  var sheet = ensureBannedWordSheet_();
  var header = sheet.getRange(1, 1, 1, 2).getDisplayValues()[0];
  if (header.join('|') !== BANNED_WORD_HEADERS_.join('|')) {
    throw new Error('기재금지어관리 시트의 1행은 "번호 | 기재 금지어" 순서여야 합니다.');
  }

  var lastRow = sheet.getLastRow();
  if (lastRow < 2) return [];

  var values = sheet.getRange(2, 1, lastRow - 1, 2).getDisplayValues();
  var seen = {};
  var list = [];

  values.forEach(function(row, index) {
    var rowNumber = index + 2;
    var number = String(row[0] || '').trim();
    var keyword = String(row[1] || '').trim();

    if (!number && !keyword) return;
    if (!/^[1-9]\d*$/.test(number)) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 번호(A열)는 1 이상의 정수여야 합니다.');
    }
    if (!keyword) throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어(B열)를 입력해 주세요.');

    var duplicateKey = normalizeBannedWord_(keyword);
    if (seen[duplicateKey]) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어가 ' + seen[duplicateKey] + '행과 중복됩니다: ' + keyword);
    }
    seen[duplicateKey] = rowNumber;
    list.push(keyword);
  });

  return list;
}

function runBannedWordCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  var values = range.getValues();
  var startRow = range.getRow();
  var startCol = range.getColumn();
  
  var db = getBannedWordList_();
  if (db.length === 0) return [];
  db.sort(function(a, b) { return normalizeBannedWord_(b).length - normalizeBannedWord_(a).length; });
  var canonicalByNormalizedKeyword = {};
  db.forEach(function(keyword) { canonicalByNormalizedKeyword[normalizeBannedWord_(keyword)] = keyword; });
  var combinedPattern = new RegExp('(' + db.map(buildWhitespaceInsensitivePattern_).join('|') + ')', 'gi');

  var results = [];

  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var original = values[i][j].toString();
      if (!original.trim()) continue;

      var hasIssue = false;
      var logs = [];

      var counts = {};
      var match;
      while ((match = combinedPattern.exec(original)) !== null) {
        var normalizedMatch = normalizeBannedWord_(match[0]);
        var keyword = canonicalByNormalizedKeyword[normalizedMatch];
        if (keyword) {
          hasIssue = true;
          counts[keyword] = (counts[keyword] || 0) + 1;
        }
      }

      Object.keys(counts).forEach(function(keyword) {
        logs.push({ k: keyword, count: counts[keyword] });
      });

      if (hasIssue) {
        results.push({
          sheetName: sheetName,
          row: startRow + i,
          col: startCol + j,
          original: original,
          logs: logs
        });
      }
    }
  }
  return results;
}

function escapeRegExp(string) {
  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); 
}

function normalizeBannedWord_(value) {
  return String(value || '').replace(/\s+/g, '').toLocaleLowerCase();
}

function buildWhitespaceInsensitivePattern_(keyword) {
  var compact = normalizeBannedWord_(keyword);
  if (!compact) throw new Error('비어 있는 기재 금지어는 검사할 수 없습니다.');
  return compact.split('').map(function(character) {
    return escapeRegExp(character);
  }).join('[\\s\\u00A0]*');
}

// =================================================================
// [4] 로컬 검토 유틸리티
// =================================================================

function unifyToStraightQuotes() {
  var range = SpreadsheetApp.getActiveRange();
  var ui = SpreadsheetApp.getUi();
  if (!range) throw new Error('선택된 셀이 없습니다.');
  var response = ui.alert('따옴표 변환', '선택 영역의 둥근 따옴표를 곧은 따옴표로 변환하시겠습니까?', ui.ButtonSet.YES_NO);
  if (response != ui.Button.YES) return;
  try {
    range.createTextFinder('[‘’]').useRegularExpression(true).matchEntireCell(false).replaceAllWith("'");
    range.createTextFinder('[“”]').useRegularExpression(true).matchEntireCell(false).replaceAllWith('"');
    SpreadsheetApp.flush();
    ui.alert('✅ 변환 완료');
  } catch (e) { ui.alert('오류: ' + e.toString()); }
}

// [신규] 선택 영역 스페이스바 실수(2칸 이상) 수정 함수
function fixDoubleSpaces() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  const values = range.getValues();
  let fixCount = 0; // 수정된 셀 개수 카운트

  const newValues = values.map(row => {
    return row.map(cell => {
      let str = String(cell);
      // 공백이 2번 이상 연속( /  +/)으로 있으면 1번으로 변경
      // 줄바꿈(\n)은 건드리지 않도록 일반 공백( )만 타겟팅
      if (/ {2,}/.test(str)) {
        fixCount++;
        return str.replace(/ {2,}/g, ' '); 
      }
      return cell;
    });
  });

  if (fixCount > 0) {
    range.setValues(newValues);
  }
  
  return fixCount;
}

// =================================================================
// [5] UI 상태 저장/불러오기
// =================================================================

function saveUiState(cardId, isExpanded) {
  var props = PropertiesService.getUserProperties();
  var state = JSON.parse(props.getProperty('UI_STATE') || '{}');
  state[cardId] = isExpanded;
  props.setProperty('UI_STATE', JSON.stringify(state));
}

function getUiState() {
  var props = PropertiesService.getUserProperties();
  return JSON.parse(props.getProperty('UI_STATE') || '{}');
}

Sidebar.html


= 0 ? initialView : "sidebar"; ?>



  
    
    
    
    
  
  
    
      
        🔑 Bareun API 키 설정
        expand_more
      
      
        
          
            내 Bareun API 키
            expand_more
          
          
            ⌛ API 키 설정 확인 중...
            
              
              Bareun API 키
              
              공용 키는 제공하지 않습니다. 키는 사용자별 설정에 저장되고 원문을 화면으로 다시 불러오지 않습니다.
              
              
            
          
        
      
    

    
      
        📝 선택 영역 검사 및 정리
        expand_more
      
      
        
        
        
        
        
        
      
    

    
  





  
    
    
    
    
    
  
  

    
      fact_check 맞춤법 검사 및 수정
      
        원본 오류
        수정 제안
      
    

    
      
        
        데이터를 불러오는 중입니다...
      
      
    

    
      
      
    

    
  





  
    
    
    
    
  
  

    
      block 기재 금지어 검사
      
        금지어 발견
        오른쪽 수정안에서 문맥에 맞게 직접 고쳐 주세요.
      
    

    
      
        
        데이터를 분석 중입니다...

성환중학교 교직원 연수

Sun, 19 Jul 2026 02:52:45 GMT

성환중학교 교직원 연수

강사: 교사 김민기(민기쌤)
일시: 2026-08-26
장소: 성환중학교

성환중학교 교직원 대상 바이브 코딩, 앱스스크립트, 웹 앱 만들기 연수

강의 자료

[강의] 성환중학교-앱스스크립트.pdf

2026 AI·디지털 교육 역량강화 연수(국어 심화) - 8. 12. 한서대학교

Tue, 11 Aug 2026 12:33:33 GMT

2026 AI·디지털 교육 역량강화 연수(국어 심화) - 8. 12. 한서대학교

강사: 교사 김민기(민기쌤)
일시: 2026-08-12
장소: 한서대학교 인곡관 206호

충청남도교육청 주관 연수입니다.

(1차시) 마주온 활용

교안 및 학습자료

[강의] 김민기_마주온 활용.pdf

(2차시) 토의·토론

교안 및 학습자료

[강의] 김민기_국어과 AI 환경에서의 주체성 토론.pdf

(3차시) AI 융합 수업 설계

Code.gs

const YT_CFG = Object.freeze({
  API_BASE: 'https://www.googleapis.com/youtube/v3',

  API_KEY_PROP: 'YT_API_KEY',
  STATE_PROP: 'YT_COMMENT_COLLECTOR_STATE',
  LAST_RESULT_PROP: 'YT_COMMENT_COLLECTOR_LAST_RESULT',
  CANCEL_REQUEST_PROP: 'YT_COMMENT_COLLECTOR_CANCEL_REQUEST',

  OUTPUT_SHEET_PREFIX: '시트',
  INTERNAL_SHEET: '_댓글수집_내부',
  LEGACY_LOG_SHEET: '수집로그',

  CONTINUE_HANDLER: 'continueCommentCollection',
  STRUCTURED_ERROR_PREFIX: 'YT_STRUCTURED_ERROR::',
  STATE_VERSION: 4,

  // Apps Script의 일반 실행 제한 전에 상태를 저장하고 다음 실행으로 넘깁니다.
  MAX_RUN_MS: 4 * 60 * 1000 + 30 * 1000,
  CONTINUE_AFTER_MS: 60 * 1000,

  MIN_LIMIT: 1,
  MAX_LIMIT: 50000,

  HEADERS: [
    '번호',
    '채널명',
    '영상 제목',
    '댓글 작성자',
    '댓글 내용',
    '좋아요 수',
    '작성 시각',
    '글자수'
  ],

  // 숨김 내부 시트의 열 구조입니다.
  INTERNAL_HEADERS: [
    'comment_id',
    'parent_comment_id',
    'display_number',
    'comment_type',
    'reply_status',
    'next_reply_index',
    'total_reply_count',
    'reply_page_token'
  ],

  INTERNAL_COL: Object.freeze({
    COMMENT_ID: 1,
    PARENT_ID: 2,
    DISPLAY_NUMBER: 3,
    COMMENT_TYPE: 4,
    REPLY_STATUS: 5,
    NEXT_REPLY_INDEX: 6,
    TOTAL_REPLY_COUNT: 7,
    REPLY_PAGE_TOKEN: 8
  })
});


/**
 * 스프레드시트를 열 때 사용자 메뉴를 만듭니다.
 */
function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('YouTube 댓글 수집')
    .addItem('사이드바 열기', 'showYouTubeCommentSidebar')
    .addSeparator()
    .addItem('중단 지점부터 실행', 'continueCommentCollection')
    .addItem('진행 중인 수집 취소', 'cancelCommentCollection')
    .addToUi();
}


/**
 * 오른쪽 사이드바를 엽니다.
 */
function showYouTubeCommentSidebar() {
  const html = HtmlService
    .createHtmlOutputFromFile('Sidebar')
    .setTitle('YouTube 댓글 수집기');

  SpreadsheetApp.getUi().showSidebar(html);
}


/**
 * 사이드바 초기 상태를 반환합니다.
 */
function getSidebarState() {
  const props = getUserProperties_();
  const apiKey = props.getProperty(YT_CFG.API_KEY_PROP) || '';
  const activeState = loadState_();
  const lastResult = loadLastResult_();
  const cancelRequested =
    props.getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';

  const progress = activeState
    ? buildProgressForClient_(activeState, 'RUNNING')
    : lastResult
      ? buildProgressForClient_(lastResult, lastResult.status || 'COMPLETED')
      : null;

  if (progress && activeState && cancelRequested) {
    progress.stage = '취소 처리 중';
    progress.message = '현재 실행 구간이 끝나는 즉시 안전하게 중단됩니다.';
  }

  return {
    apiKeyConfigured: Boolean(apiKey),
    apiKeyMask: apiKey ? maskApiKey_(apiKey) : '',
    running: Boolean(activeState),
    cancelRequested: cancelRequested,
    progress: progress
  };
}


/**
 * API 키를 실제 YouTube Data API 요청으로 검증한 뒤 사용자별 속성에 저장합니다.
 */
function saveApiKey(apiKey) {
  const cleanedKey = String(apiKey || '').trim();

  if (!cleanedKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키를 입력해야 합니다.',
      'Google Cloud에서 발급한 YouTube Data API 키가 입력되지 않았습니다.',
      ['API 키 입력란이 비어 있습니다.'],
      [
        'Google Cloud Console에서 API 키를 발급합니다.',
        'API 키 전체를 사이드바 입력란에 붙여 넣습니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  if (cleanedKey.length < 20) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_FORMAT_INVALID',
      'API 키 형식을 확인해야 합니다.',
      '입력한 문자열이 일반적인 Google API 키 길이보다 짧습니다.',
      [
        'API 키 일부만 복사했을 수 있습니다.',
        '프로젝트 ID나 다른 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 값을 처음부터 끝까지 다시 복사하여 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력'
      }
    ));
  }

  validateApiKey_(cleanedKey);

  const props = getUserProperties_();
  props.setProperty(YT_CFG.API_KEY_PROP, cleanedKey);

  // 이전 API 키 오류 안내가 새 키 저장 뒤 다시 나타나지 않도록 정리합니다.
  const previous = loadLastResult_();
  if (previous && previous.status === 'ERROR') {
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
  }

  return getSidebarState();
}


/**
 * 저장된 API 키를 삭제합니다.
 */
function deleteApiKey() {
  if (loadState_()) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_DELETE_BLOCKED',
      '수집 중에는 API 키를 삭제할 수 없습니다.',
      '현재 댓글 수집 작업이 저장된 API 키를 사용하고 있습니다.',
      ['진행 중인 작업이 존재합니다.'],
      [
        '현재 수집을 완료하거나 취소합니다.',
        '수집 상태가 종료된 뒤 API 키를 삭제합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.API_KEY_PROP);
  props.deleteProperty(YT_CFG.LAST_RESULT_PROP);

  return getSidebarState();
}


/**
 * 사이드바 입력값으로 새 수집 작업을 준비합니다.
 * 실제 수집은 runCollectionNow 또는 시간 기반 트리거가 수행합니다.
 */
function startCollectionFromSidebar(formData) {
  const lock = LockService.getScriptLock();
  lock.waitLock(10000);

  try {
    const apiKey = getApiKey_();
    const input = normalizeSidebarInput_(formData);
    const ss = SpreadsheetApp.getActiveSpreadsheet();

    if (!ss) {
      throwStructuredError_(buildErrorInfo_(
        'SPREADSHEET_NOT_FOUND',
        '댓글을 저장할 스프레드시트를 찾지 못했습니다.',
        '현재 Apps Script가 스프레드시트와 연결된 상태인지 확인해야 합니다.',
        [
          '독립 실행형 Apps Script 프로젝트에서 코드를 실행했을 수 있습니다.',
          '스프레드시트가 닫히거나 접근 권한이 변경되었을 수 있습니다.'
        ],
        [
          '댓글을 저장할 Google 스프레드시트를 엽니다.',
          '‘확장 프로그램 → Apps Script’에서 이 코드를 실행합니다.',
          '스프레드시트를 새로고침하고 사이드바를 다시 엽니다.'
        ],
        { actionLabel: '확인' }
      ));
    }

    // 영상과 API 키가 정상인지 먼저 확인합니다.
    const videoId = extractVideoId_(input.videoUrl);
    const metadata = getVideoMetadataWithKey_(videoId, apiKey);

    deleteContinuationTriggers_();

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    // 새 수집은 기존 결과를 지우지 않고 새 결과 시트에 기록합니다.
    const outputSheet = createNextOutputSheet_(ss);
    ensureInternalSheet_(ss);
    resetInternalData_(ss);
    deleteLegacyLogSheet_(ss);

    const state = {
      version: YT_CFG.STATE_VERSION,
      status: 'RUNNING',
      spreadsheetId: ss.getId(),

      outputSheetId: outputSheet.getSheetId(),
      outputSheetName: outputSheet.getName(),

      videoId: videoId,
      videoTitle: metadata.title,
      videoChannelId: metadata.channelId,
      videoChannelTitle: metadata.channelTitle,
      reportedCommentCount: metadata.commentCount,

      targetTopLevelCount: input.limit,
      includeReplies: input.includeReplies,

      nextThreadPageToken: '',
      threadDone: false,

      currentReplyParentId: '',
      nextReplyPageToken: '',

      topCount: 0,
      replyCount: 0,
      threadPages: 0,
      replyPages: 0,
      apiCalls: 1,

      startedAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      message: outputSheet.getName() + '에서 수집을 시작했습니다.',
      error: null
    };

    saveState_(state);

    // 사이드바가 닫혀도 수집이 이어지도록 예비 트리거를 만듭니다.
    scheduleContinuation_();

    return getSidebarState();

  } finally {
    lock.releaseLock();
  }
}


/**
 * 사이드바가 첫 실행 구간을 즉시 시작할 때 호출합니다.
 */
function runCollectionNow() {
  continueCommentCollection();
  return getSidebarState();
}


/**
 * 저장된 상태에서 댓글 수집을 계속합니다.
 */
function continueCommentCollection() {
  const lock = LockService.getScriptLock();

  if (!lock.tryLock(5000)) {
    return;
  }

  let ss = null;
  let state = null;
  let commentsSheet = null;

  try {
    state = loadState_();

    if (!state) {
      return;
    }

    validateStateVersion_(state);
    normalizeState_(state);

    ss = SpreadsheetApp.openById(state.spreadsheetId);
    ensureInternalSheet_(ss);
    deleteLegacyLogSheet_(ss);

    commentsSheet = getOutputSheetForState_(ss, state);
    const internalSheet = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);
    const existingIds = getExistingCommentIds_(internalSheet);
    const existingCounts = getExistingCounts_(internalSheet);

    // 시트 기록 직후 상태 저장 전에 실행이 끊긴 상황을 보정합니다.
    state.topCount = existingCounts.top;
    state.replyCount = existingCounts.reply;

    const runStartedAt = Date.now();

    while (Date.now() - runStartedAt < YT_CFG.MAX_RUN_MS) {
      if (isCancelRequested_()) {
        finalizeCancellation_(ss, commentsSheet, state);
        return;
      }

      // 처리 중이던 답글 페이지가 있으면 먼저 이어서 처리합니다.
      if (state.currentReplyParentId) {
        processReplyPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      // 내부 시트에서 답글 수집이 필요한 최상위 댓글을 하나 선택합니다.
      const pendingReply = claimNextPendingReply_(internalSheet);

      if (pendingReply) {
        state.currentReplyParentId = pendingReply.commentId;
        state.nextReplyPageToken = pendingReply.pageToken || '';
        saveState_(state);
        continue;
      }

      // 답글 대기 항목이 없을 때 다음 최상위 댓글 페이지를 가져옵니다.
      if (!state.threadDone) {
        processThreadPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      finishCollection_(ss, commentsSheet, state);
      return;
    }

    state.updatedAt = new Date().toISOString();
    state.message = '실행 시간을 고려하여 진행 상태를 저장했습니다.';
    saveState_(state);
    scheduleContinuation_();

  } catch (error) {
    deleteContinuationTriggers_();

    const errorInfo = normalizeErrorInfo_(error, '댓글 수집');

    if (errorInfo.code === 'API_KEY_INVALID') {
      getUserProperties_().deleteProperty(YT_CFG.API_KEY_PROP);
    }

    if (commentsSheet) {
      try {
        finalizeCommentsSheet_(commentsSheet);
      } catch (formatError) {
        console.error(formatError);
      }
    }

    if (state) {
      state.status = 'ERROR';
      state.updatedAt = new Date().toISOString();
      state.message = errorInfo.summary;
      state.error = errorInfo;
      saveLastResult_(state, 'ERROR', errorInfo.summary, errorInfo);
    }

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    console.error(error);
    throwStructuredError_(errorInfo);

  } finally {
    lock.releaseLock();
  }
}


/**
 * 진행 중인 수집을 취소합니다.
 */
function cancelCommentCollection() {
  const props = getUserProperties_();
  const state = loadState_();

  if (!state) {
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
    deleteContinuationTriggers_();
    return getSidebarState();
  }

  props.setProperty(YT_CFG.CANCEL_REQUEST_PROP, 'true');
  deleteContinuationTriggers_();

  const lock = LockService.getScriptLock();

  // 다른 수집 실행이 없다면 이 호출에서 즉시 취소를 마무리합니다.
  if (lock.tryLock(200)) {
    try {
      const latestState = loadState_();

      if (latestState) {
        const ss = SpreadsheetApp.openById(latestState.spreadsheetId);
        ensureInternalSheet_(ss);
        const commentsSheet = getOutputSheetForState_(ss, latestState);
        finalizeCancellation_(ss, commentsSheet, latestState);
      }
    } finally {
      lock.releaseLock();
    }
  }

  return getSidebarState();
}


/**
 * 최상위 댓글 스레드 한 페이지를 처리합니다.
 */
function processThreadPage_(state, commentsSheet, internalSheet, existingIds) {
  const remaining = state.targetTopLevelCount - state.topCount;

  if (remaining <= 0) {
    state.threadDone = true;
    state.nextThreadPageToken = '';
    return;
  }

  const params = {
    part: state.includeReplies ? 'snippet,replies' : 'snippet',
    videoId: state.videoId,
    maxResults: Math.min(100, remaining),
    textFormat: 'plainText'
  };

  if (state.nextThreadPageToken) {
    params.pageToken = state.nextThreadPageToken;
  }

  const data = youtubeGet_('commentThreads', params);

  state.apiCalls += 1;
  state.threadPages += 1;

  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();
  const items = Array.isArray(data.items) ? data.items : [];

  let topAdded = 0;
  let replyAdded = 0;
  let nextTopNumber = state.topCount + 1;

  items.forEach(function(thread) {
    if (state.topCount + topAdded >= state.targetTopLevelCount) {
      return;
    }

    const threadSnippet = thread.snippet || {};
    const topComment = threadSnippet.topLevelComment;

    if (!topComment || !topComment.id) {
      return;
    }

    const topCommentId = String(topComment.id);

    if (existingIds.has(topCommentId) || batchIds.has(topCommentId)) {
      return;
    }

    const topNumber = String(nextTopNumber);
    nextTopNumber += 1;

    const totalReplyCount = Number(threadSnippet.totalReplyCount || 0);
    let replyStatus = 'DONE';
    let nextReplyIndex = 1;

    commentRows.push(
      commentToOutputRow_(state, topComment, topNumber)
    );

    batchIds.add(topCommentId);
    topAdded += 1;

    const inlineReplies =
      thread.replies && Array.isArray(thread.replies.comments)
        ? thread.replies.comments
        : [];

    if (state.includeReplies && totalReplyCount > 0) {
      if (inlineReplies.length === totalReplyCount) {
        inlineReplies.forEach(function(reply) {
          if (!reply || !reply.id) {
            return;
          }

          const replyId = String(reply.id);

          if (existingIds.has(replyId) || batchIds.has(replyId)) {
            return;
          }

          const displayNumber = topNumber + '_' + nextReplyIndex;
          nextReplyIndex += 1;

          commentRows.push(
            commentToOutputRow_(state, reply, displayNumber)
          );

          internalRows.push(
            buildInternalRow_(
              replyId,
              topCommentId,
              displayNumber,
              'reply',
              '',
              '',
              '',
              ''
            )
          );

          batchIds.add(replyId);
          replyAdded += 1;
        });
      } else {
        // commentThreads.list의 replies에는 전체 답글이 보장되지 않으므로
        // comments.list로 전체 답글을 다시 가져옵니다.
        replyStatus = 'PENDING';
        nextReplyIndex = 1;
      }
    }

    internalRows.push(
      buildInternalRow_(
        topCommentId,
        '',
        topNumber,
        'topLevel',
        replyStatus,
        nextReplyIndex,
        totalReplyCount,
        ''
      )
    );
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.topCount += topAdded;
  state.replyCount += replyAdded;

  const reachedTarget = state.topCount >= state.targetTopLevelCount;
  const hasNextPage = Boolean(data.nextPageToken);

  state.nextThreadPageToken =
    !reachedTarget && hasNextPage
      ? data.nextPageToken
      : '';

  state.threadDone = reachedTarget || !hasNextPage;
  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 특정 최상위 댓글의 답글 한 페이지를 처리합니다.
 */
function processReplyPage_(state, commentsSheet, internalSheet, existingIds) {
  const topRecord = findInternalRecordByCommentId_(
    internalSheet,
    state.currentReplyParentId
  );

  if (!topRecord) {
    // 내부 상태가 사라진 경우 현재 항목을 건너뛰고 다음 대기 항목을 찾습니다.
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
    return;
  }

  const params = {
    part: 'snippet',
    parentId: state.currentReplyParentId,
    maxResults: 100,
    textFormat: 'plainText'
  };

  const pageToken =
    state.nextReplyPageToken || topRecord.replyPageToken || '';

  if (pageToken) {
    params.pageToken = pageToken;
  }

  const data = youtubeGet_('comments', params);

  state.apiCalls += 1;
  state.replyPages += 1;

  const items = Array.isArray(data.items) ? data.items : [];
  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();

  let nextReplyIndex = Number(topRecord.nextReplyIndex || 1);
  let replyAdded = 0;

  items.forEach(function(reply) {
    if (!reply || !reply.id) {
      return;
    }

    const replyId = String(reply.id);

    if (existingIds.has(replyId) || batchIds.has(replyId)) {
      return;
    }

    const displayNumber =
      String(topRecord.displayNumber) + '_' + nextReplyIndex;

    nextReplyIndex += 1;

    commentRows.push(
      commentToOutputRow_(state, reply, displayNumber)
    );

    internalRows.push(
      buildInternalRow_(
        replyId,
        state.currentReplyParentId,
        displayNumber,
        'reply',
        '',
        '',
        '',
        ''
      )
    );

    batchIds.add(replyId);
    replyAdded += 1;
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.replyCount += replyAdded;

  const nextPageToken = data.nextPageToken || '';
  const nextStatus = nextPageToken ? 'IN_PROGRESS' : 'DONE';

  updateTopReplyProgress_(
    internalSheet,
    topRecord.rowNumber,
    nextStatus,
    nextReplyIndex,
    nextPageToken
  );

  if (nextPageToken) {
    state.nextReplyPageToken = nextPageToken;
  } else {
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
  }

  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 내부 시트에서 답글 수집 대기 중인 최상위 댓글 하나를 선택합니다.
 */
function claimNextPendingReply_(internalSheet) {
  const statusRange = internalSheet.getRange(
    2,
    YT_CFG.INTERNAL_COL.REPLY_STATUS,
    Math.max(internalSheet.getLastRow() - 1, 1),
    1
  );

  let found = statusRange
    .createTextFinder('IN_PROGRESS')
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    found = statusRange
      .createTextFinder('PENDING')
      .matchEntireCell(true)
      .useRegularExpression(false)
      .findNext();
  }

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  if (values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] === 'PENDING') {
    internalSheet
      .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS)
      .setValue('IN_PROGRESS');
  }

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    pageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 댓글 1건을 사용자가 보는 8열 행으로 변환합니다.
 */
function commentToOutputRow_(state, comment, displayNumber) {
  const snippet = (comment && comment.snippet) || {};
  const text = String(snippet.textDisplay || '');

  return [
    String(displayNumber),
    safeCellText_(state.videoChannelTitle || ''),
    safeCellText_(state.videoTitle || ''),
    safeCellText_(snippet.authorDisplayName || ''),
    safeCellText_(text),
    Number(snippet.likeCount || 0),
    apiDateToSheetValue_(snippet.publishedAt),
    calculateCommentBytes_(text)
  ];
}


/**
 * 숨김 내부 시트의 행을 만듭니다.
 */
function buildInternalRow_(
  commentId,
  parentCommentId,
  displayNumber,
  commentType,
  replyStatus,
  nextReplyIndex,
  totalReplyCount,
  replyPageToken
) {
  return [
    safeCellText_(commentId || ''),
    safeCellText_(parentCommentId || ''),
    String(displayNumber || ''),
    String(commentType || ''),
    String(replyStatus || ''),
    nextReplyIndex === '' ? '' : Number(nextReplyIndex || 1),
    totalReplyCount === '' ? '' : Number(totalReplyCount || 0),
    safeCellText_(replyPageToken || '')
  ];
}


/**
 * 댓글 행과 내부 관리 행을 각각 일괄 기록합니다.
 */
function appendCollectedRecords_(
  commentsSheet,
  internalSheet,
  commentRows,
  internalRows
) {
  if (commentRows.length !== internalRows.length) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_ROW_MISMATCH',
      '댓글 저장 구조를 확인해야 합니다.',
      '댓글 행과 내부 관리 행의 개수가 일치하지 않습니다.',
      ['수집 상태를 기록하는 내부 데이터가 일시적으로 어긋났습니다.'],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  if (commentRows.length === 0) {
    return;
  }

  commentsSheet
    .getRange(
      commentsSheet.getLastRow() + 1,
      1,
      commentRows.length,
      YT_CFG.HEADERS.length
    )
    .setValues(commentRows);

  internalSheet
    .getRange(
      internalSheet.getLastRow() + 1,
      1,
      internalRows.length,
      YT_CFG.INTERNAL_HEADERS.length
    )
    .setValues(internalRows);
}


/**
 * 내부 시트에서 특정 댓글 ID의 관리 행을 찾습니다.
 */
function findInternalRecordByCommentId_(internalSheet, commentId) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return null;
  }

  const found = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .createTextFinder(String(commentId || ''))
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    replyStatus: String(
      values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    replyPageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 최상위 댓글의 답글 수집 진행 정보를 갱신합니다.
 */
function updateTopReplyProgress_(
  internalSheet,
  rowNumber,
  status,
  nextReplyIndex,
  pageToken
) {
  internalSheet
    .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS, 1, 4)
    .setValues([[
      status,
      Number(nextReplyIndex || 1),
      internalSheet
        .getRange(rowNumber, YT_CFG.INTERNAL_COL.TOTAL_REPLY_COUNT)
        .getValue(),
      pageToken || ''
    ]]);
}


/**
 * 완료 처리
 */
function finishCollection_(ss, commentsSheet, state) {
  state.status = 'COMPLETED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = state.topCount < state.targetTopLevelCount
    ? '댓글 ' +
      state.topCount +
      '개와 대댓글 ' +
      state.replyCount +
      '개를 수집했습니다.'
    : '댓글 수집을 완료했습니다.';
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'COMPLETED', state.message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


function isCancelRequested_() {
  return getUserProperties_().getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';
}


/**
 * 취소 처리
 */
function finalizeCancellation_(ss, commentsSheet, state) {
  const message = '사용자가 수집을 취소했습니다. 이미 저장된 댓글은 유지됩니다.';

  state.status = 'CANCELLED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = message;
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'CANCELLED', message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


/**
 * API 키가 YouTube Data API 요청에 사용 가능한지 확인합니다.
 */
function validateApiKey_(apiKey) {
  youtubeGetWithKey_(
    'videos',
    {
      part: 'id',
      id: 'jNQXAC9IVRw'
    },
    apiKey
  );
}


/**
 * 영상 메타데이터를 조회합니다.
 */
function getVideoMetadataWithKey_(videoId, apiKey) {
  const data = youtubeGetWithKey_(
    'videos',
    {
      part: 'snippet,statistics',
      id: videoId
    },
    apiKey
  );

  if (!Array.isArray(data.items) || data.items.length === 0) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '입력한 영상 주소에 해당하는 공개 영상을 YouTube Data API에서 조회하지 못했습니다.',
      [
        '영상 주소나 11자리 영상 ID가 정확하지 않을 수 있습니다.',
        '영상이 삭제되었거나 비공개 상태일 수 있습니다.',
        '연령·지역·계정 권한에 따라 접근이 제한된 영상일 수 있습니다.'
      ],
      [
        '브라우저에서 해당 영상 주소가 정상적으로 열리는지 확인합니다.',
        '주소 표시줄의 영상 URL 전체를 다시 복사합니다.',
        '사이드바의 영상 주소를 교체한 뒤 수집을 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: { videoId: videoId }
      }
    ));
  }

  const item = data.items[0];
  const snippet = item.snippet || {};
  const statistics = item.statistics || {};

  return {
    title: snippet.title || '',
    channelId: snippet.channelId || '',
    channelTitle: snippet.channelTitle || '',
    commentCount: statistics.commentCount || ''
  };
}


/**
 * 저장된 API 키로 YouTube Data API를 호출합니다.
 */
function youtubeGet_(resource, params) {
  return youtubeGetWithKey_(resource, params, getApiKey_());
}


/**
 * YouTube Data API GET 요청을 수행합니다.
 */
function youtubeGetWithKey_(resource, params, apiKey) {
  const queryParams = Object.assign({}, params, { key: apiKey });

  const query = Object.keys(queryParams)
    .filter(function(key) {
      const value = queryParams[key];
      return value !== undefined && value !== null && value !== '';
    })
    .map(function(key) {
      return encodeURIComponent(key) + '=' + encodeURIComponent(queryParams[key]);
    })
    .join('&');

  const url = YT_CFG.API_BASE + '/' + resource + '?' + query;
  const transientCodes = [429, 500, 502, 503, 504];

  for (let attempt = 0; attempt < 3; attempt += 1) {
    let response;

    try {
      response = UrlFetchApp.fetch(url, {
        method: 'get',
        muteHttpExceptions: true,
        headers: { Accept: 'application/json' }
      });
    } catch (networkError) {
      if (attempt < 2) {
        Utilities.sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      throwStructuredError_(buildErrorInfo_(
        'NETWORK_REQUEST_FAILED',
        'YouTube 서버에 연결하지 못했습니다.',
        'Apps Script에서 YouTube Data API로 보내는 외부 요청이 완료되지 않았습니다.',
        [
          'Google 서비스 또는 네트워크에 일시적인 장애가 발생했을 수 있습니다.',
          'Apps Script의 외부 요청 권한이 승인되지 않았을 수 있습니다.'
        ],
        [
          '잠시 뒤 같은 작업을 다시 실행합니다.',
          'Apps Script 권한 승인 화면이 나타나면 요청된 권한을 허용합니다.',
          'Apps Script의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.'
        ],
        {
          actionLabel: '확인',
          technical: {
            resource: resource,
            originalMessage: String(networkError && networkError.message || networkError)
          }
        }
      ));
    }

    const statusCode = response.getResponseCode();
    const responseText = response.getContentText();

    if (statusCode >= 200 && statusCode < 300) {
      return responseText ? JSON.parse(responseText) : {};
    }

    if (transientCodes.indexOf(statusCode) >= 0 && attempt < 2) {
      Utilities.sleep(Math.pow(2, attempt) * 1000);
      continue;
    }

    const parsedError = parseYouTubeErrorResponse_(responseText);

    throwStructuredError_(classifyYouTubeApiError_(
      statusCode,
      parsedError.reason,
      parsedError.message,
      resource
    ));
  }

  throwStructuredError_(buildErrorInfo_(
    'YOUTUBE_REQUEST_REPEATED_FAILURE',
    'YouTube API 요청이 반복적으로 실패했습니다.',
    '일시적인 서버 장애가 재시도 후에도 계속되었습니다.',
    ['YouTube 또는 Google 네트워크 서비스가 불안정할 수 있습니다.'],
    [
      '잠시 뒤 같은 작업을 다시 실행합니다.',
      '반복되면 Apps Script의 ‘실행’ 기록을 확인합니다.'
    ],
    { actionLabel: '확인', technical: { resource: resource } }
  ));
}


function parseYouTubeErrorResponse_(responseText) {
  let reason = '';
  let message = String(responseText || '');

  try {
    const parsed = JSON.parse(responseText);

    if (parsed.error) {
      message = parsed.error.message || message;

      if (Array.isArray(parsed.error.errors) && parsed.error.errors[0]) {
        reason = parsed.error.errors[0].reason || '';
      }

      if (!reason && parsed.error.status) {
        reason = parsed.error.status;
      }
    }
  } catch (parseError) {
    // JSON이 아닌 오류 본문은 문자열 그대로 분류합니다.
  }

  return {
    reason: String(reason || ''),
    message: String(message || '')
  };
}


/**
 * YouTube API 오류를 한국어 모달용 정보로 분류합니다.
 */
function classifyYouTubeApiError_(statusCode, reason, message, resource) {
  const reasonText = String(reason || '');
  const messageText = String(message || '');
  const combined = (reasonText + ' ' + messageText).toLowerCase();
  const technical = {
    httpStatus: statusCode,
    apiReason: reasonText,
    resource: resource,
    originalMessage: messageText
  };

  if (
    combined.indexOf('keyinvalid') >= 0 ||
    combined.indexOf('api key not valid') >= 0 ||
    combined.indexOf('api_key_invalid') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_INVALID',
      'API 키를 사용할 수 없습니다.',
      '입력한 API 키가 정확하지 않거나 삭제·재발급되어 현재 요청에 사용할 수 없습니다.',
      [
        'API 키 일부가 누락되었을 수 있습니다.',
        'Google Cloud에서 기존 키가 삭제되거나 재발급되었을 수 있습니다.',
        'API 키가 아닌 다른 프로젝트 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 전체를 다시 복사합니다.',
        '사이드바에서 API 키를 다시 입력하고 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') >= 0 ||
    combined.indexOf('access not configured') >= 0 ||
    combined.indexOf('service_disabled') >= 0 ||
    combined.indexOf('api_disabled') >= 0 ||
    combined.indexOf('has not been used in project') >= 0 ||
    combined.indexOf('it is disabled') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_API_NOT_ENABLED',
      'YouTube Data API v3가 활성화되어 있지 않습니다.',
      'API 키가 속한 Google Cloud 프로젝트에서 YouTube Data API v3 사용 설정을 켜야 합니다.',
      [
        'API 키를 만든 프로젝트에서 YouTube Data API v3를 아직 활성화하지 않았습니다.',
        'API를 활성화한 프로젝트와 API 키를 발급한 프로젝트가 다를 수 있습니다.'
      ],
      [
        'Google Cloud Console에서 API 키를 만든 프로젝트를 선택합니다.',
        '‘API 및 서비스 → 라이브러리’로 이동합니다.',
        '‘YouTube Data API v3’를 검색하고 ‘사용’을 누릅니다.',
        '설정 반영을 위해 1~5분 기다린 뒤 API 키를 다시 저장합니다.'
      ],
      {
        helpLabel: 'YouTube Data API 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/library/youtube.googleapis.com',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('iprefererblocked') >= 0 ||
    combined.indexOf('referer') >= 0 && combined.indexOf('blocked') >= 0 ||
    combined.indexOf('api key restrictions') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_APPLICATION_RESTRICTION',
      'API 키의 애플리케이션 제한이 Apps Script 요청을 차단했습니다.',
      '현재 키에 설정된 웹사이트·IP 제한이 Apps Script의 UrlFetch 요청 방식과 맞지 않습니다.',
      [
        'HTTP 리퍼러 제한 또는 특정 IP 주소 제한이 적용되어 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키의 애플리케이션 제한을 확인합니다.',
        'Apps Script에서 사용할 수 있는 제한 방식으로 조정합니다.',
        'API 제한은 ‘YouTube Data API v3’로 유지합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') < 0 &&
    (
      combined.indexOf('forbidden') >= 0 &&
      combined.indexOf('api') >= 0 &&
      combined.indexOf('key') >= 0
    )
  ) {
    return buildErrorInfo_(
      'API_KEY_API_RESTRICTION',
      'API 키의 API 제한 설정을 확인해야 합니다.',
      '현재 API 키가 YouTube Data API v3 호출을 허용하지 않을 수 있습니다.',
      [
        'API 키의 ‘API 제한’ 목록에서 YouTube Data API v3가 빠져 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키를 선택합니다.',
        '‘API 제한’에서 YouTube Data API v3를 허용합니다.',
        '저장 후 1~5분 뒤 다시 실행합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('quotaexceeded') >= 0 ||
    combined.indexOf('dailylimitexceeded') >= 0 ||
    combined.indexOf('daily limit') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_QUOTA_EXCEEDED',
      'YouTube API의 오늘 할당량을 모두 사용했습니다.',
      '현재 Google Cloud 프로젝트에서 오늘 사용할 수 있는 YouTube Data API 할당량이 남아 있지 않습니다.',
      ['같은 프로젝트의 다른 프로그램에서도 YouTube API 할당량을 사용했을 수 있습니다.'],
      [
        'Google Cloud Console에서 YouTube Data API 사용량을 확인합니다.',
        '일일 할당량이 갱신된 뒤 다시 실행합니다.',
        '필요하면 다음 수집의 댓글 개수를 줄입니다.'
      ],
      {
        helpLabel: 'YouTube API 할당량 열기',
        helpUrl: 'https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas',
        actionLabel: '확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('ratelimitexceeded') >= 0 ||
    combined.indexOf('userratelimitexceeded') >= 0 ||
    statusCode === 429
  ) {
    return buildErrorInfo_(
      'YOUTUBE_RATE_LIMIT',
      '짧은 시간에 API 요청이 많이 발생했습니다.',
      'YouTube Data API가 일시적으로 요청 속도를 제한했습니다.',
      ['여러 수집 작업을 연속으로 실행했을 수 있습니다.'],
      [
        '현재 작업이 자동 재개되는지 확인합니다.',
        '몇 분 뒤 다시 실행합니다.',
        '동시에 여러 스프레드시트에서 같은 API 키를 사용하고 있다면 실행 횟수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (combined.indexOf('commentsdisabled') >= 0) {
    return buildErrorInfo_(
      'COMMENTS_DISABLED',
      '이 영상에서는 댓글을 수집할 수 없습니다.',
      '영상 게시자가 댓글 기능을 사용하지 않도록 설정했습니다.',
      ['영상의 댓글 기능이 꺼져 있거나 YouTube 정책에 따라 제한되었습니다.'],
      [
        '영상 페이지에서 댓글 영역이 표시되는지 확인합니다.',
        '댓글이 허용된 다른 영상 주소를 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('videonotfound') >= 0 ||
    combined.indexOf('video not found') >= 0
  ) {
    return buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '영상 주소가 잘못되었거나 영상이 삭제·비공개 상태일 수 있습니다.',
      [
        '영상 ID가 정확하지 않을 수 있습니다.',
        '영상 공개 상태가 변경되었을 수 있습니다.'
      ],
      [
        '브라우저에서 영상 주소가 정상적으로 열리는지 확인합니다.',
        '영상 URL 전체를 다시 복사해 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (statusCode >= 500) {
    return buildErrorInfo_(
      'YOUTUBE_SERVER_ERROR',
      'YouTube 서버에서 일시적인 오류가 발생했습니다.',
      'YouTube Data API 서버가 현재 요청을 정상적으로 처리하지 못했습니다.',
      ['YouTube 측의 일시적인 서비스 장애일 수 있습니다.'],
      [
        '잠시 뒤 같은 작업을 다시 실행합니다.',
        '진행 중인 수집이라면 자동 재개 여부를 확인합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (statusCode === 403) {
    return buildErrorInfo_(
      'YOUTUBE_ACCESS_FORBIDDEN',
      'YouTube 데이터에 접근할 수 없습니다.',
      'API 키 설정, 영상 공개 상태 또는 Google Cloud 프로젝트 권한을 확인해야 합니다.',
      [
        'API 키 제한 설정이 요청을 차단했을 수 있습니다.',
        '영상이 공개 API에서 접근할 수 없는 상태일 수 있습니다.'
      ],
      [
        'API 키의 API 제한과 애플리케이션 제한을 확인합니다.',
        '영상이 공개 상태인지 확인합니다.',
        'Google Cloud에서 YouTube Data API v3가 활성화되어 있는지 확인합니다.'
      ],
      {
        helpLabel: 'API 키 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (statusCode === 400) {
    return buildErrorInfo_(
      'YOUTUBE_BAD_REQUEST',
      'YouTube API 요청 형식을 확인해야 합니다.',
      '영상 주소 또는 요청 매개변수 중 하나를 YouTube API가 처리하지 못했습니다.',
      ['영상 주소가 올바르지 않거나 API 요청 값이 허용 범위를 벗어났을 수 있습니다.'],
      [
        '영상 주소를 다시 확인합니다.',
        '수집 개수와 정렬 기준을 확인합니다.',
        '같은 문제가 계속되면 새 수집으로 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '입력값 확인',
        technical: technical
      }
    );
  }

  return buildErrorInfo_(
    'YOUTUBE_API_ERROR',
    'YouTube API 요청을 완료하지 못했습니다.',
    'YouTube Data API가 요청을 거부하거나 처리하지 못했습니다.',
    ['API 키, 영상 공개 상태, 할당량 또는 네트워크 상태를 확인해야 합니다.'],
    [
      'API 키 설정과 YouTube Data API 활성화 여부를 확인합니다.',
      '영상 주소가 공개 영상인지 확인합니다.',
      '잠시 뒤 다시 실행합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}


/**
 * 영상 URL 또는 11자리 영상 ID에서 videoId를 추출합니다.
 */
function extractVideoId_(input) {
  const text = String(input || '').trim();

  if (/^[A-Za-z0-9_-]{11}$/.test(text)) {
    return text;
  }

  const patterns = [
    /[?&]v=([A-Za-z0-9_-]{11})/,
    /youtu\.be\/([A-Za-z0-9_-]{11})/,
    /youtube(?:-nocookie)?\.com\/(?:embed|shorts|live)\/([A-Za-z0-9_-]{11})/
  ];

  for (let i = 0; i < patterns.length; i += 1) {
    const match = text.match(patterns[i]);

    if (match) {
      return match[1];
    }
  }

  throwStructuredError_(buildErrorInfo_(
    'INVALID_VIDEO_URL',
    'YouTube 영상 주소를 확인해야 합니다.',
    '입력한 값에서 11자리 YouTube 영상 ID를 찾지 못했습니다.',
    [
      '영상 주소 일부가 빠졌을 수 있습니다.',
      '채널·재생목록 주소를 입력했을 수 있습니다.'
    ],
    [
      'YouTube에서 수집할 영상을 엽니다.',
      '브라우저 주소 표시줄의 영상 URL 전체를 복사합니다.',
      '사이드바의 영상 주소 입력란에 붙여 넣습니다.'
    ],
    {
      focusTarget: 'videoUrl',
      actionLabel: '영상 주소 다시 입력'
    }
  ));
}


/**
 * 사이드바 입력값을 검증합니다.
 */
function normalizeSidebarInput_(formData) {
  const form = formData || {};
  const videoUrl = String(form.videoUrl || '').trim();
  const limit = parseInt(form.limit, 10);

  if (!videoUrl) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_URL_REQUIRED',
      'YouTube 영상 주소를 입력해야 합니다.',
      '수집 대상 영상 주소가 비어 있습니다.',
      ['영상 주소 입력란에 값이 없습니다.'],
      ['수집할 YouTube 영상의 URL을 입력합니다.'],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 입력'
      }
    ));
  }

  if (!Number.isInteger(limit)) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_INVALID',
      '수집 개수를 정수로 입력해야 합니다.',
      '수집할 최상위 댓글 개수가 올바른 정수 형식이 아닙니다.',
      ['빈 값, 소수 또는 문자가 입력되었을 수 있습니다.'],
      ['1 이상의 정수를 입력합니다.'],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 입력'
      }
    ));
  }

  if (limit < YT_CFG.MIN_LIMIT || limit > YT_CFG.MAX_LIMIT) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_OUT_OF_RANGE',
      '수집 개수가 허용 범위를 벗어났습니다.',
      '수집 개수는 ' + YT_CFG.MIN_LIMIT + '개 이상 ' +
        YT_CFG.MAX_LIMIT + '개 이하로 입력해야 합니다.',
      ['입력한 개수가 코드에 설정된 운영 범위를 벗어났습니다.'],
      [
        YT_CFG.MIN_LIMIT + '~' + YT_CFG.MAX_LIMIT +
          ' 사이의 정수를 입력합니다.'
      ],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 수정'
      }
    ));
  }

  return {
    videoUrl: videoUrl,
    limit: limit,
    includeReplies: form.includeReplies === true
  };
}


/**
 * 결과 시트와 숨김 내부 시트를 준비합니다.
 */
function ensureInternalSheet_(ss) {
  let internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    internal = ss.insertSheet(YT_CFG.INTERNAL_SHEET);
  }

  ensureColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);

  if (internal.getLastRow() === 0) {
    internal
      .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
      .setValues([YT_CFG.INTERNAL_HEADERS]);
  }

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 새 수집에 사용할 결과 시트를 시트1, 시트2, 시트3 ... 순서로 만듭니다.
 *
 * 새 스프레드시트에 기본 빈 '시트1' 하나만 존재하는 경우에는 그 시트를
 * 첫 결과 시트로 사용합니다. 그 이후 수집부터는 항상 새 시트를 추가합니다.
 */
function createNextOutputSheet_(ss) {
  const sheets = ss.getSheets();

  if (
    sheets.length === 1 &&
    sheets[0].getName() === YT_CFG.OUTPUT_SHEET_PREFIX + '1' &&
    isSheetCompletelyBlank_(sheets[0])
  ) {
    prepareOutputSheet_(sheets[0]);
    return sheets[0];
  }

  let maxNumber = 0;
  const namePattern = new RegExp(
    '^' + escapeRegExp_(YT_CFG.OUTPUT_SHEET_PREFIX) + '(\\d+)$'
  );

  sheets.forEach(function(sheet) {
    const match = sheet.getName().match(namePattern);

    if (match) {
      maxNumber = Math.max(maxNumber, Number(match[1] || 0));
    }
  });

  let nextNumber = maxNumber + 1;
  let nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;

  while (ss.getSheetByName(nextName)) {
    nextNumber += 1;
    nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;
  }

  const sheet = ss.insertSheet(nextName);
  prepareOutputSheet_(sheet);
  return sheet;
}


function isSheetCompletelyBlank_(sheet) {
  return sheet.getLastRow() === 0 && sheet.getLastColumn() === 0;
}


function prepareOutputSheet_(sheet) {
  if (sheet.getFilter()) {
    sheet.getFilter().remove();
  }

  sheet.clear();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setValues([YT_CFG.HEADERS]);

  sheet.setFrozenRows(1);
  sheet.getRange('A:A').setNumberFormat('@');
  formatCommentsSheet_(sheet);
}


/**
 * 새 수집을 위해 숨김 내부 시트만 초기화합니다.
 * 이전 결과 시트의 내용은 변경하지 않습니다.
 */
function resetInternalData_(ss) {
  const internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_SHEET_NOT_FOUND',
      '내부 관리 시트를 준비하지 못했습니다.',
      '댓글 수집 상태를 저장하는 숨김 시트가 존재하지 않습니다.',
      ['내부 시트 생성 과정이 완료되지 않았습니다.'],
      ['사이드바를 닫았다가 다시 열고 새 수집을 시작합니다.'],
      { actionLabel: '확인' }
    ));
  }

  internal.clear();
  ensureExactColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);
  internal
    .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .setValues([YT_CFG.INTERNAL_HEADERS]);

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 현재 수집 상태에 연결된 결과 시트를 찾습니다.
 */
function getOutputSheetForState_(ss, state) {
  const expectedId = Number(state.outputSheetId || 0);
  let outputSheet = null;

  if (expectedId > 0) {
    outputSheet = ss.getSheets().find(function(sheet) {
      return sheet.getSheetId() === expectedId;
    }) || null;
  }

  if (!outputSheet && state.outputSheetName) {
    outputSheet = ss.getSheetByName(String(state.outputSheetName));
  }

  if (!outputSheet) {
    throwStructuredError_(buildErrorInfo_(
      'OUTPUT_SHEET_NOT_FOUND',
      '수집 결과 시트를 찾을 수 없습니다.',
      '현재 수집 작업과 연결된 결과 시트가 삭제되었거나 이름과 식별 정보가 변경되었습니다.',
      [
        '수집 중 결과 시트를 삭제했을 수 있습니다.',
        '스프레드시트 구조가 외부 작업으로 변경되었을 수 있습니다.'
      ],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }

  return outputSheet;
}


function escapeRegExp_(text) {
  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}


/**
 * 이전 버전이 만든 수집로그 시트를 제거합니다.
 */
function deleteLegacyLogSheet_(ss) {
  const logSheet = ss.getSheetByName(YT_CFG.LEGACY_LOG_SHEET);

  if (logSheet && ss.getSheets().length > 1) {
    ss.deleteSheet(logSheet);
  }
}


/**
 * 댓글 시트를 번호 순으로 정렬하고 최종 서식을 적용합니다.
 */
function finalizeCommentsSheet_(sheet) {
  sortCommentsByDisplayNumber_(sheet);
  formatCommentsSheet_(sheet);
}


function sortCommentsByDisplayNumber_(sheet) {
  const lastRow = sheet.getLastRow();

  if (lastRow <= 2) {
    return;
  }

  // 정렬용 임시 열 I, J를 만든 뒤 최상위 번호와 답글 번호로 정렬합니다.
  ensureColumnCount_(sheet, 10);

  const numberValues = sheet
    .getRange(2, 1, lastRow - 1, 1)
    .getDisplayValues();

  const sortKeys = numberValues.map(function(row) {
    const parts = String(row[0] || '').split('_');
    return [
      Number(parts[0] || 0),
      parts.length > 1 ? Number(parts[1] || 0) : 0
    ];
  });

  sheet
    .getRange(2, 9, sortKeys.length, 2)
    .setValues(sortKeys);

  sheet
    .getRange(2, 1, lastRow - 1, 10)
    .sort([
      { column: 9, ascending: true },
      { column: 10, ascending: true }
    ]);

  sheet.getRange(2, 9, lastRow - 1, 2).clearContent();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
}


function formatCommentsSheet_(sheet) {
  const lastRow = sheet.getLastRow();

  sheet.setFrozenRows(1);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setFontWeight('bold')
    .setWrap(true)
    .setVerticalAlignment('middle');

  sheet.getRange('A:A').setNumberFormat('@');

  if (lastRow > 1) {
    sheet
      .getRange(2, 7, lastRow - 1, 1)
      .setNumberFormat('yyyy-mm-dd hh:mm:ss');

    sheet
      .getRange(2, 5, lastRow - 1, 1)
      .setWrap(true)
      .setVerticalAlignment('top');

    sheet
      .getRange(2, 1, lastRow - 1, YT_CFG.HEADERS.length)
      .setVerticalAlignment('top');

    if (sheet.getFilter()) {
      sheet.getFilter().remove();
    }

    sheet
      .getRange(1, 1, lastRow, YT_CFG.HEADERS.length)
      .createFilter();
  }

  sheet.setColumnWidth(1, 90);
  sheet.setColumnWidth(2, 180);
  sheet.setColumnWidth(3, 260);
  sheet.setColumnWidth(4, 170);
  sheet.setColumnWidth(5, 520);
  sheet.setColumnWidth(6, 95);
  sheet.setColumnWidth(7, 155);
  sheet.setColumnWidth(8, 95);
}


/**
 * 숨김 내부 시트에 저장된 댓글 ID 집합을 만듭니다.
 */
function getExistingCommentIds_(internalSheet) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return new Set();
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .getDisplayValues();

  return new Set(
    values
      .map(function(row) {
        return row[0];
      })
      .filter(function(value) {
        return Boolean(value);
      })
  );
}


/**
 * 숨김 내부 시트 기준으로 실제 최상위 댓글·답글 수를 계산합니다.
 */
function getExistingCounts_(internalSheet) {
  const lastRow = internalSheet.getLastRow();
  const counts = { top: 0, reply: 0 };

  if (lastRow <= 1) {
    return counts;
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_TYPE, lastRow - 1, 1)
    .getDisplayValues();

  values.forEach(function(row) {
    if (row[0] === 'topLevel') {
      counts.top += 1;
    } else if (row[0] === 'reply') {
      counts.reply += 1;
    }
  });

  return counts;
}


/**
 * 댓글 글자수를 지정된 바이트 규칙으로 계산합니다.
 * - ASCII 영역(영문, 숫자, 공백, 일반 문장부호): 1바이트
 * - 한글을 포함한 비ASCII 유니코드 문자: 코드 포인트당 2바이트
 */
function calculateCommentBytes_(value) {
  const text = String(value || '');
  let bytes = 0;

  Array.from(text).forEach(function(character) {
    const codePoint = character.codePointAt(0);
    bytes += codePoint <= 0x7F ? 1 : 2;
  });

  return bytes;
}


/**
 * 외부 문자열이 시트 수식으로 실행되는 것을 방지합니다.
 */
function safeCellText_(value) {
  const text = value === undefined || value === null ? '' : String(value);
  return /^[=+\-@]/.test(text) ? "'" + text : text;
}


function apiDateToSheetValue_(value) {
  return value ? new Date(value) : '';
}


function ensureColumnCount_(sheet, requiredColumns) {
  const current = sheet.getMaxColumns();

  if (current < requiredColumns) {
    sheet.insertColumnsAfter(current, requiredColumns - current);
  }
}


function ensureExactColumnCount_(sheet, requiredColumns) {
  ensureColumnCount_(sheet, requiredColumns);

  const current = sheet.getMaxColumns();

  if (current > requiredColumns) {
    sheet.deleteColumns(requiredColumns + 1, current - requiredColumns);
  }
}


function getUserProperties_() {
  return PropertiesService.getUserProperties();
}


function getApiKey_() {
  const apiKey = getUserProperties_().getProperty(YT_CFG.API_KEY_PROP);

  if (!apiKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키 설정이 필요합니다.',
      '댓글 수집을 시작하기 전에 YouTube Data API 키를 저장해야 합니다.',
      ['현재 사용자 계정에 저장된 API 키가 없습니다.'],
      [
        '사이드바 상단의 API 키 입력란에 키를 입력합니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  return apiKey.trim();
}


function loadState_() {
  const text = getUserProperties_().getProperty(YT_CFG.STATE_PROP);
  return text ? JSON.parse(text) : null;
}


function saveState_(state) {
  state.updatedAt = new Date().toISOString();
  const text = JSON.stringify(state);
  const byteLength = Utilities.newBlob(text).getBytes().length;

  if (byteLength > 8500) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_STORAGE_LIMIT',
      '수집 진행 상태를 저장할 수 없습니다.',
      'Apps Script 사용자 속성의 안전 저장 크기를 초과했습니다.',
      ['진행 상태 데이터가 예상보다 커졌습니다.'],
      [
        '현재 수집을 취소합니다.',
        '댓글 수집 개수를 줄여 새로 실행합니다.'
      ],
      { actionLabel: '확인', technical: { byteLength: byteLength } }
    ));
  }

  getUserProperties_().setProperty(YT_CFG.STATE_PROP, text);
}


function loadLastResult_() {
  const text = getUserProperties_().getProperty(YT_CFG.LAST_RESULT_PROP);
  return text ? JSON.parse(text) : null;
}


function saveLastResult_(state, status, message, errorInfo) {
  const result = {
    status: status,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: Number(state.targetTopLevelCount || 0),
    topCount: Number(state.topCount || 0),
    replyCount: Number(state.replyCount || 0),
    apiCalls: Number(state.apiCalls || 0),
    startedAt: state.startedAt || '',
    updatedAt: new Date().toISOString(),
    finishedAt: new Date().toISOString(),
    message: message || '',
    error: errorInfo || null
  };

  getUserProperties_().setProperty(
    YT_CFG.LAST_RESULT_PROP,
    JSON.stringify(result)
  );
}


function validateStateVersion_(state) {
  if (Number(state.version || 0) !== YT_CFG.STATE_VERSION) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_VERSION_MISMATCH',
      '이전 코드에서 시작된 수집 작업을 이어갈 수 없습니다.',
      '현재 Code.gs의 댓글 저장 구조가 이전 실행 상태와 다릅니다.',
      ['고정 결과 시트 또는 정렬 기준을 사용하던 이전 코드의 작업 상태가 남아 있습니다.'],
      [
        '사이드바에서 진행 중인 수집을 취소합니다.',
        '현재 코드로 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }
}


function normalizeState_(state) {
  state.currentReplyParentId = state.currentReplyParentId || '';
  state.nextReplyPageToken = state.nextReplyPageToken || '';
  state.nextThreadPageToken = state.nextThreadPageToken || '';
  state.threadDone = Boolean(state.threadDone);
  state.topCount = Number(state.topCount || 0);
  state.replyCount = Number(state.replyCount || 0);
  state.apiCalls = Number(state.apiCalls || 0);
  state.threadPages = Number(state.threadPages || 0);
  state.replyPages = Number(state.replyPages || 0);
  state.targetTopLevelCount = Number(state.targetTopLevelCount || 0);
  state.outputSheetId = Number(state.outputSheetId || 0);
  state.outputSheetName = String(state.outputSheetName || '');
  state.error = state.error || null;
}


function maskApiKey_(apiKey) {
  const key = String(apiKey || '');
  return '••••••••••••' + key.slice(-4);
}


function buildProgressForClient_(state, status) {
  const target = Number(state.targetTopLevelCount || 0);
  const top = Number(state.topCount || 0);
  const reply = Number(state.replyCount || 0);
  const percent = target > 0
    ? Math.min(100, Math.round((top / target) * 100))
    : 0;

  let stage = '대기 중';

  if (status === 'RUNNING') {
    if (state.currentReplyParentId) {
      stage = '답글 수집 중';
    } else if (!state.threadDone) {
      stage = '최상위 댓글 수집 중';
    } else {
      stage = '마무리 중';
    }
  } else if (status === 'COMPLETED') {
    stage = '완료';
  } else if (status === 'ERROR') {
    stage = '오류';
  } else if (status === 'CANCELLED') {
    stage = '취소됨';
  }

  return {
    status: status,
    stage: stage,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: target,
    topCount: top,
    replyCount: reply,
    totalRows: top + reply,
    apiCalls: Number(state.apiCalls || 0),
    percent: percent,
    startedAt: state.startedAt || '',
    updatedAt: state.updatedAt || '',
    message: state.message || '',
    error: state.error || null
  };
}


function buildServerProgressMessage_(state) {
  return (
    '최상위 댓글 ' +
    state.topCount +
    '/' +
    state.targetTopLevelCount +
    '개, 답글 ' +
    state.replyCount +
    '개를 저장했습니다.'
  );
}


function scheduleContinuation_() {
  deleteContinuationTriggers_();

  ScriptApp
    .newTrigger(YT_CFG.CONTINUE_HANDLER)
    .timeBased()
    .after(YT_CFG.CONTINUE_AFTER_MS)
    .create();
}


function deleteContinuationTriggers_() {
  ScriptApp.getProjectTriggers().forEach(function(trigger) {
    if (trigger.getHandlerFunction() === YT_CFG.CONTINUE_HANDLER) {
      ScriptApp.deleteTrigger(trigger);
    }
  });
}


/**
 * 한국어 모달용 오류 정보를 만듭니다.
 */
function buildErrorInfo_(code, title, summary, causes, steps, options) {
  const opts = options || {};

  return {
    code: String(code || 'UNKNOWN_ERROR'),
    title: String(title || '작업을 완료하지 못했습니다.'),
    summary: String(summary || '처리 중 문제가 발생했습니다.'),
    causes: Array.isArray(causes) ? causes.map(String) : [],
    steps: Array.isArray(steps) ? steps.map(String) : [],
    helpLabel: String(opts.helpLabel || ''),
    helpUrl: String(opts.helpUrl || ''),
    focusTarget: String(opts.focusTarget || ''),
    actionLabel: String(opts.actionLabel || '확인'),
    technical:
      opts.technical && typeof opts.technical === 'object'
        ? opts.technical
        : {}
  };
}


/**
 * 서버 오류를 Sidebar.html이 해석할 수 있는 구조화된 예외로 전달합니다.
 */
function throwStructuredError_(errorInfo) {
  throw new Error(
    YT_CFG.STRUCTURED_ERROR_PREFIX + JSON.stringify(errorInfo)
  );
}


function extractStructuredError_(rawText) {
  const raw = String(rawText || '');
  const markerIndex = raw.indexOf(YT_CFG.STRUCTURED_ERROR_PREFIX);

  if (markerIndex < 0) {
    return null;
  }

  const jsonText = raw.slice(
    markerIndex + YT_CFG.STRUCTURED_ERROR_PREFIX.length
  );

  try {
    return JSON.parse(jsonText);
  } catch (parseError) {
    return null;
  }
}


/**
 * Apps Script 자체 오류도 한국어 모달 정보로 변환합니다.
 */
function normalizeErrorInfo_(error, context) {
  const raw = error && error.message
    ? String(error.message)
    : String(error || '');

  const structured = extractStructuredError_(raw);

  if (structured) {
    return structured;
  }

  const lower = raw.toLowerCase();
  const technical = {
    context: String(context || '작업 실행'),
    originalMessage: raw
  };

  if (
    lower.indexOf('authorization is required') >= 0 ||
    lower.indexOf('you do not have permission') >= 0 ||
    lower.indexOf('permissions') >= 0 && lower.indexOf('required') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_AUTH_REQUIRED',
      'Google 권한 승인이 필요합니다.',
      '현재 계정이 스프레드시트 또는 외부 API 요청 권한을 아직 승인하지 않았습니다.',
      ['Apps Script를 처음 실행했거나 새로운 권한이 추가되었습니다.'],
      [
        '스프레드시트 메뉴에서 사이드바를 다시 엽니다.',
        '권한 검토 화면에서 현재 Google 계정을 선택합니다.',
        '요청되는 권한을 허용한 뒤 다시 실행합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('maximum execution time') >= 0 ||
    lower.indexOf('exceeded maximum execution time') >= 0 ||
    lower.indexOf('timed out') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_EXECUTION_TIMEOUT',
      '한 번의 실행 가능 시간을 초과했습니다.',
      '댓글 또는 답글 처리 시간이 길어 현재 실행 구간이 종료되었습니다.',
      ['대량 댓글 수집으로 한 번의 Apps Script 실행 시간이 길어졌습니다.'],
      [
        '사이드바를 다시 열어 진행 상태를 확인합니다.',
        '멈춘 경우 ‘중단 지점부터 실행’을 한 번 실행합니다.',
        '같은 문제가 반복되면 수집 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('service invoked too many times') >= 0 ||
    lower.indexOf('quota') >= 0 && lower.indexOf('apps script') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_SERVICE_QUOTA',
      'Apps Script 서비스 사용 한도를 초과했습니다.',
      '현재 Google 계정 또는 스크립트의 일일 서비스 사용량이 허용 범위를 넘었습니다.',
      ['짧은 시간에 많은 외부 요청이나 스프레드시트 쓰기 작업이 실행되었습니다.'],
      [
        '잠시 뒤 다시 실행합니다.',
        '같은 날 반복되면 다음 날 다시 실행합니다.',
        '한 번에 수집하는 댓글 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  return buildErrorInfo_(
    'UNEXPECTED_ERROR',
    '예상하지 못한 오류가 발생했습니다.',
    '오류 유형을 자동으로 판별하지 못했습니다.',
    [
      '네트워크, 권한, Google 서비스 상태 또는 실행 환경에서 문제가 발생했을 수 있습니다.'
    ],
    [
      '사이드바를 닫았다가 다시 열고 같은 작업을 한 번 더 실행합니다.',
      'Apps Script 편집기의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.',
      'API 키와 영상 주소를 다시 확인합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}

Sidebar.html

YouTube 댓글 수집기

YouTube Data API v3 → Google Sheets

1. API 키

YouTube Data API 키

최초 1회 저장합니다. 키는 사용자별 Apps Script 속성에 보관됩니다.

2. 수집 설정

API 키를 저장하면 수집 설정이 활성화됩니다.

YouTube 영상 주소

수집할 최상위 댓글 수

1~50,000개. 답글 포함 시 실제 저장 행 수가 이 값보다 많아질 수 있습니다.

대댓글도 모두 수집

새 수집을 시작할 때마다 ‘시트1’, ‘시트2’, ‘시트3’ 형식의 새 시트가 생성됩니다. 기존 수집 결과는 유지됩니다.

Youtube Data API v3 KEY

AIzaSyDETqF5gzbFh3DG4U0N-rjT1yK2asM-1X4

교안 및 학습자료

(4차시) 앱스스크립트

교안 및 학습자료

[강의] 김민기_앱스스크립트.pdf

(5차시) 바른 API로 생기부 검토

Code.gs

// =================================================================
// [0] 초기 설정 및 메뉴
// =================================================================

function onOpen() {
  SpreadsheetApp.getUi().createMenu('민기쌤 생기부 도우미')
      .addItem('🚀 사이드바 열기', 'openSidebar') 
      .addToUi();
}

function renderView_(viewName) {
  var template = HtmlService.createTemplateFromFile('Sidebar');
  template.initialView = viewName || 'sidebar';
  return template.evaluate();
}

function openSidebar() {
  ensureBannedWordSheet_();
  var html = renderView_('sidebar')
      .setTitle('민기쌤 생기부 맞춤법 도우미')
      .setWidth(300); 
  SpreadsheetApp.getUi().showSidebar(html);
}

function openSpellCheckViewer() {
  var html = renderView_('spellcheck')
      .setWidth(1000) 
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '📝 Bareun 맞춤법 검사 및 수정');
}

function openBannedWordViewer() {
  var html = renderView_('banned')
      .setWidth(1000)
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '🚫 기재 금지어 점검');
}

// =================================================================
// [1] Bareun API 키 및 UI 설정
// =================================================================

function getBareunUserProperties_() {
  ensureBannedWordSheet_();
  var props = PropertiesService.getUserProperties();
  var currentPolicy = 'BAREUN_ONLY_KEYS_V3';
  var previousPolicy = props.getProperty('API_KEY_POLICY_VERSION');

  // 정책 변경 시 현재 기능에서 쓰지 않는 예전 사용자 설정을 한 번 정리합니다.
  if (previousPolicy !== currentPolicy) {
    var allowedProperties = {
      UI_STATE: true,
      API_KEY_POLICY_VERSION: true
    };
    // 바로 이전 사용자 입력형 정책에서 저장한 키만 보존합니다.
    if (previousPolicy === 'USER_SUPPLIED_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V2') {
      allowedProperties.USER_BAREUN_KEY = true;
    }
    Object.keys(props.getProperties()).forEach(function(propertyName) {
      if (!allowedProperties[propertyName]) props.deleteProperty(propertyName);
    });

    var previousUiState = {};
    try {
      previousUiState = JSON.parse(props.getProperty('UI_STATE') || '{}');
    } catch (e) {
      previousUiState = {};
    }
    var currentUiState = {};
    ['card-api', 'sub-api-settings', 'card-util'].forEach(function(id) {
      if (previousUiState[id]) currentUiState[id] = true;
    });
    props.setProperty('UI_STATE', JSON.stringify(currentUiState));
    props.setProperty('API_KEY_POLICY_VERSION', currentPolicy);
  }

  return props;
}

function saveUserBareunKey(bareunKey) {
  var props = getBareunUserProperties_();
  var cleanBareunKey = String(bareunKey || '').trim();

  if (!cleanBareunKey) {
    throw new Error('Bareun API 키를 입력해 주세요. 이 도우미는 API 키를 제공하지 않습니다.');
  }

  props.setProperty('USER_BAREUN_KEY', cleanBareunKey);
  return { hasBareun: true };
}

function checkUserBareunStatus() {
  var props = getBareunUserProperties_();
  return { hasBareun: !!props.getProperty('USER_BAREUN_KEY') };
}

function clearUserBareunKey() {
  var props = getBareunUserProperties_();
  props.deleteProperty('USER_BAREUN_KEY');
  return { hasBareun: false };
}

function getBareunKey() {
  var key = getBareunUserProperties_().getProperty('USER_BAREUN_KEY');
  if (!key) throw new Error("Bareun API 키가 없습니다. 사이드바 상단에서 등록해주세요.");
  return key;
}

// =================================================================
// [2] Bareun 맞춤법 검사
// =================================================================

function getSelectedDataForSpellCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");
  var rows = [];
  var startRow = range.getRow();
  var startCol = range.getColumn();
  var values = range.getValues();
  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var text = values[i][j].toString();
      if (text.trim() !== "") {
        rows.push({ sheetName: sheetName, row: startRow + i, col: startCol + j, original: text });
      }
    }
  }
  return rows;
}

function getBareunCorrection(text) {
  var userKey = getBareunKey();
  var result = callBareunApi(text, userKey); 
  return result; 
}

function applySpellCheckResults(updates) {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  updates.forEach(function(item) {
    var sheet = spreadsheet.getSheetByName(item.sheetName);
    if (!sheet) throw new Error('검사한 시트를 찾을 수 없습니다: ' + item.sheetName);
    sheet.getRange(item.row, item.col).setValue(item.text);
  });
  return updates.length;
}

function callBareunApi(text, userKey) {
  var url = "https://api.bareun.ai/bareun.RevisionService/CorrectError";
  var options = {
    "method": "post", "contentType": "application/json", "headers": { "api-key": userKey }, "muteHttpExceptions": true,
    "payload": JSON.stringify({ "document": { "content": text, "language": "ko-KR" }, "encoding_type": "UTF16" })
  };
  var response = UrlFetchApp.fetch(url, options);
  var result = JSON.parse(response.getContentText());
  
  if (response.getResponseCode() !== 200) {
    return { error: "API 오류: " + response.getResponseCode() };
  }
  return { revised: result.revised, helps: result.helps || {}, rawBlocks: result.revisedBlocks || result.revised_blocks || [], error: null };
}

// =================================================================
// [3] 기재 금지어 관리
// =================================================================

var BANNED_WORD_SHEET_NAME_ = '기재금지어관리';
var BANNED_WORD_HEADERS_ = ['번호', '기재 금지어'];
var LEGACY_BANNED_WORD_HEADERS_ = ['유형', '기재 금지어', '대체 표현'];
var ONE_COLUMN_BANNED_WORD_HEADERS_ = ['기재 금지어'];

function getLegacyBannedWordList_() {
  var saved = PropertiesService.getUserProperties().getProperty('BANNED_WORDS_DB');
  if (!saved) return getDefaultBannedList_();

  try {
    var parsed = JSON.parse(saved);
    if (!Array.isArray(parsed)) return getDefaultBannedList_();
    return parsed
      .map(function(item) {
        return String(item && item.k || '').trim();
      })
      .filter(function(keyword) { return keyword !== ''; });
  } catch (e) {
    return getDefaultBannedList_();
  }
}

function initializeBannedWordSheet_(sheet, list) {
  sheet.getRange(1, 1, 1, BANNED_WORD_HEADERS_.length)
    .setValues([BANNED_WORD_HEADERS_])
    .setBackground('#fce8e6')
    .setFontColor('#a50e0e')
    .setFontWeight('bold')
    .setHorizontalAlignment('center');

  var rows = list.map(function(keyword, index) {
    return [index + 1, keyword];
  });
  if (rows.length > 0) sheet.getRange(2, 1, rows.length, 2).setValues(rows);

  sheet.setFrozenRows(1);
  sheet.setColumnWidth(1, 60);
  sheet.setColumnWidth(2, 260);
  sheet.setTabColor('#d93025');
}

function migrateLegacyBannedWordSheet_(sheet) {
  var lastColumn = sheet.getLastColumn();
  var legacyColumn;
  var clearColumns;

  if (lastColumn >= 3 && sheet.getRange(1, 1, 1, 3).getDisplayValues()[0].join('|') === LEGACY_BANNED_WORD_HEADERS_.join('|')) {
    legacyColumn = 2;
    clearColumns = 3;
  } else if (sheet.getRange(1, 1, 1, 1).getDisplayValues()[0][0] === ONE_COLUMN_BANNED_WORD_HEADERS_[0]) {
    legacyColumn = 1;
    clearColumns = 1;
  } else {
    return false;
  }

  var lastRow = sheet.getLastRow();
  var keywords = lastRow < 2 ? [] : sheet.getRange(2, legacyColumn, lastRow - 1, 1)
    .getDisplayValues()
    .map(function(row) { return String(row[0] || '').trim(); })
    .filter(function(keyword) { return keyword !== ''; });

  var clearRows = Math.max(sheet.getLastRow(), 1);
  sheet.getRange(1, 1, clearRows, clearColumns).clearContent();
  initializeBannedWordSheet_(sheet, keywords);
  return true;
}

function ensureBannedWordSheet_() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  if (!spreadsheet) throw new Error('활성 스프레드시트를 찾을 수 없습니다.');

  var originalSheet = spreadsheet.getActiveSheet();
  var originalRange = spreadsheet.getActiveRange();
  var lock = LockService.getDocumentLock() || LockService.getScriptLock();
  lock.waitLock(30000);

  var sheet;
  try {
    sheet = spreadsheet.getSheetByName(BANNED_WORD_SHEET_NAME_);
    if (!sheet) {
      sheet = spreadsheet.insertSheet(BANNED_WORD_SHEET_NAME_);
      initializeBannedWordSheet_(sheet, getLegacyBannedWordList_());
    } else {
      // 이전 형식은 금지어만 보존하여 번호·기재금지어 두 열 목록으로 안전하게 바꿉니다.
      migrateLegacyBannedWordSheet_(sheet);
    }

    // 시트로 옮긴 뒤 예전 사용자별 저장값은 더 이상 별도 원본으로 남기지 않습니다.
    PropertiesService.getUserProperties().deleteProperty('BANNED_WORDS_DB');
    return sheet;
  } finally {
    if (originalSheet && sheet && originalSheet.getSheetId() !== sheet.getSheetId()) {
      spreadsheet.setActiveSheet(originalSheet);
      if (originalRange) spreadsheet.setActiveRange(originalRange);
    }
    lock.releaseLock();
  }
}

function openBannedWordManagementSheet() {
  var sheet = ensureBannedWordSheet_();
  sheet.activate();
  sheet.getRange('A1').activate();
  return sheet.getName();
}

function getDefaultBannedList_() {
  return [
    "MBTI", "커리어넷", "메이저맵", "패들렛", "띵커벨", "알로",
    "미리캔버스", "망고보드", "유튜버", "유튜브", "넷플릭스", "왓챠",
    "티빙", "네이버 폼", "구글 폼", "OECD", "UN", "유네스코", "WTO",
    "WHO", "그린피스", "앰네스티", "IMF", "인스타그램", "페이스북",
    "카카오톡", "네이버", "구글", "클래스 카드", "구글 클래스룸", "게더타운",
    "제페토", "아이패드", "갤럭시 탭", "비트코인", "TED", "반크", "TOEIC",
    "TOEFL", "TEPS", "대회", "수상", "한자능력검정"
  ];
}

function getBannedWordList_() {
  var sheet = ensureBannedWordSheet_();
  var header = sheet.getRange(1, 1, 1, 2).getDisplayValues()[0];
  if (header.join('|') !== BANNED_WORD_HEADERS_.join('|')) {
    throw new Error('기재금지어관리 시트의 1행은 "번호 | 기재 금지어" 순서여야 합니다.');
  }

  var lastRow = sheet.getLastRow();
  if (lastRow < 2) return [];

  var values = sheet.getRange(2, 1, lastRow - 1, 2).getDisplayValues();
  var seen = {};
  var list = [];

  values.forEach(function(row, index) {
    var rowNumber = index + 2;
    var number = String(row[0] || '').trim();
    var keyword = String(row[1] || '').trim();

    if (!number && !keyword) return;
    if (!/^[1-9]\d*$/.test(number)) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 번호(A열)는 1 이상의 정수여야 합니다.');
    }
    if (!keyword) throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어(B열)를 입력해 주세요.');

    var duplicateKey = normalizeBannedWord_(keyword);
    if (seen[duplicateKey]) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어가 ' + seen[duplicateKey] + '행과 중복됩니다: ' + keyword);
    }
    seen[duplicateKey] = rowNumber;
    list.push(keyword);
  });

  return list;
}

function runBannedWordCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  var values = range.getValues();
  var startRow = range.getRow();
  var startCol = range.getColumn();
  
  var db = getBannedWordList_();
  if (db.length === 0) return [];
  db.sort(function(a, b) { return normalizeBannedWord_(b).length - normalizeBannedWord_(a).length; });
  var canonicalByNormalizedKeyword = {};
  db.forEach(function(keyword) { canonicalByNormalizedKeyword[normalizeBannedWord_(keyword)] = keyword; });
  var combinedPattern = new RegExp('(' + db.map(buildWhitespaceInsensitivePattern_).join('|') + ')', 'gi');

  var results = [];

  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var original = values[i][j].toString();
      if (!original.trim()) continue;

      var hasIssue = false;
      var logs = [];

      var counts = {};
      var match;
      while ((match = combinedPattern.exec(original)) !== null) {
        var normalizedMatch = normalizeBannedWord_(match[0]);
        var keyword = canonicalByNormalizedKeyword[normalizedMatch];
        if (keyword) {
          hasIssue = true;
          counts[keyword] = (counts[keyword] || 0) + 1;
        }
      }

      Object.keys(counts).forEach(function(keyword) {
        logs.push({ k: keyword, count: counts[keyword] });
      });

      if (hasIssue) {
        results.push({
          sheetName: sheetName,
          row: startRow + i,
          col: startCol + j,
          original: original,
          logs: logs
        });
      }
    }
  }
  return results;
}

function escapeRegExp(string) {
  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); 
}

function normalizeBannedWord_(value) {
  return String(value || '').replace(/\s+/g, '').toLocaleLowerCase();
}

function buildWhitespaceInsensitivePattern_(keyword) {
  var compact = normalizeBannedWord_(keyword);
  if (!compact) throw new Error('비어 있는 기재 금지어는 검사할 수 없습니다.');
  return compact.split('').map(function(character) {
    return escapeRegExp(character);
  }).join('[\\s\\u00A0]*');
}

// =================================================================
// [4] 로컬 검토 유틸리티
// =================================================================

function unifyToStraightQuotes() {
  var range = SpreadsheetApp.getActiveRange();
  var ui = SpreadsheetApp.getUi();
  if (!range) throw new Error('선택된 셀이 없습니다.');
  var response = ui.alert('따옴표 변환', '선택 영역의 둥근 따옴표를 곧은 따옴표로 변환하시겠습니까?', ui.ButtonSet.YES_NO);
  if (response != ui.Button.YES) return;
  try {
    range.createTextFinder('[‘’]').useRegularExpression(true).matchEntireCell(false).replaceAllWith("'");
    range.createTextFinder('[“”]').useRegularExpression(true).matchEntireCell(false).replaceAllWith('"');
    SpreadsheetApp.flush();
    ui.alert('✅ 변환 완료');
  } catch (e) { ui.alert('오류: ' + e.toString()); }
}

// [신규] 선택 영역 스페이스바 실수(2칸 이상) 수정 함수
function fixDoubleSpaces() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  const values = range.getValues();
  let fixCount = 0; // 수정된 셀 개수 카운트

  const newValues = values.map(row => {
    return row.map(cell => {
      let str = String(cell);
      // 공백이 2번 이상 연속( /  +/)으로 있으면 1번으로 변경
      // 줄바꿈(\n)은 건드리지 않도록 일반 공백( )만 타겟팅
      if (/ {2,}/.test(str)) {
        fixCount++;
        return str.replace(/ {2,}/g, ' '); 
      }
      return cell;
    });
  });

  if (fixCount > 0) {
    range.setValues(newValues);
  }
  
  return fixCount;
}

// =================================================================
// [5] UI 상태 저장/불러오기
// =================================================================

function saveUiState(cardId, isExpanded) {
  var props = PropertiesService.getUserProperties();
  var state = JSON.parse(props.getProperty('UI_STATE') || '{}');
  state[cardId] = isExpanded;
  props.setProperty('UI_STATE', JSON.stringify(state));
}

function getUiState() {
  var props = PropertiesService.getUserProperties();
  return JSON.parse(props.getProperty('UI_STATE') || '{}');
}

Sidebar.html


= 0 ? initialView : "sidebar"; ?>



  
    
    
    
    
  
  
    
      
        🔑 Bareun API 키 설정
        expand_more
      
      
        
          
            내 Bareun API 키
            expand_more
          
          
            ⌛ API 키 설정 확인 중...
            
              
              Bareun API 키
              
              공용 키는 제공하지 않습니다. 키는 사용자별 설정에 저장되고 원문을 화면으로 다시 불러오지 않습니다.
              
              
            
          
        
      
    

    
      
        📝 선택 영역 검사 및 정리
        expand_more
      
      
        
        
        
        
        
        
      
    

    
  





  
    
    
    
    
    
  
  

    
      fact_check 맞춤법 검사 및 수정
      
        원본 오류
        수정 제안
      
    

    
      
        
        데이터를 불러오는 중입니다...
      
      
    

    
      
      
    

    
  





  
    
    
    
    
  
  

    
      block 기재 금지어 검사
      
        금지어 발견
        오른쪽 수정안에서 문맥에 맞게 직접 고쳐 주세요.
      
    

    
      
        
        데이터를 분석 중입니다...

2026 AI·디지털 교육 역량강화 연수(국어 기초) - 8. 11. 공주대학교 천안캠퍼스

Tue, 11 Aug 2026 00:30:22 GMT

2026 AI·디지털 교육 역량강화 연수(국어 기초) - 8. 11. 공주대학교 천안캠퍼스

강사: 교사 김민기(민기쌤)
일시: 2026-08-11
장소: 공주대학교 8공학관

충청남도교육청 주관 연수입니다.

(1차시) 마주온 활용

교안 및 학습자료

[강의] 김민기_마주온 활용.pdf

(2차시) 토의·토론

교안 및 학습자료

[강의] 김민기_국어과 AI 환경에서의 주체성 토론.pdf

(3차시) AI 융합 수업 설계

Code.gs

const YT_CFG = Object.freeze({
  API_BASE: 'https://www.googleapis.com/youtube/v3',

  API_KEY_PROP: 'YT_API_KEY',
  STATE_PROP: 'YT_COMMENT_COLLECTOR_STATE',
  LAST_RESULT_PROP: 'YT_COMMENT_COLLECTOR_LAST_RESULT',
  CANCEL_REQUEST_PROP: 'YT_COMMENT_COLLECTOR_CANCEL_REQUEST',

  OUTPUT_SHEET_PREFIX: '시트',
  INTERNAL_SHEET: '_댓글수집_내부',
  LEGACY_LOG_SHEET: '수집로그',

  CONTINUE_HANDLER: 'continueCommentCollection',
  STRUCTURED_ERROR_PREFIX: 'YT_STRUCTURED_ERROR::',
  STATE_VERSION: 4,

  // Apps Script의 일반 실행 제한 전에 상태를 저장하고 다음 실행으로 넘깁니다.
  MAX_RUN_MS: 4 * 60 * 1000 + 30 * 1000,
  CONTINUE_AFTER_MS: 60 * 1000,

  MIN_LIMIT: 1,
  MAX_LIMIT: 50000,

  HEADERS: [
    '번호',
    '채널명',
    '영상 제목',
    '댓글 작성자',
    '댓글 내용',
    '좋아요 수',
    '작성 시각',
    '글자수'
  ],

  // 숨김 내부 시트의 열 구조입니다.
  INTERNAL_HEADERS: [
    'comment_id',
    'parent_comment_id',
    'display_number',
    'comment_type',
    'reply_status',
    'next_reply_index',
    'total_reply_count',
    'reply_page_token'
  ],

  INTERNAL_COL: Object.freeze({
    COMMENT_ID: 1,
    PARENT_ID: 2,
    DISPLAY_NUMBER: 3,
    COMMENT_TYPE: 4,
    REPLY_STATUS: 5,
    NEXT_REPLY_INDEX: 6,
    TOTAL_REPLY_COUNT: 7,
    REPLY_PAGE_TOKEN: 8
  })
});


/**
 * 스프레드시트를 열 때 사용자 메뉴를 만듭니다.
 */
function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('YouTube 댓글 수집')
    .addItem('사이드바 열기', 'showYouTubeCommentSidebar')
    .addSeparator()
    .addItem('중단 지점부터 실행', 'continueCommentCollection')
    .addItem('진행 중인 수집 취소', 'cancelCommentCollection')
    .addToUi();
}


/**
 * 오른쪽 사이드바를 엽니다.
 */
function showYouTubeCommentSidebar() {
  const html = HtmlService
    .createHtmlOutputFromFile('Sidebar')
    .setTitle('YouTube 댓글 수집기');

  SpreadsheetApp.getUi().showSidebar(html);
}


/**
 * 사이드바 초기 상태를 반환합니다.
 */
function getSidebarState() {
  const props = getUserProperties_();
  const apiKey = props.getProperty(YT_CFG.API_KEY_PROP) || '';
  const activeState = loadState_();
  const lastResult = loadLastResult_();
  const cancelRequested =
    props.getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';

  const progress = activeState
    ? buildProgressForClient_(activeState, 'RUNNING')
    : lastResult
      ? buildProgressForClient_(lastResult, lastResult.status || 'COMPLETED')
      : null;

  if (progress && activeState && cancelRequested) {
    progress.stage = '취소 처리 중';
    progress.message = '현재 실행 구간이 끝나는 즉시 안전하게 중단됩니다.';
  }

  return {
    apiKeyConfigured: Boolean(apiKey),
    apiKeyMask: apiKey ? maskApiKey_(apiKey) : '',
    running: Boolean(activeState),
    cancelRequested: cancelRequested,
    progress: progress
  };
}


/**
 * API 키를 실제 YouTube Data API 요청으로 검증한 뒤 사용자별 속성에 저장합니다.
 */
function saveApiKey(apiKey) {
  const cleanedKey = String(apiKey || '').trim();

  if (!cleanedKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키를 입력해야 합니다.',
      'Google Cloud에서 발급한 YouTube Data API 키가 입력되지 않았습니다.',
      ['API 키 입력란이 비어 있습니다.'],
      [
        'Google Cloud Console에서 API 키를 발급합니다.',
        'API 키 전체를 사이드바 입력란에 붙여 넣습니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  if (cleanedKey.length < 20) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_FORMAT_INVALID',
      'API 키 형식을 확인해야 합니다.',
      '입력한 문자열이 일반적인 Google API 키 길이보다 짧습니다.',
      [
        'API 키 일부만 복사했을 수 있습니다.',
        '프로젝트 ID나 다른 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 값을 처음부터 끝까지 다시 복사하여 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력'
      }
    ));
  }

  validateApiKey_(cleanedKey);

  const props = getUserProperties_();
  props.setProperty(YT_CFG.API_KEY_PROP, cleanedKey);

  // 이전 API 키 오류 안내가 새 키 저장 뒤 다시 나타나지 않도록 정리합니다.
  const previous = loadLastResult_();
  if (previous && previous.status === 'ERROR') {
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
  }

  return getSidebarState();
}


/**
 * 저장된 API 키를 삭제합니다.
 */
function deleteApiKey() {
  if (loadState_()) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_DELETE_BLOCKED',
      '수집 중에는 API 키를 삭제할 수 없습니다.',
      '현재 댓글 수집 작업이 저장된 API 키를 사용하고 있습니다.',
      ['진행 중인 작업이 존재합니다.'],
      [
        '현재 수집을 완료하거나 취소합니다.',
        '수집 상태가 종료된 뒤 API 키를 삭제합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.API_KEY_PROP);
  props.deleteProperty(YT_CFG.LAST_RESULT_PROP);

  return getSidebarState();
}


/**
 * 사이드바 입력값으로 새 수집 작업을 준비합니다.
 * 실제 수집은 runCollectionNow 또는 시간 기반 트리거가 수행합니다.
 */
function startCollectionFromSidebar(formData) {
  const lock = LockService.getScriptLock();
  lock.waitLock(10000);

  try {
    const apiKey = getApiKey_();
    const input = normalizeSidebarInput_(formData);
    const ss = SpreadsheetApp.getActiveSpreadsheet();

    if (!ss) {
      throwStructuredError_(buildErrorInfo_(
        'SPREADSHEET_NOT_FOUND',
        '댓글을 저장할 스프레드시트를 찾지 못했습니다.',
        '현재 Apps Script가 스프레드시트와 연결된 상태인지 확인해야 합니다.',
        [
          '독립 실행형 Apps Script 프로젝트에서 코드를 실행했을 수 있습니다.',
          '스프레드시트가 닫히거나 접근 권한이 변경되었을 수 있습니다.'
        ],
        [
          '댓글을 저장할 Google 스프레드시트를 엽니다.',
          '‘확장 프로그램 → Apps Script’에서 이 코드를 실행합니다.',
          '스프레드시트를 새로고침하고 사이드바를 다시 엽니다.'
        ],
        { actionLabel: '확인' }
      ));
    }

    // 영상과 API 키가 정상인지 먼저 확인합니다.
    const videoId = extractVideoId_(input.videoUrl);
    const metadata = getVideoMetadataWithKey_(videoId, apiKey);

    deleteContinuationTriggers_();

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    // 새 수집은 기존 결과를 지우지 않고 새 결과 시트에 기록합니다.
    const outputSheet = createNextOutputSheet_(ss);
    ensureInternalSheet_(ss);
    resetInternalData_(ss);
    deleteLegacyLogSheet_(ss);

    const state = {
      version: YT_CFG.STATE_VERSION,
      status: 'RUNNING',
      spreadsheetId: ss.getId(),

      outputSheetId: outputSheet.getSheetId(),
      outputSheetName: outputSheet.getName(),

      videoId: videoId,
      videoTitle: metadata.title,
      videoChannelId: metadata.channelId,
      videoChannelTitle: metadata.channelTitle,
      reportedCommentCount: metadata.commentCount,

      targetTopLevelCount: input.limit,
      includeReplies: input.includeReplies,

      nextThreadPageToken: '',
      threadDone: false,

      currentReplyParentId: '',
      nextReplyPageToken: '',

      topCount: 0,
      replyCount: 0,
      threadPages: 0,
      replyPages: 0,
      apiCalls: 1,

      startedAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      message: outputSheet.getName() + '에서 수집을 시작했습니다.',
      error: null
    };

    saveState_(state);

    // 사이드바가 닫혀도 수집이 이어지도록 예비 트리거를 만듭니다.
    scheduleContinuation_();

    return getSidebarState();

  } finally {
    lock.releaseLock();
  }
}


/**
 * 사이드바가 첫 실행 구간을 즉시 시작할 때 호출합니다.
 */
function runCollectionNow() {
  continueCommentCollection();
  return getSidebarState();
}


/**
 * 저장된 상태에서 댓글 수집을 계속합니다.
 */
function continueCommentCollection() {
  const lock = LockService.getScriptLock();

  if (!lock.tryLock(5000)) {
    return;
  }

  let ss = null;
  let state = null;
  let commentsSheet = null;

  try {
    state = loadState_();

    if (!state) {
      return;
    }

    validateStateVersion_(state);
    normalizeState_(state);

    ss = SpreadsheetApp.openById(state.spreadsheetId);
    ensureInternalSheet_(ss);
    deleteLegacyLogSheet_(ss);

    commentsSheet = getOutputSheetForState_(ss, state);
    const internalSheet = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);
    const existingIds = getExistingCommentIds_(internalSheet);
    const existingCounts = getExistingCounts_(internalSheet);

    // 시트 기록 직후 상태 저장 전에 실행이 끊긴 상황을 보정합니다.
    state.topCount = existingCounts.top;
    state.replyCount = existingCounts.reply;

    const runStartedAt = Date.now();

    while (Date.now() - runStartedAt < YT_CFG.MAX_RUN_MS) {
      if (isCancelRequested_()) {
        finalizeCancellation_(ss, commentsSheet, state);
        return;
      }

      // 처리 중이던 답글 페이지가 있으면 먼저 이어서 처리합니다.
      if (state.currentReplyParentId) {
        processReplyPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      // 내부 시트에서 답글 수집이 필요한 최상위 댓글을 하나 선택합니다.
      const pendingReply = claimNextPendingReply_(internalSheet);

      if (pendingReply) {
        state.currentReplyParentId = pendingReply.commentId;
        state.nextReplyPageToken = pendingReply.pageToken || '';
        saveState_(state);
        continue;
      }

      // 답글 대기 항목이 없을 때 다음 최상위 댓글 페이지를 가져옵니다.
      if (!state.threadDone) {
        processThreadPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      finishCollection_(ss, commentsSheet, state);
      return;
    }

    state.updatedAt = new Date().toISOString();
    state.message = '실행 시간을 고려하여 진행 상태를 저장했습니다.';
    saveState_(state);
    scheduleContinuation_();

  } catch (error) {
    deleteContinuationTriggers_();

    const errorInfo = normalizeErrorInfo_(error, '댓글 수집');

    if (errorInfo.code === 'API_KEY_INVALID') {
      getUserProperties_().deleteProperty(YT_CFG.API_KEY_PROP);
    }

    if (commentsSheet) {
      try {
        finalizeCommentsSheet_(commentsSheet);
      } catch (formatError) {
        console.error(formatError);
      }
    }

    if (state) {
      state.status = 'ERROR';
      state.updatedAt = new Date().toISOString();
      state.message = errorInfo.summary;
      state.error = errorInfo;
      saveLastResult_(state, 'ERROR', errorInfo.summary, errorInfo);
    }

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    console.error(error);
    throwStructuredError_(errorInfo);

  } finally {
    lock.releaseLock();
  }
}


/**
 * 진행 중인 수집을 취소합니다.
 */
function cancelCommentCollection() {
  const props = getUserProperties_();
  const state = loadState_();

  if (!state) {
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
    deleteContinuationTriggers_();
    return getSidebarState();
  }

  props.setProperty(YT_CFG.CANCEL_REQUEST_PROP, 'true');
  deleteContinuationTriggers_();

  const lock = LockService.getScriptLock();

  // 다른 수집 실행이 없다면 이 호출에서 즉시 취소를 마무리합니다.
  if (lock.tryLock(200)) {
    try {
      const latestState = loadState_();

      if (latestState) {
        const ss = SpreadsheetApp.openById(latestState.spreadsheetId);
        ensureInternalSheet_(ss);
        const commentsSheet = getOutputSheetForState_(ss, latestState);
        finalizeCancellation_(ss, commentsSheet, latestState);
      }
    } finally {
      lock.releaseLock();
    }
  }

  return getSidebarState();
}


/**
 * 최상위 댓글 스레드 한 페이지를 처리합니다.
 */
function processThreadPage_(state, commentsSheet, internalSheet, existingIds) {
  const remaining = state.targetTopLevelCount - state.topCount;

  if (remaining <= 0) {
    state.threadDone = true;
    state.nextThreadPageToken = '';
    return;
  }

  const params = {
    part: state.includeReplies ? 'snippet,replies' : 'snippet',
    videoId: state.videoId,
    maxResults: Math.min(100, remaining),
    textFormat: 'plainText'
  };

  if (state.nextThreadPageToken) {
    params.pageToken = state.nextThreadPageToken;
  }

  const data = youtubeGet_('commentThreads', params);

  state.apiCalls += 1;
  state.threadPages += 1;

  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();
  const items = Array.isArray(data.items) ? data.items : [];

  let topAdded = 0;
  let replyAdded = 0;
  let nextTopNumber = state.topCount + 1;

  items.forEach(function(thread) {
    if (state.topCount + topAdded >= state.targetTopLevelCount) {
      return;
    }

    const threadSnippet = thread.snippet || {};
    const topComment = threadSnippet.topLevelComment;

    if (!topComment || !topComment.id) {
      return;
    }

    const topCommentId = String(topComment.id);

    if (existingIds.has(topCommentId) || batchIds.has(topCommentId)) {
      return;
    }

    const topNumber = String(nextTopNumber);
    nextTopNumber += 1;

    const totalReplyCount = Number(threadSnippet.totalReplyCount || 0);
    let replyStatus = 'DONE';
    let nextReplyIndex = 1;

    commentRows.push(
      commentToOutputRow_(state, topComment, topNumber)
    );

    batchIds.add(topCommentId);
    topAdded += 1;

    const inlineReplies =
      thread.replies && Array.isArray(thread.replies.comments)
        ? thread.replies.comments
        : [];

    if (state.includeReplies && totalReplyCount > 0) {
      if (inlineReplies.length === totalReplyCount) {
        inlineReplies.forEach(function(reply) {
          if (!reply || !reply.id) {
            return;
          }

          const replyId = String(reply.id);

          if (existingIds.has(replyId) || batchIds.has(replyId)) {
            return;
          }

          const displayNumber = topNumber + '_' + nextReplyIndex;
          nextReplyIndex += 1;

          commentRows.push(
            commentToOutputRow_(state, reply, displayNumber)
          );

          internalRows.push(
            buildInternalRow_(
              replyId,
              topCommentId,
              displayNumber,
              'reply',
              '',
              '',
              '',
              ''
            )
          );

          batchIds.add(replyId);
          replyAdded += 1;
        });
      } else {
        // commentThreads.list의 replies에는 전체 답글이 보장되지 않으므로
        // comments.list로 전체 답글을 다시 가져옵니다.
        replyStatus = 'PENDING';
        nextReplyIndex = 1;
      }
    }

    internalRows.push(
      buildInternalRow_(
        topCommentId,
        '',
        topNumber,
        'topLevel',
        replyStatus,
        nextReplyIndex,
        totalReplyCount,
        ''
      )
    );
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.topCount += topAdded;
  state.replyCount += replyAdded;

  const reachedTarget = state.topCount >= state.targetTopLevelCount;
  const hasNextPage = Boolean(data.nextPageToken);

  state.nextThreadPageToken =
    !reachedTarget && hasNextPage
      ? data.nextPageToken
      : '';

  state.threadDone = reachedTarget || !hasNextPage;
  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 특정 최상위 댓글의 답글 한 페이지를 처리합니다.
 */
function processReplyPage_(state, commentsSheet, internalSheet, existingIds) {
  const topRecord = findInternalRecordByCommentId_(
    internalSheet,
    state.currentReplyParentId
  );

  if (!topRecord) {
    // 내부 상태가 사라진 경우 현재 항목을 건너뛰고 다음 대기 항목을 찾습니다.
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
    return;
  }

  const params = {
    part: 'snippet',
    parentId: state.currentReplyParentId,
    maxResults: 100,
    textFormat: 'plainText'
  };

  const pageToken =
    state.nextReplyPageToken || topRecord.replyPageToken || '';

  if (pageToken) {
    params.pageToken = pageToken;
  }

  const data = youtubeGet_('comments', params);

  state.apiCalls += 1;
  state.replyPages += 1;

  const items = Array.isArray(data.items) ? data.items : [];
  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();

  let nextReplyIndex = Number(topRecord.nextReplyIndex || 1);
  let replyAdded = 0;

  items.forEach(function(reply) {
    if (!reply || !reply.id) {
      return;
    }

    const replyId = String(reply.id);

    if (existingIds.has(replyId) || batchIds.has(replyId)) {
      return;
    }

    const displayNumber =
      String(topRecord.displayNumber) + '_' + nextReplyIndex;

    nextReplyIndex += 1;

    commentRows.push(
      commentToOutputRow_(state, reply, displayNumber)
    );

    internalRows.push(
      buildInternalRow_(
        replyId,
        state.currentReplyParentId,
        displayNumber,
        'reply',
        '',
        '',
        '',
        ''
      )
    );

    batchIds.add(replyId);
    replyAdded += 1;
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.replyCount += replyAdded;

  const nextPageToken = data.nextPageToken || '';
  const nextStatus = nextPageToken ? 'IN_PROGRESS' : 'DONE';

  updateTopReplyProgress_(
    internalSheet,
    topRecord.rowNumber,
    nextStatus,
    nextReplyIndex,
    nextPageToken
  );

  if (nextPageToken) {
    state.nextReplyPageToken = nextPageToken;
  } else {
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
  }

  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 내부 시트에서 답글 수집 대기 중인 최상위 댓글 하나를 선택합니다.
 */
function claimNextPendingReply_(internalSheet) {
  const statusRange = internalSheet.getRange(
    2,
    YT_CFG.INTERNAL_COL.REPLY_STATUS,
    Math.max(internalSheet.getLastRow() - 1, 1),
    1
  );

  let found = statusRange
    .createTextFinder('IN_PROGRESS')
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    found = statusRange
      .createTextFinder('PENDING')
      .matchEntireCell(true)
      .useRegularExpression(false)
      .findNext();
  }

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  if (values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] === 'PENDING') {
    internalSheet
      .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS)
      .setValue('IN_PROGRESS');
  }

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    pageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 댓글 1건을 사용자가 보는 8열 행으로 변환합니다.
 */
function commentToOutputRow_(state, comment, displayNumber) {
  const snippet = (comment && comment.snippet) || {};
  const text = String(snippet.textDisplay || '');

  return [
    String(displayNumber),
    safeCellText_(state.videoChannelTitle || ''),
    safeCellText_(state.videoTitle || ''),
    safeCellText_(snippet.authorDisplayName || ''),
    safeCellText_(text),
    Number(snippet.likeCount || 0),
    apiDateToSheetValue_(snippet.publishedAt),
    calculateCommentBytes_(text)
  ];
}


/**
 * 숨김 내부 시트의 행을 만듭니다.
 */
function buildInternalRow_(
  commentId,
  parentCommentId,
  displayNumber,
  commentType,
  replyStatus,
  nextReplyIndex,
  totalReplyCount,
  replyPageToken
) {
  return [
    safeCellText_(commentId || ''),
    safeCellText_(parentCommentId || ''),
    String(displayNumber || ''),
    String(commentType || ''),
    String(replyStatus || ''),
    nextReplyIndex === '' ? '' : Number(nextReplyIndex || 1),
    totalReplyCount === '' ? '' : Number(totalReplyCount || 0),
    safeCellText_(replyPageToken || '')
  ];
}


/**
 * 댓글 행과 내부 관리 행을 각각 일괄 기록합니다.
 */
function appendCollectedRecords_(
  commentsSheet,
  internalSheet,
  commentRows,
  internalRows
) {
  if (commentRows.length !== internalRows.length) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_ROW_MISMATCH',
      '댓글 저장 구조를 확인해야 합니다.',
      '댓글 행과 내부 관리 행의 개수가 일치하지 않습니다.',
      ['수집 상태를 기록하는 내부 데이터가 일시적으로 어긋났습니다.'],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  if (commentRows.length === 0) {
    return;
  }

  commentsSheet
    .getRange(
      commentsSheet.getLastRow() + 1,
      1,
      commentRows.length,
      YT_CFG.HEADERS.length
    )
    .setValues(commentRows);

  internalSheet
    .getRange(
      internalSheet.getLastRow() + 1,
      1,
      internalRows.length,
      YT_CFG.INTERNAL_HEADERS.length
    )
    .setValues(internalRows);
}


/**
 * 내부 시트에서 특정 댓글 ID의 관리 행을 찾습니다.
 */
function findInternalRecordByCommentId_(internalSheet, commentId) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return null;
  }

  const found = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .createTextFinder(String(commentId || ''))
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    replyStatus: String(
      values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    replyPageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 최상위 댓글의 답글 수집 진행 정보를 갱신합니다.
 */
function updateTopReplyProgress_(
  internalSheet,
  rowNumber,
  status,
  nextReplyIndex,
  pageToken
) {
  internalSheet
    .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS, 1, 4)
    .setValues([[
      status,
      Number(nextReplyIndex || 1),
      internalSheet
        .getRange(rowNumber, YT_CFG.INTERNAL_COL.TOTAL_REPLY_COUNT)
        .getValue(),
      pageToken || ''
    ]]);
}


/**
 * 완료 처리
 */
function finishCollection_(ss, commentsSheet, state) {
  state.status = 'COMPLETED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = state.topCount < state.targetTopLevelCount
    ? '댓글 ' +
      state.topCount +
      '개와 대댓글 ' +
      state.replyCount +
      '개를 수집했습니다.'
    : '댓글 수집을 완료했습니다.';
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'COMPLETED', state.message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


function isCancelRequested_() {
  return getUserProperties_().getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';
}


/**
 * 취소 처리
 */
function finalizeCancellation_(ss, commentsSheet, state) {
  const message = '사용자가 수집을 취소했습니다. 이미 저장된 댓글은 유지됩니다.';

  state.status = 'CANCELLED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = message;
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'CANCELLED', message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


/**
 * API 키가 YouTube Data API 요청에 사용 가능한지 확인합니다.
 */
function validateApiKey_(apiKey) {
  youtubeGetWithKey_(
    'videos',
    {
      part: 'id',
      id: 'jNQXAC9IVRw'
    },
    apiKey
  );
}


/**
 * 영상 메타데이터를 조회합니다.
 */
function getVideoMetadataWithKey_(videoId, apiKey) {
  const data = youtubeGetWithKey_(
    'videos',
    {
      part: 'snippet,statistics',
      id: videoId
    },
    apiKey
  );

  if (!Array.isArray(data.items) || data.items.length === 0) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '입력한 영상 주소에 해당하는 공개 영상을 YouTube Data API에서 조회하지 못했습니다.',
      [
        '영상 주소나 11자리 영상 ID가 정확하지 않을 수 있습니다.',
        '영상이 삭제되었거나 비공개 상태일 수 있습니다.',
        '연령·지역·계정 권한에 따라 접근이 제한된 영상일 수 있습니다.'
      ],
      [
        '브라우저에서 해당 영상 주소가 정상적으로 열리는지 확인합니다.',
        '주소 표시줄의 영상 URL 전체를 다시 복사합니다.',
        '사이드바의 영상 주소를 교체한 뒤 수집을 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: { videoId: videoId }
      }
    ));
  }

  const item = data.items[0];
  const snippet = item.snippet || {};
  const statistics = item.statistics || {};

  return {
    title: snippet.title || '',
    channelId: snippet.channelId || '',
    channelTitle: snippet.channelTitle || '',
    commentCount: statistics.commentCount || ''
  };
}


/**
 * 저장된 API 키로 YouTube Data API를 호출합니다.
 */
function youtubeGet_(resource, params) {
  return youtubeGetWithKey_(resource, params, getApiKey_());
}


/**
 * YouTube Data API GET 요청을 수행합니다.
 */
function youtubeGetWithKey_(resource, params, apiKey) {
  const queryParams = Object.assign({}, params, { key: apiKey });

  const query = Object.keys(queryParams)
    .filter(function(key) {
      const value = queryParams[key];
      return value !== undefined && value !== null && value !== '';
    })
    .map(function(key) {
      return encodeURIComponent(key) + '=' + encodeURIComponent(queryParams[key]);
    })
    .join('&');

  const url = YT_CFG.API_BASE + '/' + resource + '?' + query;
  const transientCodes = [429, 500, 502, 503, 504];

  for (let attempt = 0; attempt < 3; attempt += 1) {
    let response;

    try {
      response = UrlFetchApp.fetch(url, {
        method: 'get',
        muteHttpExceptions: true,
        headers: { Accept: 'application/json' }
      });
    } catch (networkError) {
      if (attempt < 2) {
        Utilities.sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      throwStructuredError_(buildErrorInfo_(
        'NETWORK_REQUEST_FAILED',
        'YouTube 서버에 연결하지 못했습니다.',
        'Apps Script에서 YouTube Data API로 보내는 외부 요청이 완료되지 않았습니다.',
        [
          'Google 서비스 또는 네트워크에 일시적인 장애가 발생했을 수 있습니다.',
          'Apps Script의 외부 요청 권한이 승인되지 않았을 수 있습니다.'
        ],
        [
          '잠시 뒤 같은 작업을 다시 실행합니다.',
          'Apps Script 권한 승인 화면이 나타나면 요청된 권한을 허용합니다.',
          'Apps Script의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.'
        ],
        {
          actionLabel: '확인',
          technical: {
            resource: resource,
            originalMessage: String(networkError && networkError.message || networkError)
          }
        }
      ));
    }

    const statusCode = response.getResponseCode();
    const responseText = response.getContentText();

    if (statusCode >= 200 && statusCode < 300) {
      return responseText ? JSON.parse(responseText) : {};
    }

    if (transientCodes.indexOf(statusCode) >= 0 && attempt < 2) {
      Utilities.sleep(Math.pow(2, attempt) * 1000);
      continue;
    }

    const parsedError = parseYouTubeErrorResponse_(responseText);

    throwStructuredError_(classifyYouTubeApiError_(
      statusCode,
      parsedError.reason,
      parsedError.message,
      resource
    ));
  }

  throwStructuredError_(buildErrorInfo_(
    'YOUTUBE_REQUEST_REPEATED_FAILURE',
    'YouTube API 요청이 반복적으로 실패했습니다.',
    '일시적인 서버 장애가 재시도 후에도 계속되었습니다.',
    ['YouTube 또는 Google 네트워크 서비스가 불안정할 수 있습니다.'],
    [
      '잠시 뒤 같은 작업을 다시 실행합니다.',
      '반복되면 Apps Script의 ‘실행’ 기록을 확인합니다.'
    ],
    { actionLabel: '확인', technical: { resource: resource } }
  ));
}


function parseYouTubeErrorResponse_(responseText) {
  let reason = '';
  let message = String(responseText || '');

  try {
    const parsed = JSON.parse(responseText);

    if (parsed.error) {
      message = parsed.error.message || message;

      if (Array.isArray(parsed.error.errors) && parsed.error.errors[0]) {
        reason = parsed.error.errors[0].reason || '';
      }

      if (!reason && parsed.error.status) {
        reason = parsed.error.status;
      }
    }
  } catch (parseError) {
    // JSON이 아닌 오류 본문은 문자열 그대로 분류합니다.
  }

  return {
    reason: String(reason || ''),
    message: String(message || '')
  };
}


/**
 * YouTube API 오류를 한국어 모달용 정보로 분류합니다.
 */
function classifyYouTubeApiError_(statusCode, reason, message, resource) {
  const reasonText = String(reason || '');
  const messageText = String(message || '');
  const combined = (reasonText + ' ' + messageText).toLowerCase();
  const technical = {
    httpStatus: statusCode,
    apiReason: reasonText,
    resource: resource,
    originalMessage: messageText
  };

  if (
    combined.indexOf('keyinvalid') >= 0 ||
    combined.indexOf('api key not valid') >= 0 ||
    combined.indexOf('api_key_invalid') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_INVALID',
      'API 키를 사용할 수 없습니다.',
      '입력한 API 키가 정확하지 않거나 삭제·재발급되어 현재 요청에 사용할 수 없습니다.',
      [
        'API 키 일부가 누락되었을 수 있습니다.',
        'Google Cloud에서 기존 키가 삭제되거나 재발급되었을 수 있습니다.',
        'API 키가 아닌 다른 프로젝트 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 전체를 다시 복사합니다.',
        '사이드바에서 API 키를 다시 입력하고 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') >= 0 ||
    combined.indexOf('access not configured') >= 0 ||
    combined.indexOf('service_disabled') >= 0 ||
    combined.indexOf('api_disabled') >= 0 ||
    combined.indexOf('has not been used in project') >= 0 ||
    combined.indexOf('it is disabled') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_API_NOT_ENABLED',
      'YouTube Data API v3가 활성화되어 있지 않습니다.',
      'API 키가 속한 Google Cloud 프로젝트에서 YouTube Data API v3 사용 설정을 켜야 합니다.',
      [
        'API 키를 만든 프로젝트에서 YouTube Data API v3를 아직 활성화하지 않았습니다.',
        'API를 활성화한 프로젝트와 API 키를 발급한 프로젝트가 다를 수 있습니다.'
      ],
      [
        'Google Cloud Console에서 API 키를 만든 프로젝트를 선택합니다.',
        '‘API 및 서비스 → 라이브러리’로 이동합니다.',
        '‘YouTube Data API v3’를 검색하고 ‘사용’을 누릅니다.',
        '설정 반영을 위해 1~5분 기다린 뒤 API 키를 다시 저장합니다.'
      ],
      {
        helpLabel: 'YouTube Data API 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/library/youtube.googleapis.com',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('iprefererblocked') >= 0 ||
    combined.indexOf('referer') >= 0 && combined.indexOf('blocked') >= 0 ||
    combined.indexOf('api key restrictions') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_APPLICATION_RESTRICTION',
      'API 키의 애플리케이션 제한이 Apps Script 요청을 차단했습니다.',
      '현재 키에 설정된 웹사이트·IP 제한이 Apps Script의 UrlFetch 요청 방식과 맞지 않습니다.',
      [
        'HTTP 리퍼러 제한 또는 특정 IP 주소 제한이 적용되어 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키의 애플리케이션 제한을 확인합니다.',
        'Apps Script에서 사용할 수 있는 제한 방식으로 조정합니다.',
        'API 제한은 ‘YouTube Data API v3’로 유지합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') < 0 &&
    (
      combined.indexOf('forbidden') >= 0 &&
      combined.indexOf('api') >= 0 &&
      combined.indexOf('key') >= 0
    )
  ) {
    return buildErrorInfo_(
      'API_KEY_API_RESTRICTION',
      'API 키의 API 제한 설정을 확인해야 합니다.',
      '현재 API 키가 YouTube Data API v3 호출을 허용하지 않을 수 있습니다.',
      [
        'API 키의 ‘API 제한’ 목록에서 YouTube Data API v3가 빠져 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키를 선택합니다.',
        '‘API 제한’에서 YouTube Data API v3를 허용합니다.',
        '저장 후 1~5분 뒤 다시 실행합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('quotaexceeded') >= 0 ||
    combined.indexOf('dailylimitexceeded') >= 0 ||
    combined.indexOf('daily limit') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_QUOTA_EXCEEDED',
      'YouTube API의 오늘 할당량을 모두 사용했습니다.',
      '현재 Google Cloud 프로젝트에서 오늘 사용할 수 있는 YouTube Data API 할당량이 남아 있지 않습니다.',
      ['같은 프로젝트의 다른 프로그램에서도 YouTube API 할당량을 사용했을 수 있습니다.'],
      [
        'Google Cloud Console에서 YouTube Data API 사용량을 확인합니다.',
        '일일 할당량이 갱신된 뒤 다시 실행합니다.',
        '필요하면 다음 수집의 댓글 개수를 줄입니다.'
      ],
      {
        helpLabel: 'YouTube API 할당량 열기',
        helpUrl: 'https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas',
        actionLabel: '확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('ratelimitexceeded') >= 0 ||
    combined.indexOf('userratelimitexceeded') >= 0 ||
    statusCode === 429
  ) {
    return buildErrorInfo_(
      'YOUTUBE_RATE_LIMIT',
      '짧은 시간에 API 요청이 많이 발생했습니다.',
      'YouTube Data API가 일시적으로 요청 속도를 제한했습니다.',
      ['여러 수집 작업을 연속으로 실행했을 수 있습니다.'],
      [
        '현재 작업이 자동 재개되는지 확인합니다.',
        '몇 분 뒤 다시 실행합니다.',
        '동시에 여러 스프레드시트에서 같은 API 키를 사용하고 있다면 실행 횟수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (combined.indexOf('commentsdisabled') >= 0) {
    return buildErrorInfo_(
      'COMMENTS_DISABLED',
      '이 영상에서는 댓글을 수집할 수 없습니다.',
      '영상 게시자가 댓글 기능을 사용하지 않도록 설정했습니다.',
      ['영상의 댓글 기능이 꺼져 있거나 YouTube 정책에 따라 제한되었습니다.'],
      [
        '영상 페이지에서 댓글 영역이 표시되는지 확인합니다.',
        '댓글이 허용된 다른 영상 주소를 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('videonotfound') >= 0 ||
    combined.indexOf('video not found') >= 0
  ) {
    return buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '영상 주소가 잘못되었거나 영상이 삭제·비공개 상태일 수 있습니다.',
      [
        '영상 ID가 정확하지 않을 수 있습니다.',
        '영상 공개 상태가 변경되었을 수 있습니다.'
      ],
      [
        '브라우저에서 영상 주소가 정상적으로 열리는지 확인합니다.',
        '영상 URL 전체를 다시 복사해 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (statusCode >= 500) {
    return buildErrorInfo_(
      'YOUTUBE_SERVER_ERROR',
      'YouTube 서버에서 일시적인 오류가 발생했습니다.',
      'YouTube Data API 서버가 현재 요청을 정상적으로 처리하지 못했습니다.',
      ['YouTube 측의 일시적인 서비스 장애일 수 있습니다.'],
      [
        '잠시 뒤 같은 작업을 다시 실행합니다.',
        '진행 중인 수집이라면 자동 재개 여부를 확인합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (statusCode === 403) {
    return buildErrorInfo_(
      'YOUTUBE_ACCESS_FORBIDDEN',
      'YouTube 데이터에 접근할 수 없습니다.',
      'API 키 설정, 영상 공개 상태 또는 Google Cloud 프로젝트 권한을 확인해야 합니다.',
      [
        'API 키 제한 설정이 요청을 차단했을 수 있습니다.',
        '영상이 공개 API에서 접근할 수 없는 상태일 수 있습니다.'
      ],
      [
        'API 키의 API 제한과 애플리케이션 제한을 확인합니다.',
        '영상이 공개 상태인지 확인합니다.',
        'Google Cloud에서 YouTube Data API v3가 활성화되어 있는지 확인합니다.'
      ],
      {
        helpLabel: 'API 키 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (statusCode === 400) {
    return buildErrorInfo_(
      'YOUTUBE_BAD_REQUEST',
      'YouTube API 요청 형식을 확인해야 합니다.',
      '영상 주소 또는 요청 매개변수 중 하나를 YouTube API가 처리하지 못했습니다.',
      ['영상 주소가 올바르지 않거나 API 요청 값이 허용 범위를 벗어났을 수 있습니다.'],
      [
        '영상 주소를 다시 확인합니다.',
        '수집 개수와 정렬 기준을 확인합니다.',
        '같은 문제가 계속되면 새 수집으로 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '입력값 확인',
        technical: technical
      }
    );
  }

  return buildErrorInfo_(
    'YOUTUBE_API_ERROR',
    'YouTube API 요청을 완료하지 못했습니다.',
    'YouTube Data API가 요청을 거부하거나 처리하지 못했습니다.',
    ['API 키, 영상 공개 상태, 할당량 또는 네트워크 상태를 확인해야 합니다.'],
    [
      'API 키 설정과 YouTube Data API 활성화 여부를 확인합니다.',
      '영상 주소가 공개 영상인지 확인합니다.',
      '잠시 뒤 다시 실행합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}


/**
 * 영상 URL 또는 11자리 영상 ID에서 videoId를 추출합니다.
 */
function extractVideoId_(input) {
  const text = String(input || '').trim();

  if (/^[A-Za-z0-9_-]{11}$/.test(text)) {
    return text;
  }

  const patterns = [
    /[?&]v=([A-Za-z0-9_-]{11})/,
    /youtu\.be\/([A-Za-z0-9_-]{11})/,
    /youtube(?:-nocookie)?\.com\/(?:embed|shorts|live)\/([A-Za-z0-9_-]{11})/
  ];

  for (let i = 0; i < patterns.length; i += 1) {
    const match = text.match(patterns[i]);

    if (match) {
      return match[1];
    }
  }

  throwStructuredError_(buildErrorInfo_(
    'INVALID_VIDEO_URL',
    'YouTube 영상 주소를 확인해야 합니다.',
    '입력한 값에서 11자리 YouTube 영상 ID를 찾지 못했습니다.',
    [
      '영상 주소 일부가 빠졌을 수 있습니다.',
      '채널·재생목록 주소를 입력했을 수 있습니다.'
    ],
    [
      'YouTube에서 수집할 영상을 엽니다.',
      '브라우저 주소 표시줄의 영상 URL 전체를 복사합니다.',
      '사이드바의 영상 주소 입력란에 붙여 넣습니다.'
    ],
    {
      focusTarget: 'videoUrl',
      actionLabel: '영상 주소 다시 입력'
    }
  ));
}


/**
 * 사이드바 입력값을 검증합니다.
 */
function normalizeSidebarInput_(formData) {
  const form = formData || {};
  const videoUrl = String(form.videoUrl || '').trim();
  const limit = parseInt(form.limit, 10);

  if (!videoUrl) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_URL_REQUIRED',
      'YouTube 영상 주소를 입력해야 합니다.',
      '수집 대상 영상 주소가 비어 있습니다.',
      ['영상 주소 입력란에 값이 없습니다.'],
      ['수집할 YouTube 영상의 URL을 입력합니다.'],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 입력'
      }
    ));
  }

  if (!Number.isInteger(limit)) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_INVALID',
      '수집 개수를 정수로 입력해야 합니다.',
      '수집할 최상위 댓글 개수가 올바른 정수 형식이 아닙니다.',
      ['빈 값, 소수 또는 문자가 입력되었을 수 있습니다.'],
      ['1 이상의 정수를 입력합니다.'],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 입력'
      }
    ));
  }

  if (limit < YT_CFG.MIN_LIMIT || limit > YT_CFG.MAX_LIMIT) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_OUT_OF_RANGE',
      '수집 개수가 허용 범위를 벗어났습니다.',
      '수집 개수는 ' + YT_CFG.MIN_LIMIT + '개 이상 ' +
        YT_CFG.MAX_LIMIT + '개 이하로 입력해야 합니다.',
      ['입력한 개수가 코드에 설정된 운영 범위를 벗어났습니다.'],
      [
        YT_CFG.MIN_LIMIT + '~' + YT_CFG.MAX_LIMIT +
          ' 사이의 정수를 입력합니다.'
      ],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 수정'
      }
    ));
  }

  return {
    videoUrl: videoUrl,
    limit: limit,
    includeReplies: form.includeReplies === true
  };
}


/**
 * 결과 시트와 숨김 내부 시트를 준비합니다.
 */
function ensureInternalSheet_(ss) {
  let internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    internal = ss.insertSheet(YT_CFG.INTERNAL_SHEET);
  }

  ensureColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);

  if (internal.getLastRow() === 0) {
    internal
      .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
      .setValues([YT_CFG.INTERNAL_HEADERS]);
  }

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 새 수집에 사용할 결과 시트를 시트1, 시트2, 시트3 ... 순서로 만듭니다.
 *
 * 새 스프레드시트에 기본 빈 '시트1' 하나만 존재하는 경우에는 그 시트를
 * 첫 결과 시트로 사용합니다. 그 이후 수집부터는 항상 새 시트를 추가합니다.
 */
function createNextOutputSheet_(ss) {
  const sheets = ss.getSheets();

  if (
    sheets.length === 1 &&
    sheets[0].getName() === YT_CFG.OUTPUT_SHEET_PREFIX + '1' &&
    isSheetCompletelyBlank_(sheets[0])
  ) {
    prepareOutputSheet_(sheets[0]);
    return sheets[0];
  }

  let maxNumber = 0;
  const namePattern = new RegExp(
    '^' + escapeRegExp_(YT_CFG.OUTPUT_SHEET_PREFIX) + '(\\d+)$'
  );

  sheets.forEach(function(sheet) {
    const match = sheet.getName().match(namePattern);

    if (match) {
      maxNumber = Math.max(maxNumber, Number(match[1] || 0));
    }
  });

  let nextNumber = maxNumber + 1;
  let nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;

  while (ss.getSheetByName(nextName)) {
    nextNumber += 1;
    nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;
  }

  const sheet = ss.insertSheet(nextName);
  prepareOutputSheet_(sheet);
  return sheet;
}


function isSheetCompletelyBlank_(sheet) {
  return sheet.getLastRow() === 0 && sheet.getLastColumn() === 0;
}


function prepareOutputSheet_(sheet) {
  if (sheet.getFilter()) {
    sheet.getFilter().remove();
  }

  sheet.clear();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setValues([YT_CFG.HEADERS]);

  sheet.setFrozenRows(1);
  sheet.getRange('A:A').setNumberFormat('@');
  formatCommentsSheet_(sheet);
}


/**
 * 새 수집을 위해 숨김 내부 시트만 초기화합니다.
 * 이전 결과 시트의 내용은 변경하지 않습니다.
 */
function resetInternalData_(ss) {
  const internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_SHEET_NOT_FOUND',
      '내부 관리 시트를 준비하지 못했습니다.',
      '댓글 수집 상태를 저장하는 숨김 시트가 존재하지 않습니다.',
      ['내부 시트 생성 과정이 완료되지 않았습니다.'],
      ['사이드바를 닫았다가 다시 열고 새 수집을 시작합니다.'],
      { actionLabel: '확인' }
    ));
  }

  internal.clear();
  ensureExactColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);
  internal
    .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .setValues([YT_CFG.INTERNAL_HEADERS]);

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 현재 수집 상태에 연결된 결과 시트를 찾습니다.
 */
function getOutputSheetForState_(ss, state) {
  const expectedId = Number(state.outputSheetId || 0);
  let outputSheet = null;

  if (expectedId > 0) {
    outputSheet = ss.getSheets().find(function(sheet) {
      return sheet.getSheetId() === expectedId;
    }) || null;
  }

  if (!outputSheet && state.outputSheetName) {
    outputSheet = ss.getSheetByName(String(state.outputSheetName));
  }

  if (!outputSheet) {
    throwStructuredError_(buildErrorInfo_(
      'OUTPUT_SHEET_NOT_FOUND',
      '수집 결과 시트를 찾을 수 없습니다.',
      '현재 수집 작업과 연결된 결과 시트가 삭제되었거나 이름과 식별 정보가 변경되었습니다.',
      [
        '수집 중 결과 시트를 삭제했을 수 있습니다.',
        '스프레드시트 구조가 외부 작업으로 변경되었을 수 있습니다.'
      ],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }

  return outputSheet;
}


function escapeRegExp_(text) {
  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}


/**
 * 이전 버전이 만든 수집로그 시트를 제거합니다.
 */
function deleteLegacyLogSheet_(ss) {
  const logSheet = ss.getSheetByName(YT_CFG.LEGACY_LOG_SHEET);

  if (logSheet && ss.getSheets().length > 1) {
    ss.deleteSheet(logSheet);
  }
}


/**
 * 댓글 시트를 번호 순으로 정렬하고 최종 서식을 적용합니다.
 */
function finalizeCommentsSheet_(sheet) {
  sortCommentsByDisplayNumber_(sheet);
  formatCommentsSheet_(sheet);
}


function sortCommentsByDisplayNumber_(sheet) {
  const lastRow = sheet.getLastRow();

  if (lastRow <= 2) {
    return;
  }

  // 정렬용 임시 열 I, J를 만든 뒤 최상위 번호와 답글 번호로 정렬합니다.
  ensureColumnCount_(sheet, 10);

  const numberValues = sheet
    .getRange(2, 1, lastRow - 1, 1)
    .getDisplayValues();

  const sortKeys = numberValues.map(function(row) {
    const parts = String(row[0] || '').split('_');
    return [
      Number(parts[0] || 0),
      parts.length > 1 ? Number(parts[1] || 0) : 0
    ];
  });

  sheet
    .getRange(2, 9, sortKeys.length, 2)
    .setValues(sortKeys);

  sheet
    .getRange(2, 1, lastRow - 1, 10)
    .sort([
      { column: 9, ascending: true },
      { column: 10, ascending: true }
    ]);

  sheet.getRange(2, 9, lastRow - 1, 2).clearContent();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
}


function formatCommentsSheet_(sheet) {
  const lastRow = sheet.getLastRow();

  sheet.setFrozenRows(1);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setFontWeight('bold')
    .setWrap(true)
    .setVerticalAlignment('middle');

  sheet.getRange('A:A').setNumberFormat('@');

  if (lastRow > 1) {
    sheet
      .getRange(2, 7, lastRow - 1, 1)
      .setNumberFormat('yyyy-mm-dd hh:mm:ss');

    sheet
      .getRange(2, 5, lastRow - 1, 1)
      .setWrap(true)
      .setVerticalAlignment('top');

    sheet
      .getRange(2, 1, lastRow - 1, YT_CFG.HEADERS.length)
      .setVerticalAlignment('top');

    if (sheet.getFilter()) {
      sheet.getFilter().remove();
    }

    sheet
      .getRange(1, 1, lastRow, YT_CFG.HEADERS.length)
      .createFilter();
  }

  sheet.setColumnWidth(1, 90);
  sheet.setColumnWidth(2, 180);
  sheet.setColumnWidth(3, 260);
  sheet.setColumnWidth(4, 170);
  sheet.setColumnWidth(5, 520);
  sheet.setColumnWidth(6, 95);
  sheet.setColumnWidth(7, 155);
  sheet.setColumnWidth(8, 95);
}


/**
 * 숨김 내부 시트에 저장된 댓글 ID 집합을 만듭니다.
 */
function getExistingCommentIds_(internalSheet) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return new Set();
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .getDisplayValues();

  return new Set(
    values
      .map(function(row) {
        return row[0];
      })
      .filter(function(value) {
        return Boolean(value);
      })
  );
}


/**
 * 숨김 내부 시트 기준으로 실제 최상위 댓글·답글 수를 계산합니다.
 */
function getExistingCounts_(internalSheet) {
  const lastRow = internalSheet.getLastRow();
  const counts = { top: 0, reply: 0 };

  if (lastRow <= 1) {
    return counts;
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_TYPE, lastRow - 1, 1)
    .getDisplayValues();

  values.forEach(function(row) {
    if (row[0] === 'topLevel') {
      counts.top += 1;
    } else if (row[0] === 'reply') {
      counts.reply += 1;
    }
  });

  return counts;
}


/**
 * 댓글 글자수를 지정된 바이트 규칙으로 계산합니다.
 * - ASCII 영역(영문, 숫자, 공백, 일반 문장부호): 1바이트
 * - 한글을 포함한 비ASCII 유니코드 문자: 코드 포인트당 2바이트
 */
function calculateCommentBytes_(value) {
  const text = String(value || '');
  let bytes = 0;

  Array.from(text).forEach(function(character) {
    const codePoint = character.codePointAt(0);
    bytes += codePoint <= 0x7F ? 1 : 2;
  });

  return bytes;
}


/**
 * 외부 문자열이 시트 수식으로 실행되는 것을 방지합니다.
 */
function safeCellText_(value) {
  const text = value === undefined || value === null ? '' : String(value);
  return /^[=+\-@]/.test(text) ? "'" + text : text;
}


function apiDateToSheetValue_(value) {
  return value ? new Date(value) : '';
}


function ensureColumnCount_(sheet, requiredColumns) {
  const current = sheet.getMaxColumns();

  if (current < requiredColumns) {
    sheet.insertColumnsAfter(current, requiredColumns - current);
  }
}


function ensureExactColumnCount_(sheet, requiredColumns) {
  ensureColumnCount_(sheet, requiredColumns);

  const current = sheet.getMaxColumns();

  if (current > requiredColumns) {
    sheet.deleteColumns(requiredColumns + 1, current - requiredColumns);
  }
}


function getUserProperties_() {
  return PropertiesService.getUserProperties();
}


function getApiKey_() {
  const apiKey = getUserProperties_().getProperty(YT_CFG.API_KEY_PROP);

  if (!apiKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키 설정이 필요합니다.',
      '댓글 수집을 시작하기 전에 YouTube Data API 키를 저장해야 합니다.',
      ['현재 사용자 계정에 저장된 API 키가 없습니다.'],
      [
        '사이드바 상단의 API 키 입력란에 키를 입력합니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  return apiKey.trim();
}


function loadState_() {
  const text = getUserProperties_().getProperty(YT_CFG.STATE_PROP);
  return text ? JSON.parse(text) : null;
}


function saveState_(state) {
  state.updatedAt = new Date().toISOString();
  const text = JSON.stringify(state);
  const byteLength = Utilities.newBlob(text).getBytes().length;

  if (byteLength > 8500) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_STORAGE_LIMIT',
      '수집 진행 상태를 저장할 수 없습니다.',
      'Apps Script 사용자 속성의 안전 저장 크기를 초과했습니다.',
      ['진행 상태 데이터가 예상보다 커졌습니다.'],
      [
        '현재 수집을 취소합니다.',
        '댓글 수집 개수를 줄여 새로 실행합니다.'
      ],
      { actionLabel: '확인', technical: { byteLength: byteLength } }
    ));
  }

  getUserProperties_().setProperty(YT_CFG.STATE_PROP, text);
}


function loadLastResult_() {
  const text = getUserProperties_().getProperty(YT_CFG.LAST_RESULT_PROP);
  return text ? JSON.parse(text) : null;
}


function saveLastResult_(state, status, message, errorInfo) {
  const result = {
    status: status,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: Number(state.targetTopLevelCount || 0),
    topCount: Number(state.topCount || 0),
    replyCount: Number(state.replyCount || 0),
    apiCalls: Number(state.apiCalls || 0),
    startedAt: state.startedAt || '',
    updatedAt: new Date().toISOString(),
    finishedAt: new Date().toISOString(),
    message: message || '',
    error: errorInfo || null
  };

  getUserProperties_().setProperty(
    YT_CFG.LAST_RESULT_PROP,
    JSON.stringify(result)
  );
}


function validateStateVersion_(state) {
  if (Number(state.version || 0) !== YT_CFG.STATE_VERSION) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_VERSION_MISMATCH',
      '이전 코드에서 시작된 수집 작업을 이어갈 수 없습니다.',
      '현재 Code.gs의 댓글 저장 구조가 이전 실행 상태와 다릅니다.',
      ['고정 결과 시트 또는 정렬 기준을 사용하던 이전 코드의 작업 상태가 남아 있습니다.'],
      [
        '사이드바에서 진행 중인 수집을 취소합니다.',
        '현재 코드로 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }
}


function normalizeState_(state) {
  state.currentReplyParentId = state.currentReplyParentId || '';
  state.nextReplyPageToken = state.nextReplyPageToken || '';
  state.nextThreadPageToken = state.nextThreadPageToken || '';
  state.threadDone = Boolean(state.threadDone);
  state.topCount = Number(state.topCount || 0);
  state.replyCount = Number(state.replyCount || 0);
  state.apiCalls = Number(state.apiCalls || 0);
  state.threadPages = Number(state.threadPages || 0);
  state.replyPages = Number(state.replyPages || 0);
  state.targetTopLevelCount = Number(state.targetTopLevelCount || 0);
  state.outputSheetId = Number(state.outputSheetId || 0);
  state.outputSheetName = String(state.outputSheetName || '');
  state.error = state.error || null;
}


function maskApiKey_(apiKey) {
  const key = String(apiKey || '');
  return '••••••••••••' + key.slice(-4);
}


function buildProgressForClient_(state, status) {
  const target = Number(state.targetTopLevelCount || 0);
  const top = Number(state.topCount || 0);
  const reply = Number(state.replyCount || 0);
  const percent = target > 0
    ? Math.min(100, Math.round((top / target) * 100))
    : 0;

  let stage = '대기 중';

  if (status === 'RUNNING') {
    if (state.currentReplyParentId) {
      stage = '답글 수집 중';
    } else if (!state.threadDone) {
      stage = '최상위 댓글 수집 중';
    } else {
      stage = '마무리 중';
    }
  } else if (status === 'COMPLETED') {
    stage = '완료';
  } else if (status === 'ERROR') {
    stage = '오류';
  } else if (status === 'CANCELLED') {
    stage = '취소됨';
  }

  return {
    status: status,
    stage: stage,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: target,
    topCount: top,
    replyCount: reply,
    totalRows: top + reply,
    apiCalls: Number(state.apiCalls || 0),
    percent: percent,
    startedAt: state.startedAt || '',
    updatedAt: state.updatedAt || '',
    message: state.message || '',
    error: state.error || null
  };
}


function buildServerProgressMessage_(state) {
  return (
    '최상위 댓글 ' +
    state.topCount +
    '/' +
    state.targetTopLevelCount +
    '개, 답글 ' +
    state.replyCount +
    '개를 저장했습니다.'
  );
}


function scheduleContinuation_() {
  deleteContinuationTriggers_();

  ScriptApp
    .newTrigger(YT_CFG.CONTINUE_HANDLER)
    .timeBased()
    .after(YT_CFG.CONTINUE_AFTER_MS)
    .create();
}


function deleteContinuationTriggers_() {
  ScriptApp.getProjectTriggers().forEach(function(trigger) {
    if (trigger.getHandlerFunction() === YT_CFG.CONTINUE_HANDLER) {
      ScriptApp.deleteTrigger(trigger);
    }
  });
}


/**
 * 한국어 모달용 오류 정보를 만듭니다.
 */
function buildErrorInfo_(code, title, summary, causes, steps, options) {
  const opts = options || {};

  return {
    code: String(code || 'UNKNOWN_ERROR'),
    title: String(title || '작업을 완료하지 못했습니다.'),
    summary: String(summary || '처리 중 문제가 발생했습니다.'),
    causes: Array.isArray(causes) ? causes.map(String) : [],
    steps: Array.isArray(steps) ? steps.map(String) : [],
    helpLabel: String(opts.helpLabel || ''),
    helpUrl: String(opts.helpUrl || ''),
    focusTarget: String(opts.focusTarget || ''),
    actionLabel: String(opts.actionLabel || '확인'),
    technical:
      opts.technical && typeof opts.technical === 'object'
        ? opts.technical
        : {}
  };
}


/**
 * 서버 오류를 Sidebar.html이 해석할 수 있는 구조화된 예외로 전달합니다.
 */
function throwStructuredError_(errorInfo) {
  throw new Error(
    YT_CFG.STRUCTURED_ERROR_PREFIX + JSON.stringify(errorInfo)
  );
}


function extractStructuredError_(rawText) {
  const raw = String(rawText || '');
  const markerIndex = raw.indexOf(YT_CFG.STRUCTURED_ERROR_PREFIX);

  if (markerIndex < 0) {
    return null;
  }

  const jsonText = raw.slice(
    markerIndex + YT_CFG.STRUCTURED_ERROR_PREFIX.length
  );

  try {
    return JSON.parse(jsonText);
  } catch (parseError) {
    return null;
  }
}


/**
 * Apps Script 자체 오류도 한국어 모달 정보로 변환합니다.
 */
function normalizeErrorInfo_(error, context) {
  const raw = error && error.message
    ? String(error.message)
    : String(error || '');

  const structured = extractStructuredError_(raw);

  if (structured) {
    return structured;
  }

  const lower = raw.toLowerCase();
  const technical = {
    context: String(context || '작업 실행'),
    originalMessage: raw
  };

  if (
    lower.indexOf('authorization is required') >= 0 ||
    lower.indexOf('you do not have permission') >= 0 ||
    lower.indexOf('permissions') >= 0 && lower.indexOf('required') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_AUTH_REQUIRED',
      'Google 권한 승인이 필요합니다.',
      '현재 계정이 스프레드시트 또는 외부 API 요청 권한을 아직 승인하지 않았습니다.',
      ['Apps Script를 처음 실행했거나 새로운 권한이 추가되었습니다.'],
      [
        '스프레드시트 메뉴에서 사이드바를 다시 엽니다.',
        '권한 검토 화면에서 현재 Google 계정을 선택합니다.',
        '요청되는 권한을 허용한 뒤 다시 실행합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('maximum execution time') >= 0 ||
    lower.indexOf('exceeded maximum execution time') >= 0 ||
    lower.indexOf('timed out') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_EXECUTION_TIMEOUT',
      '한 번의 실행 가능 시간을 초과했습니다.',
      '댓글 또는 답글 처리 시간이 길어 현재 실행 구간이 종료되었습니다.',
      ['대량 댓글 수집으로 한 번의 Apps Script 실행 시간이 길어졌습니다.'],
      [
        '사이드바를 다시 열어 진행 상태를 확인합니다.',
        '멈춘 경우 ‘중단 지점부터 실행’을 한 번 실행합니다.',
        '같은 문제가 반복되면 수집 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('service invoked too many times') >= 0 ||
    lower.indexOf('quota') >= 0 && lower.indexOf('apps script') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_SERVICE_QUOTA',
      'Apps Script 서비스 사용 한도를 초과했습니다.',
      '현재 Google 계정 또는 스크립트의 일일 서비스 사용량이 허용 범위를 넘었습니다.',
      ['짧은 시간에 많은 외부 요청이나 스프레드시트 쓰기 작업이 실행되었습니다.'],
      [
        '잠시 뒤 다시 실행합니다.',
        '같은 날 반복되면 다음 날 다시 실행합니다.',
        '한 번에 수집하는 댓글 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  return buildErrorInfo_(
    'UNEXPECTED_ERROR',
    '예상하지 못한 오류가 발생했습니다.',
    '오류 유형을 자동으로 판별하지 못했습니다.',
    [
      '네트워크, 권한, Google 서비스 상태 또는 실행 환경에서 문제가 발생했을 수 있습니다.'
    ],
    [
      '사이드바를 닫았다가 다시 열고 같은 작업을 한 번 더 실행합니다.',
      'Apps Script 편집기의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.',
      'API 키와 영상 주소를 다시 확인합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}

Sidebar.html

YouTube 댓글 수집기

YouTube Data API v3 → Google Sheets

1. API 키

YouTube Data API 키

최초 1회 저장합니다. 키는 사용자별 Apps Script 속성에 보관됩니다.

2. 수집 설정

API 키를 저장하면 수집 설정이 활성화됩니다.

YouTube 영상 주소

수집할 최상위 댓글 수

1~50,000개. 답글 포함 시 실제 저장 행 수가 이 값보다 많아질 수 있습니다.

대댓글도 모두 수집

새 수집을 시작할 때마다 ‘시트1’, ‘시트2’, ‘시트3’ 형식의 새 시트가 생성됩니다. 기존 수집 결과는 유지됩니다.

Youtube Data API v3 KEY

AIzaSyDETqF5gzbFh3DG4U0N-rjT1yK2asM-1X4

교안 및 학습자료

(4차시) 앱스스크립트

교안 및 학습자료

[강의] 김민기_앱스스크립트.pdf

(5차시) 바른 API로 생기부 검토

Code.gs

// =================================================================
// [0] 초기 설정 및 메뉴
// =================================================================

function onOpen() {
  SpreadsheetApp.getUi().createMenu('민기쌤 생기부 도우미')
      .addItem('🚀 사이드바 열기', 'openSidebar') 
      .addToUi();
}

function renderView_(viewName) {
  var template = HtmlService.createTemplateFromFile('Sidebar');
  template.initialView = viewName || 'sidebar';
  return template.evaluate();
}

function openSidebar() {
  ensureBannedWordSheet_();
  var html = renderView_('sidebar')
      .setTitle('민기쌤 생기부 맞춤법 도우미')
      .setWidth(300); 
  SpreadsheetApp.getUi().showSidebar(html);
}

function openSpellCheckViewer() {
  var html = renderView_('spellcheck')
      .setWidth(1000) 
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '📝 Bareun 맞춤법 검사 및 수정');
}

function openBannedWordViewer() {
  var html = renderView_('banned')
      .setWidth(1000)
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '🚫 기재 금지어 점검');
}

// =================================================================
// [1] Bareun API 키 및 UI 설정
// =================================================================

function getBareunUserProperties_() {
  ensureBannedWordSheet_();
  var props = PropertiesService.getUserProperties();
  var currentPolicy = 'BAREUN_ONLY_KEYS_V3';
  var previousPolicy = props.getProperty('API_KEY_POLICY_VERSION');

  // 정책 변경 시 현재 기능에서 쓰지 않는 예전 사용자 설정을 한 번 정리합니다.
  if (previousPolicy !== currentPolicy) {
    var allowedProperties = {
      UI_STATE: true,
      API_KEY_POLICY_VERSION: true
    };
    // 바로 이전 사용자 입력형 정책에서 저장한 키만 보존합니다.
    if (previousPolicy === 'USER_SUPPLIED_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V2') {
      allowedProperties.USER_BAREUN_KEY = true;
    }
    Object.keys(props.getProperties()).forEach(function(propertyName) {
      if (!allowedProperties[propertyName]) props.deleteProperty(propertyName);
    });

    var previousUiState = {};
    try {
      previousUiState = JSON.parse(props.getProperty('UI_STATE') || '{}');
    } catch (e) {
      previousUiState = {};
    }
    var currentUiState = {};
    ['card-api', 'sub-api-settings', 'card-util'].forEach(function(id) {
      if (previousUiState[id]) currentUiState[id] = true;
    });
    props.setProperty('UI_STATE', JSON.stringify(currentUiState));
    props.setProperty('API_KEY_POLICY_VERSION', currentPolicy);
  }

  return props;
}

function saveUserBareunKey(bareunKey) {
  var props = getBareunUserProperties_();
  var cleanBareunKey = String(bareunKey || '').trim();

  if (!cleanBareunKey) {
    throw new Error('Bareun API 키를 입력해 주세요. 이 도우미는 API 키를 제공하지 않습니다.');
  }

  props.setProperty('USER_BAREUN_KEY', cleanBareunKey);
  return { hasBareun: true };
}

function checkUserBareunStatus() {
  var props = getBareunUserProperties_();
  return { hasBareun: !!props.getProperty('USER_BAREUN_KEY') };
}

function clearUserBareunKey() {
  var props = getBareunUserProperties_();
  props.deleteProperty('USER_BAREUN_KEY');
  return { hasBareun: false };
}

function getBareunKey() {
  var key = getBareunUserProperties_().getProperty('USER_BAREUN_KEY');
  if (!key) throw new Error("Bareun API 키가 없습니다. 사이드바 상단에서 등록해주세요.");
  return key;
}

// =================================================================
// [2] Bareun 맞춤법 검사
// =================================================================

function getSelectedDataForSpellCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");
  var rows = [];
  var startRow = range.getRow();
  var startCol = range.getColumn();
  var values = range.getValues();
  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var text = values[i][j].toString();
      if (text.trim() !== "") {
        rows.push({ sheetName: sheetName, row: startRow + i, col: startCol + j, original: text });
      }
    }
  }
  return rows;
}

function getBareunCorrection(text) {
  var userKey = getBareunKey();
  var result = callBareunApi(text, userKey); 
  return result; 
}

function applySpellCheckResults(updates) {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  updates.forEach(function(item) {
    var sheet = spreadsheet.getSheetByName(item.sheetName);
    if (!sheet) throw new Error('검사한 시트를 찾을 수 없습니다: ' + item.sheetName);
    sheet.getRange(item.row, item.col).setValue(item.text);
  });
  return updates.length;
}

function callBareunApi(text, userKey) {
  var url = "https://api.bareun.ai/bareun.RevisionService/CorrectError";
  var options = {
    "method": "post", "contentType": "application/json", "headers": { "api-key": userKey }, "muteHttpExceptions": true,
    "payload": JSON.stringify({ "document": { "content": text, "language": "ko-KR" }, "encoding_type": "UTF16" })
  };
  var response = UrlFetchApp.fetch(url, options);
  var result = JSON.parse(response.getContentText());
  
  if (response.getResponseCode() !== 200) {
    return { error: "API 오류: " + response.getResponseCode() };
  }
  return { revised: result.revised, helps: result.helps || {}, rawBlocks: result.revisedBlocks || result.revised_blocks || [], error: null };
}

// =================================================================
// [3] 기재 금지어 관리
// =================================================================

var BANNED_WORD_SHEET_NAME_ = '기재금지어관리';
var BANNED_WORD_HEADERS_ = ['번호', '기재 금지어'];
var LEGACY_BANNED_WORD_HEADERS_ = ['유형', '기재 금지어', '대체 표현'];
var ONE_COLUMN_BANNED_WORD_HEADERS_ = ['기재 금지어'];

function getLegacyBannedWordList_() {
  var saved = PropertiesService.getUserProperties().getProperty('BANNED_WORDS_DB');
  if (!saved) return getDefaultBannedList_();

  try {
    var parsed = JSON.parse(saved);
    if (!Array.isArray(parsed)) return getDefaultBannedList_();
    return parsed
      .map(function(item) {
        return String(item && item.k || '').trim();
      })
      .filter(function(keyword) { return keyword !== ''; });
  } catch (e) {
    return getDefaultBannedList_();
  }
}

function initializeBannedWordSheet_(sheet, list) {
  sheet.getRange(1, 1, 1, BANNED_WORD_HEADERS_.length)
    .setValues([BANNED_WORD_HEADERS_])
    .setBackground('#fce8e6')
    .setFontColor('#a50e0e')
    .setFontWeight('bold')
    .setHorizontalAlignment('center');

  var rows = list.map(function(keyword, index) {
    return [index + 1, keyword];
  });
  if (rows.length > 0) sheet.getRange(2, 1, rows.length, 2).setValues(rows);

  sheet.setFrozenRows(1);
  sheet.setColumnWidth(1, 60);
  sheet.setColumnWidth(2, 260);
  sheet.setTabColor('#d93025');
}

function migrateLegacyBannedWordSheet_(sheet) {
  var lastColumn = sheet.getLastColumn();
  var legacyColumn;
  var clearColumns;

  if (lastColumn >= 3 && sheet.getRange(1, 1, 1, 3).getDisplayValues()[0].join('|') === LEGACY_BANNED_WORD_HEADERS_.join('|')) {
    legacyColumn = 2;
    clearColumns = 3;
  } else if (sheet.getRange(1, 1, 1, 1).getDisplayValues()[0][0] === ONE_COLUMN_BANNED_WORD_HEADERS_[0]) {
    legacyColumn = 1;
    clearColumns = 1;
  } else {
    return false;
  }

  var lastRow = sheet.getLastRow();
  var keywords = lastRow < 2 ? [] : sheet.getRange(2, legacyColumn, lastRow - 1, 1)
    .getDisplayValues()
    .map(function(row) { return String(row[0] || '').trim(); })
    .filter(function(keyword) { return keyword !== ''; });

  var clearRows = Math.max(sheet.getLastRow(), 1);
  sheet.getRange(1, 1, clearRows, clearColumns).clearContent();
  initializeBannedWordSheet_(sheet, keywords);
  return true;
}

function ensureBannedWordSheet_() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  if (!spreadsheet) throw new Error('활성 스프레드시트를 찾을 수 없습니다.');

  var originalSheet = spreadsheet.getActiveSheet();
  var originalRange = spreadsheet.getActiveRange();
  var lock = LockService.getDocumentLock() || LockService.getScriptLock();
  lock.waitLock(30000);

  var sheet;
  try {
    sheet = spreadsheet.getSheetByName(BANNED_WORD_SHEET_NAME_);
    if (!sheet) {
      sheet = spreadsheet.insertSheet(BANNED_WORD_SHEET_NAME_);
      initializeBannedWordSheet_(sheet, getLegacyBannedWordList_());
    } else {
      // 이전 형식은 금지어만 보존하여 번호·기재금지어 두 열 목록으로 안전하게 바꿉니다.
      migrateLegacyBannedWordSheet_(sheet);
    }

    // 시트로 옮긴 뒤 예전 사용자별 저장값은 더 이상 별도 원본으로 남기지 않습니다.
    PropertiesService.getUserProperties().deleteProperty('BANNED_WORDS_DB');
    return sheet;
  } finally {
    if (originalSheet && sheet && originalSheet.getSheetId() !== sheet.getSheetId()) {
      spreadsheet.setActiveSheet(originalSheet);
      if (originalRange) spreadsheet.setActiveRange(originalRange);
    }
    lock.releaseLock();
  }
}

function openBannedWordManagementSheet() {
  var sheet = ensureBannedWordSheet_();
  sheet.activate();
  sheet.getRange('A1').activate();
  return sheet.getName();
}

function getDefaultBannedList_() {
  return [
    "MBTI", "커리어넷", "메이저맵", "패들렛", "띵커벨", "알로",
    "미리캔버스", "망고보드", "유튜버", "유튜브", "넷플릭스", "왓챠",
    "티빙", "네이버 폼", "구글 폼", "OECD", "UN", "유네스코", "WTO",
    "WHO", "그린피스", "앰네스티", "IMF", "인스타그램", "페이스북",
    "카카오톡", "네이버", "구글", "클래스 카드", "구글 클래스룸", "게더타운",
    "제페토", "아이패드", "갤럭시 탭", "비트코인", "TED", "반크", "TOEIC",
    "TOEFL", "TEPS", "대회", "수상", "한자능력검정"
  ];
}

function getBannedWordList_() {
  var sheet = ensureBannedWordSheet_();
  var header = sheet.getRange(1, 1, 1, 2).getDisplayValues()[0];
  if (header.join('|') !== BANNED_WORD_HEADERS_.join('|')) {
    throw new Error('기재금지어관리 시트의 1행은 "번호 | 기재 금지어" 순서여야 합니다.');
  }

  var lastRow = sheet.getLastRow();
  if (lastRow < 2) return [];

  var values = sheet.getRange(2, 1, lastRow - 1, 2).getDisplayValues();
  var seen = {};
  var list = [];

  values.forEach(function(row, index) {
    var rowNumber = index + 2;
    var number = String(row[0] || '').trim();
    var keyword = String(row[1] || '').trim();

    if (!number && !keyword) return;
    if (!/^[1-9]\d*$/.test(number)) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 번호(A열)는 1 이상의 정수여야 합니다.');
    }
    if (!keyword) throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어(B열)를 입력해 주세요.');

    var duplicateKey = normalizeBannedWord_(keyword);
    if (seen[duplicateKey]) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어가 ' + seen[duplicateKey] + '행과 중복됩니다: ' + keyword);
    }
    seen[duplicateKey] = rowNumber;
    list.push(keyword);
  });

  return list;
}

function runBannedWordCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  var values = range.getValues();
  var startRow = range.getRow();
  var startCol = range.getColumn();
  
  var db = getBannedWordList_();
  if (db.length === 0) return [];
  db.sort(function(a, b) { return normalizeBannedWord_(b).length - normalizeBannedWord_(a).length; });
  var canonicalByNormalizedKeyword = {};
  db.forEach(function(keyword) { canonicalByNormalizedKeyword[normalizeBannedWord_(keyword)] = keyword; });
  var combinedPattern = new RegExp('(' + db.map(buildWhitespaceInsensitivePattern_).join('|') + ')', 'gi');

  var results = [];

  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var original = values[i][j].toString();
      if (!original.trim()) continue;

      var hasIssue = false;
      var logs = [];

      var counts = {};
      var match;
      while ((match = combinedPattern.exec(original)) !== null) {
        var normalizedMatch = normalizeBannedWord_(match[0]);
        var keyword = canonicalByNormalizedKeyword[normalizedMatch];
        if (keyword) {
          hasIssue = true;
          counts[keyword] = (counts[keyword] || 0) + 1;
        }
      }

      Object.keys(counts).forEach(function(keyword) {
        logs.push({ k: keyword, count: counts[keyword] });
      });

      if (hasIssue) {
        results.push({
          sheetName: sheetName,
          row: startRow + i,
          col: startCol + j,
          original: original,
          logs: logs
        });
      }
    }
  }
  return results;
}

function escapeRegExp(string) {
  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); 
}

function normalizeBannedWord_(value) {
  return String(value || '').replace(/\s+/g, '').toLocaleLowerCase();
}

function buildWhitespaceInsensitivePattern_(keyword) {
  var compact = normalizeBannedWord_(keyword);
  if (!compact) throw new Error('비어 있는 기재 금지어는 검사할 수 없습니다.');
  return compact.split('').map(function(character) {
    return escapeRegExp(character);
  }).join('[\\s\\u00A0]*');
}

// =================================================================
// [4] 로컬 검토 유틸리티
// =================================================================

function unifyToStraightQuotes() {
  var range = SpreadsheetApp.getActiveRange();
  var ui = SpreadsheetApp.getUi();
  if (!range) throw new Error('선택된 셀이 없습니다.');
  var response = ui.alert('따옴표 변환', '선택 영역의 둥근 따옴표를 곧은 따옴표로 변환하시겠습니까?', ui.ButtonSet.YES_NO);
  if (response != ui.Button.YES) return;
  try {
    range.createTextFinder('[‘’]').useRegularExpression(true).matchEntireCell(false).replaceAllWith("'");
    range.createTextFinder('[“”]').useRegularExpression(true).matchEntireCell(false).replaceAllWith('"');
    SpreadsheetApp.flush();
    ui.alert('✅ 변환 완료');
  } catch (e) { ui.alert('오류: ' + e.toString()); }
}

// [신규] 선택 영역 스페이스바 실수(2칸 이상) 수정 함수
function fixDoubleSpaces() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  const values = range.getValues();
  let fixCount = 0; // 수정된 셀 개수 카운트

  const newValues = values.map(row => {
    return row.map(cell => {
      let str = String(cell);
      // 공백이 2번 이상 연속( /  +/)으로 있으면 1번으로 변경
      // 줄바꿈(\n)은 건드리지 않도록 일반 공백( )만 타겟팅
      if (/ {2,}/.test(str)) {
        fixCount++;
        return str.replace(/ {2,}/g, ' '); 
      }
      return cell;
    });
  });

  if (fixCount > 0) {
    range.setValues(newValues);
  }
  
  return fixCount;
}

// =================================================================
// [5] UI 상태 저장/불러오기
// =================================================================

function saveUiState(cardId, isExpanded) {
  var props = PropertiesService.getUserProperties();
  var state = JSON.parse(props.getProperty('UI_STATE') || '{}');
  state[cardId] = isExpanded;
  props.setProperty('UI_STATE', JSON.stringify(state));
}

function getUiState() {
  var props = PropertiesService.getUserProperties();
  return JSON.parse(props.getProperty('UI_STATE') || '{}');
}

Sidebar.html


= 0 ? initialView : "sidebar"; ?>



  
    
    
    
    
  
  
    
      
        🔑 Bareun API 키 설정
        expand_more
      
      
        
          
            내 Bareun API 키
            expand_more
          
          
            ⌛ API 키 설정 확인 중...
            
              
              Bareun API 키
              
              공용 키는 제공하지 않습니다. 키는 사용자별 설정에 저장되고 원문을 화면으로 다시 불러오지 않습니다.
              
              
            
          
        
      
    

    
      
        📝 선택 영역 검사 및 정리
        expand_more
      
      
        
        
        
        
        
        
      
    

    
  





  
    
    
    
    
    
  
  

    
      fact_check 맞춤법 검사 및 수정
      
        원본 오류
        수정 제안
      
    

    
      
        
        데이터를 불러오는 중입니다...
      
      
    

    
      
      
    

    
  





  
    
    
    
    
  
  

    
      block 기재 금지어 검사
      
        금지어 발견
        오른쪽 수정안에서 문맥에 맞게 직접 고쳐 주세요.
      
    

    
      
        
        데이터를 분석 중입니다...

AIEDAP 마스터 교원 전문성 강화 연수 - 교과 기반(국어 심화)

Sun, 09 Aug 2026 04:08:37 GMT

AIEDAP 마스터 교원 전문성 강화 연수 - 교과 기반(국어 심화)

강사: 교사 김민기(민기쌤)
일시: 2026-08-09
장소: 공주대학교

AIEDAP 마스터 교원 대상 전문성 강화 연수 강의입니다.

강의 자료

유튜브 댓글 데이터 분석

Code.gs

const YT_CFG = Object.freeze({
  API_BASE: 'https://www.googleapis.com/youtube/v3',

  API_KEY_PROP: 'YT_API_KEY',
  STATE_PROP: 'YT_COMMENT_COLLECTOR_STATE',
  LAST_RESULT_PROP: 'YT_COMMENT_COLLECTOR_LAST_RESULT',
  CANCEL_REQUEST_PROP: 'YT_COMMENT_COLLECTOR_CANCEL_REQUEST',

  OUTPUT_SHEET_PREFIX: '시트',
  INTERNAL_SHEET: '_댓글수집_내부',
  LEGACY_LOG_SHEET: '수집로그',

  CONTINUE_HANDLER: 'continueCommentCollection',
  STRUCTURED_ERROR_PREFIX: 'YT_STRUCTURED_ERROR::',
  STATE_VERSION: 4,

  // Apps Script의 일반 실행 제한 전에 상태를 저장하고 다음 실행으로 넘깁니다.
  MAX_RUN_MS: 4 * 60 * 1000 + 30 * 1000,
  CONTINUE_AFTER_MS: 60 * 1000,

  MIN_LIMIT: 1,
  MAX_LIMIT: 50000,

  HEADERS: [
    '번호',
    '채널명',
    '영상 제목',
    '댓글 작성자',
    '댓글 내용',
    '좋아요 수',
    '작성 시각',
    '글자수'
  ],

  // 숨김 내부 시트의 열 구조입니다.
  INTERNAL_HEADERS: [
    'comment_id',
    'parent_comment_id',
    'display_number',
    'comment_type',
    'reply_status',
    'next_reply_index',
    'total_reply_count',
    'reply_page_token'
  ],

  INTERNAL_COL: Object.freeze({
    COMMENT_ID: 1,
    PARENT_ID: 2,
    DISPLAY_NUMBER: 3,
    COMMENT_TYPE: 4,
    REPLY_STATUS: 5,
    NEXT_REPLY_INDEX: 6,
    TOTAL_REPLY_COUNT: 7,
    REPLY_PAGE_TOKEN: 8
  })
});


/**
 * 스프레드시트를 열 때 사용자 메뉴를 만듭니다.
 */
function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('YouTube 댓글 수집')
    .addItem('사이드바 열기', 'showYouTubeCommentSidebar')
    .addSeparator()
    .addItem('중단 지점부터 실행', 'continueCommentCollection')
    .addItem('진행 중인 수집 취소', 'cancelCommentCollection')
    .addToUi();
}


/**
 * 오른쪽 사이드바를 엽니다.
 */
function showYouTubeCommentSidebar() {
  const html = HtmlService
    .createHtmlOutputFromFile('Sidebar')
    .setTitle('YouTube 댓글 수집기');

  SpreadsheetApp.getUi().showSidebar(html);
}


/**
 * 사이드바 초기 상태를 반환합니다.
 */
function getSidebarState() {
  const props = getUserProperties_();
  const apiKey = props.getProperty(YT_CFG.API_KEY_PROP) || '';
  const activeState = loadState_();
  const lastResult = loadLastResult_();
  const cancelRequested =
    props.getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';

  const progress = activeState
    ? buildProgressForClient_(activeState, 'RUNNING')
    : lastResult
      ? buildProgressForClient_(lastResult, lastResult.status || 'COMPLETED')
      : null;

  if (progress && activeState && cancelRequested) {
    progress.stage = '취소 처리 중';
    progress.message = '현재 실행 구간이 끝나는 즉시 안전하게 중단됩니다.';
  }

  return {
    apiKeyConfigured: Boolean(apiKey),
    apiKeyMask: apiKey ? maskApiKey_(apiKey) : '',
    running: Boolean(activeState),
    cancelRequested: cancelRequested,
    progress: progress
  };
}


/**
 * API 키를 실제 YouTube Data API 요청으로 검증한 뒤 사용자별 속성에 저장합니다.
 */
function saveApiKey(apiKey) {
  const cleanedKey = String(apiKey || '').trim();

  if (!cleanedKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키를 입력해야 합니다.',
      'Google Cloud에서 발급한 YouTube Data API 키가 입력되지 않았습니다.',
      ['API 키 입력란이 비어 있습니다.'],
      [
        'Google Cloud Console에서 API 키를 발급합니다.',
        'API 키 전체를 사이드바 입력란에 붙여 넣습니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  if (cleanedKey.length < 20) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_FORMAT_INVALID',
      'API 키 형식을 확인해야 합니다.',
      '입력한 문자열이 일반적인 Google API 키 길이보다 짧습니다.',
      [
        'API 키 일부만 복사했을 수 있습니다.',
        '프로젝트 ID나 다른 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 값을 처음부터 끝까지 다시 복사하여 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력'
      }
    ));
  }

  validateApiKey_(cleanedKey);

  const props = getUserProperties_();
  props.setProperty(YT_CFG.API_KEY_PROP, cleanedKey);

  // 이전 API 키 오류 안내가 새 키 저장 뒤 다시 나타나지 않도록 정리합니다.
  const previous = loadLastResult_();
  if (previous && previous.status === 'ERROR') {
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
  }

  return getSidebarState();
}


/**
 * 저장된 API 키를 삭제합니다.
 */
function deleteApiKey() {
  if (loadState_()) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_DELETE_BLOCKED',
      '수집 중에는 API 키를 삭제할 수 없습니다.',
      '현재 댓글 수집 작업이 저장된 API 키를 사용하고 있습니다.',
      ['진행 중인 작업이 존재합니다.'],
      [
        '현재 수집을 완료하거나 취소합니다.',
        '수집 상태가 종료된 뒤 API 키를 삭제합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.API_KEY_PROP);
  props.deleteProperty(YT_CFG.LAST_RESULT_PROP);

  return getSidebarState();
}


/**
 * 사이드바 입력값으로 새 수집 작업을 준비합니다.
 * 실제 수집은 runCollectionNow 또는 시간 기반 트리거가 수행합니다.
 */
function startCollectionFromSidebar(formData) {
  const lock = LockService.getScriptLock();
  lock.waitLock(10000);

  try {
    const apiKey = getApiKey_();
    const input = normalizeSidebarInput_(formData);
    const ss = SpreadsheetApp.getActiveSpreadsheet();

    if (!ss) {
      throwStructuredError_(buildErrorInfo_(
        'SPREADSHEET_NOT_FOUND',
        '댓글을 저장할 스프레드시트를 찾지 못했습니다.',
        '현재 Apps Script가 스프레드시트와 연결된 상태인지 확인해야 합니다.',
        [
          '독립 실행형 Apps Script 프로젝트에서 코드를 실행했을 수 있습니다.',
          '스프레드시트가 닫히거나 접근 권한이 변경되었을 수 있습니다.'
        ],
        [
          '댓글을 저장할 Google 스프레드시트를 엽니다.',
          '‘확장 프로그램 → Apps Script’에서 이 코드를 실행합니다.',
          '스프레드시트를 새로고침하고 사이드바를 다시 엽니다.'
        ],
        { actionLabel: '확인' }
      ));
    }

    // 영상과 API 키가 정상인지 먼저 확인합니다.
    const videoId = extractVideoId_(input.videoUrl);
    const metadata = getVideoMetadataWithKey_(videoId, apiKey);

    deleteContinuationTriggers_();

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    // 새 수집은 기존 결과를 지우지 않고 새 결과 시트에 기록합니다.
    const outputSheet = createNextOutputSheet_(ss);
    ensureInternalSheet_(ss);
    resetInternalData_(ss);
    deleteLegacyLogSheet_(ss);

    const state = {
      version: YT_CFG.STATE_VERSION,
      status: 'RUNNING',
      spreadsheetId: ss.getId(),

      outputSheetId: outputSheet.getSheetId(),
      outputSheetName: outputSheet.getName(),

      videoId: videoId,
      videoTitle: metadata.title,
      videoChannelId: metadata.channelId,
      videoChannelTitle: metadata.channelTitle,
      reportedCommentCount: metadata.commentCount,

      targetTopLevelCount: input.limit,
      includeReplies: input.includeReplies,

      nextThreadPageToken: '',
      threadDone: false,

      currentReplyParentId: '',
      nextReplyPageToken: '',

      topCount: 0,
      replyCount: 0,
      threadPages: 0,
      replyPages: 0,
      apiCalls: 1,

      startedAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      message: outputSheet.getName() + '에서 수집을 시작했습니다.',
      error: null
    };

    saveState_(state);

    // 사이드바가 닫혀도 수집이 이어지도록 예비 트리거를 만듭니다.
    scheduleContinuation_();

    return getSidebarState();

  } finally {
    lock.releaseLock();
  }
}


/**
 * 사이드바가 첫 실행 구간을 즉시 시작할 때 호출합니다.
 */
function runCollectionNow() {
  continueCommentCollection();
  return getSidebarState();
}


/**
 * 저장된 상태에서 댓글 수집을 계속합니다.
 */
function continueCommentCollection() {
  const lock = LockService.getScriptLock();

  if (!lock.tryLock(5000)) {
    return;
  }

  let ss = null;
  let state = null;
  let commentsSheet = null;

  try {
    state = loadState_();

    if (!state) {
      return;
    }

    validateStateVersion_(state);
    normalizeState_(state);

    ss = SpreadsheetApp.openById(state.spreadsheetId);
    ensureInternalSheet_(ss);
    deleteLegacyLogSheet_(ss);

    commentsSheet = getOutputSheetForState_(ss, state);
    const internalSheet = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);
    const existingIds = getExistingCommentIds_(internalSheet);
    const existingCounts = getExistingCounts_(internalSheet);

    // 시트 기록 직후 상태 저장 전에 실행이 끊긴 상황을 보정합니다.
    state.topCount = existingCounts.top;
    state.replyCount = existingCounts.reply;

    const runStartedAt = Date.now();

    while (Date.now() - runStartedAt < YT_CFG.MAX_RUN_MS) {
      if (isCancelRequested_()) {
        finalizeCancellation_(ss, commentsSheet, state);
        return;
      }

      // 처리 중이던 답글 페이지가 있으면 먼저 이어서 처리합니다.
      if (state.currentReplyParentId) {
        processReplyPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      // 내부 시트에서 답글 수집이 필요한 최상위 댓글을 하나 선택합니다.
      const pendingReply = claimNextPendingReply_(internalSheet);

      if (pendingReply) {
        state.currentReplyParentId = pendingReply.commentId;
        state.nextReplyPageToken = pendingReply.pageToken || '';
        saveState_(state);
        continue;
      }

      // 답글 대기 항목이 없을 때 다음 최상위 댓글 페이지를 가져옵니다.
      if (!state.threadDone) {
        processThreadPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      finishCollection_(ss, commentsSheet, state);
      return;
    }

    state.updatedAt = new Date().toISOString();
    state.message = '실행 시간을 고려하여 진행 상태를 저장했습니다.';
    saveState_(state);
    scheduleContinuation_();

  } catch (error) {
    deleteContinuationTriggers_();

    const errorInfo = normalizeErrorInfo_(error, '댓글 수집');

    if (errorInfo.code === 'API_KEY_INVALID') {
      getUserProperties_().deleteProperty(YT_CFG.API_KEY_PROP);
    }

    if (commentsSheet) {
      try {
        finalizeCommentsSheet_(commentsSheet);
      } catch (formatError) {
        console.error(formatError);
      }
    }

    if (state) {
      state.status = 'ERROR';
      state.updatedAt = new Date().toISOString();
      state.message = errorInfo.summary;
      state.error = errorInfo;
      saveLastResult_(state, 'ERROR', errorInfo.summary, errorInfo);
    }

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    console.error(error);
    throwStructuredError_(errorInfo);

  } finally {
    lock.releaseLock();
  }
}


/**
 * 진행 중인 수집을 취소합니다.
 */
function cancelCommentCollection() {
  const props = getUserProperties_();
  const state = loadState_();

  if (!state) {
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
    deleteContinuationTriggers_();
    return getSidebarState();
  }

  props.setProperty(YT_CFG.CANCEL_REQUEST_PROP, 'true');
  deleteContinuationTriggers_();

  const lock = LockService.getScriptLock();

  // 다른 수집 실행이 없다면 이 호출에서 즉시 취소를 마무리합니다.
  if (lock.tryLock(200)) {
    try {
      const latestState = loadState_();

      if (latestState) {
        const ss = SpreadsheetApp.openById(latestState.spreadsheetId);
        ensureInternalSheet_(ss);
        const commentsSheet = getOutputSheetForState_(ss, latestState);
        finalizeCancellation_(ss, commentsSheet, latestState);
      }
    } finally {
      lock.releaseLock();
    }
  }

  return getSidebarState();
}


/**
 * 최상위 댓글 스레드 한 페이지를 처리합니다.
 */
function processThreadPage_(state, commentsSheet, internalSheet, existingIds) {
  const remaining = state.targetTopLevelCount - state.topCount;

  if (remaining <= 0) {
    state.threadDone = true;
    state.nextThreadPageToken = '';
    return;
  }

  const params = {
    part: state.includeReplies ? 'snippet,replies' : 'snippet',
    videoId: state.videoId,
    maxResults: Math.min(100, remaining),
    textFormat: 'plainText'
  };

  if (state.nextThreadPageToken) {
    params.pageToken = state.nextThreadPageToken;
  }

  const data = youtubeGet_('commentThreads', params);

  state.apiCalls += 1;
  state.threadPages += 1;

  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();
  const items = Array.isArray(data.items) ? data.items : [];

  let topAdded = 0;
  let replyAdded = 0;
  let nextTopNumber = state.topCount + 1;

  items.forEach(function(thread) {
    if (state.topCount + topAdded >= state.targetTopLevelCount) {
      return;
    }

    const threadSnippet = thread.snippet || {};
    const topComment = threadSnippet.topLevelComment;

    if (!topComment || !topComment.id) {
      return;
    }

    const topCommentId = String(topComment.id);

    if (existingIds.has(topCommentId) || batchIds.has(topCommentId)) {
      return;
    }

    const topNumber = String(nextTopNumber);
    nextTopNumber += 1;

    const totalReplyCount = Number(threadSnippet.totalReplyCount || 0);
    let replyStatus = 'DONE';
    let nextReplyIndex = 1;

    commentRows.push(
      commentToOutputRow_(state, topComment, topNumber)
    );

    batchIds.add(topCommentId);
    topAdded += 1;

    const inlineReplies =
      thread.replies && Array.isArray(thread.replies.comments)
        ? thread.replies.comments
        : [];

    if (state.includeReplies && totalReplyCount > 0) {
      if (inlineReplies.length === totalReplyCount) {
        inlineReplies.forEach(function(reply) {
          if (!reply || !reply.id) {
            return;
          }

          const replyId = String(reply.id);

          if (existingIds.has(replyId) || batchIds.has(replyId)) {
            return;
          }

          const displayNumber = topNumber + '_' + nextReplyIndex;
          nextReplyIndex += 1;

          commentRows.push(
            commentToOutputRow_(state, reply, displayNumber)
          );

          internalRows.push(
            buildInternalRow_(
              replyId,
              topCommentId,
              displayNumber,
              'reply',
              '',
              '',
              '',
              ''
            )
          );

          batchIds.add(replyId);
          replyAdded += 1;
        });
      } else {
        // commentThreads.list의 replies에는 전체 답글이 보장되지 않으므로
        // comments.list로 전체 답글을 다시 가져옵니다.
        replyStatus = 'PENDING';
        nextReplyIndex = 1;
      }
    }

    internalRows.push(
      buildInternalRow_(
        topCommentId,
        '',
        topNumber,
        'topLevel',
        replyStatus,
        nextReplyIndex,
        totalReplyCount,
        ''
      )
    );
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.topCount += topAdded;
  state.replyCount += replyAdded;

  const reachedTarget = state.topCount >= state.targetTopLevelCount;
  const hasNextPage = Boolean(data.nextPageToken);

  state.nextThreadPageToken =
    !reachedTarget && hasNextPage
      ? data.nextPageToken
      : '';

  state.threadDone = reachedTarget || !hasNextPage;
  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 특정 최상위 댓글의 답글 한 페이지를 처리합니다.
 */
function processReplyPage_(state, commentsSheet, internalSheet, existingIds) {
  const topRecord = findInternalRecordByCommentId_(
    internalSheet,
    state.currentReplyParentId
  );

  if (!topRecord) {
    // 내부 상태가 사라진 경우 현재 항목을 건너뛰고 다음 대기 항목을 찾습니다.
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
    return;
  }

  const params = {
    part: 'snippet',
    parentId: state.currentReplyParentId,
    maxResults: 100,
    textFormat: 'plainText'
  };

  const pageToken =
    state.nextReplyPageToken || topRecord.replyPageToken || '';

  if (pageToken) {
    params.pageToken = pageToken;
  }

  const data = youtubeGet_('comments', params);

  state.apiCalls += 1;
  state.replyPages += 1;

  const items = Array.isArray(data.items) ? data.items : [];
  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();

  let nextReplyIndex = Number(topRecord.nextReplyIndex || 1);
  let replyAdded = 0;

  items.forEach(function(reply) {
    if (!reply || !reply.id) {
      return;
    }

    const replyId = String(reply.id);

    if (existingIds.has(replyId) || batchIds.has(replyId)) {
      return;
    }

    const displayNumber =
      String(topRecord.displayNumber) + '_' + nextReplyIndex;

    nextReplyIndex += 1;

    commentRows.push(
      commentToOutputRow_(state, reply, displayNumber)
    );

    internalRows.push(
      buildInternalRow_(
        replyId,
        state.currentReplyParentId,
        displayNumber,
        'reply',
        '',
        '',
        '',
        ''
      )
    );

    batchIds.add(replyId);
    replyAdded += 1;
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.replyCount += replyAdded;

  const nextPageToken = data.nextPageToken || '';
  const nextStatus = nextPageToken ? 'IN_PROGRESS' : 'DONE';

  updateTopReplyProgress_(
    internalSheet,
    topRecord.rowNumber,
    nextStatus,
    nextReplyIndex,
    nextPageToken
  );

  if (nextPageToken) {
    state.nextReplyPageToken = nextPageToken;
  } else {
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
  }

  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 내부 시트에서 답글 수집 대기 중인 최상위 댓글 하나를 선택합니다.
 */
function claimNextPendingReply_(internalSheet) {
  const statusRange = internalSheet.getRange(
    2,
    YT_CFG.INTERNAL_COL.REPLY_STATUS,
    Math.max(internalSheet.getLastRow() - 1, 1),
    1
  );

  let found = statusRange
    .createTextFinder('IN_PROGRESS')
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    found = statusRange
      .createTextFinder('PENDING')
      .matchEntireCell(true)
      .useRegularExpression(false)
      .findNext();
  }

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  if (values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] === 'PENDING') {
    internalSheet
      .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS)
      .setValue('IN_PROGRESS');
  }

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    pageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 댓글 1건을 사용자가 보는 8열 행으로 변환합니다.
 */
function commentToOutputRow_(state, comment, displayNumber) {
  const snippet = (comment && comment.snippet) || {};
  const text = String(snippet.textDisplay || '');

  return [
    String(displayNumber),
    safeCellText_(state.videoChannelTitle || ''),
    safeCellText_(state.videoTitle || ''),
    safeCellText_(snippet.authorDisplayName || ''),
    safeCellText_(text),
    Number(snippet.likeCount || 0),
    apiDateToSheetValue_(snippet.publishedAt),
    calculateCommentBytes_(text)
  ];
}


/**
 * 숨김 내부 시트의 행을 만듭니다.
 */
function buildInternalRow_(
  commentId,
  parentCommentId,
  displayNumber,
  commentType,
  replyStatus,
  nextReplyIndex,
  totalReplyCount,
  replyPageToken
) {
  return [
    safeCellText_(commentId || ''),
    safeCellText_(parentCommentId || ''),
    String(displayNumber || ''),
    String(commentType || ''),
    String(replyStatus || ''),
    nextReplyIndex === '' ? '' : Number(nextReplyIndex || 1),
    totalReplyCount === '' ? '' : Number(totalReplyCount || 0),
    safeCellText_(replyPageToken || '')
  ];
}


/**
 * 댓글 행과 내부 관리 행을 각각 일괄 기록합니다.
 */
function appendCollectedRecords_(
  commentsSheet,
  internalSheet,
  commentRows,
  internalRows
) {
  if (commentRows.length !== internalRows.length) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_ROW_MISMATCH',
      '댓글 저장 구조를 확인해야 합니다.',
      '댓글 행과 내부 관리 행의 개수가 일치하지 않습니다.',
      ['수집 상태를 기록하는 내부 데이터가 일시적으로 어긋났습니다.'],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  if (commentRows.length === 0) {
    return;
  }

  commentsSheet
    .getRange(
      commentsSheet.getLastRow() + 1,
      1,
      commentRows.length,
      YT_CFG.HEADERS.length
    )
    .setValues(commentRows);

  internalSheet
    .getRange(
      internalSheet.getLastRow() + 1,
      1,
      internalRows.length,
      YT_CFG.INTERNAL_HEADERS.length
    )
    .setValues(internalRows);
}


/**
 * 내부 시트에서 특정 댓글 ID의 관리 행을 찾습니다.
 */
function findInternalRecordByCommentId_(internalSheet, commentId) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return null;
  }

  const found = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .createTextFinder(String(commentId || ''))
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    replyStatus: String(
      values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    replyPageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 최상위 댓글의 답글 수집 진행 정보를 갱신합니다.
 */
function updateTopReplyProgress_(
  internalSheet,
  rowNumber,
  status,
  nextReplyIndex,
  pageToken
) {
  internalSheet
    .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS, 1, 4)
    .setValues([[
      status,
      Number(nextReplyIndex || 1),
      internalSheet
        .getRange(rowNumber, YT_CFG.INTERNAL_COL.TOTAL_REPLY_COUNT)
        .getValue(),
      pageToken || ''
    ]]);
}


/**
 * 완료 처리
 */
function finishCollection_(ss, commentsSheet, state) {
  state.status = 'COMPLETED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = state.topCount < state.targetTopLevelCount
    ? '댓글 ' +
      state.topCount +
      '개와 대댓글 ' +
      state.replyCount +
      '개를 수집했습니다.'
    : '댓글 수집을 완료했습니다.';
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'COMPLETED', state.message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


function isCancelRequested_() {
  return getUserProperties_().getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';
}


/**
 * 취소 처리
 */
function finalizeCancellation_(ss, commentsSheet, state) {
  const message = '사용자가 수집을 취소했습니다. 이미 저장된 댓글은 유지됩니다.';

  state.status = 'CANCELLED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = message;
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'CANCELLED', message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


/**
 * API 키가 YouTube Data API 요청에 사용 가능한지 확인합니다.
 */
function validateApiKey_(apiKey) {
  youtubeGetWithKey_(
    'videos',
    {
      part: 'id',
      id: 'jNQXAC9IVRw'
    },
    apiKey
  );
}


/**
 * 영상 메타데이터를 조회합니다.
 */
function getVideoMetadataWithKey_(videoId, apiKey) {
  const data = youtubeGetWithKey_(
    'videos',
    {
      part: 'snippet,statistics',
      id: videoId
    },
    apiKey
  );

  if (!Array.isArray(data.items) || data.items.length === 0) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '입력한 영상 주소에 해당하는 공개 영상을 YouTube Data API에서 조회하지 못했습니다.',
      [
        '영상 주소나 11자리 영상 ID가 정확하지 않을 수 있습니다.',
        '영상이 삭제되었거나 비공개 상태일 수 있습니다.',
        '연령·지역·계정 권한에 따라 접근이 제한된 영상일 수 있습니다.'
      ],
      [
        '브라우저에서 해당 영상 주소가 정상적으로 열리는지 확인합니다.',
        '주소 표시줄의 영상 URL 전체를 다시 복사합니다.',
        '사이드바의 영상 주소를 교체한 뒤 수집을 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: { videoId: videoId }
      }
    ));
  }

  const item = data.items[0];
  const snippet = item.snippet || {};
  const statistics = item.statistics || {};

  return {
    title: snippet.title || '',
    channelId: snippet.channelId || '',
    channelTitle: snippet.channelTitle || '',
    commentCount: statistics.commentCount || ''
  };
}


/**
 * 저장된 API 키로 YouTube Data API를 호출합니다.
 */
function youtubeGet_(resource, params) {
  return youtubeGetWithKey_(resource, params, getApiKey_());
}


/**
 * YouTube Data API GET 요청을 수행합니다.
 */
function youtubeGetWithKey_(resource, params, apiKey) {
  const queryParams = Object.assign({}, params, { key: apiKey });

  const query = Object.keys(queryParams)
    .filter(function(key) {
      const value = queryParams[key];
      return value !== undefined && value !== null && value !== '';
    })
    .map(function(key) {
      return encodeURIComponent(key) + '=' + encodeURIComponent(queryParams[key]);
    })
    .join('&');

  const url = YT_CFG.API_BASE + '/' + resource + '?' + query;
  const transientCodes = [429, 500, 502, 503, 504];

  for (let attempt = 0; attempt < 3; attempt += 1) {
    let response;

    try {
      response = UrlFetchApp.fetch(url, {
        method: 'get',
        muteHttpExceptions: true,
        headers: { Accept: 'application/json' }
      });
    } catch (networkError) {
      if (attempt < 2) {
        Utilities.sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      throwStructuredError_(buildErrorInfo_(
        'NETWORK_REQUEST_FAILED',
        'YouTube 서버에 연결하지 못했습니다.',
        'Apps Script에서 YouTube Data API로 보내는 외부 요청이 완료되지 않았습니다.',
        [
          'Google 서비스 또는 네트워크에 일시적인 장애가 발생했을 수 있습니다.',
          'Apps Script의 외부 요청 권한이 승인되지 않았을 수 있습니다.'
        ],
        [
          '잠시 뒤 같은 작업을 다시 실행합니다.',
          'Apps Script 권한 승인 화면이 나타나면 요청된 권한을 허용합니다.',
          'Apps Script의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.'
        ],
        {
          actionLabel: '확인',
          technical: {
            resource: resource,
            originalMessage: String(networkError && networkError.message || networkError)
          }
        }
      ));
    }

    const statusCode = response.getResponseCode();
    const responseText = response.getContentText();

    if (statusCode >= 200 && statusCode < 300) {
      return responseText ? JSON.parse(responseText) : {};
    }

    if (transientCodes.indexOf(statusCode) >= 0 && attempt < 2) {
      Utilities.sleep(Math.pow(2, attempt) * 1000);
      continue;
    }

    const parsedError = parseYouTubeErrorResponse_(responseText);

    throwStructuredError_(classifyYouTubeApiError_(
      statusCode,
      parsedError.reason,
      parsedError.message,
      resource
    ));
  }

  throwStructuredError_(buildErrorInfo_(
    'YOUTUBE_REQUEST_REPEATED_FAILURE',
    'YouTube API 요청이 반복적으로 실패했습니다.',
    '일시적인 서버 장애가 재시도 후에도 계속되었습니다.',
    ['YouTube 또는 Google 네트워크 서비스가 불안정할 수 있습니다.'],
    [
      '잠시 뒤 같은 작업을 다시 실행합니다.',
      '반복되면 Apps Script의 ‘실행’ 기록을 확인합니다.'
    ],
    { actionLabel: '확인', technical: { resource: resource } }
  ));
}


function parseYouTubeErrorResponse_(responseText) {
  let reason = '';
  let message = String(responseText || '');

  try {
    const parsed = JSON.parse(responseText);

    if (parsed.error) {
      message = parsed.error.message || message;

      if (Array.isArray(parsed.error.errors) && parsed.error.errors[0]) {
        reason = parsed.error.errors[0].reason || '';
      }

      if (!reason && parsed.error.status) {
        reason = parsed.error.status;
      }
    }
  } catch (parseError) {
    // JSON이 아닌 오류 본문은 문자열 그대로 분류합니다.
  }

  return {
    reason: String(reason || ''),
    message: String(message || '')
  };
}


/**
 * YouTube API 오류를 한국어 모달용 정보로 분류합니다.
 */
function classifyYouTubeApiError_(statusCode, reason, message, resource) {
  const reasonText = String(reason || '');
  const messageText = String(message || '');
  const combined = (reasonText + ' ' + messageText).toLowerCase();
  const technical = {
    httpStatus: statusCode,
    apiReason: reasonText,
    resource: resource,
    originalMessage: messageText
  };

  if (
    combined.indexOf('keyinvalid') >= 0 ||
    combined.indexOf('api key not valid') >= 0 ||
    combined.indexOf('api_key_invalid') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_INVALID',
      'API 키를 사용할 수 없습니다.',
      '입력한 API 키가 정확하지 않거나 삭제·재발급되어 현재 요청에 사용할 수 없습니다.',
      [
        'API 키 일부가 누락되었을 수 있습니다.',
        'Google Cloud에서 기존 키가 삭제되거나 재발급되었을 수 있습니다.',
        'API 키가 아닌 다른 프로젝트 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 전체를 다시 복사합니다.',
        '사이드바에서 API 키를 다시 입력하고 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') >= 0 ||
    combined.indexOf('access not configured') >= 0 ||
    combined.indexOf('service_disabled') >= 0 ||
    combined.indexOf('api_disabled') >= 0 ||
    combined.indexOf('has not been used in project') >= 0 ||
    combined.indexOf('it is disabled') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_API_NOT_ENABLED',
      'YouTube Data API v3가 활성화되어 있지 않습니다.',
      'API 키가 속한 Google Cloud 프로젝트에서 YouTube Data API v3 사용 설정을 켜야 합니다.',
      [
        'API 키를 만든 프로젝트에서 YouTube Data API v3를 아직 활성화하지 않았습니다.',
        'API를 활성화한 프로젝트와 API 키를 발급한 프로젝트가 다를 수 있습니다.'
      ],
      [
        'Google Cloud Console에서 API 키를 만든 프로젝트를 선택합니다.',
        '‘API 및 서비스 → 라이브러리’로 이동합니다.',
        '‘YouTube Data API v3’를 검색하고 ‘사용’을 누릅니다.',
        '설정 반영을 위해 1~5분 기다린 뒤 API 키를 다시 저장합니다.'
      ],
      {
        helpLabel: 'YouTube Data API 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/library/youtube.googleapis.com',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('iprefererblocked') >= 0 ||
    combined.indexOf('referer') >= 0 && combined.indexOf('blocked') >= 0 ||
    combined.indexOf('api key restrictions') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_APPLICATION_RESTRICTION',
      'API 키의 애플리케이션 제한이 Apps Script 요청을 차단했습니다.',
      '현재 키에 설정된 웹사이트·IP 제한이 Apps Script의 UrlFetch 요청 방식과 맞지 않습니다.',
      [
        'HTTP 리퍼러 제한 또는 특정 IP 주소 제한이 적용되어 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키의 애플리케이션 제한을 확인합니다.',
        'Apps Script에서 사용할 수 있는 제한 방식으로 조정합니다.',
        'API 제한은 ‘YouTube Data API v3’로 유지합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') < 0 &&
    (
      combined.indexOf('forbidden') >= 0 &&
      combined.indexOf('api') >= 0 &&
      combined.indexOf('key') >= 0
    )
  ) {
    return buildErrorInfo_(
      'API_KEY_API_RESTRICTION',
      'API 키의 API 제한 설정을 확인해야 합니다.',
      '현재 API 키가 YouTube Data API v3 호출을 허용하지 않을 수 있습니다.',
      [
        'API 키의 ‘API 제한’ 목록에서 YouTube Data API v3가 빠져 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키를 선택합니다.',
        '‘API 제한’에서 YouTube Data API v3를 허용합니다.',
        '저장 후 1~5분 뒤 다시 실행합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('quotaexceeded') >= 0 ||
    combined.indexOf('dailylimitexceeded') >= 0 ||
    combined.indexOf('daily limit') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_QUOTA_EXCEEDED',
      'YouTube API의 오늘 할당량을 모두 사용했습니다.',
      '현재 Google Cloud 프로젝트에서 오늘 사용할 수 있는 YouTube Data API 할당량이 남아 있지 않습니다.',
      ['같은 프로젝트의 다른 프로그램에서도 YouTube API 할당량을 사용했을 수 있습니다.'],
      [
        'Google Cloud Console에서 YouTube Data API 사용량을 확인합니다.',
        '일일 할당량이 갱신된 뒤 다시 실행합니다.',
        '필요하면 다음 수집의 댓글 개수를 줄입니다.'
      ],
      {
        helpLabel: 'YouTube API 할당량 열기',
        helpUrl: 'https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas',
        actionLabel: '확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('ratelimitexceeded') >= 0 ||
    combined.indexOf('userratelimitexceeded') >= 0 ||
    statusCode === 429
  ) {
    return buildErrorInfo_(
      'YOUTUBE_RATE_LIMIT',
      '짧은 시간에 API 요청이 많이 발생했습니다.',
      'YouTube Data API가 일시적으로 요청 속도를 제한했습니다.',
      ['여러 수집 작업을 연속으로 실행했을 수 있습니다.'],
      [
        '현재 작업이 자동 재개되는지 확인합니다.',
        '몇 분 뒤 다시 실행합니다.',
        '동시에 여러 스프레드시트에서 같은 API 키를 사용하고 있다면 실행 횟수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (combined.indexOf('commentsdisabled') >= 0) {
    return buildErrorInfo_(
      'COMMENTS_DISABLED',
      '이 영상에서는 댓글을 수집할 수 없습니다.',
      '영상 게시자가 댓글 기능을 사용하지 않도록 설정했습니다.',
      ['영상의 댓글 기능이 꺼져 있거나 YouTube 정책에 따라 제한되었습니다.'],
      [
        '영상 페이지에서 댓글 영역이 표시되는지 확인합니다.',
        '댓글이 허용된 다른 영상 주소를 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('videonotfound') >= 0 ||
    combined.indexOf('video not found') >= 0
  ) {
    return buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '영상 주소가 잘못되었거나 영상이 삭제·비공개 상태일 수 있습니다.',
      [
        '영상 ID가 정확하지 않을 수 있습니다.',
        '영상 공개 상태가 변경되었을 수 있습니다.'
      ],
      [
        '브라우저에서 영상 주소가 정상적으로 열리는지 확인합니다.',
        '영상 URL 전체를 다시 복사해 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (statusCode >= 500) {
    return buildErrorInfo_(
      'YOUTUBE_SERVER_ERROR',
      'YouTube 서버에서 일시적인 오류가 발생했습니다.',
      'YouTube Data API 서버가 현재 요청을 정상적으로 처리하지 못했습니다.',
      ['YouTube 측의 일시적인 서비스 장애일 수 있습니다.'],
      [
        '잠시 뒤 같은 작업을 다시 실행합니다.',
        '진행 중인 수집이라면 자동 재개 여부를 확인합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (statusCode === 403) {
    return buildErrorInfo_(
      'YOUTUBE_ACCESS_FORBIDDEN',
      'YouTube 데이터에 접근할 수 없습니다.',
      'API 키 설정, 영상 공개 상태 또는 Google Cloud 프로젝트 권한을 확인해야 합니다.',
      [
        'API 키 제한 설정이 요청을 차단했을 수 있습니다.',
        '영상이 공개 API에서 접근할 수 없는 상태일 수 있습니다.'
      ],
      [
        'API 키의 API 제한과 애플리케이션 제한을 확인합니다.',
        '영상이 공개 상태인지 확인합니다.',
        'Google Cloud에서 YouTube Data API v3가 활성화되어 있는지 확인합니다.'
      ],
      {
        helpLabel: 'API 키 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (statusCode === 400) {
    return buildErrorInfo_(
      'YOUTUBE_BAD_REQUEST',
      'YouTube API 요청 형식을 확인해야 합니다.',
      '영상 주소 또는 요청 매개변수 중 하나를 YouTube API가 처리하지 못했습니다.',
      ['영상 주소가 올바르지 않거나 API 요청 값이 허용 범위를 벗어났을 수 있습니다.'],
      [
        '영상 주소를 다시 확인합니다.',
        '수집 개수와 정렬 기준을 확인합니다.',
        '같은 문제가 계속되면 새 수집으로 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '입력값 확인',
        technical: technical
      }
    );
  }

  return buildErrorInfo_(
    'YOUTUBE_API_ERROR',
    'YouTube API 요청을 완료하지 못했습니다.',
    'YouTube Data API가 요청을 거부하거나 처리하지 못했습니다.',
    ['API 키, 영상 공개 상태, 할당량 또는 네트워크 상태를 확인해야 합니다.'],
    [
      'API 키 설정과 YouTube Data API 활성화 여부를 확인합니다.',
      '영상 주소가 공개 영상인지 확인합니다.',
      '잠시 뒤 다시 실행합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}


/**
 * 영상 URL 또는 11자리 영상 ID에서 videoId를 추출합니다.
 */
function extractVideoId_(input) {
  const text = String(input || '').trim();

  if (/^[A-Za-z0-9_-]{11}$/.test(text)) {
    return text;
  }

  const patterns = [
    /[?&]v=([A-Za-z0-9_-]{11})/,
    /youtu\.be\/([A-Za-z0-9_-]{11})/,
    /youtube(?:-nocookie)?\.com\/(?:embed|shorts|live)\/([A-Za-z0-9_-]{11})/
  ];

  for (let i = 0; i < patterns.length; i += 1) {
    const match = text.match(patterns[i]);

    if (match) {
      return match[1];
    }
  }

  throwStructuredError_(buildErrorInfo_(
    'INVALID_VIDEO_URL',
    'YouTube 영상 주소를 확인해야 합니다.',
    '입력한 값에서 11자리 YouTube 영상 ID를 찾지 못했습니다.',
    [
      '영상 주소 일부가 빠졌을 수 있습니다.',
      '채널·재생목록 주소를 입력했을 수 있습니다.'
    ],
    [
      'YouTube에서 수집할 영상을 엽니다.',
      '브라우저 주소 표시줄의 영상 URL 전체를 복사합니다.',
      '사이드바의 영상 주소 입력란에 붙여 넣습니다.'
    ],
    {
      focusTarget: 'videoUrl',
      actionLabel: '영상 주소 다시 입력'
    }
  ));
}


/**
 * 사이드바 입력값을 검증합니다.
 */
function normalizeSidebarInput_(formData) {
  const form = formData || {};
  const videoUrl = String(form.videoUrl || '').trim();
  const limit = parseInt(form.limit, 10);

  if (!videoUrl) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_URL_REQUIRED',
      'YouTube 영상 주소를 입력해야 합니다.',
      '수집 대상 영상 주소가 비어 있습니다.',
      ['영상 주소 입력란에 값이 없습니다.'],
      ['수집할 YouTube 영상의 URL을 입력합니다.'],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 입력'
      }
    ));
  }

  if (!Number.isInteger(limit)) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_INVALID',
      '수집 개수를 정수로 입력해야 합니다.',
      '수집할 최상위 댓글 개수가 올바른 정수 형식이 아닙니다.',
      ['빈 값, 소수 또는 문자가 입력되었을 수 있습니다.'],
      ['1 이상의 정수를 입력합니다.'],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 입력'
      }
    ));
  }

  if (limit < YT_CFG.MIN_LIMIT || limit > YT_CFG.MAX_LIMIT) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_OUT_OF_RANGE',
      '수집 개수가 허용 범위를 벗어났습니다.',
      '수집 개수는 ' + YT_CFG.MIN_LIMIT + '개 이상 ' +
        YT_CFG.MAX_LIMIT + '개 이하로 입력해야 합니다.',
      ['입력한 개수가 코드에 설정된 운영 범위를 벗어났습니다.'],
      [
        YT_CFG.MIN_LIMIT + '~' + YT_CFG.MAX_LIMIT +
          ' 사이의 정수를 입력합니다.'
      ],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 수정'
      }
    ));
  }

  return {
    videoUrl: videoUrl,
    limit: limit,
    includeReplies: form.includeReplies === true
  };
}


/**
 * 결과 시트와 숨김 내부 시트를 준비합니다.
 */
function ensureInternalSheet_(ss) {
  let internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    internal = ss.insertSheet(YT_CFG.INTERNAL_SHEET);
  }

  ensureColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);

  if (internal.getLastRow() === 0) {
    internal
      .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
      .setValues([YT_CFG.INTERNAL_HEADERS]);
  }

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 새 수집에 사용할 결과 시트를 시트1, 시트2, 시트3 ... 순서로 만듭니다.
 *
 * 새 스프레드시트에 기본 빈 '시트1' 하나만 존재하는 경우에는 그 시트를
 * 첫 결과 시트로 사용합니다. 그 이후 수집부터는 항상 새 시트를 추가합니다.
 */
function createNextOutputSheet_(ss) {
  const sheets = ss.getSheets();

  if (
    sheets.length === 1 &&
    sheets[0].getName() === YT_CFG.OUTPUT_SHEET_PREFIX + '1' &&
    isSheetCompletelyBlank_(sheets[0])
  ) {
    prepareOutputSheet_(sheets[0]);
    return sheets[0];
  }

  let maxNumber = 0;
  const namePattern = new RegExp(
    '^' + escapeRegExp_(YT_CFG.OUTPUT_SHEET_PREFIX) + '(\\d+)$'
  );

  sheets.forEach(function(sheet) {
    const match = sheet.getName().match(namePattern);

    if (match) {
      maxNumber = Math.max(maxNumber, Number(match[1] || 0));
    }
  });

  let nextNumber = maxNumber + 1;
  let nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;

  while (ss.getSheetByName(nextName)) {
    nextNumber += 1;
    nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;
  }

  const sheet = ss.insertSheet(nextName);
  prepareOutputSheet_(sheet);
  return sheet;
}


function isSheetCompletelyBlank_(sheet) {
  return sheet.getLastRow() === 0 && sheet.getLastColumn() === 0;
}


function prepareOutputSheet_(sheet) {
  if (sheet.getFilter()) {
    sheet.getFilter().remove();
  }

  sheet.clear();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setValues([YT_CFG.HEADERS]);

  sheet.setFrozenRows(1);
  sheet.getRange('A:A').setNumberFormat('@');
  formatCommentsSheet_(sheet);
}


/**
 * 새 수집을 위해 숨김 내부 시트만 초기화합니다.
 * 이전 결과 시트의 내용은 변경하지 않습니다.
 */
function resetInternalData_(ss) {
  const internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_SHEET_NOT_FOUND',
      '내부 관리 시트를 준비하지 못했습니다.',
      '댓글 수집 상태를 저장하는 숨김 시트가 존재하지 않습니다.',
      ['내부 시트 생성 과정이 완료되지 않았습니다.'],
      ['사이드바를 닫았다가 다시 열고 새 수집을 시작합니다.'],
      { actionLabel: '확인' }
    ));
  }

  internal.clear();
  ensureExactColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);
  internal
    .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .setValues([YT_CFG.INTERNAL_HEADERS]);

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 현재 수집 상태에 연결된 결과 시트를 찾습니다.
 */
function getOutputSheetForState_(ss, state) {
  const expectedId = Number(state.outputSheetId || 0);
  let outputSheet = null;

  if (expectedId > 0) {
    outputSheet = ss.getSheets().find(function(sheet) {
      return sheet.getSheetId() === expectedId;
    }) || null;
  }

  if (!outputSheet && state.outputSheetName) {
    outputSheet = ss.getSheetByName(String(state.outputSheetName));
  }

  if (!outputSheet) {
    throwStructuredError_(buildErrorInfo_(
      'OUTPUT_SHEET_NOT_FOUND',
      '수집 결과 시트를 찾을 수 없습니다.',
      '현재 수집 작업과 연결된 결과 시트가 삭제되었거나 이름과 식별 정보가 변경되었습니다.',
      [
        '수집 중 결과 시트를 삭제했을 수 있습니다.',
        '스프레드시트 구조가 외부 작업으로 변경되었을 수 있습니다.'
      ],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }

  return outputSheet;
}


function escapeRegExp_(text) {
  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}


/**
 * 이전 버전이 만든 수집로그 시트를 제거합니다.
 */
function deleteLegacyLogSheet_(ss) {
  const logSheet = ss.getSheetByName(YT_CFG.LEGACY_LOG_SHEET);

  if (logSheet && ss.getSheets().length > 1) {
    ss.deleteSheet(logSheet);
  }
}


/**
 * 댓글 시트를 번호 순으로 정렬하고 최종 서식을 적용합니다.
 */
function finalizeCommentsSheet_(sheet) {
  sortCommentsByDisplayNumber_(sheet);
  formatCommentsSheet_(sheet);
}


function sortCommentsByDisplayNumber_(sheet) {
  const lastRow = sheet.getLastRow();

  if (lastRow <= 2) {
    return;
  }

  // 정렬용 임시 열 I, J를 만든 뒤 최상위 번호와 답글 번호로 정렬합니다.
  ensureColumnCount_(sheet, 10);

  const numberValues = sheet
    .getRange(2, 1, lastRow - 1, 1)
    .getDisplayValues();

  const sortKeys = numberValues.map(function(row) {
    const parts = String(row[0] || '').split('_');
    return [
      Number(parts[0] || 0),
      parts.length > 1 ? Number(parts[1] || 0) : 0
    ];
  });

  sheet
    .getRange(2, 9, sortKeys.length, 2)
    .setValues(sortKeys);

  sheet
    .getRange(2, 1, lastRow - 1, 10)
    .sort([
      { column: 9, ascending: true },
      { column: 10, ascending: true }
    ]);

  sheet.getRange(2, 9, lastRow - 1, 2).clearContent();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
}


function formatCommentsSheet_(sheet) {
  const lastRow = sheet.getLastRow();

  sheet.setFrozenRows(1);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setFontWeight('bold')
    .setWrap(true)
    .setVerticalAlignment('middle');

  sheet.getRange('A:A').setNumberFormat('@');

  if (lastRow > 1) {
    sheet
      .getRange(2, 7, lastRow - 1, 1)
      .setNumberFormat('yyyy-mm-dd hh:mm:ss');

    sheet
      .getRange(2, 5, lastRow - 1, 1)
      .setWrap(true)
      .setVerticalAlignment('top');

    sheet
      .getRange(2, 1, lastRow - 1, YT_CFG.HEADERS.length)
      .setVerticalAlignment('top');

    if (sheet.getFilter()) {
      sheet.getFilter().remove();
    }

    sheet
      .getRange(1, 1, lastRow, YT_CFG.HEADERS.length)
      .createFilter();
  }

  sheet.setColumnWidth(1, 90);
  sheet.setColumnWidth(2, 180);
  sheet.setColumnWidth(3, 260);
  sheet.setColumnWidth(4, 170);
  sheet.setColumnWidth(5, 520);
  sheet.setColumnWidth(6, 95);
  sheet.setColumnWidth(7, 155);
  sheet.setColumnWidth(8, 95);
}


/**
 * 숨김 내부 시트에 저장된 댓글 ID 집합을 만듭니다.
 */
function getExistingCommentIds_(internalSheet) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return new Set();
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .getDisplayValues();

  return new Set(
    values
      .map(function(row) {
        return row[0];
      })
      .filter(function(value) {
        return Boolean(value);
      })
  );
}


/**
 * 숨김 내부 시트 기준으로 실제 최상위 댓글·답글 수를 계산합니다.
 */
function getExistingCounts_(internalSheet) {
  const lastRow = internalSheet.getLastRow();
  const counts = { top: 0, reply: 0 };

  if (lastRow <= 1) {
    return counts;
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_TYPE, lastRow - 1, 1)
    .getDisplayValues();

  values.forEach(function(row) {
    if (row[0] === 'topLevel') {
      counts.top += 1;
    } else if (row[0] === 'reply') {
      counts.reply += 1;
    }
  });

  return counts;
}


/**
 * 댓글 글자수를 지정된 바이트 규칙으로 계산합니다.
 * - ASCII 영역(영문, 숫자, 공백, 일반 문장부호): 1바이트
 * - 한글을 포함한 비ASCII 유니코드 문자: 코드 포인트당 2바이트
 */
function calculateCommentBytes_(value) {
  const text = String(value || '');
  let bytes = 0;

  Array.from(text).forEach(function(character) {
    const codePoint = character.codePointAt(0);
    bytes += codePoint <= 0x7F ? 1 : 2;
  });

  return bytes;
}


/**
 * 외부 문자열이 시트 수식으로 실행되는 것을 방지합니다.
 */
function safeCellText_(value) {
  const text = value === undefined || value === null ? '' : String(value);
  return /^[=+\-@]/.test(text) ? "'" + text : text;
}


function apiDateToSheetValue_(value) {
  return value ? new Date(value) : '';
}


function ensureColumnCount_(sheet, requiredColumns) {
  const current = sheet.getMaxColumns();

  if (current < requiredColumns) {
    sheet.insertColumnsAfter(current, requiredColumns - current);
  }
}


function ensureExactColumnCount_(sheet, requiredColumns) {
  ensureColumnCount_(sheet, requiredColumns);

  const current = sheet.getMaxColumns();

  if (current > requiredColumns) {
    sheet.deleteColumns(requiredColumns + 1, current - requiredColumns);
  }
}


function getUserProperties_() {
  return PropertiesService.getUserProperties();
}


function getApiKey_() {
  const apiKey = getUserProperties_().getProperty(YT_CFG.API_KEY_PROP);

  if (!apiKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키 설정이 필요합니다.',
      '댓글 수집을 시작하기 전에 YouTube Data API 키를 저장해야 합니다.',
      ['현재 사용자 계정에 저장된 API 키가 없습니다.'],
      [
        '사이드바 상단의 API 키 입력란에 키를 입력합니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  return apiKey.trim();
}


function loadState_() {
  const text = getUserProperties_().getProperty(YT_CFG.STATE_PROP);
  return text ? JSON.parse(text) : null;
}


function saveState_(state) {
  state.updatedAt = new Date().toISOString();
  const text = JSON.stringify(state);
  const byteLength = Utilities.newBlob(text).getBytes().length;

  if (byteLength > 8500) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_STORAGE_LIMIT',
      '수집 진행 상태를 저장할 수 없습니다.',
      'Apps Script 사용자 속성의 안전 저장 크기를 초과했습니다.',
      ['진행 상태 데이터가 예상보다 커졌습니다.'],
      [
        '현재 수집을 취소합니다.',
        '댓글 수집 개수를 줄여 새로 실행합니다.'
      ],
      { actionLabel: '확인', technical: { byteLength: byteLength } }
    ));
  }

  getUserProperties_().setProperty(YT_CFG.STATE_PROP, text);
}


function loadLastResult_() {
  const text = getUserProperties_().getProperty(YT_CFG.LAST_RESULT_PROP);
  return text ? JSON.parse(text) : null;
}


function saveLastResult_(state, status, message, errorInfo) {
  const result = {
    status: status,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: Number(state.targetTopLevelCount || 0),
    topCount: Number(state.topCount || 0),
    replyCount: Number(state.replyCount || 0),
    apiCalls: Number(state.apiCalls || 0),
    startedAt: state.startedAt || '',
    updatedAt: new Date().toISOString(),
    finishedAt: new Date().toISOString(),
    message: message || '',
    error: errorInfo || null
  };

  getUserProperties_().setProperty(
    YT_CFG.LAST_RESULT_PROP,
    JSON.stringify(result)
  );
}


function validateStateVersion_(state) {
  if (Number(state.version || 0) !== YT_CFG.STATE_VERSION) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_VERSION_MISMATCH',
      '이전 코드에서 시작된 수집 작업을 이어갈 수 없습니다.',
      '현재 Code.gs의 댓글 저장 구조가 이전 실행 상태와 다릅니다.',
      ['고정 결과 시트 또는 정렬 기준을 사용하던 이전 코드의 작업 상태가 남아 있습니다.'],
      [
        '사이드바에서 진행 중인 수집을 취소합니다.',
        '현재 코드로 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }
}


function normalizeState_(state) {
  state.currentReplyParentId = state.currentReplyParentId || '';
  state.nextReplyPageToken = state.nextReplyPageToken || '';
  state.nextThreadPageToken = state.nextThreadPageToken || '';
  state.threadDone = Boolean(state.threadDone);
  state.topCount = Number(state.topCount || 0);
  state.replyCount = Number(state.replyCount || 0);
  state.apiCalls = Number(state.apiCalls || 0);
  state.threadPages = Number(state.threadPages || 0);
  state.replyPages = Number(state.replyPages || 0);
  state.targetTopLevelCount = Number(state.targetTopLevelCount || 0);
  state.outputSheetId = Number(state.outputSheetId || 0);
  state.outputSheetName = String(state.outputSheetName || '');
  state.error = state.error || null;
}


function maskApiKey_(apiKey) {
  const key = String(apiKey || '');
  return '••••••••••••' + key.slice(-4);
}


function buildProgressForClient_(state, status) {
  const target = Number(state.targetTopLevelCount || 0);
  const top = Number(state.topCount || 0);
  const reply = Number(state.replyCount || 0);
  const percent = target > 0
    ? Math.min(100, Math.round((top / target) * 100))
    : 0;

  let stage = '대기 중';

  if (status === 'RUNNING') {
    if (state.currentReplyParentId) {
      stage = '답글 수집 중';
    } else if (!state.threadDone) {
      stage = '최상위 댓글 수집 중';
    } else {
      stage = '마무리 중';
    }
  } else if (status === 'COMPLETED') {
    stage = '완료';
  } else if (status === 'ERROR') {
    stage = '오류';
  } else if (status === 'CANCELLED') {
    stage = '취소됨';
  }

  return {
    status: status,
    stage: stage,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: target,
    topCount: top,
    replyCount: reply,
    totalRows: top + reply,
    apiCalls: Number(state.apiCalls || 0),
    percent: percent,
    startedAt: state.startedAt || '',
    updatedAt: state.updatedAt || '',
    message: state.message || '',
    error: state.error || null
  };
}


function buildServerProgressMessage_(state) {
  return (
    '최상위 댓글 ' +
    state.topCount +
    '/' +
    state.targetTopLevelCount +
    '개, 답글 ' +
    state.replyCount +
    '개를 저장했습니다.'
  );
}


function scheduleContinuation_() {
  deleteContinuationTriggers_();

  ScriptApp
    .newTrigger(YT_CFG.CONTINUE_HANDLER)
    .timeBased()
    .after(YT_CFG.CONTINUE_AFTER_MS)
    .create();
}


function deleteContinuationTriggers_() {
  ScriptApp.getProjectTriggers().forEach(function(trigger) {
    if (trigger.getHandlerFunction() === YT_CFG.CONTINUE_HANDLER) {
      ScriptApp.deleteTrigger(trigger);
    }
  });
}


/**
 * 한국어 모달용 오류 정보를 만듭니다.
 */
function buildErrorInfo_(code, title, summary, causes, steps, options) {
  const opts = options || {};

  return {
    code: String(code || 'UNKNOWN_ERROR'),
    title: String(title || '작업을 완료하지 못했습니다.'),
    summary: String(summary || '처리 중 문제가 발생했습니다.'),
    causes: Array.isArray(causes) ? causes.map(String) : [],
    steps: Array.isArray(steps) ? steps.map(String) : [],
    helpLabel: String(opts.helpLabel || ''),
    helpUrl: String(opts.helpUrl || ''),
    focusTarget: String(opts.focusTarget || ''),
    actionLabel: String(opts.actionLabel || '확인'),
    technical:
      opts.technical && typeof opts.technical === 'object'
        ? opts.technical
        : {}
  };
}


/**
 * 서버 오류를 Sidebar.html이 해석할 수 있는 구조화된 예외로 전달합니다.
 */
function throwStructuredError_(errorInfo) {
  throw new Error(
    YT_CFG.STRUCTURED_ERROR_PREFIX + JSON.stringify(errorInfo)
  );
}


function extractStructuredError_(rawText) {
  const raw = String(rawText || '');
  const markerIndex = raw.indexOf(YT_CFG.STRUCTURED_ERROR_PREFIX);

  if (markerIndex < 0) {
    return null;
  }

  const jsonText = raw.slice(
    markerIndex + YT_CFG.STRUCTURED_ERROR_PREFIX.length
  );

  try {
    return JSON.parse(jsonText);
  } catch (parseError) {
    return null;
  }
}


/**
 * Apps Script 자체 오류도 한국어 모달 정보로 변환합니다.
 */
function normalizeErrorInfo_(error, context) {
  const raw = error && error.message
    ? String(error.message)
    : String(error || '');

  const structured = extractStructuredError_(raw);

  if (structured) {
    return structured;
  }

  const lower = raw.toLowerCase();
  const technical = {
    context: String(context || '작업 실행'),
    originalMessage: raw
  };

  if (
    lower.indexOf('authorization is required') >= 0 ||
    lower.indexOf('you do not have permission') >= 0 ||
    lower.indexOf('permissions') >= 0 && lower.indexOf('required') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_AUTH_REQUIRED',
      'Google 권한 승인이 필요합니다.',
      '현재 계정이 스프레드시트 또는 외부 API 요청 권한을 아직 승인하지 않았습니다.',
      ['Apps Script를 처음 실행했거나 새로운 권한이 추가되었습니다.'],
      [
        '스프레드시트 메뉴에서 사이드바를 다시 엽니다.',
        '권한 검토 화면에서 현재 Google 계정을 선택합니다.',
        '요청되는 권한을 허용한 뒤 다시 실행합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('maximum execution time') >= 0 ||
    lower.indexOf('exceeded maximum execution time') >= 0 ||
    lower.indexOf('timed out') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_EXECUTION_TIMEOUT',
      '한 번의 실행 가능 시간을 초과했습니다.',
      '댓글 또는 답글 처리 시간이 길어 현재 실행 구간이 종료되었습니다.',
      ['대량 댓글 수집으로 한 번의 Apps Script 실행 시간이 길어졌습니다.'],
      [
        '사이드바를 다시 열어 진행 상태를 확인합니다.',
        '멈춘 경우 ‘중단 지점부터 실행’을 한 번 실행합니다.',
        '같은 문제가 반복되면 수집 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('service invoked too many times') >= 0 ||
    lower.indexOf('quota') >= 0 && lower.indexOf('apps script') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_SERVICE_QUOTA',
      'Apps Script 서비스 사용 한도를 초과했습니다.',
      '현재 Google 계정 또는 스크립트의 일일 서비스 사용량이 허용 범위를 넘었습니다.',
      ['짧은 시간에 많은 외부 요청이나 스프레드시트 쓰기 작업이 실행되었습니다.'],
      [
        '잠시 뒤 다시 실행합니다.',
        '같은 날 반복되면 다음 날 다시 실행합니다.',
        '한 번에 수집하는 댓글 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  return buildErrorInfo_(
    'UNEXPECTED_ERROR',
    '예상하지 못한 오류가 발생했습니다.',
    '오류 유형을 자동으로 판별하지 못했습니다.',
    [
      '네트워크, 권한, Google 서비스 상태 또는 실행 환경에서 문제가 발생했을 수 있습니다.'
    ],
    [
      '사이드바를 닫았다가 다시 열고 같은 작업을 한 번 더 실행합니다.',
      'Apps Script 편집기의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.',
      'API 키와 영상 주소를 다시 확인합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}

Sidebar.html

YouTube 댓글 수집기

YouTube Data API v3 → Google Sheets

1. API 키

YouTube Data API 키

최초 1회 저장합니다. 키는 사용자별 Apps Script 속성에 보관됩니다.

2. 수집 설정

API 키를 저장하면 수집 설정이 활성화됩니다.

YouTube 영상 주소

수집할 최상위 댓글 수

1~50,000개. 답글 포함 시 실제 저장 행 수가 이 값보다 많아질 수 있습니다.

대댓글도 모두 수집

새 수집을 시작할 때마다 ‘시트1’, ‘시트2’, ‘시트3’ 형식의 새 시트가 생성됩니다. 기존 수집 결과는 유지됩니다.

Youtube Data API v3 KEY

AIzaSyDETqF5gzbFh3DG4U0N-rjT1yK2asM-1X4

2026년 인공지능 활용 선도교사 연수 (충남 천안 - 8.2.)

Sun, 02 Aug 2026 05:08:25 GMT

2026년 인공지능 활용 선도교사 연수 (충남 천안 - 8.2.)

강사: 교사 김민기(민기쌤)
일시: 2026-08-02
장소: 천안 신라스테이

(1) 음성 데이터

(2) 댓글 데이터

Code.gs

const YT_CFG = Object.freeze({
  API_BASE: 'https://www.googleapis.com/youtube/v3',

  API_KEY_PROP: 'YT_API_KEY',
  STATE_PROP: 'YT_COMMENT_COLLECTOR_STATE',
  LAST_RESULT_PROP: 'YT_COMMENT_COLLECTOR_LAST_RESULT',
  CANCEL_REQUEST_PROP: 'YT_COMMENT_COLLECTOR_CANCEL_REQUEST',

  OUTPUT_SHEET_PREFIX: '시트',
  INTERNAL_SHEET: '_댓글수집_내부',
  LEGACY_LOG_SHEET: '수집로그',

  CONTINUE_HANDLER: 'continueCommentCollection',
  STRUCTURED_ERROR_PREFIX: 'YT_STRUCTURED_ERROR::',
  STATE_VERSION: 4,

  // Apps Script의 일반 실행 제한 전에 상태를 저장하고 다음 실행으로 넘깁니다.
  MAX_RUN_MS: 4 * 60 * 1000 + 30 * 1000,
  CONTINUE_AFTER_MS: 60 * 1000,

  MIN_LIMIT: 1,
  MAX_LIMIT: 50000,

  HEADERS: [
    '번호',
    '채널명',
    '영상 제목',
    '댓글 작성자',
    '댓글 내용',
    '좋아요 수',
    '작성 시각',
    '글자수'
  ],

  // 숨김 내부 시트의 열 구조입니다.
  INTERNAL_HEADERS: [
    'comment_id',
    'parent_comment_id',
    'display_number',
    'comment_type',
    'reply_status',
    'next_reply_index',
    'total_reply_count',
    'reply_page_token'
  ],

  INTERNAL_COL: Object.freeze({
    COMMENT_ID: 1,
    PARENT_ID: 2,
    DISPLAY_NUMBER: 3,
    COMMENT_TYPE: 4,
    REPLY_STATUS: 5,
    NEXT_REPLY_INDEX: 6,
    TOTAL_REPLY_COUNT: 7,
    REPLY_PAGE_TOKEN: 8
  })
});


/**
 * 스프레드시트를 열 때 사용자 메뉴를 만듭니다.
 */
function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('YouTube 댓글 수집')
    .addItem('사이드바 열기', 'showYouTubeCommentSidebar')
    .addSeparator()
    .addItem('중단 지점부터 실행', 'continueCommentCollection')
    .addItem('진행 중인 수집 취소', 'cancelCommentCollection')
    .addToUi();
}


/**
 * 오른쪽 사이드바를 엽니다.
 */
function showYouTubeCommentSidebar() {
  const html = HtmlService
    .createHtmlOutputFromFile('Sidebar')
    .setTitle('YouTube 댓글 수집기');

  SpreadsheetApp.getUi().showSidebar(html);
}


/**
 * 사이드바 초기 상태를 반환합니다.
 */
function getSidebarState() {
  const props = getUserProperties_();
  const apiKey = props.getProperty(YT_CFG.API_KEY_PROP) || '';
  const activeState = loadState_();
  const lastResult = loadLastResult_();
  const cancelRequested =
    props.getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';

  const progress = activeState
    ? buildProgressForClient_(activeState, 'RUNNING')
    : lastResult
      ? buildProgressForClient_(lastResult, lastResult.status || 'COMPLETED')
      : null;

  if (progress && activeState && cancelRequested) {
    progress.stage = '취소 처리 중';
    progress.message = '현재 실행 구간이 끝나는 즉시 안전하게 중단됩니다.';
  }

  return {
    apiKeyConfigured: Boolean(apiKey),
    apiKeyMask: apiKey ? maskApiKey_(apiKey) : '',
    running: Boolean(activeState),
    cancelRequested: cancelRequested,
    progress: progress
  };
}


/**
 * API 키를 실제 YouTube Data API 요청으로 검증한 뒤 사용자별 속성에 저장합니다.
 */
function saveApiKey(apiKey) {
  const cleanedKey = String(apiKey || '').trim();

  if (!cleanedKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키를 입력해야 합니다.',
      'Google Cloud에서 발급한 YouTube Data API 키가 입력되지 않았습니다.',
      ['API 키 입력란이 비어 있습니다.'],
      [
        'Google Cloud Console에서 API 키를 발급합니다.',
        'API 키 전체를 사이드바 입력란에 붙여 넣습니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  if (cleanedKey.length < 20) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_FORMAT_INVALID',
      'API 키 형식을 확인해야 합니다.',
      '입력한 문자열이 일반적인 Google API 키 길이보다 짧습니다.',
      [
        'API 키 일부만 복사했을 수 있습니다.',
        '프로젝트 ID나 다른 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 값을 처음부터 끝까지 다시 복사하여 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력'
      }
    ));
  }

  validateApiKey_(cleanedKey);

  const props = getUserProperties_();
  props.setProperty(YT_CFG.API_KEY_PROP, cleanedKey);

  // 이전 API 키 오류 안내가 새 키 저장 뒤 다시 나타나지 않도록 정리합니다.
  const previous = loadLastResult_();
  if (previous && previous.status === 'ERROR') {
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
  }

  return getSidebarState();
}


/**
 * 저장된 API 키를 삭제합니다.
 */
function deleteApiKey() {
  if (loadState_()) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_DELETE_BLOCKED',
      '수집 중에는 API 키를 삭제할 수 없습니다.',
      '현재 댓글 수집 작업이 저장된 API 키를 사용하고 있습니다.',
      ['진행 중인 작업이 존재합니다.'],
      [
        '현재 수집을 완료하거나 취소합니다.',
        '수집 상태가 종료된 뒤 API 키를 삭제합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.API_KEY_PROP);
  props.deleteProperty(YT_CFG.LAST_RESULT_PROP);

  return getSidebarState();
}


/**
 * 사이드바 입력값으로 새 수집 작업을 준비합니다.
 * 실제 수집은 runCollectionNow 또는 시간 기반 트리거가 수행합니다.
 */
function startCollectionFromSidebar(formData) {
  const lock = LockService.getScriptLock();
  lock.waitLock(10000);

  try {
    const apiKey = getApiKey_();
    const input = normalizeSidebarInput_(formData);
    const ss = SpreadsheetApp.getActiveSpreadsheet();

    if (!ss) {
      throwStructuredError_(buildErrorInfo_(
        'SPREADSHEET_NOT_FOUND',
        '댓글을 저장할 스프레드시트를 찾지 못했습니다.',
        '현재 Apps Script가 스프레드시트와 연결된 상태인지 확인해야 합니다.',
        [
          '독립 실행형 Apps Script 프로젝트에서 코드를 실행했을 수 있습니다.',
          '스프레드시트가 닫히거나 접근 권한이 변경되었을 수 있습니다.'
        ],
        [
          '댓글을 저장할 Google 스프레드시트를 엽니다.',
          '‘확장 프로그램 → Apps Script’에서 이 코드를 실행합니다.',
          '스프레드시트를 새로고침하고 사이드바를 다시 엽니다.'
        ],
        { actionLabel: '확인' }
      ));
    }

    // 영상과 API 키가 정상인지 먼저 확인합니다.
    const videoId = extractVideoId_(input.videoUrl);
    const metadata = getVideoMetadataWithKey_(videoId, apiKey);

    deleteContinuationTriggers_();

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    // 새 수집은 기존 결과를 지우지 않고 새 결과 시트에 기록합니다.
    const outputSheet = createNextOutputSheet_(ss);
    ensureInternalSheet_(ss);
    resetInternalData_(ss);
    deleteLegacyLogSheet_(ss);

    const state = {
      version: YT_CFG.STATE_VERSION,
      status: 'RUNNING',
      spreadsheetId: ss.getId(),

      outputSheetId: outputSheet.getSheetId(),
      outputSheetName: outputSheet.getName(),

      videoId: videoId,
      videoTitle: metadata.title,
      videoChannelId: metadata.channelId,
      videoChannelTitle: metadata.channelTitle,
      reportedCommentCount: metadata.commentCount,

      targetTopLevelCount: input.limit,
      includeReplies: input.includeReplies,

      nextThreadPageToken: '',
      threadDone: false,

      currentReplyParentId: '',
      nextReplyPageToken: '',

      topCount: 0,
      replyCount: 0,
      threadPages: 0,
      replyPages: 0,
      apiCalls: 1,

      startedAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      message: outputSheet.getName() + '에서 수집을 시작했습니다.',
      error: null
    };

    saveState_(state);

    // 사이드바가 닫혀도 수집이 이어지도록 예비 트리거를 만듭니다.
    scheduleContinuation_();

    return getSidebarState();

  } finally {
    lock.releaseLock();
  }
}


/**
 * 사이드바가 첫 실행 구간을 즉시 시작할 때 호출합니다.
 */
function runCollectionNow() {
  continueCommentCollection();
  return getSidebarState();
}


/**
 * 저장된 상태에서 댓글 수집을 계속합니다.
 */
function continueCommentCollection() {
  const lock = LockService.getScriptLock();

  if (!lock.tryLock(5000)) {
    return;
  }

  let ss = null;
  let state = null;
  let commentsSheet = null;

  try {
    state = loadState_();

    if (!state) {
      return;
    }

    validateStateVersion_(state);
    normalizeState_(state);

    ss = SpreadsheetApp.openById(state.spreadsheetId);
    ensureInternalSheet_(ss);
    deleteLegacyLogSheet_(ss);

    commentsSheet = getOutputSheetForState_(ss, state);
    const internalSheet = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);
    const existingIds = getExistingCommentIds_(internalSheet);
    const existingCounts = getExistingCounts_(internalSheet);

    // 시트 기록 직후 상태 저장 전에 실행이 끊긴 상황을 보정합니다.
    state.topCount = existingCounts.top;
    state.replyCount = existingCounts.reply;

    const runStartedAt = Date.now();

    while (Date.now() - runStartedAt < YT_CFG.MAX_RUN_MS) {
      if (isCancelRequested_()) {
        finalizeCancellation_(ss, commentsSheet, state);
        return;
      }

      // 처리 중이던 답글 페이지가 있으면 먼저 이어서 처리합니다.
      if (state.currentReplyParentId) {
        processReplyPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      // 내부 시트에서 답글 수집이 필요한 최상위 댓글을 하나 선택합니다.
      const pendingReply = claimNextPendingReply_(internalSheet);

      if (pendingReply) {
        state.currentReplyParentId = pendingReply.commentId;
        state.nextReplyPageToken = pendingReply.pageToken || '';
        saveState_(state);
        continue;
      }

      // 답글 대기 항목이 없을 때 다음 최상위 댓글 페이지를 가져옵니다.
      if (!state.threadDone) {
        processThreadPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      finishCollection_(ss, commentsSheet, state);
      return;
    }

    state.updatedAt = new Date().toISOString();
    state.message = '실행 시간을 고려하여 진행 상태를 저장했습니다.';
    saveState_(state);
    scheduleContinuation_();

  } catch (error) {
    deleteContinuationTriggers_();

    const errorInfo = normalizeErrorInfo_(error, '댓글 수집');

    if (errorInfo.code === 'API_KEY_INVALID') {
      getUserProperties_().deleteProperty(YT_CFG.API_KEY_PROP);
    }

    if (commentsSheet) {
      try {
        finalizeCommentsSheet_(commentsSheet);
      } catch (formatError) {
        console.error(formatError);
      }
    }

    if (state) {
      state.status = 'ERROR';
      state.updatedAt = new Date().toISOString();
      state.message = errorInfo.summary;
      state.error = errorInfo;
      saveLastResult_(state, 'ERROR', errorInfo.summary, errorInfo);
    }

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    console.error(error);
    throwStructuredError_(errorInfo);

  } finally {
    lock.releaseLock();
  }
}


/**
 * 진행 중인 수집을 취소합니다.
 */
function cancelCommentCollection() {
  const props = getUserProperties_();
  const state = loadState_();

  if (!state) {
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
    deleteContinuationTriggers_();
    return getSidebarState();
  }

  props.setProperty(YT_CFG.CANCEL_REQUEST_PROP, 'true');
  deleteContinuationTriggers_();

  const lock = LockService.getScriptLock();

  // 다른 수집 실행이 없다면 이 호출에서 즉시 취소를 마무리합니다.
  if (lock.tryLock(200)) {
    try {
      const latestState = loadState_();

      if (latestState) {
        const ss = SpreadsheetApp.openById(latestState.spreadsheetId);
        ensureInternalSheet_(ss);
        const commentsSheet = getOutputSheetForState_(ss, latestState);
        finalizeCancellation_(ss, commentsSheet, latestState);
      }
    } finally {
      lock.releaseLock();
    }
  }

  return getSidebarState();
}


/**
 * 최상위 댓글 스레드 한 페이지를 처리합니다.
 */
function processThreadPage_(state, commentsSheet, internalSheet, existingIds) {
  const remaining = state.targetTopLevelCount - state.topCount;

  if (remaining <= 0) {
    state.threadDone = true;
    state.nextThreadPageToken = '';
    return;
  }

  const params = {
    part: state.includeReplies ? 'snippet,replies' : 'snippet',
    videoId: state.videoId,
    maxResults: Math.min(100, remaining),
    textFormat: 'plainText'
  };

  if (state.nextThreadPageToken) {
    params.pageToken = state.nextThreadPageToken;
  }

  const data = youtubeGet_('commentThreads', params);

  state.apiCalls += 1;
  state.threadPages += 1;

  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();
  const items = Array.isArray(data.items) ? data.items : [];

  let topAdded = 0;
  let replyAdded = 0;
  let nextTopNumber = state.topCount + 1;

  items.forEach(function(thread) {
    if (state.topCount + topAdded >= state.targetTopLevelCount) {
      return;
    }

    const threadSnippet = thread.snippet || {};
    const topComment = threadSnippet.topLevelComment;

    if (!topComment || !topComment.id) {
      return;
    }

    const topCommentId = String(topComment.id);

    if (existingIds.has(topCommentId) || batchIds.has(topCommentId)) {
      return;
    }

    const topNumber = String(nextTopNumber);
    nextTopNumber += 1;

    const totalReplyCount = Number(threadSnippet.totalReplyCount || 0);
    let replyStatus = 'DONE';
    let nextReplyIndex = 1;

    commentRows.push(
      commentToOutputRow_(state, topComment, topNumber)
    );

    batchIds.add(topCommentId);
    topAdded += 1;

    const inlineReplies =
      thread.replies && Array.isArray(thread.replies.comments)
        ? thread.replies.comments
        : [];

    if (state.includeReplies && totalReplyCount > 0) {
      if (inlineReplies.length === totalReplyCount) {
        inlineReplies.forEach(function(reply) {
          if (!reply || !reply.id) {
            return;
          }

          const replyId = String(reply.id);

          if (existingIds.has(replyId) || batchIds.has(replyId)) {
            return;
          }

          const displayNumber = topNumber + '_' + nextReplyIndex;
          nextReplyIndex += 1;

          commentRows.push(
            commentToOutputRow_(state, reply, displayNumber)
          );

          internalRows.push(
            buildInternalRow_(
              replyId,
              topCommentId,
              displayNumber,
              'reply',
              '',
              '',
              '',
              ''
            )
          );

          batchIds.add(replyId);
          replyAdded += 1;
        });
      } else {
        // commentThreads.list의 replies에는 전체 답글이 보장되지 않으므로
        // comments.list로 전체 답글을 다시 가져옵니다.
        replyStatus = 'PENDING';
        nextReplyIndex = 1;
      }
    }

    internalRows.push(
      buildInternalRow_(
        topCommentId,
        '',
        topNumber,
        'topLevel',
        replyStatus,
        nextReplyIndex,
        totalReplyCount,
        ''
      )
    );
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.topCount += topAdded;
  state.replyCount += replyAdded;

  const reachedTarget = state.topCount >= state.targetTopLevelCount;
  const hasNextPage = Boolean(data.nextPageToken);

  state.nextThreadPageToken =
    !reachedTarget && hasNextPage
      ? data.nextPageToken
      : '';

  state.threadDone = reachedTarget || !hasNextPage;
  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 특정 최상위 댓글의 답글 한 페이지를 처리합니다.
 */
function processReplyPage_(state, commentsSheet, internalSheet, existingIds) {
  const topRecord = findInternalRecordByCommentId_(
    internalSheet,
    state.currentReplyParentId
  );

  if (!topRecord) {
    // 내부 상태가 사라진 경우 현재 항목을 건너뛰고 다음 대기 항목을 찾습니다.
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
    return;
  }

  const params = {
    part: 'snippet',
    parentId: state.currentReplyParentId,
    maxResults: 100,
    textFormat: 'plainText'
  };

  const pageToken =
    state.nextReplyPageToken || topRecord.replyPageToken || '';

  if (pageToken) {
    params.pageToken = pageToken;
  }

  const data = youtubeGet_('comments', params);

  state.apiCalls += 1;
  state.replyPages += 1;

  const items = Array.isArray(data.items) ? data.items : [];
  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();

  let nextReplyIndex = Number(topRecord.nextReplyIndex || 1);
  let replyAdded = 0;

  items.forEach(function(reply) {
    if (!reply || !reply.id) {
      return;
    }

    const replyId = String(reply.id);

    if (existingIds.has(replyId) || batchIds.has(replyId)) {
      return;
    }

    const displayNumber =
      String(topRecord.displayNumber) + '_' + nextReplyIndex;

    nextReplyIndex += 1;

    commentRows.push(
      commentToOutputRow_(state, reply, displayNumber)
    );

    internalRows.push(
      buildInternalRow_(
        replyId,
        state.currentReplyParentId,
        displayNumber,
        'reply',
        '',
        '',
        '',
        ''
      )
    );

    batchIds.add(replyId);
    replyAdded += 1;
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.replyCount += replyAdded;

  const nextPageToken = data.nextPageToken || '';
  const nextStatus = nextPageToken ? 'IN_PROGRESS' : 'DONE';

  updateTopReplyProgress_(
    internalSheet,
    topRecord.rowNumber,
    nextStatus,
    nextReplyIndex,
    nextPageToken
  );

  if (nextPageToken) {
    state.nextReplyPageToken = nextPageToken;
  } else {
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
  }

  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 내부 시트에서 답글 수집 대기 중인 최상위 댓글 하나를 선택합니다.
 */
function claimNextPendingReply_(internalSheet) {
  const statusRange = internalSheet.getRange(
    2,
    YT_CFG.INTERNAL_COL.REPLY_STATUS,
    Math.max(internalSheet.getLastRow() - 1, 1),
    1
  );

  let found = statusRange
    .createTextFinder('IN_PROGRESS')
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    found = statusRange
      .createTextFinder('PENDING')
      .matchEntireCell(true)
      .useRegularExpression(false)
      .findNext();
  }

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  if (values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] === 'PENDING') {
    internalSheet
      .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS)
      .setValue('IN_PROGRESS');
  }

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    pageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 댓글 1건을 사용자가 보는 8열 행으로 변환합니다.
 */
function commentToOutputRow_(state, comment, displayNumber) {
  const snippet = (comment && comment.snippet) || {};
  const text = String(snippet.textDisplay || '');

  return [
    String(displayNumber),
    safeCellText_(state.videoChannelTitle || ''),
    safeCellText_(state.videoTitle || ''),
    safeCellText_(snippet.authorDisplayName || ''),
    safeCellText_(text),
    Number(snippet.likeCount || 0),
    apiDateToSheetValue_(snippet.publishedAt),
    calculateCommentBytes_(text)
  ];
}


/**
 * 숨김 내부 시트의 행을 만듭니다.
 */
function buildInternalRow_(
  commentId,
  parentCommentId,
  displayNumber,
  commentType,
  replyStatus,
  nextReplyIndex,
  totalReplyCount,
  replyPageToken
) {
  return [
    safeCellText_(commentId || ''),
    safeCellText_(parentCommentId || ''),
    String(displayNumber || ''),
    String(commentType || ''),
    String(replyStatus || ''),
    nextReplyIndex === '' ? '' : Number(nextReplyIndex || 1),
    totalReplyCount === '' ? '' : Number(totalReplyCount || 0),
    safeCellText_(replyPageToken || '')
  ];
}


/**
 * 댓글 행과 내부 관리 행을 각각 일괄 기록합니다.
 */
function appendCollectedRecords_(
  commentsSheet,
  internalSheet,
  commentRows,
  internalRows
) {
  if (commentRows.length !== internalRows.length) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_ROW_MISMATCH',
      '댓글 저장 구조를 확인해야 합니다.',
      '댓글 행과 내부 관리 행의 개수가 일치하지 않습니다.',
      ['수집 상태를 기록하는 내부 데이터가 일시적으로 어긋났습니다.'],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  if (commentRows.length === 0) {
    return;
  }

  commentsSheet
    .getRange(
      commentsSheet.getLastRow() + 1,
      1,
      commentRows.length,
      YT_CFG.HEADERS.length
    )
    .setValues(commentRows);

  internalSheet
    .getRange(
      internalSheet.getLastRow() + 1,
      1,
      internalRows.length,
      YT_CFG.INTERNAL_HEADERS.length
    )
    .setValues(internalRows);
}


/**
 * 내부 시트에서 특정 댓글 ID의 관리 행을 찾습니다.
 */
function findInternalRecordByCommentId_(internalSheet, commentId) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return null;
  }

  const found = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .createTextFinder(String(commentId || ''))
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    replyStatus: String(
      values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    replyPageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 최상위 댓글의 답글 수집 진행 정보를 갱신합니다.
 */
function updateTopReplyProgress_(
  internalSheet,
  rowNumber,
  status,
  nextReplyIndex,
  pageToken
) {
  internalSheet
    .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS, 1, 4)
    .setValues([[
      status,
      Number(nextReplyIndex || 1),
      internalSheet
        .getRange(rowNumber, YT_CFG.INTERNAL_COL.TOTAL_REPLY_COUNT)
        .getValue(),
      pageToken || ''
    ]]);
}


/**
 * 완료 처리
 */
function finishCollection_(ss, commentsSheet, state) {
  state.status = 'COMPLETED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = state.topCount < state.targetTopLevelCount
    ? '댓글 ' +
      state.topCount +
      '개와 대댓글 ' +
      state.replyCount +
      '개를 수집했습니다.'
    : '댓글 수집을 완료했습니다.';
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'COMPLETED', state.message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


function isCancelRequested_() {
  return getUserProperties_().getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';
}


/**
 * 취소 처리
 */
function finalizeCancellation_(ss, commentsSheet, state) {
  const message = '사용자가 수집을 취소했습니다. 이미 저장된 댓글은 유지됩니다.';

  state.status = 'CANCELLED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = message;
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'CANCELLED', message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


/**
 * API 키가 YouTube Data API 요청에 사용 가능한지 확인합니다.
 */
function validateApiKey_(apiKey) {
  youtubeGetWithKey_(
    'videos',
    {
      part: 'id',
      id: 'jNQXAC9IVRw'
    },
    apiKey
  );
}


/**
 * 영상 메타데이터를 조회합니다.
 */
function getVideoMetadataWithKey_(videoId, apiKey) {
  const data = youtubeGetWithKey_(
    'videos',
    {
      part: 'snippet,statistics',
      id: videoId
    },
    apiKey
  );

  if (!Array.isArray(data.items) || data.items.length === 0) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '입력한 영상 주소에 해당하는 공개 영상을 YouTube Data API에서 조회하지 못했습니다.',
      [
        '영상 주소나 11자리 영상 ID가 정확하지 않을 수 있습니다.',
        '영상이 삭제되었거나 비공개 상태일 수 있습니다.',
        '연령·지역·계정 권한에 따라 접근이 제한된 영상일 수 있습니다.'
      ],
      [
        '브라우저에서 해당 영상 주소가 정상적으로 열리는지 확인합니다.',
        '주소 표시줄의 영상 URL 전체를 다시 복사합니다.',
        '사이드바의 영상 주소를 교체한 뒤 수집을 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: { videoId: videoId }
      }
    ));
  }

  const item = data.items[0];
  const snippet = item.snippet || {};
  const statistics = item.statistics || {};

  return {
    title: snippet.title || '',
    channelId: snippet.channelId || '',
    channelTitle: snippet.channelTitle || '',
    commentCount: statistics.commentCount || ''
  };
}


/**
 * 저장된 API 키로 YouTube Data API를 호출합니다.
 */
function youtubeGet_(resource, params) {
  return youtubeGetWithKey_(resource, params, getApiKey_());
}


/**
 * YouTube Data API GET 요청을 수행합니다.
 */
function youtubeGetWithKey_(resource, params, apiKey) {
  const queryParams = Object.assign({}, params, { key: apiKey });

  const query = Object.keys(queryParams)
    .filter(function(key) {
      const value = queryParams[key];
      return value !== undefined && value !== null && value !== '';
    })
    .map(function(key) {
      return encodeURIComponent(key) + '=' + encodeURIComponent(queryParams[key]);
    })
    .join('&');

  const url = YT_CFG.API_BASE + '/' + resource + '?' + query;
  const transientCodes = [429, 500, 502, 503, 504];

  for (let attempt = 0; attempt < 3; attempt += 1) {
    let response;

    try {
      response = UrlFetchApp.fetch(url, {
        method: 'get',
        muteHttpExceptions: true,
        headers: { Accept: 'application/json' }
      });
    } catch (networkError) {
      if (attempt < 2) {
        Utilities.sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      throwStructuredError_(buildErrorInfo_(
        'NETWORK_REQUEST_FAILED',
        'YouTube 서버에 연결하지 못했습니다.',
        'Apps Script에서 YouTube Data API로 보내는 외부 요청이 완료되지 않았습니다.',
        [
          'Google 서비스 또는 네트워크에 일시적인 장애가 발생했을 수 있습니다.',
          'Apps Script의 외부 요청 권한이 승인되지 않았을 수 있습니다.'
        ],
        [
          '잠시 뒤 같은 작업을 다시 실행합니다.',
          'Apps Script 권한 승인 화면이 나타나면 요청된 권한을 허용합니다.',
          'Apps Script의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.'
        ],
        {
          actionLabel: '확인',
          technical: {
            resource: resource,
            originalMessage: String(networkError && networkError.message || networkError)
          }
        }
      ));
    }

    const statusCode = response.getResponseCode();
    const responseText = response.getContentText();

    if (statusCode >= 200 && statusCode < 300) {
      return responseText ? JSON.parse(responseText) : {};
    }

    if (transientCodes.indexOf(statusCode) >= 0 && attempt < 2) {
      Utilities.sleep(Math.pow(2, attempt) * 1000);
      continue;
    }

    const parsedError = parseYouTubeErrorResponse_(responseText);

    throwStructuredError_(classifyYouTubeApiError_(
      statusCode,
      parsedError.reason,
      parsedError.message,
      resource
    ));
  }

  throwStructuredError_(buildErrorInfo_(
    'YOUTUBE_REQUEST_REPEATED_FAILURE',
    'YouTube API 요청이 반복적으로 실패했습니다.',
    '일시적인 서버 장애가 재시도 후에도 계속되었습니다.',
    ['YouTube 또는 Google 네트워크 서비스가 불안정할 수 있습니다.'],
    [
      '잠시 뒤 같은 작업을 다시 실행합니다.',
      '반복되면 Apps Script의 ‘실행’ 기록을 확인합니다.'
    ],
    { actionLabel: '확인', technical: { resource: resource } }
  ));
}


function parseYouTubeErrorResponse_(responseText) {
  let reason = '';
  let message = String(responseText || '');

  try {
    const parsed = JSON.parse(responseText);

    if (parsed.error) {
      message = parsed.error.message || message;

      if (Array.isArray(parsed.error.errors) && parsed.error.errors[0]) {
        reason = parsed.error.errors[0].reason || '';
      }

      if (!reason && parsed.error.status) {
        reason = parsed.error.status;
      }
    }
  } catch (parseError) {
    // JSON이 아닌 오류 본문은 문자열 그대로 분류합니다.
  }

  return {
    reason: String(reason || ''),
    message: String(message || '')
  };
}


/**
 * YouTube API 오류를 한국어 모달용 정보로 분류합니다.
 */
function classifyYouTubeApiError_(statusCode, reason, message, resource) {
  const reasonText = String(reason || '');
  const messageText = String(message || '');
  const combined = (reasonText + ' ' + messageText).toLowerCase();
  const technical = {
    httpStatus: statusCode,
    apiReason: reasonText,
    resource: resource,
    originalMessage: messageText
  };

  if (
    combined.indexOf('keyinvalid') >= 0 ||
    combined.indexOf('api key not valid') >= 0 ||
    combined.indexOf('api_key_invalid') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_INVALID',
      'API 키를 사용할 수 없습니다.',
      '입력한 API 키가 정확하지 않거나 삭제·재발급되어 현재 요청에 사용할 수 없습니다.',
      [
        'API 키 일부가 누락되었을 수 있습니다.',
        'Google Cloud에서 기존 키가 삭제되거나 재발급되었을 수 있습니다.',
        'API 키가 아닌 다른 프로젝트 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 전체를 다시 복사합니다.',
        '사이드바에서 API 키를 다시 입력하고 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') >= 0 ||
    combined.indexOf('access not configured') >= 0 ||
    combined.indexOf('service_disabled') >= 0 ||
    combined.indexOf('api_disabled') >= 0 ||
    combined.indexOf('has not been used in project') >= 0 ||
    combined.indexOf('it is disabled') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_API_NOT_ENABLED',
      'YouTube Data API v3가 활성화되어 있지 않습니다.',
      'API 키가 속한 Google Cloud 프로젝트에서 YouTube Data API v3 사용 설정을 켜야 합니다.',
      [
        'API 키를 만든 프로젝트에서 YouTube Data API v3를 아직 활성화하지 않았습니다.',
        'API를 활성화한 프로젝트와 API 키를 발급한 프로젝트가 다를 수 있습니다.'
      ],
      [
        'Google Cloud Console에서 API 키를 만든 프로젝트를 선택합니다.',
        '‘API 및 서비스 → 라이브러리’로 이동합니다.',
        '‘YouTube Data API v3’를 검색하고 ‘사용’을 누릅니다.',
        '설정 반영을 위해 1~5분 기다린 뒤 API 키를 다시 저장합니다.'
      ],
      {
        helpLabel: 'YouTube Data API 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/library/youtube.googleapis.com',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('iprefererblocked') >= 0 ||
    combined.indexOf('referer') >= 0 && combined.indexOf('blocked') >= 0 ||
    combined.indexOf('api key restrictions') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_APPLICATION_RESTRICTION',
      'API 키의 애플리케이션 제한이 Apps Script 요청을 차단했습니다.',
      '현재 키에 설정된 웹사이트·IP 제한이 Apps Script의 UrlFetch 요청 방식과 맞지 않습니다.',
      [
        'HTTP 리퍼러 제한 또는 특정 IP 주소 제한이 적용되어 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키의 애플리케이션 제한을 확인합니다.',
        'Apps Script에서 사용할 수 있는 제한 방식으로 조정합니다.',
        'API 제한은 ‘YouTube Data API v3’로 유지합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') < 0 &&
    (
      combined.indexOf('forbidden') >= 0 &&
      combined.indexOf('api') >= 0 &&
      combined.indexOf('key') >= 0
    )
  ) {
    return buildErrorInfo_(
      'API_KEY_API_RESTRICTION',
      'API 키의 API 제한 설정을 확인해야 합니다.',
      '현재 API 키가 YouTube Data API v3 호출을 허용하지 않을 수 있습니다.',
      [
        'API 키의 ‘API 제한’ 목록에서 YouTube Data API v3가 빠져 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키를 선택합니다.',
        '‘API 제한’에서 YouTube Data API v3를 허용합니다.',
        '저장 후 1~5분 뒤 다시 실행합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('quotaexceeded') >= 0 ||
    combined.indexOf('dailylimitexceeded') >= 0 ||
    combined.indexOf('daily limit') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_QUOTA_EXCEEDED',
      'YouTube API의 오늘 할당량을 모두 사용했습니다.',
      '현재 Google Cloud 프로젝트에서 오늘 사용할 수 있는 YouTube Data API 할당량이 남아 있지 않습니다.',
      ['같은 프로젝트의 다른 프로그램에서도 YouTube API 할당량을 사용했을 수 있습니다.'],
      [
        'Google Cloud Console에서 YouTube Data API 사용량을 확인합니다.',
        '일일 할당량이 갱신된 뒤 다시 실행합니다.',
        '필요하면 다음 수집의 댓글 개수를 줄입니다.'
      ],
      {
        helpLabel: 'YouTube API 할당량 열기',
        helpUrl: 'https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas',
        actionLabel: '확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('ratelimitexceeded') >= 0 ||
    combined.indexOf('userratelimitexceeded') >= 0 ||
    statusCode === 429
  ) {
    return buildErrorInfo_(
      'YOUTUBE_RATE_LIMIT',
      '짧은 시간에 API 요청이 많이 발생했습니다.',
      'YouTube Data API가 일시적으로 요청 속도를 제한했습니다.',
      ['여러 수집 작업을 연속으로 실행했을 수 있습니다.'],
      [
        '현재 작업이 자동 재개되는지 확인합니다.',
        '몇 분 뒤 다시 실행합니다.',
        '동시에 여러 스프레드시트에서 같은 API 키를 사용하고 있다면 실행 횟수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (combined.indexOf('commentsdisabled') >= 0) {
    return buildErrorInfo_(
      'COMMENTS_DISABLED',
      '이 영상에서는 댓글을 수집할 수 없습니다.',
      '영상 게시자가 댓글 기능을 사용하지 않도록 설정했습니다.',
      ['영상의 댓글 기능이 꺼져 있거나 YouTube 정책에 따라 제한되었습니다.'],
      [
        '영상 페이지에서 댓글 영역이 표시되는지 확인합니다.',
        '댓글이 허용된 다른 영상 주소를 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('videonotfound') >= 0 ||
    combined.indexOf('video not found') >= 0
  ) {
    return buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '영상 주소가 잘못되었거나 영상이 삭제·비공개 상태일 수 있습니다.',
      [
        '영상 ID가 정확하지 않을 수 있습니다.',
        '영상 공개 상태가 변경되었을 수 있습니다.'
      ],
      [
        '브라우저에서 영상 주소가 정상적으로 열리는지 확인합니다.',
        '영상 URL 전체를 다시 복사해 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (statusCode >= 500) {
    return buildErrorInfo_(
      'YOUTUBE_SERVER_ERROR',
      'YouTube 서버에서 일시적인 오류가 발생했습니다.',
      'YouTube Data API 서버가 현재 요청을 정상적으로 처리하지 못했습니다.',
      ['YouTube 측의 일시적인 서비스 장애일 수 있습니다.'],
      [
        '잠시 뒤 같은 작업을 다시 실행합니다.',
        '진행 중인 수집이라면 자동 재개 여부를 확인합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (statusCode === 403) {
    return buildErrorInfo_(
      'YOUTUBE_ACCESS_FORBIDDEN',
      'YouTube 데이터에 접근할 수 없습니다.',
      'API 키 설정, 영상 공개 상태 또는 Google Cloud 프로젝트 권한을 확인해야 합니다.',
      [
        'API 키 제한 설정이 요청을 차단했을 수 있습니다.',
        '영상이 공개 API에서 접근할 수 없는 상태일 수 있습니다.'
      ],
      [
        'API 키의 API 제한과 애플리케이션 제한을 확인합니다.',
        '영상이 공개 상태인지 확인합니다.',
        'Google Cloud에서 YouTube Data API v3가 활성화되어 있는지 확인합니다.'
      ],
      {
        helpLabel: 'API 키 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (statusCode === 400) {
    return buildErrorInfo_(
      'YOUTUBE_BAD_REQUEST',
      'YouTube API 요청 형식을 확인해야 합니다.',
      '영상 주소 또는 요청 매개변수 중 하나를 YouTube API가 처리하지 못했습니다.',
      ['영상 주소가 올바르지 않거나 API 요청 값이 허용 범위를 벗어났을 수 있습니다.'],
      [
        '영상 주소를 다시 확인합니다.',
        '수집 개수와 정렬 기준을 확인합니다.',
        '같은 문제가 계속되면 새 수집으로 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '입력값 확인',
        technical: technical
      }
    );
  }

  return buildErrorInfo_(
    'YOUTUBE_API_ERROR',
    'YouTube API 요청을 완료하지 못했습니다.',
    'YouTube Data API가 요청을 거부하거나 처리하지 못했습니다.',
    ['API 키, 영상 공개 상태, 할당량 또는 네트워크 상태를 확인해야 합니다.'],
    [
      'API 키 설정과 YouTube Data API 활성화 여부를 확인합니다.',
      '영상 주소가 공개 영상인지 확인합니다.',
      '잠시 뒤 다시 실행합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}


/**
 * 영상 URL 또는 11자리 영상 ID에서 videoId를 추출합니다.
 */
function extractVideoId_(input) {
  const text = String(input || '').trim();

  if (/^[A-Za-z0-9_-]{11}$/.test(text)) {
    return text;
  }

  const patterns = [
    /[?&]v=([A-Za-z0-9_-]{11})/,
    /youtu\.be\/([A-Za-z0-9_-]{11})/,
    /youtube(?:-nocookie)?\.com\/(?:embed|shorts|live)\/([A-Za-z0-9_-]{11})/
  ];

  for (let i = 0; i < patterns.length; i += 1) {
    const match = text.match(patterns[i]);

    if (match) {
      return match[1];
    }
  }

  throwStructuredError_(buildErrorInfo_(
    'INVALID_VIDEO_URL',
    'YouTube 영상 주소를 확인해야 합니다.',
    '입력한 값에서 11자리 YouTube 영상 ID를 찾지 못했습니다.',
    [
      '영상 주소 일부가 빠졌을 수 있습니다.',
      '채널·재생목록 주소를 입력했을 수 있습니다.'
    ],
    [
      'YouTube에서 수집할 영상을 엽니다.',
      '브라우저 주소 표시줄의 영상 URL 전체를 복사합니다.',
      '사이드바의 영상 주소 입력란에 붙여 넣습니다.'
    ],
    {
      focusTarget: 'videoUrl',
      actionLabel: '영상 주소 다시 입력'
    }
  ));
}


/**
 * 사이드바 입력값을 검증합니다.
 */
function normalizeSidebarInput_(formData) {
  const form = formData || {};
  const videoUrl = String(form.videoUrl || '').trim();
  const limit = parseInt(form.limit, 10);

  if (!videoUrl) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_URL_REQUIRED',
      'YouTube 영상 주소를 입력해야 합니다.',
      '수집 대상 영상 주소가 비어 있습니다.',
      ['영상 주소 입력란에 값이 없습니다.'],
      ['수집할 YouTube 영상의 URL을 입력합니다.'],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 입력'
      }
    ));
  }

  if (!Number.isInteger(limit)) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_INVALID',
      '수집 개수를 정수로 입력해야 합니다.',
      '수집할 최상위 댓글 개수가 올바른 정수 형식이 아닙니다.',
      ['빈 값, 소수 또는 문자가 입력되었을 수 있습니다.'],
      ['1 이상의 정수를 입력합니다.'],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 입력'
      }
    ));
  }

  if (limit < YT_CFG.MIN_LIMIT || limit > YT_CFG.MAX_LIMIT) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_OUT_OF_RANGE',
      '수집 개수가 허용 범위를 벗어났습니다.',
      '수집 개수는 ' + YT_CFG.MIN_LIMIT + '개 이상 ' +
        YT_CFG.MAX_LIMIT + '개 이하로 입력해야 합니다.',
      ['입력한 개수가 코드에 설정된 운영 범위를 벗어났습니다.'],
      [
        YT_CFG.MIN_LIMIT + '~' + YT_CFG.MAX_LIMIT +
          ' 사이의 정수를 입력합니다.'
      ],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 수정'
      }
    ));
  }

  return {
    videoUrl: videoUrl,
    limit: limit,
    includeReplies: form.includeReplies === true
  };
}


/**
 * 결과 시트와 숨김 내부 시트를 준비합니다.
 */
function ensureInternalSheet_(ss) {
  let internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    internal = ss.insertSheet(YT_CFG.INTERNAL_SHEET);
  }

  ensureColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);

  if (internal.getLastRow() === 0) {
    internal
      .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
      .setValues([YT_CFG.INTERNAL_HEADERS]);
  }

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 새 수집에 사용할 결과 시트를 시트1, 시트2, 시트3 ... 순서로 만듭니다.
 *
 * 새 스프레드시트에 기본 빈 '시트1' 하나만 존재하는 경우에는 그 시트를
 * 첫 결과 시트로 사용합니다. 그 이후 수집부터는 항상 새 시트를 추가합니다.
 */
function createNextOutputSheet_(ss) {
  const sheets = ss.getSheets();

  if (
    sheets.length === 1 &&
    sheets[0].getName() === YT_CFG.OUTPUT_SHEET_PREFIX + '1' &&
    isSheetCompletelyBlank_(sheets[0])
  ) {
    prepareOutputSheet_(sheets[0]);
    return sheets[0];
  }

  let maxNumber = 0;
  const namePattern = new RegExp(
    '^' + escapeRegExp_(YT_CFG.OUTPUT_SHEET_PREFIX) + '(\\d+)$'
  );

  sheets.forEach(function(sheet) {
    const match = sheet.getName().match(namePattern);

    if (match) {
      maxNumber = Math.max(maxNumber, Number(match[1] || 0));
    }
  });

  let nextNumber = maxNumber + 1;
  let nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;

  while (ss.getSheetByName(nextName)) {
    nextNumber += 1;
    nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;
  }

  const sheet = ss.insertSheet(nextName);
  prepareOutputSheet_(sheet);
  return sheet;
}


function isSheetCompletelyBlank_(sheet) {
  return sheet.getLastRow() === 0 && sheet.getLastColumn() === 0;
}


function prepareOutputSheet_(sheet) {
  if (sheet.getFilter()) {
    sheet.getFilter().remove();
  }

  sheet.clear();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setValues([YT_CFG.HEADERS]);

  sheet.setFrozenRows(1);
  sheet.getRange('A:A').setNumberFormat('@');
  formatCommentsSheet_(sheet);
}


/**
 * 새 수집을 위해 숨김 내부 시트만 초기화합니다.
 * 이전 결과 시트의 내용은 변경하지 않습니다.
 */
function resetInternalData_(ss) {
  const internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_SHEET_NOT_FOUND',
      '내부 관리 시트를 준비하지 못했습니다.',
      '댓글 수집 상태를 저장하는 숨김 시트가 존재하지 않습니다.',
      ['내부 시트 생성 과정이 완료되지 않았습니다.'],
      ['사이드바를 닫았다가 다시 열고 새 수집을 시작합니다.'],
      { actionLabel: '확인' }
    ));
  }

  internal.clear();
  ensureExactColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);
  internal
    .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .setValues([YT_CFG.INTERNAL_HEADERS]);

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 현재 수집 상태에 연결된 결과 시트를 찾습니다.
 */
function getOutputSheetForState_(ss, state) {
  const expectedId = Number(state.outputSheetId || 0);
  let outputSheet = null;

  if (expectedId > 0) {
    outputSheet = ss.getSheets().find(function(sheet) {
      return sheet.getSheetId() === expectedId;
    }) || null;
  }

  if (!outputSheet && state.outputSheetName) {
    outputSheet = ss.getSheetByName(String(state.outputSheetName));
  }

  if (!outputSheet) {
    throwStructuredError_(buildErrorInfo_(
      'OUTPUT_SHEET_NOT_FOUND',
      '수집 결과 시트를 찾을 수 없습니다.',
      '현재 수집 작업과 연결된 결과 시트가 삭제되었거나 이름과 식별 정보가 변경되었습니다.',
      [
        '수집 중 결과 시트를 삭제했을 수 있습니다.',
        '스프레드시트 구조가 외부 작업으로 변경되었을 수 있습니다.'
      ],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }

  return outputSheet;
}


function escapeRegExp_(text) {
  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}


/**
 * 이전 버전이 만든 수집로그 시트를 제거합니다.
 */
function deleteLegacyLogSheet_(ss) {
  const logSheet = ss.getSheetByName(YT_CFG.LEGACY_LOG_SHEET);

  if (logSheet && ss.getSheets().length > 1) {
    ss.deleteSheet(logSheet);
  }
}


/**
 * 댓글 시트를 번호 순으로 정렬하고 최종 서식을 적용합니다.
 */
function finalizeCommentsSheet_(sheet) {
  sortCommentsByDisplayNumber_(sheet);
  formatCommentsSheet_(sheet);
}


function sortCommentsByDisplayNumber_(sheet) {
  const lastRow = sheet.getLastRow();

  if (lastRow <= 2) {
    return;
  }

  // 정렬용 임시 열 I, J를 만든 뒤 최상위 번호와 답글 번호로 정렬합니다.
  ensureColumnCount_(sheet, 10);

  const numberValues = sheet
    .getRange(2, 1, lastRow - 1, 1)
    .getDisplayValues();

  const sortKeys = numberValues.map(function(row) {
    const parts = String(row[0] || '').split('_');
    return [
      Number(parts[0] || 0),
      parts.length > 1 ? Number(parts[1] || 0) : 0
    ];
  });

  sheet
    .getRange(2, 9, sortKeys.length, 2)
    .setValues(sortKeys);

  sheet
    .getRange(2, 1, lastRow - 1, 10)
    .sort([
      { column: 9, ascending: true },
      { column: 10, ascending: true }
    ]);

  sheet.getRange(2, 9, lastRow - 1, 2).clearContent();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
}


function formatCommentsSheet_(sheet) {
  const lastRow = sheet.getLastRow();

  sheet.setFrozenRows(1);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setFontWeight('bold')
    .setWrap(true)
    .setVerticalAlignment('middle');

  sheet.getRange('A:A').setNumberFormat('@');

  if (lastRow > 1) {
    sheet
      .getRange(2, 7, lastRow - 1, 1)
      .setNumberFormat('yyyy-mm-dd hh:mm:ss');

    sheet
      .getRange(2, 5, lastRow - 1, 1)
      .setWrap(true)
      .setVerticalAlignment('top');

    sheet
      .getRange(2, 1, lastRow - 1, YT_CFG.HEADERS.length)
      .setVerticalAlignment('top');

    if (sheet.getFilter()) {
      sheet.getFilter().remove();
    }

    sheet
      .getRange(1, 1, lastRow, YT_CFG.HEADERS.length)
      .createFilter();
  }

  sheet.setColumnWidth(1, 90);
  sheet.setColumnWidth(2, 180);
  sheet.setColumnWidth(3, 260);
  sheet.setColumnWidth(4, 170);
  sheet.setColumnWidth(5, 520);
  sheet.setColumnWidth(6, 95);
  sheet.setColumnWidth(7, 155);
  sheet.setColumnWidth(8, 95);
}


/**
 * 숨김 내부 시트에 저장된 댓글 ID 집합을 만듭니다.
 */
function getExistingCommentIds_(internalSheet) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return new Set();
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .getDisplayValues();

  return new Set(
    values
      .map(function(row) {
        return row[0];
      })
      .filter(function(value) {
        return Boolean(value);
      })
  );
}


/**
 * 숨김 내부 시트 기준으로 실제 최상위 댓글·답글 수를 계산합니다.
 */
function getExistingCounts_(internalSheet) {
  const lastRow = internalSheet.getLastRow();
  const counts = { top: 0, reply: 0 };

  if (lastRow <= 1) {
    return counts;
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_TYPE, lastRow - 1, 1)
    .getDisplayValues();

  values.forEach(function(row) {
    if (row[0] === 'topLevel') {
      counts.top += 1;
    } else if (row[0] === 'reply') {
      counts.reply += 1;
    }
  });

  return counts;
}


/**
 * 댓글 글자수를 지정된 바이트 규칙으로 계산합니다.
 * - ASCII 영역(영문, 숫자, 공백, 일반 문장부호): 1바이트
 * - 한글을 포함한 비ASCII 유니코드 문자: 코드 포인트당 2바이트
 */
function calculateCommentBytes_(value) {
  const text = String(value || '');
  let bytes = 0;

  Array.from(text).forEach(function(character) {
    const codePoint = character.codePointAt(0);
    bytes += codePoint <= 0x7F ? 1 : 2;
  });

  return bytes;
}


/**
 * 외부 문자열이 시트 수식으로 실행되는 것을 방지합니다.
 */
function safeCellText_(value) {
  const text = value === undefined || value === null ? '' : String(value);
  return /^[=+\-@]/.test(text) ? "'" + text : text;
}


function apiDateToSheetValue_(value) {
  return value ? new Date(value) : '';
}


function ensureColumnCount_(sheet, requiredColumns) {
  const current = sheet.getMaxColumns();

  if (current < requiredColumns) {
    sheet.insertColumnsAfter(current, requiredColumns - current);
  }
}


function ensureExactColumnCount_(sheet, requiredColumns) {
  ensureColumnCount_(sheet, requiredColumns);

  const current = sheet.getMaxColumns();

  if (current > requiredColumns) {
    sheet.deleteColumns(requiredColumns + 1, current - requiredColumns);
  }
}


function getUserProperties_() {
  return PropertiesService.getUserProperties();
}


function getApiKey_() {
  const apiKey = getUserProperties_().getProperty(YT_CFG.API_KEY_PROP);

  if (!apiKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키 설정이 필요합니다.',
      '댓글 수집을 시작하기 전에 YouTube Data API 키를 저장해야 합니다.',
      ['현재 사용자 계정에 저장된 API 키가 없습니다.'],
      [
        '사이드바 상단의 API 키 입력란에 키를 입력합니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  return apiKey.trim();
}


function loadState_() {
  const text = getUserProperties_().getProperty(YT_CFG.STATE_PROP);
  return text ? JSON.parse(text) : null;
}


function saveState_(state) {
  state.updatedAt = new Date().toISOString();
  const text = JSON.stringify(state);
  const byteLength = Utilities.newBlob(text).getBytes().length;

  if (byteLength > 8500) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_STORAGE_LIMIT',
      '수집 진행 상태를 저장할 수 없습니다.',
      'Apps Script 사용자 속성의 안전 저장 크기를 초과했습니다.',
      ['진행 상태 데이터가 예상보다 커졌습니다.'],
      [
        '현재 수집을 취소합니다.',
        '댓글 수집 개수를 줄여 새로 실행합니다.'
      ],
      { actionLabel: '확인', technical: { byteLength: byteLength } }
    ));
  }

  getUserProperties_().setProperty(YT_CFG.STATE_PROP, text);
}


function loadLastResult_() {
  const text = getUserProperties_().getProperty(YT_CFG.LAST_RESULT_PROP);
  return text ? JSON.parse(text) : null;
}


function saveLastResult_(state, status, message, errorInfo) {
  const result = {
    status: status,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: Number(state.targetTopLevelCount || 0),
    topCount: Number(state.topCount || 0),
    replyCount: Number(state.replyCount || 0),
    apiCalls: Number(state.apiCalls || 0),
    startedAt: state.startedAt || '',
    updatedAt: new Date().toISOString(),
    finishedAt: new Date().toISOString(),
    message: message || '',
    error: errorInfo || null
  };

  getUserProperties_().setProperty(
    YT_CFG.LAST_RESULT_PROP,
    JSON.stringify(result)
  );
}


function validateStateVersion_(state) {
  if (Number(state.version || 0) !== YT_CFG.STATE_VERSION) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_VERSION_MISMATCH',
      '이전 코드에서 시작된 수집 작업을 이어갈 수 없습니다.',
      '현재 Code.gs의 댓글 저장 구조가 이전 실행 상태와 다릅니다.',
      ['고정 결과 시트 또는 정렬 기준을 사용하던 이전 코드의 작업 상태가 남아 있습니다.'],
      [
        '사이드바에서 진행 중인 수집을 취소합니다.',
        '현재 코드로 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }
}


function normalizeState_(state) {
  state.currentReplyParentId = state.currentReplyParentId || '';
  state.nextReplyPageToken = state.nextReplyPageToken || '';
  state.nextThreadPageToken = state.nextThreadPageToken || '';
  state.threadDone = Boolean(state.threadDone);
  state.topCount = Number(state.topCount || 0);
  state.replyCount = Number(state.replyCount || 0);
  state.apiCalls = Number(state.apiCalls || 0);
  state.threadPages = Number(state.threadPages || 0);
  state.replyPages = Number(state.replyPages || 0);
  state.targetTopLevelCount = Number(state.targetTopLevelCount || 0);
  state.outputSheetId = Number(state.outputSheetId || 0);
  state.outputSheetName = String(state.outputSheetName || '');
  state.error = state.error || null;
}


function maskApiKey_(apiKey) {
  const key = String(apiKey || '');
  return '••••••••••••' + key.slice(-4);
}


function buildProgressForClient_(state, status) {
  const target = Number(state.targetTopLevelCount || 0);
  const top = Number(state.topCount || 0);
  const reply = Number(state.replyCount || 0);
  const percent = target > 0
    ? Math.min(100, Math.round((top / target) * 100))
    : 0;

  let stage = '대기 중';

  if (status === 'RUNNING') {
    if (state.currentReplyParentId) {
      stage = '답글 수집 중';
    } else if (!state.threadDone) {
      stage = '최상위 댓글 수집 중';
    } else {
      stage = '마무리 중';
    }
  } else if (status === 'COMPLETED') {
    stage = '완료';
  } else if (status === 'ERROR') {
    stage = '오류';
  } else if (status === 'CANCELLED') {
    stage = '취소됨';
  }

  return {
    status: status,
    stage: stage,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: target,
    topCount: top,
    replyCount: reply,
    totalRows: top + reply,
    apiCalls: Number(state.apiCalls || 0),
    percent: percent,
    startedAt: state.startedAt || '',
    updatedAt: state.updatedAt || '',
    message: state.message || '',
    error: state.error || null
  };
}


function buildServerProgressMessage_(state) {
  return (
    '최상위 댓글 ' +
    state.topCount +
    '/' +
    state.targetTopLevelCount +
    '개, 답글 ' +
    state.replyCount +
    '개를 저장했습니다.'
  );
}


function scheduleContinuation_() {
  deleteContinuationTriggers_();

  ScriptApp
    .newTrigger(YT_CFG.CONTINUE_HANDLER)
    .timeBased()
    .after(YT_CFG.CONTINUE_AFTER_MS)
    .create();
}


function deleteContinuationTriggers_() {
  ScriptApp.getProjectTriggers().forEach(function(trigger) {
    if (trigger.getHandlerFunction() === YT_CFG.CONTINUE_HANDLER) {
      ScriptApp.deleteTrigger(trigger);
    }
  });
}


/**
 * 한국어 모달용 오류 정보를 만듭니다.
 */
function buildErrorInfo_(code, title, summary, causes, steps, options) {
  const opts = options || {};

  return {
    code: String(code || 'UNKNOWN_ERROR'),
    title: String(title || '작업을 완료하지 못했습니다.'),
    summary: String(summary || '처리 중 문제가 발생했습니다.'),
    causes: Array.isArray(causes) ? causes.map(String) : [],
    steps: Array.isArray(steps) ? steps.map(String) : [],
    helpLabel: String(opts.helpLabel || ''),
    helpUrl: String(opts.helpUrl || ''),
    focusTarget: String(opts.focusTarget || ''),
    actionLabel: String(opts.actionLabel || '확인'),
    technical:
      opts.technical && typeof opts.technical === 'object'
        ? opts.technical
        : {}
  };
}


/**
 * 서버 오류를 Sidebar.html이 해석할 수 있는 구조화된 예외로 전달합니다.
 */
function throwStructuredError_(errorInfo) {
  throw new Error(
    YT_CFG.STRUCTURED_ERROR_PREFIX + JSON.stringify(errorInfo)
  );
}


function extractStructuredError_(rawText) {
  const raw = String(rawText || '');
  const markerIndex = raw.indexOf(YT_CFG.STRUCTURED_ERROR_PREFIX);

  if (markerIndex < 0) {
    return null;
  }

  const jsonText = raw.slice(
    markerIndex + YT_CFG.STRUCTURED_ERROR_PREFIX.length
  );

  try {
    return JSON.parse(jsonText);
  } catch (parseError) {
    return null;
  }
}


/**
 * Apps Script 자체 오류도 한국어 모달 정보로 변환합니다.
 */
function normalizeErrorInfo_(error, context) {
  const raw = error && error.message
    ? String(error.message)
    : String(error || '');

  const structured = extractStructuredError_(raw);

  if (structured) {
    return structured;
  }

  const lower = raw.toLowerCase();
  const technical = {
    context: String(context || '작업 실행'),
    originalMessage: raw
  };

  if (
    lower.indexOf('authorization is required') >= 0 ||
    lower.indexOf('you do not have permission') >= 0 ||
    lower.indexOf('permissions') >= 0 && lower.indexOf('required') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_AUTH_REQUIRED',
      'Google 권한 승인이 필요합니다.',
      '현재 계정이 스프레드시트 또는 외부 API 요청 권한을 아직 승인하지 않았습니다.',
      ['Apps Script를 처음 실행했거나 새로운 권한이 추가되었습니다.'],
      [
        '스프레드시트 메뉴에서 사이드바를 다시 엽니다.',
        '권한 검토 화면에서 현재 Google 계정을 선택합니다.',
        '요청되는 권한을 허용한 뒤 다시 실행합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('maximum execution time') >= 0 ||
    lower.indexOf('exceeded maximum execution time') >= 0 ||
    lower.indexOf('timed out') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_EXECUTION_TIMEOUT',
      '한 번의 실행 가능 시간을 초과했습니다.',
      '댓글 또는 답글 처리 시간이 길어 현재 실행 구간이 종료되었습니다.',
      ['대량 댓글 수집으로 한 번의 Apps Script 실행 시간이 길어졌습니다.'],
      [
        '사이드바를 다시 열어 진행 상태를 확인합니다.',
        '멈춘 경우 ‘중단 지점부터 실행’을 한 번 실행합니다.',
        '같은 문제가 반복되면 수집 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('service invoked too many times') >= 0 ||
    lower.indexOf('quota') >= 0 && lower.indexOf('apps script') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_SERVICE_QUOTA',
      'Apps Script 서비스 사용 한도를 초과했습니다.',
      '현재 Google 계정 또는 스크립트의 일일 서비스 사용량이 허용 범위를 넘었습니다.',
      ['짧은 시간에 많은 외부 요청이나 스프레드시트 쓰기 작업이 실행되었습니다.'],
      [
        '잠시 뒤 다시 실행합니다.',
        '같은 날 반복되면 다음 날 다시 실행합니다.',
        '한 번에 수집하는 댓글 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  return buildErrorInfo_(
    'UNEXPECTED_ERROR',
    '예상하지 못한 오류가 발생했습니다.',
    '오류 유형을 자동으로 판별하지 못했습니다.',
    [
      '네트워크, 권한, Google 서비스 상태 또는 실행 환경에서 문제가 발생했을 수 있습니다.'
    ],
    [
      '사이드바를 닫았다가 다시 열고 같은 작업을 한 번 더 실행합니다.',
      'Apps Script 편집기의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.',
      'API 키와 영상 주소를 다시 확인합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}

Sidebar.html

YouTube 댓글 수집기

YouTube Data API v3 → Google Sheets

1. API 키

YouTube Data API 키

최초 1회 저장합니다. 키는 사용자별 Apps Script 속성에 보관됩니다.

2. 수집 설정

API 키를 저장하면 수집 설정이 활성화됩니다.

YouTube 영상 주소

수집할 최상위 댓글 수

1~50,000개. 답글 포함 시 실제 저장 행 수가 이 값보다 많아질 수 있습니다.

대댓글도 모두 수집

새 수집을 시작할 때마다 ‘시트1’, ‘시트2’, ‘시트3’ 형식의 새 시트가 생성됩니다. 기존 수집 결과는 유지됩니다.

실습용 API KEY

AIzaSyDETqF5gzbFh3DG4U0N-rjT1yK2asM-1X4

(3) 추가 강의자료

교안 및 학습자료

[강의] 김민기.pdf

(4) 민기쌤 생기부 도우미

Code.gs

// =================================================================
// [0] 초기 설정 및 메뉴
// =================================================================

function onOpen() {
  SpreadsheetApp.getUi().createMenu('민기쌤 생기부 도우미')
      .addItem('🚀 사이드바 열기', 'openSidebar') 
      .addToUi();
}

function renderView_(viewName) {
  var template = HtmlService.createTemplateFromFile('Sidebar');
  template.initialView = viewName || 'sidebar';
  return template.evaluate();
}

function openSidebar() {
  ensureBannedWordSheet_();
  var html = renderView_('sidebar')
      .setTitle('민기쌤 생기부 맞춤법 도우미')
      .setWidth(300); 
  SpreadsheetApp.getUi().showSidebar(html);
}

function openSpellCheckViewer() {
  var html = renderView_('spellcheck')
      .setWidth(1000) 
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '📝 Bareun 맞춤법 검사 및 수정');
}

function openBannedWordViewer() {
  var html = renderView_('banned')
      .setWidth(1000)
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '🚫 기재 금지어 점검');
}

// =================================================================
// [1] Bareun API 키 및 UI 설정
// =================================================================

function getBareunUserProperties_() {
  ensureBannedWordSheet_();
  var props = PropertiesService.getUserProperties();
  var currentPolicy = 'BAREUN_ONLY_KEYS_V3';
  var previousPolicy = props.getProperty('API_KEY_POLICY_VERSION');

  // 정책 변경 시 현재 기능에서 쓰지 않는 예전 사용자 설정을 한 번 정리합니다.
  if (previousPolicy !== currentPolicy) {
    var allowedProperties = {
      UI_STATE: true,
      API_KEY_POLICY_VERSION: true
    };
    // 바로 이전 사용자 입력형 정책에서 저장한 키만 보존합니다.
    if (previousPolicy === 'USER_SUPPLIED_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V2') {
      allowedProperties.USER_BAREUN_KEY = true;
    }
    Object.keys(props.getProperties()).forEach(function(propertyName) {
      if (!allowedProperties[propertyName]) props.deleteProperty(propertyName);
    });

    var previousUiState = {};
    try {
      previousUiState = JSON.parse(props.getProperty('UI_STATE') || '{}');
    } catch (e) {
      previousUiState = {};
    }
    var currentUiState = {};
    ['card-api', 'sub-api-settings', 'card-util'].forEach(function(id) {
      if (previousUiState[id]) currentUiState[id] = true;
    });
    props.setProperty('UI_STATE', JSON.stringify(currentUiState));
    props.setProperty('API_KEY_POLICY_VERSION', currentPolicy);
  }

  return props;
}

function saveUserBareunKey(bareunKey) {
  var props = getBareunUserProperties_();
  var cleanBareunKey = String(bareunKey || '').trim();

  if (!cleanBareunKey) {
    throw new Error('Bareun API 키를 입력해 주세요. 이 도우미는 API 키를 제공하지 않습니다.');
  }

  props.setProperty('USER_BAREUN_KEY', cleanBareunKey);
  return { hasBareun: true };
}

function checkUserBareunStatus() {
  var props = getBareunUserProperties_();
  return { hasBareun: !!props.getProperty('USER_BAREUN_KEY') };
}

function clearUserBareunKey() {
  var props = getBareunUserProperties_();
  props.deleteProperty('USER_BAREUN_KEY');
  return { hasBareun: false };
}

function getBareunKey() {
  var key = getBareunUserProperties_().getProperty('USER_BAREUN_KEY');
  if (!key) throw new Error("Bareun API 키가 없습니다. 사이드바 상단에서 등록해주세요.");
  return key;
}

// =================================================================
// [2] Bareun 맞춤법 검사
// =================================================================

function getSelectedDataForSpellCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");
  var rows = [];
  var startRow = range.getRow();
  var startCol = range.getColumn();
  var values = range.getValues();
  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var text = values[i][j].toString();
      if (text.trim() !== "") {
        rows.push({ sheetName: sheetName, row: startRow + i, col: startCol + j, original: text });
      }
    }
  }
  return rows;
}

function getBareunCorrection(text) {
  var userKey = getBareunKey();
  var result = callBareunApi(text, userKey); 
  return result; 
}

function applySpellCheckResults(updates) {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  updates.forEach(function(item) {
    var sheet = spreadsheet.getSheetByName(item.sheetName);
    if (!sheet) throw new Error('검사한 시트를 찾을 수 없습니다: ' + item.sheetName);
    sheet.getRange(item.row, item.col).setValue(item.text);
  });
  return updates.length;
}

function callBareunApi(text, userKey) {
  var url = "https://api.bareun.ai/bareun.RevisionService/CorrectError";
  var options = {
    "method": "post", "contentType": "application/json", "headers": { "api-key": userKey }, "muteHttpExceptions": true,
    "payload": JSON.stringify({ "document": { "content": text, "language": "ko-KR" }, "encoding_type": "UTF16" })
  };
  var response = UrlFetchApp.fetch(url, options);
  var result = JSON.parse(response.getContentText());
  
  if (response.getResponseCode() !== 200) {
    return { error: "API 오류: " + response.getResponseCode() };
  }
  return { revised: result.revised, helps: result.helps || {}, rawBlocks: result.revisedBlocks || result.revised_blocks || [], error: null };
}

// =================================================================
// [3] 기재 금지어 관리
// =================================================================

var BANNED_WORD_SHEET_NAME_ = '기재금지어관리';
var BANNED_WORD_HEADERS_ = ['번호', '기재 금지어'];
var LEGACY_BANNED_WORD_HEADERS_ = ['유형', '기재 금지어', '대체 표현'];
var ONE_COLUMN_BANNED_WORD_HEADERS_ = ['기재 금지어'];

function getLegacyBannedWordList_() {
  var saved = PropertiesService.getUserProperties().getProperty('BANNED_WORDS_DB');
  if (!saved) return getDefaultBannedList_();

  try {
    var parsed = JSON.parse(saved);
    if (!Array.isArray(parsed)) return getDefaultBannedList_();
    return parsed
      .map(function(item) {
        return String(item && item.k || '').trim();
      })
      .filter(function(keyword) { return keyword !== ''; });
  } catch (e) {
    return getDefaultBannedList_();
  }
}

function initializeBannedWordSheet_(sheet, list) {
  sheet.getRange(1, 1, 1, BANNED_WORD_HEADERS_.length)
    .setValues([BANNED_WORD_HEADERS_])
    .setBackground('#fce8e6')
    .setFontColor('#a50e0e')
    .setFontWeight('bold')
    .setHorizontalAlignment('center');

  var rows = list.map(function(keyword, index) {
    return [index + 1, keyword];
  });
  if (rows.length > 0) sheet.getRange(2, 1, rows.length, 2).setValues(rows);

  sheet.setFrozenRows(1);
  sheet.setColumnWidth(1, 60);
  sheet.setColumnWidth(2, 260);
  sheet.setTabColor('#d93025');
}

function migrateLegacyBannedWordSheet_(sheet) {
  var lastColumn = sheet.getLastColumn();
  var legacyColumn;
  var clearColumns;

  if (lastColumn >= 3 && sheet.getRange(1, 1, 1, 3).getDisplayValues()[0].join('|') === LEGACY_BANNED_WORD_HEADERS_.join('|')) {
    legacyColumn = 2;
    clearColumns = 3;
  } else if (sheet.getRange(1, 1, 1, 1).getDisplayValues()[0][0] === ONE_COLUMN_BANNED_WORD_HEADERS_[0]) {
    legacyColumn = 1;
    clearColumns = 1;
  } else {
    return false;
  }

  var lastRow = sheet.getLastRow();
  var keywords = lastRow < 2 ? [] : sheet.getRange(2, legacyColumn, lastRow - 1, 1)
    .getDisplayValues()
    .map(function(row) { return String(row[0] || '').trim(); })
    .filter(function(keyword) { return keyword !== ''; });

  var clearRows = Math.max(sheet.getLastRow(), 1);
  sheet.getRange(1, 1, clearRows, clearColumns).clearContent();
  initializeBannedWordSheet_(sheet, keywords);
  return true;
}

function ensureBannedWordSheet_() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  if (!spreadsheet) throw new Error('활성 스프레드시트를 찾을 수 없습니다.');

  var originalSheet = spreadsheet.getActiveSheet();
  var originalRange = spreadsheet.getActiveRange();
  var lock = LockService.getDocumentLock() || LockService.getScriptLock();
  lock.waitLock(30000);

  var sheet;
  try {
    sheet = spreadsheet.getSheetByName(BANNED_WORD_SHEET_NAME_);
    if (!sheet) {
      sheet = spreadsheet.insertSheet(BANNED_WORD_SHEET_NAME_);
      initializeBannedWordSheet_(sheet, getLegacyBannedWordList_());
    } else {
      // 이전 형식은 금지어만 보존하여 번호·기재금지어 두 열 목록으로 안전하게 바꿉니다.
      migrateLegacyBannedWordSheet_(sheet);
    }

    // 시트로 옮긴 뒤 예전 사용자별 저장값은 더 이상 별도 원본으로 남기지 않습니다.
    PropertiesService.getUserProperties().deleteProperty('BANNED_WORDS_DB');
    return sheet;
  } finally {
    if (originalSheet && sheet && originalSheet.getSheetId() !== sheet.getSheetId()) {
      spreadsheet.setActiveSheet(originalSheet);
      if (originalRange) spreadsheet.setActiveRange(originalRange);
    }
    lock.releaseLock();
  }
}

function openBannedWordManagementSheet() {
  var sheet = ensureBannedWordSheet_();
  sheet.activate();
  sheet.getRange('A1').activate();
  return sheet.getName();
}

function getDefaultBannedList_() {
  return [
    "MBTI", "커리어넷", "메이저맵", "패들렛", "띵커벨", "알로",
    "미리캔버스", "망고보드", "유튜버", "유튜브", "넷플릭스", "왓챠",
    "티빙", "네이버 폼", "구글 폼", "OECD", "UN", "유네스코", "WTO",
    "WHO", "그린피스", "앰네스티", "IMF", "인스타그램", "페이스북",
    "카카오톡", "네이버", "구글", "클래스 카드", "구글 클래스룸", "게더타운",
    "제페토", "아이패드", "갤럭시 탭", "비트코인", "TED", "반크", "TOEIC",
    "TOEFL", "TEPS", "대회", "수상", "한자능력검정"
  ];
}

function getBannedWordList_() {
  var sheet = ensureBannedWordSheet_();
  var header = sheet.getRange(1, 1, 1, 2).getDisplayValues()[0];
  if (header.join('|') !== BANNED_WORD_HEADERS_.join('|')) {
    throw new Error('기재금지어관리 시트의 1행은 "번호 | 기재 금지어" 순서여야 합니다.');
  }

  var lastRow = sheet.getLastRow();
  if (lastRow < 2) return [];

  var values = sheet.getRange(2, 1, lastRow - 1, 2).getDisplayValues();
  var seen = {};
  var list = [];

  values.forEach(function(row, index) {
    var rowNumber = index + 2;
    var number = String(row[0] || '').trim();
    var keyword = String(row[1] || '').trim();

    if (!number && !keyword) return;
    if (!/^[1-9]\d*$/.test(number)) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 번호(A열)는 1 이상의 정수여야 합니다.');
    }
    if (!keyword) throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어(B열)를 입력해 주세요.');

    var duplicateKey = normalizeBannedWord_(keyword);
    if (seen[duplicateKey]) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어가 ' + seen[duplicateKey] + '행과 중복됩니다: ' + keyword);
    }
    seen[duplicateKey] = rowNumber;
    list.push(keyword);
  });

  return list;
}

function runBannedWordCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  var values = range.getValues();
  var startRow = range.getRow();
  var startCol = range.getColumn();
  
  var db = getBannedWordList_();
  if (db.length === 0) return [];
  db.sort(function(a, b) { return normalizeBannedWord_(b).length - normalizeBannedWord_(a).length; });
  var canonicalByNormalizedKeyword = {};
  db.forEach(function(keyword) { canonicalByNormalizedKeyword[normalizeBannedWord_(keyword)] = keyword; });
  var combinedPattern = new RegExp('(' + db.map(buildWhitespaceInsensitivePattern_).join('|') + ')', 'gi');

  var results = [];

  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var original = values[i][j].toString();
      if (!original.trim()) continue;

      var hasIssue = false;
      var logs = [];

      var counts = {};
      var match;
      while ((match = combinedPattern.exec(original)) !== null) {
        var normalizedMatch = normalizeBannedWord_(match[0]);
        var keyword = canonicalByNormalizedKeyword[normalizedMatch];
        if (keyword) {
          hasIssue = true;
          counts[keyword] = (counts[keyword] || 0) + 1;
        }
      }

      Object.keys(counts).forEach(function(keyword) {
        logs.push({ k: keyword, count: counts[keyword] });
      });

      if (hasIssue) {
        results.push({
          sheetName: sheetName,
          row: startRow + i,
          col: startCol + j,
          original: original,
          logs: logs
        });
      }
    }
  }
  return results;
}

function escapeRegExp(string) {
  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); 
}

function normalizeBannedWord_(value) {
  return String(value || '').replace(/\s+/g, '').toLocaleLowerCase();
}

function buildWhitespaceInsensitivePattern_(keyword) {
  var compact = normalizeBannedWord_(keyword);
  if (!compact) throw new Error('비어 있는 기재 금지어는 검사할 수 없습니다.');
  return compact.split('').map(function(character) {
    return escapeRegExp(character);
  }).join('[\\s\\u00A0]*');
}

// =================================================================
// [4] 로컬 검토 유틸리티
// =================================================================

function unifyToStraightQuotes() {
  var range = SpreadsheetApp.getActiveRange();
  var ui = SpreadsheetApp.getUi();
  if (!range) throw new Error('선택된 셀이 없습니다.');
  var response = ui.alert('따옴표 변환', '선택 영역의 둥근 따옴표를 곧은 따옴표로 변환하시겠습니까?', ui.ButtonSet.YES_NO);
  if (response != ui.Button.YES) return;
  try {
    range.createTextFinder('[‘’]').useRegularExpression(true).matchEntireCell(false).replaceAllWith("'");
    range.createTextFinder('[“”]').useRegularExpression(true).matchEntireCell(false).replaceAllWith('"');
    SpreadsheetApp.flush();
    ui.alert('✅ 변환 완료');
  } catch (e) { ui.alert('오류: ' + e.toString()); }
}

// [신규] 선택 영역 스페이스바 실수(2칸 이상) 수정 함수
function fixDoubleSpaces() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  const values = range.getValues();
  let fixCount = 0; // 수정된 셀 개수 카운트

  const newValues = values.map(row => {
    return row.map(cell => {
      let str = String(cell);
      // 공백이 2번 이상 연속( /  +/)으로 있으면 1번으로 변경
      // 줄바꿈(\n)은 건드리지 않도록 일반 공백( )만 타겟팅
      if (/ {2,}/.test(str)) {
        fixCount++;
        return str.replace(/ {2,}/g, ' '); 
      }
      return cell;
    });
  });

  if (fixCount > 0) {
    range.setValues(newValues);
  }
  
  return fixCount;
}

// =================================================================
// [5] UI 상태 저장/불러오기
// =================================================================

function saveUiState(cardId, isExpanded) {
  var props = PropertiesService.getUserProperties();
  var state = JSON.parse(props.getProperty('UI_STATE') || '{}');
  state[cardId] = isExpanded;
  props.setProperty('UI_STATE', JSON.stringify(state));
}

function getUiState() {
  var props = PropertiesService.getUserProperties();
  return JSON.parse(props.getProperty('UI_STATE') || '{}');
}

Sidebar.html


= 0 ? initialView : "sidebar"; ?>



  
    
    
    
    
  
  
    
      
        🔑 Bareun API 키 설정
        expand_more
      
      
        
          
            내 Bareun API 키
            expand_more
          
          
            ⌛ API 키 설정 확인 중...
            
              
              Bareun API 키
              
              공용 키는 제공하지 않습니다. 키는 사용자별 설정에 저장되고 원문을 화면으로 다시 불러오지 않습니다.
              
              
            
          
        
      
    

    
      
        📝 선택 영역 검사 및 정리
        expand_more
      
      
        
        
        
        
        
        
      
    

    
  





  
    
    
    
    
    
  
  

    
      fact_check 맞춤법 검사 및 수정
      
        원본 오류
        수정 제안
      
    

    
      
        
        데이터를 불러오는 중입니다...
      
      
    

    
      
      
    

    
  





  
    
    
    
    
  
  

    
      block 기재 금지어 검사
      
        금지어 발견
        오른쪽 수정안에서 문맥에 맞게 직접 고쳐 주세요.
      
    

    
      
        
        데이터를 분석 중입니다...

(5) 각종 조사

2026 인공지능 활용 선도교사 양성연수 - 전북 익산

Sun, 19 Jul 2026 02:52:45 GMT

2026 인공지능 활용 선도교사 양성연수 - 전북 익산

강사: 교사 김민기(민기쌤)
일시: 2026-07-30
장소: 건국대학교

인공지능 활용 선도교사를 위한 중등 공통과정의 핵심 내용을 다루는 연수입니다.

(1) 클로바노트 음성 전사

(2) 유튜브 댓글 수집

아래 블로그의 설명에 따라 Youtube Data API 키를 발급합니다. 어려운 경우 최후의 수단으로 다음 연수용 API KEY를 사용할 수 있습니다. 이 KEY는 오늘 이후 폐기 처리되므로 유튜브 댓글 수집기가 더이상 작동하지 않습니다. AIzaSyDETqF5gzbFh3DG4U0N-rjT1yK2asM-1X4

Code.gs

const YT_CFG = Object.freeze({
  API_BASE: 'https://www.googleapis.com/youtube/v3',

  API_KEY_PROP: 'YT_API_KEY',
  STATE_PROP: 'YT_COMMENT_COLLECTOR_STATE',
  LAST_RESULT_PROP: 'YT_COMMENT_COLLECTOR_LAST_RESULT',
  CANCEL_REQUEST_PROP: 'YT_COMMENT_COLLECTOR_CANCEL_REQUEST',

  OUTPUT_SHEET_PREFIX: '시트',
  INTERNAL_SHEET: '_댓글수집_내부',
  LEGACY_LOG_SHEET: '수집로그',

  CONTINUE_HANDLER: 'continueCommentCollection',
  STRUCTURED_ERROR_PREFIX: 'YT_STRUCTURED_ERROR::',
  STATE_VERSION: 4,

  // Apps Script의 일반 실행 제한 전에 상태를 저장하고 다음 실행으로 넘깁니다.
  MAX_RUN_MS: 4 * 60 * 1000 + 30 * 1000,
  CONTINUE_AFTER_MS: 60 * 1000,

  MIN_LIMIT: 1,
  MAX_LIMIT: 50000,

  HEADERS: [
    '번호',
    '채널명',
    '영상 제목',
    '댓글 작성자',
    '댓글 내용',
    '좋아요 수',
    '작성 시각',
    '글자수'
  ],

  // 숨김 내부 시트의 열 구조입니다.
  INTERNAL_HEADERS: [
    'comment_id',
    'parent_comment_id',
    'display_number',
    'comment_type',
    'reply_status',
    'next_reply_index',
    'total_reply_count',
    'reply_page_token'
  ],

  INTERNAL_COL: Object.freeze({
    COMMENT_ID: 1,
    PARENT_ID: 2,
    DISPLAY_NUMBER: 3,
    COMMENT_TYPE: 4,
    REPLY_STATUS: 5,
    NEXT_REPLY_INDEX: 6,
    TOTAL_REPLY_COUNT: 7,
    REPLY_PAGE_TOKEN: 8
  })
});


/**
 * 스프레드시트를 열 때 사용자 메뉴를 만듭니다.
 */
function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('YouTube 댓글 수집')
    .addItem('사이드바 열기', 'showYouTubeCommentSidebar')
    .addSeparator()
    .addItem('중단 지점부터 실행', 'continueCommentCollection')
    .addItem('진행 중인 수집 취소', 'cancelCommentCollection')
    .addToUi();
}


/**
 * 오른쪽 사이드바를 엽니다.
 */
function showYouTubeCommentSidebar() {
  const html = HtmlService
    .createHtmlOutputFromFile('Sidebar')
    .setTitle('YouTube 댓글 수집기');

  SpreadsheetApp.getUi().showSidebar(html);
}


/**
 * 사이드바 초기 상태를 반환합니다.
 */
function getSidebarState() {
  const props = getUserProperties_();
  const apiKey = props.getProperty(YT_CFG.API_KEY_PROP) || '';
  const activeState = loadState_();
  const lastResult = loadLastResult_();
  const cancelRequested =
    props.getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';

  const progress = activeState
    ? buildProgressForClient_(activeState, 'RUNNING')
    : lastResult
      ? buildProgressForClient_(lastResult, lastResult.status || 'COMPLETED')
      : null;

  if (progress && activeState && cancelRequested) {
    progress.stage = '취소 처리 중';
    progress.message = '현재 실행 구간이 끝나는 즉시 안전하게 중단됩니다.';
  }

  return {
    apiKeyConfigured: Boolean(apiKey),
    apiKeyMask: apiKey ? maskApiKey_(apiKey) : '',
    running: Boolean(activeState),
    cancelRequested: cancelRequested,
    progress: progress
  };
}


/**
 * API 키를 실제 YouTube Data API 요청으로 검증한 뒤 사용자별 속성에 저장합니다.
 */
function saveApiKey(apiKey) {
  const cleanedKey = String(apiKey || '').trim();

  if (!cleanedKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키를 입력해야 합니다.',
      'Google Cloud에서 발급한 YouTube Data API 키가 입력되지 않았습니다.',
      ['API 키 입력란이 비어 있습니다.'],
      [
        'Google Cloud Console에서 API 키를 발급합니다.',
        'API 키 전체를 사이드바 입력란에 붙여 넣습니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  if (cleanedKey.length < 20) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_FORMAT_INVALID',
      'API 키 형식을 확인해야 합니다.',
      '입력한 문자열이 일반적인 Google API 키 길이보다 짧습니다.',
      [
        'API 키 일부만 복사했을 수 있습니다.',
        '프로젝트 ID나 다른 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 값을 처음부터 끝까지 다시 복사하여 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력'
      }
    ));
  }

  validateApiKey_(cleanedKey);

  const props = getUserProperties_();
  props.setProperty(YT_CFG.API_KEY_PROP, cleanedKey);

  // 이전 API 키 오류 안내가 새 키 저장 뒤 다시 나타나지 않도록 정리합니다.
  const previous = loadLastResult_();
  if (previous && previous.status === 'ERROR') {
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
  }

  return getSidebarState();
}


/**
 * 저장된 API 키를 삭제합니다.
 */
function deleteApiKey() {
  if (loadState_()) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_DELETE_BLOCKED',
      '수집 중에는 API 키를 삭제할 수 없습니다.',
      '현재 댓글 수집 작업이 저장된 API 키를 사용하고 있습니다.',
      ['진행 중인 작업이 존재합니다.'],
      [
        '현재 수집을 완료하거나 취소합니다.',
        '수집 상태가 종료된 뒤 API 키를 삭제합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.API_KEY_PROP);
  props.deleteProperty(YT_CFG.LAST_RESULT_PROP);

  return getSidebarState();
}


/**
 * 사이드바 입력값으로 새 수집 작업을 준비합니다.
 * 실제 수집은 runCollectionNow 또는 시간 기반 트리거가 수행합니다.
 */
function startCollectionFromSidebar(formData) {
  const lock = LockService.getScriptLock();
  lock.waitLock(10000);

  try {
    const apiKey = getApiKey_();
    const input = normalizeSidebarInput_(formData);
    const ss = SpreadsheetApp.getActiveSpreadsheet();

    if (!ss) {
      throwStructuredError_(buildErrorInfo_(
        'SPREADSHEET_NOT_FOUND',
        '댓글을 저장할 스프레드시트를 찾지 못했습니다.',
        '현재 Apps Script가 스프레드시트와 연결된 상태인지 확인해야 합니다.',
        [
          '독립 실행형 Apps Script 프로젝트에서 코드를 실행했을 수 있습니다.',
          '스프레드시트가 닫히거나 접근 권한이 변경되었을 수 있습니다.'
        ],
        [
          '댓글을 저장할 Google 스프레드시트를 엽니다.',
          '‘확장 프로그램 → Apps Script’에서 이 코드를 실행합니다.',
          '스프레드시트를 새로고침하고 사이드바를 다시 엽니다.'
        ],
        { actionLabel: '확인' }
      ));
    }

    // 영상과 API 키가 정상인지 먼저 확인합니다.
    const videoId = extractVideoId_(input.videoUrl);
    const metadata = getVideoMetadataWithKey_(videoId, apiKey);

    deleteContinuationTriggers_();

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    // 새 수집은 기존 결과를 지우지 않고 새 결과 시트에 기록합니다.
    const outputSheet = createNextOutputSheet_(ss);
    ensureInternalSheet_(ss);
    resetInternalData_(ss);
    deleteLegacyLogSheet_(ss);

    const state = {
      version: YT_CFG.STATE_VERSION,
      status: 'RUNNING',
      spreadsheetId: ss.getId(),

      outputSheetId: outputSheet.getSheetId(),
      outputSheetName: outputSheet.getName(),

      videoId: videoId,
      videoTitle: metadata.title,
      videoChannelId: metadata.channelId,
      videoChannelTitle: metadata.channelTitle,
      reportedCommentCount: metadata.commentCount,

      targetTopLevelCount: input.limit,
      includeReplies: input.includeReplies,

      nextThreadPageToken: '',
      threadDone: false,

      currentReplyParentId: '',
      nextReplyPageToken: '',

      topCount: 0,
      replyCount: 0,
      threadPages: 0,
      replyPages: 0,
      apiCalls: 1,

      startedAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      message: outputSheet.getName() + '에서 수집을 시작했습니다.',
      error: null
    };

    saveState_(state);

    // 사이드바가 닫혀도 수집이 이어지도록 예비 트리거를 만듭니다.
    scheduleContinuation_();

    return getSidebarState();

  } finally {
    lock.releaseLock();
  }
}


/**
 * 사이드바가 첫 실행 구간을 즉시 시작할 때 호출합니다.
 */
function runCollectionNow() {
  continueCommentCollection();
  return getSidebarState();
}


/**
 * 저장된 상태에서 댓글 수집을 계속합니다.
 */
function continueCommentCollection() {
  const lock = LockService.getScriptLock();

  if (!lock.tryLock(5000)) {
    return;
  }

  let ss = null;
  let state = null;
  let commentsSheet = null;

  try {
    state = loadState_();

    if (!state) {
      return;
    }

    validateStateVersion_(state);
    normalizeState_(state);

    ss = SpreadsheetApp.openById(state.spreadsheetId);
    ensureInternalSheet_(ss);
    deleteLegacyLogSheet_(ss);

    commentsSheet = getOutputSheetForState_(ss, state);
    const internalSheet = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);
    const existingIds = getExistingCommentIds_(internalSheet);
    const existingCounts = getExistingCounts_(internalSheet);

    // 시트 기록 직후 상태 저장 전에 실행이 끊긴 상황을 보정합니다.
    state.topCount = existingCounts.top;
    state.replyCount = existingCounts.reply;

    const runStartedAt = Date.now();

    while (Date.now() - runStartedAt < YT_CFG.MAX_RUN_MS) {
      if (isCancelRequested_()) {
        finalizeCancellation_(ss, commentsSheet, state);
        return;
      }

      // 처리 중이던 답글 페이지가 있으면 먼저 이어서 처리합니다.
      if (state.currentReplyParentId) {
        processReplyPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      // 내부 시트에서 답글 수집이 필요한 최상위 댓글을 하나 선택합니다.
      const pendingReply = claimNextPendingReply_(internalSheet);

      if (pendingReply) {
        state.currentReplyParentId = pendingReply.commentId;
        state.nextReplyPageToken = pendingReply.pageToken || '';
        saveState_(state);
        continue;
      }

      // 답글 대기 항목이 없을 때 다음 최상위 댓글 페이지를 가져옵니다.
      if (!state.threadDone) {
        processThreadPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      finishCollection_(ss, commentsSheet, state);
      return;
    }

    state.updatedAt = new Date().toISOString();
    state.message = '실행 시간을 고려하여 진행 상태를 저장했습니다.';
    saveState_(state);
    scheduleContinuation_();

  } catch (error) {
    deleteContinuationTriggers_();

    const errorInfo = normalizeErrorInfo_(error, '댓글 수집');

    if (errorInfo.code === 'API_KEY_INVALID') {
      getUserProperties_().deleteProperty(YT_CFG.API_KEY_PROP);
    }

    if (commentsSheet) {
      try {
        finalizeCommentsSheet_(commentsSheet);
      } catch (formatError) {
        console.error(formatError);
      }
    }

    if (state) {
      state.status = 'ERROR';
      state.updatedAt = new Date().toISOString();
      state.message = errorInfo.summary;
      state.error = errorInfo;
      saveLastResult_(state, 'ERROR', errorInfo.summary, errorInfo);
    }

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    console.error(error);
    throwStructuredError_(errorInfo);

  } finally {
    lock.releaseLock();
  }
}


/**
 * 진행 중인 수집을 취소합니다.
 */
function cancelCommentCollection() {
  const props = getUserProperties_();
  const state = loadState_();

  if (!state) {
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
    deleteContinuationTriggers_();
    return getSidebarState();
  }

  props.setProperty(YT_CFG.CANCEL_REQUEST_PROP, 'true');
  deleteContinuationTriggers_();

  const lock = LockService.getScriptLock();

  // 다른 수집 실행이 없다면 이 호출에서 즉시 취소를 마무리합니다.
  if (lock.tryLock(200)) {
    try {
      const latestState = loadState_();

      if (latestState) {
        const ss = SpreadsheetApp.openById(latestState.spreadsheetId);
        ensureInternalSheet_(ss);
        const commentsSheet = getOutputSheetForState_(ss, latestState);
        finalizeCancellation_(ss, commentsSheet, latestState);
      }
    } finally {
      lock.releaseLock();
    }
  }

  return getSidebarState();
}


/**
 * 최상위 댓글 스레드 한 페이지를 처리합니다.
 */
function processThreadPage_(state, commentsSheet, internalSheet, existingIds) {
  const remaining = state.targetTopLevelCount - state.topCount;

  if (remaining <= 0) {
    state.threadDone = true;
    state.nextThreadPageToken = '';
    return;
  }

  const params = {
    part: state.includeReplies ? 'snippet,replies' : 'snippet',
    videoId: state.videoId,
    maxResults: Math.min(100, remaining),
    textFormat: 'plainText'
  };

  if (state.nextThreadPageToken) {
    params.pageToken = state.nextThreadPageToken;
  }

  const data = youtubeGet_('commentThreads', params);

  state.apiCalls += 1;
  state.threadPages += 1;

  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();
  const items = Array.isArray(data.items) ? data.items : [];

  let topAdded = 0;
  let replyAdded = 0;
  let nextTopNumber = state.topCount + 1;

  items.forEach(function(thread) {
    if (state.topCount + topAdded >= state.targetTopLevelCount) {
      return;
    }

    const threadSnippet = thread.snippet || {};
    const topComment = threadSnippet.topLevelComment;

    if (!topComment || !topComment.id) {
      return;
    }

    const topCommentId = String(topComment.id);

    if (existingIds.has(topCommentId) || batchIds.has(topCommentId)) {
      return;
    }

    const topNumber = String(nextTopNumber);
    nextTopNumber += 1;

    const totalReplyCount = Number(threadSnippet.totalReplyCount || 0);
    let replyStatus = 'DONE';
    let nextReplyIndex = 1;

    commentRows.push(
      commentToOutputRow_(state, topComment, topNumber)
    );

    batchIds.add(topCommentId);
    topAdded += 1;

    const inlineReplies =
      thread.replies && Array.isArray(thread.replies.comments)
        ? thread.replies.comments
        : [];

    if (state.includeReplies && totalReplyCount > 0) {
      if (inlineReplies.length === totalReplyCount) {
        inlineReplies.forEach(function(reply) {
          if (!reply || !reply.id) {
            return;
          }

          const replyId = String(reply.id);

          if (existingIds.has(replyId) || batchIds.has(replyId)) {
            return;
          }

          const displayNumber = topNumber + '_' + nextReplyIndex;
          nextReplyIndex += 1;

          commentRows.push(
            commentToOutputRow_(state, reply, displayNumber)
          );

          internalRows.push(
            buildInternalRow_(
              replyId,
              topCommentId,
              displayNumber,
              'reply',
              '',
              '',
              '',
              ''
            )
          );

          batchIds.add(replyId);
          replyAdded += 1;
        });
      } else {
        // commentThreads.list의 replies에는 전체 답글이 보장되지 않으므로
        // comments.list로 전체 답글을 다시 가져옵니다.
        replyStatus = 'PENDING';
        nextReplyIndex = 1;
      }
    }

    internalRows.push(
      buildInternalRow_(
        topCommentId,
        '',
        topNumber,
        'topLevel',
        replyStatus,
        nextReplyIndex,
        totalReplyCount,
        ''
      )
    );
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.topCount += topAdded;
  state.replyCount += replyAdded;

  const reachedTarget = state.topCount >= state.targetTopLevelCount;
  const hasNextPage = Boolean(data.nextPageToken);

  state.nextThreadPageToken =
    !reachedTarget && hasNextPage
      ? data.nextPageToken
      : '';

  state.threadDone = reachedTarget || !hasNextPage;
  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 특정 최상위 댓글의 답글 한 페이지를 처리합니다.
 */
function processReplyPage_(state, commentsSheet, internalSheet, existingIds) {
  const topRecord = findInternalRecordByCommentId_(
    internalSheet,
    state.currentReplyParentId
  );

  if (!topRecord) {
    // 내부 상태가 사라진 경우 현재 항목을 건너뛰고 다음 대기 항목을 찾습니다.
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
    return;
  }

  const params = {
    part: 'snippet',
    parentId: state.currentReplyParentId,
    maxResults: 100,
    textFormat: 'plainText'
  };

  const pageToken =
    state.nextReplyPageToken || topRecord.replyPageToken || '';

  if (pageToken) {
    params.pageToken = pageToken;
  }

  const data = youtubeGet_('comments', params);

  state.apiCalls += 1;
  state.replyPages += 1;

  const items = Array.isArray(data.items) ? data.items : [];
  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();

  let nextReplyIndex = Number(topRecord.nextReplyIndex || 1);
  let replyAdded = 0;

  items.forEach(function(reply) {
    if (!reply || !reply.id) {
      return;
    }

    const replyId = String(reply.id);

    if (existingIds.has(replyId) || batchIds.has(replyId)) {
      return;
    }

    const displayNumber =
      String(topRecord.displayNumber) + '_' + nextReplyIndex;

    nextReplyIndex += 1;

    commentRows.push(
      commentToOutputRow_(state, reply, displayNumber)
    );

    internalRows.push(
      buildInternalRow_(
        replyId,
        state.currentReplyParentId,
        displayNumber,
        'reply',
        '',
        '',
        '',
        ''
      )
    );

    batchIds.add(replyId);
    replyAdded += 1;
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.replyCount += replyAdded;

  const nextPageToken = data.nextPageToken || '';
  const nextStatus = nextPageToken ? 'IN_PROGRESS' : 'DONE';

  updateTopReplyProgress_(
    internalSheet,
    topRecord.rowNumber,
    nextStatus,
    nextReplyIndex,
    nextPageToken
  );

  if (nextPageToken) {
    state.nextReplyPageToken = nextPageToken;
  } else {
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
  }

  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 내부 시트에서 답글 수집 대기 중인 최상위 댓글 하나를 선택합니다.
 */
function claimNextPendingReply_(internalSheet) {
  const statusRange = internalSheet.getRange(
    2,
    YT_CFG.INTERNAL_COL.REPLY_STATUS,
    Math.max(internalSheet.getLastRow() - 1, 1),
    1
  );

  let found = statusRange
    .createTextFinder('IN_PROGRESS')
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    found = statusRange
      .createTextFinder('PENDING')
      .matchEntireCell(true)
      .useRegularExpression(false)
      .findNext();
  }

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  if (values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] === 'PENDING') {
    internalSheet
      .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS)
      .setValue('IN_PROGRESS');
  }

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    pageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 댓글 1건을 사용자가 보는 8열 행으로 변환합니다.
 */
function commentToOutputRow_(state, comment, displayNumber) {
  const snippet = (comment && comment.snippet) || {};
  const text = String(snippet.textDisplay || '');

  return [
    String(displayNumber),
    safeCellText_(state.videoChannelTitle || ''),
    safeCellText_(state.videoTitle || ''),
    safeCellText_(snippet.authorDisplayName || ''),
    safeCellText_(text),
    Number(snippet.likeCount || 0),
    apiDateToSheetValue_(snippet.publishedAt),
    calculateCommentBytes_(text)
  ];
}


/**
 * 숨김 내부 시트의 행을 만듭니다.
 */
function buildInternalRow_(
  commentId,
  parentCommentId,
  displayNumber,
  commentType,
  replyStatus,
  nextReplyIndex,
  totalReplyCount,
  replyPageToken
) {
  return [
    safeCellText_(commentId || ''),
    safeCellText_(parentCommentId || ''),
    String(displayNumber || ''),
    String(commentType || ''),
    String(replyStatus || ''),
    nextReplyIndex === '' ? '' : Number(nextReplyIndex || 1),
    totalReplyCount === '' ? '' : Number(totalReplyCount || 0),
    safeCellText_(replyPageToken || '')
  ];
}


/**
 * 댓글 행과 내부 관리 행을 각각 일괄 기록합니다.
 */
function appendCollectedRecords_(
  commentsSheet,
  internalSheet,
  commentRows,
  internalRows
) {
  if (commentRows.length !== internalRows.length) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_ROW_MISMATCH',
      '댓글 저장 구조를 확인해야 합니다.',
      '댓글 행과 내부 관리 행의 개수가 일치하지 않습니다.',
      ['수집 상태를 기록하는 내부 데이터가 일시적으로 어긋났습니다.'],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  if (commentRows.length === 0) {
    return;
  }

  commentsSheet
    .getRange(
      commentsSheet.getLastRow() + 1,
      1,
      commentRows.length,
      YT_CFG.HEADERS.length
    )
    .setValues(commentRows);

  internalSheet
    .getRange(
      internalSheet.getLastRow() + 1,
      1,
      internalRows.length,
      YT_CFG.INTERNAL_HEADERS.length
    )
    .setValues(internalRows);
}


/**
 * 내부 시트에서 특정 댓글 ID의 관리 행을 찾습니다.
 */
function findInternalRecordByCommentId_(internalSheet, commentId) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return null;
  }

  const found = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .createTextFinder(String(commentId || ''))
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    replyStatus: String(
      values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    replyPageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 최상위 댓글의 답글 수집 진행 정보를 갱신합니다.
 */
function updateTopReplyProgress_(
  internalSheet,
  rowNumber,
  status,
  nextReplyIndex,
  pageToken
) {
  internalSheet
    .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS, 1, 4)
    .setValues([[
      status,
      Number(nextReplyIndex || 1),
      internalSheet
        .getRange(rowNumber, YT_CFG.INTERNAL_COL.TOTAL_REPLY_COUNT)
        .getValue(),
      pageToken || ''
    ]]);
}


/**
 * 완료 처리
 */
function finishCollection_(ss, commentsSheet, state) {
  state.status = 'COMPLETED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = state.topCount < state.targetTopLevelCount
    ? '댓글 ' +
      state.topCount +
      '개와 대댓글 ' +
      state.replyCount +
      '개를 수집했습니다.'
    : '댓글 수집을 완료했습니다.';
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'COMPLETED', state.message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


function isCancelRequested_() {
  return getUserProperties_().getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';
}


/**
 * 취소 처리
 */
function finalizeCancellation_(ss, commentsSheet, state) {
  const message = '사용자가 수집을 취소했습니다. 이미 저장된 댓글은 유지됩니다.';

  state.status = 'CANCELLED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = message;
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'CANCELLED', message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


/**
 * API 키가 YouTube Data API 요청에 사용 가능한지 확인합니다.
 */
function validateApiKey_(apiKey) {
  youtubeGetWithKey_(
    'videos',
    {
      part: 'id',
      id: 'jNQXAC9IVRw'
    },
    apiKey
  );
}


/**
 * 영상 메타데이터를 조회합니다.
 */
function getVideoMetadataWithKey_(videoId, apiKey) {
  const data = youtubeGetWithKey_(
    'videos',
    {
      part: 'snippet,statistics',
      id: videoId
    },
    apiKey
  );

  if (!Array.isArray(data.items) || data.items.length === 0) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '입력한 영상 주소에 해당하는 공개 영상을 YouTube Data API에서 조회하지 못했습니다.',
      [
        '영상 주소나 11자리 영상 ID가 정확하지 않을 수 있습니다.',
        '영상이 삭제되었거나 비공개 상태일 수 있습니다.',
        '연령·지역·계정 권한에 따라 접근이 제한된 영상일 수 있습니다.'
      ],
      [
        '브라우저에서 해당 영상 주소가 정상적으로 열리는지 확인합니다.',
        '주소 표시줄의 영상 URL 전체를 다시 복사합니다.',
        '사이드바의 영상 주소를 교체한 뒤 수집을 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: { videoId: videoId }
      }
    ));
  }

  const item = data.items[0];
  const snippet = item.snippet || {};
  const statistics = item.statistics || {};

  return {
    title: snippet.title || '',
    channelId: snippet.channelId || '',
    channelTitle: snippet.channelTitle || '',
    commentCount: statistics.commentCount || ''
  };
}


/**
 * 저장된 API 키로 YouTube Data API를 호출합니다.
 */
function youtubeGet_(resource, params) {
  return youtubeGetWithKey_(resource, params, getApiKey_());
}


/**
 * YouTube Data API GET 요청을 수행합니다.
 */
function youtubeGetWithKey_(resource, params, apiKey) {
  const queryParams = Object.assign({}, params, { key: apiKey });

  const query = Object.keys(queryParams)
    .filter(function(key) {
      const value = queryParams[key];
      return value !== undefined && value !== null && value !== '';
    })
    .map(function(key) {
      return encodeURIComponent(key) + '=' + encodeURIComponent(queryParams[key]);
    })
    .join('&');

  const url = YT_CFG.API_BASE + '/' + resource + '?' + query;
  const transientCodes = [429, 500, 502, 503, 504];

  for (let attempt = 0; attempt < 3; attempt += 1) {
    let response;

    try {
      response = UrlFetchApp.fetch(url, {
        method: 'get',
        muteHttpExceptions: true,
        headers: { Accept: 'application/json' }
      });
    } catch (networkError) {
      if (attempt < 2) {
        Utilities.sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      throwStructuredError_(buildErrorInfo_(
        'NETWORK_REQUEST_FAILED',
        'YouTube 서버에 연결하지 못했습니다.',
        'Apps Script에서 YouTube Data API로 보내는 외부 요청이 완료되지 않았습니다.',
        [
          'Google 서비스 또는 네트워크에 일시적인 장애가 발생했을 수 있습니다.',
          'Apps Script의 외부 요청 권한이 승인되지 않았을 수 있습니다.'
        ],
        [
          '잠시 뒤 같은 작업을 다시 실행합니다.',
          'Apps Script 권한 승인 화면이 나타나면 요청된 권한을 허용합니다.',
          'Apps Script의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.'
        ],
        {
          actionLabel: '확인',
          technical: {
            resource: resource,
            originalMessage: String(networkError && networkError.message || networkError)
          }
        }
      ));
    }

    const statusCode = response.getResponseCode();
    const responseText = response.getContentText();

    if (statusCode >= 200 && statusCode < 300) {
      return responseText ? JSON.parse(responseText) : {};
    }

    if (transientCodes.indexOf(statusCode) >= 0 && attempt < 2) {
      Utilities.sleep(Math.pow(2, attempt) * 1000);
      continue;
    }

    const parsedError = parseYouTubeErrorResponse_(responseText);

    throwStructuredError_(classifyYouTubeApiError_(
      statusCode,
      parsedError.reason,
      parsedError.message,
      resource
    ));
  }

  throwStructuredError_(buildErrorInfo_(
    'YOUTUBE_REQUEST_REPEATED_FAILURE',
    'YouTube API 요청이 반복적으로 실패했습니다.',
    '일시적인 서버 장애가 재시도 후에도 계속되었습니다.',
    ['YouTube 또는 Google 네트워크 서비스가 불안정할 수 있습니다.'],
    [
      '잠시 뒤 같은 작업을 다시 실행합니다.',
      '반복되면 Apps Script의 ‘실행’ 기록을 확인합니다.'
    ],
    { actionLabel: '확인', technical: { resource: resource } }
  ));
}


function parseYouTubeErrorResponse_(responseText) {
  let reason = '';
  let message = String(responseText || '');

  try {
    const parsed = JSON.parse(responseText);

    if (parsed.error) {
      message = parsed.error.message || message;

      if (Array.isArray(parsed.error.errors) && parsed.error.errors[0]) {
        reason = parsed.error.errors[0].reason || '';
      }

      if (!reason && parsed.error.status) {
        reason = parsed.error.status;
      }
    }
  } catch (parseError) {
    // JSON이 아닌 오류 본문은 문자열 그대로 분류합니다.
  }

  return {
    reason: String(reason || ''),
    message: String(message || '')
  };
}


/**
 * YouTube API 오류를 한국어 모달용 정보로 분류합니다.
 */
function classifyYouTubeApiError_(statusCode, reason, message, resource) {
  const reasonText = String(reason || '');
  const messageText = String(message || '');
  const combined = (reasonText + ' ' + messageText).toLowerCase();
  const technical = {
    httpStatus: statusCode,
    apiReason: reasonText,
    resource: resource,
    originalMessage: messageText
  };

  if (
    combined.indexOf('keyinvalid') >= 0 ||
    combined.indexOf('api key not valid') >= 0 ||
    combined.indexOf('api_key_invalid') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_INVALID',
      'API 키를 사용할 수 없습니다.',
      '입력한 API 키가 정확하지 않거나 삭제·재발급되어 현재 요청에 사용할 수 없습니다.',
      [
        'API 키 일부가 누락되었을 수 있습니다.',
        'Google Cloud에서 기존 키가 삭제되거나 재발급되었을 수 있습니다.',
        'API 키가 아닌 다른 프로젝트 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 전체를 다시 복사합니다.',
        '사이드바에서 API 키를 다시 입력하고 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') >= 0 ||
    combined.indexOf('access not configured') >= 0 ||
    combined.indexOf('service_disabled') >= 0 ||
    combined.indexOf('api_disabled') >= 0 ||
    combined.indexOf('has not been used in project') >= 0 ||
    combined.indexOf('it is disabled') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_API_NOT_ENABLED',
      'YouTube Data API v3가 활성화되어 있지 않습니다.',
      'API 키가 속한 Google Cloud 프로젝트에서 YouTube Data API v3 사용 설정을 켜야 합니다.',
      [
        'API 키를 만든 프로젝트에서 YouTube Data API v3를 아직 활성화하지 않았습니다.',
        'API를 활성화한 프로젝트와 API 키를 발급한 프로젝트가 다를 수 있습니다.'
      ],
      [
        'Google Cloud Console에서 API 키를 만든 프로젝트를 선택합니다.',
        '‘API 및 서비스 → 라이브러리’로 이동합니다.',
        '‘YouTube Data API v3’를 검색하고 ‘사용’을 누릅니다.',
        '설정 반영을 위해 1~5분 기다린 뒤 API 키를 다시 저장합니다.'
      ],
      {
        helpLabel: 'YouTube Data API 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/library/youtube.googleapis.com',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('iprefererblocked') >= 0 ||
    combined.indexOf('referer') >= 0 && combined.indexOf('blocked') >= 0 ||
    combined.indexOf('api key restrictions') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_APPLICATION_RESTRICTION',
      'API 키의 애플리케이션 제한이 Apps Script 요청을 차단했습니다.',
      '현재 키에 설정된 웹사이트·IP 제한이 Apps Script의 UrlFetch 요청 방식과 맞지 않습니다.',
      [
        'HTTP 리퍼러 제한 또는 특정 IP 주소 제한이 적용되어 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키의 애플리케이션 제한을 확인합니다.',
        'Apps Script에서 사용할 수 있는 제한 방식으로 조정합니다.',
        'API 제한은 ‘YouTube Data API v3’로 유지합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') < 0 &&
    (
      combined.indexOf('forbidden') >= 0 &&
      combined.indexOf('api') >= 0 &&
      combined.indexOf('key') >= 0
    )
  ) {
    return buildErrorInfo_(
      'API_KEY_API_RESTRICTION',
      'API 키의 API 제한 설정을 확인해야 합니다.',
      '현재 API 키가 YouTube Data API v3 호출을 허용하지 않을 수 있습니다.',
      [
        'API 키의 ‘API 제한’ 목록에서 YouTube Data API v3가 빠져 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키를 선택합니다.',
        '‘API 제한’에서 YouTube Data API v3를 허용합니다.',
        '저장 후 1~5분 뒤 다시 실행합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('quotaexceeded') >= 0 ||
    combined.indexOf('dailylimitexceeded') >= 0 ||
    combined.indexOf('daily limit') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_QUOTA_EXCEEDED',
      'YouTube API의 오늘 할당량을 모두 사용했습니다.',
      '현재 Google Cloud 프로젝트에서 오늘 사용할 수 있는 YouTube Data API 할당량이 남아 있지 않습니다.',
      ['같은 프로젝트의 다른 프로그램에서도 YouTube API 할당량을 사용했을 수 있습니다.'],
      [
        'Google Cloud Console에서 YouTube Data API 사용량을 확인합니다.',
        '일일 할당량이 갱신된 뒤 다시 실행합니다.',
        '필요하면 다음 수집의 댓글 개수를 줄입니다.'
      ],
      {
        helpLabel: 'YouTube API 할당량 열기',
        helpUrl: 'https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas',
        actionLabel: '확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('ratelimitexceeded') >= 0 ||
    combined.indexOf('userratelimitexceeded') >= 0 ||
    statusCode === 429
  ) {
    return buildErrorInfo_(
      'YOUTUBE_RATE_LIMIT',
      '짧은 시간에 API 요청이 많이 발생했습니다.',
      'YouTube Data API가 일시적으로 요청 속도를 제한했습니다.',
      ['여러 수집 작업을 연속으로 실행했을 수 있습니다.'],
      [
        '현재 작업이 자동 재개되는지 확인합니다.',
        '몇 분 뒤 다시 실행합니다.',
        '동시에 여러 스프레드시트에서 같은 API 키를 사용하고 있다면 실행 횟수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (combined.indexOf('commentsdisabled') >= 0) {
    return buildErrorInfo_(
      'COMMENTS_DISABLED',
      '이 영상에서는 댓글을 수집할 수 없습니다.',
      '영상 게시자가 댓글 기능을 사용하지 않도록 설정했습니다.',
      ['영상의 댓글 기능이 꺼져 있거나 YouTube 정책에 따라 제한되었습니다.'],
      [
        '영상 페이지에서 댓글 영역이 표시되는지 확인합니다.',
        '댓글이 허용된 다른 영상 주소를 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('videonotfound') >= 0 ||
    combined.indexOf('video not found') >= 0
  ) {
    return buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '영상 주소가 잘못되었거나 영상이 삭제·비공개 상태일 수 있습니다.',
      [
        '영상 ID가 정확하지 않을 수 있습니다.',
        '영상 공개 상태가 변경되었을 수 있습니다.'
      ],
      [
        '브라우저에서 영상 주소가 정상적으로 열리는지 확인합니다.',
        '영상 URL 전체를 다시 복사해 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (statusCode >= 500) {
    return buildErrorInfo_(
      'YOUTUBE_SERVER_ERROR',
      'YouTube 서버에서 일시적인 오류가 발생했습니다.',
      'YouTube Data API 서버가 현재 요청을 정상적으로 처리하지 못했습니다.',
      ['YouTube 측의 일시적인 서비스 장애일 수 있습니다.'],
      [
        '잠시 뒤 같은 작업을 다시 실행합니다.',
        '진행 중인 수집이라면 자동 재개 여부를 확인합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (statusCode === 403) {
    return buildErrorInfo_(
      'YOUTUBE_ACCESS_FORBIDDEN',
      'YouTube 데이터에 접근할 수 없습니다.',
      'API 키 설정, 영상 공개 상태 또는 Google Cloud 프로젝트 권한을 확인해야 합니다.',
      [
        'API 키 제한 설정이 요청을 차단했을 수 있습니다.',
        '영상이 공개 API에서 접근할 수 없는 상태일 수 있습니다.'
      ],
      [
        'API 키의 API 제한과 애플리케이션 제한을 확인합니다.',
        '영상이 공개 상태인지 확인합니다.',
        'Google Cloud에서 YouTube Data API v3가 활성화되어 있는지 확인합니다.'
      ],
      {
        helpLabel: 'API 키 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (statusCode === 400) {
    return buildErrorInfo_(
      'YOUTUBE_BAD_REQUEST',
      'YouTube API 요청 형식을 확인해야 합니다.',
      '영상 주소 또는 요청 매개변수 중 하나를 YouTube API가 처리하지 못했습니다.',
      ['영상 주소가 올바르지 않거나 API 요청 값이 허용 범위를 벗어났을 수 있습니다.'],
      [
        '영상 주소를 다시 확인합니다.',
        '수집 개수와 정렬 기준을 확인합니다.',
        '같은 문제가 계속되면 새 수집으로 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '입력값 확인',
        technical: technical
      }
    );
  }

  return buildErrorInfo_(
    'YOUTUBE_API_ERROR',
    'YouTube API 요청을 완료하지 못했습니다.',
    'YouTube Data API가 요청을 거부하거나 처리하지 못했습니다.',
    ['API 키, 영상 공개 상태, 할당량 또는 네트워크 상태를 확인해야 합니다.'],
    [
      'API 키 설정과 YouTube Data API 활성화 여부를 확인합니다.',
      '영상 주소가 공개 영상인지 확인합니다.',
      '잠시 뒤 다시 실행합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}


/**
 * 영상 URL 또는 11자리 영상 ID에서 videoId를 추출합니다.
 */
function extractVideoId_(input) {
  const text = String(input || '').trim();

  if (/^[A-Za-z0-9_-]{11}$/.test(text)) {
    return text;
  }

  const patterns = [
    /[?&]v=([A-Za-z0-9_-]{11})/,
    /youtu\.be\/([A-Za-z0-9_-]{11})/,
    /youtube(?:-nocookie)?\.com\/(?:embed|shorts|live)\/([A-Za-z0-9_-]{11})/
  ];

  for (let i = 0; i < patterns.length; i += 1) {
    const match = text.match(patterns[i]);

    if (match) {
      return match[1];
    }
  }

  throwStructuredError_(buildErrorInfo_(
    'INVALID_VIDEO_URL',
    'YouTube 영상 주소를 확인해야 합니다.',
    '입력한 값에서 11자리 YouTube 영상 ID를 찾지 못했습니다.',
    [
      '영상 주소 일부가 빠졌을 수 있습니다.',
      '채널·재생목록 주소를 입력했을 수 있습니다.'
    ],
    [
      'YouTube에서 수집할 영상을 엽니다.',
      '브라우저 주소 표시줄의 영상 URL 전체를 복사합니다.',
      '사이드바의 영상 주소 입력란에 붙여 넣습니다.'
    ],
    {
      focusTarget: 'videoUrl',
      actionLabel: '영상 주소 다시 입력'
    }
  ));
}


/**
 * 사이드바 입력값을 검증합니다.
 */
function normalizeSidebarInput_(formData) {
  const form = formData || {};
  const videoUrl = String(form.videoUrl || '').trim();
  const limit = parseInt(form.limit, 10);

  if (!videoUrl) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_URL_REQUIRED',
      'YouTube 영상 주소를 입력해야 합니다.',
      '수집 대상 영상 주소가 비어 있습니다.',
      ['영상 주소 입력란에 값이 없습니다.'],
      ['수집할 YouTube 영상의 URL을 입력합니다.'],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 입력'
      }
    ));
  }

  if (!Number.isInteger(limit)) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_INVALID',
      '수집 개수를 정수로 입력해야 합니다.',
      '수집할 최상위 댓글 개수가 올바른 정수 형식이 아닙니다.',
      ['빈 값, 소수 또는 문자가 입력되었을 수 있습니다.'],
      ['1 이상의 정수를 입력합니다.'],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 입력'
      }
    ));
  }

  if (limit < YT_CFG.MIN_LIMIT || limit > YT_CFG.MAX_LIMIT) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_OUT_OF_RANGE',
      '수집 개수가 허용 범위를 벗어났습니다.',
      '수집 개수는 ' + YT_CFG.MIN_LIMIT + '개 이상 ' +
        YT_CFG.MAX_LIMIT + '개 이하로 입력해야 합니다.',
      ['입력한 개수가 코드에 설정된 운영 범위를 벗어났습니다.'],
      [
        YT_CFG.MIN_LIMIT + '~' + YT_CFG.MAX_LIMIT +
          ' 사이의 정수를 입력합니다.'
      ],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 수정'
      }
    ));
  }

  return {
    videoUrl: videoUrl,
    limit: limit,
    includeReplies: form.includeReplies === true
  };
}


/**
 * 결과 시트와 숨김 내부 시트를 준비합니다.
 */
function ensureInternalSheet_(ss) {
  let internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    internal = ss.insertSheet(YT_CFG.INTERNAL_SHEET);
  }

  ensureColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);

  if (internal.getLastRow() === 0) {
    internal
      .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
      .setValues([YT_CFG.INTERNAL_HEADERS]);
  }

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 새 수집에 사용할 결과 시트를 시트1, 시트2, 시트3 ... 순서로 만듭니다.
 *
 * 새 스프레드시트에 기본 빈 '시트1' 하나만 존재하는 경우에는 그 시트를
 * 첫 결과 시트로 사용합니다. 그 이후 수집부터는 항상 새 시트를 추가합니다.
 */
function createNextOutputSheet_(ss) {
  const sheets = ss.getSheets();

  if (
    sheets.length === 1 &&
    sheets[0].getName() === YT_CFG.OUTPUT_SHEET_PREFIX + '1' &&
    isSheetCompletelyBlank_(sheets[0])
  ) {
    prepareOutputSheet_(sheets[0]);
    return sheets[0];
  }

  let maxNumber = 0;
  const namePattern = new RegExp(
    '^' + escapeRegExp_(YT_CFG.OUTPUT_SHEET_PREFIX) + '(\\d+)$'
  );

  sheets.forEach(function(sheet) {
    const match = sheet.getName().match(namePattern);

    if (match) {
      maxNumber = Math.max(maxNumber, Number(match[1] || 0));
    }
  });

  let nextNumber = maxNumber + 1;
  let nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;

  while (ss.getSheetByName(nextName)) {
    nextNumber += 1;
    nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;
  }

  const sheet = ss.insertSheet(nextName);
  prepareOutputSheet_(sheet);
  return sheet;
}


function isSheetCompletelyBlank_(sheet) {
  return sheet.getLastRow() === 0 && sheet.getLastColumn() === 0;
}


function prepareOutputSheet_(sheet) {
  if (sheet.getFilter()) {
    sheet.getFilter().remove();
  }

  sheet.clear();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setValues([YT_CFG.HEADERS]);

  sheet.setFrozenRows(1);
  sheet.getRange('A:A').setNumberFormat('@');
  formatCommentsSheet_(sheet);
}


/**
 * 새 수집을 위해 숨김 내부 시트만 초기화합니다.
 * 이전 결과 시트의 내용은 변경하지 않습니다.
 */
function resetInternalData_(ss) {
  const internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_SHEET_NOT_FOUND',
      '내부 관리 시트를 준비하지 못했습니다.',
      '댓글 수집 상태를 저장하는 숨김 시트가 존재하지 않습니다.',
      ['내부 시트 생성 과정이 완료되지 않았습니다.'],
      ['사이드바를 닫았다가 다시 열고 새 수집을 시작합니다.'],
      { actionLabel: '확인' }
    ));
  }

  internal.clear();
  ensureExactColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);
  internal
    .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .setValues([YT_CFG.INTERNAL_HEADERS]);

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 현재 수집 상태에 연결된 결과 시트를 찾습니다.
 */
function getOutputSheetForState_(ss, state) {
  const expectedId = Number(state.outputSheetId || 0);
  let outputSheet = null;

  if (expectedId > 0) {
    outputSheet = ss.getSheets().find(function(sheet) {
      return sheet.getSheetId() === expectedId;
    }) || null;
  }

  if (!outputSheet && state.outputSheetName) {
    outputSheet = ss.getSheetByName(String(state.outputSheetName));
  }

  if (!outputSheet) {
    throwStructuredError_(buildErrorInfo_(
      'OUTPUT_SHEET_NOT_FOUND',
      '수집 결과 시트를 찾을 수 없습니다.',
      '현재 수집 작업과 연결된 결과 시트가 삭제되었거나 이름과 식별 정보가 변경되었습니다.',
      [
        '수집 중 결과 시트를 삭제했을 수 있습니다.',
        '스프레드시트 구조가 외부 작업으로 변경되었을 수 있습니다.'
      ],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }

  return outputSheet;
}


function escapeRegExp_(text) {
  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}


/**
 * 이전 버전이 만든 수집로그 시트를 제거합니다.
 */
function deleteLegacyLogSheet_(ss) {
  const logSheet = ss.getSheetByName(YT_CFG.LEGACY_LOG_SHEET);

  if (logSheet && ss.getSheets().length > 1) {
    ss.deleteSheet(logSheet);
  }
}


/**
 * 댓글 시트를 번호 순으로 정렬하고 최종 서식을 적용합니다.
 */
function finalizeCommentsSheet_(sheet) {
  sortCommentsByDisplayNumber_(sheet);
  formatCommentsSheet_(sheet);
}


function sortCommentsByDisplayNumber_(sheet) {
  const lastRow = sheet.getLastRow();

  if (lastRow <= 2) {
    return;
  }

  // 정렬용 임시 열 I, J를 만든 뒤 최상위 번호와 답글 번호로 정렬합니다.
  ensureColumnCount_(sheet, 10);

  const numberValues = sheet
    .getRange(2, 1, lastRow - 1, 1)
    .getDisplayValues();

  const sortKeys = numberValues.map(function(row) {
    const parts = String(row[0] || '').split('_');
    return [
      Number(parts[0] || 0),
      parts.length > 1 ? Number(parts[1] || 0) : 0
    ];
  });

  sheet
    .getRange(2, 9, sortKeys.length, 2)
    .setValues(sortKeys);

  sheet
    .getRange(2, 1, lastRow - 1, 10)
    .sort([
      { column: 9, ascending: true },
      { column: 10, ascending: true }
    ]);

  sheet.getRange(2, 9, lastRow - 1, 2).clearContent();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
}


function formatCommentsSheet_(sheet) {
  const lastRow = sheet.getLastRow();

  sheet.setFrozenRows(1);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setFontWeight('bold')
    .setWrap(true)
    .setVerticalAlignment('middle');

  sheet.getRange('A:A').setNumberFormat('@');

  if (lastRow > 1) {
    sheet
      .getRange(2, 7, lastRow - 1, 1)
      .setNumberFormat('yyyy-mm-dd hh:mm:ss');

    sheet
      .getRange(2, 5, lastRow - 1, 1)
      .setWrap(true)
      .setVerticalAlignment('top');

    sheet
      .getRange(2, 1, lastRow - 1, YT_CFG.HEADERS.length)
      .setVerticalAlignment('top');

    if (sheet.getFilter()) {
      sheet.getFilter().remove();
    }

    sheet
      .getRange(1, 1, lastRow, YT_CFG.HEADERS.length)
      .createFilter();
  }

  sheet.setColumnWidth(1, 90);
  sheet.setColumnWidth(2, 180);
  sheet.setColumnWidth(3, 260);
  sheet.setColumnWidth(4, 170);
  sheet.setColumnWidth(5, 520);
  sheet.setColumnWidth(6, 95);
  sheet.setColumnWidth(7, 155);
  sheet.setColumnWidth(8, 95);
}


/**
 * 숨김 내부 시트에 저장된 댓글 ID 집합을 만듭니다.
 */
function getExistingCommentIds_(internalSheet) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return new Set();
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .getDisplayValues();

  return new Set(
    values
      .map(function(row) {
        return row[0];
      })
      .filter(function(value) {
        return Boolean(value);
      })
  );
}


/**
 * 숨김 내부 시트 기준으로 실제 최상위 댓글·답글 수를 계산합니다.
 */
function getExistingCounts_(internalSheet) {
  const lastRow = internalSheet.getLastRow();
  const counts = { top: 0, reply: 0 };

  if (lastRow <= 1) {
    return counts;
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_TYPE, lastRow - 1, 1)
    .getDisplayValues();

  values.forEach(function(row) {
    if (row[0] === 'topLevel') {
      counts.top += 1;
    } else if (row[0] === 'reply') {
      counts.reply += 1;
    }
  });

  return counts;
}


/**
 * 댓글 글자수를 지정된 바이트 규칙으로 계산합니다.
 * - ASCII 영역(영문, 숫자, 공백, 일반 문장부호): 1바이트
 * - 한글을 포함한 비ASCII 유니코드 문자: 코드 포인트당 2바이트
 */
function calculateCommentBytes_(value) {
  const text = String(value || '');
  let bytes = 0;

  Array.from(text).forEach(function(character) {
    const codePoint = character.codePointAt(0);
    bytes += codePoint <= 0x7F ? 1 : 2;
  });

  return bytes;
}


/**
 * 외부 문자열이 시트 수식으로 실행되는 것을 방지합니다.
 */
function safeCellText_(value) {
  const text = value === undefined || value === null ? '' : String(value);
  return /^[=+\-@]/.test(text) ? "'" + text : text;
}


function apiDateToSheetValue_(value) {
  return value ? new Date(value) : '';
}


function ensureColumnCount_(sheet, requiredColumns) {
  const current = sheet.getMaxColumns();

  if (current < requiredColumns) {
    sheet.insertColumnsAfter(current, requiredColumns - current);
  }
}


function ensureExactColumnCount_(sheet, requiredColumns) {
  ensureColumnCount_(sheet, requiredColumns);

  const current = sheet.getMaxColumns();

  if (current > requiredColumns) {
    sheet.deleteColumns(requiredColumns + 1, current - requiredColumns);
  }
}


function getUserProperties_() {
  return PropertiesService.getUserProperties();
}


function getApiKey_() {
  const apiKey = getUserProperties_().getProperty(YT_CFG.API_KEY_PROP);

  if (!apiKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키 설정이 필요합니다.',
      '댓글 수집을 시작하기 전에 YouTube Data API 키를 저장해야 합니다.',
      ['현재 사용자 계정에 저장된 API 키가 없습니다.'],
      [
        '사이드바 상단의 API 키 입력란에 키를 입력합니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  return apiKey.trim();
}


function loadState_() {
  const text = getUserProperties_().getProperty(YT_CFG.STATE_PROP);
  return text ? JSON.parse(text) : null;
}


function saveState_(state) {
  state.updatedAt = new Date().toISOString();
  const text = JSON.stringify(state);
  const byteLength = Utilities.newBlob(text).getBytes().length;

  if (byteLength > 8500) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_STORAGE_LIMIT',
      '수집 진행 상태를 저장할 수 없습니다.',
      'Apps Script 사용자 속성의 안전 저장 크기를 초과했습니다.',
      ['진행 상태 데이터가 예상보다 커졌습니다.'],
      [
        '현재 수집을 취소합니다.',
        '댓글 수집 개수를 줄여 새로 실행합니다.'
      ],
      { actionLabel: '확인', technical: { byteLength: byteLength } }
    ));
  }

  getUserProperties_().setProperty(YT_CFG.STATE_PROP, text);
}


function loadLastResult_() {
  const text = getUserProperties_().getProperty(YT_CFG.LAST_RESULT_PROP);
  return text ? JSON.parse(text) : null;
}


function saveLastResult_(state, status, message, errorInfo) {
  const result = {
    status: status,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: Number(state.targetTopLevelCount || 0),
    topCount: Number(state.topCount || 0),
    replyCount: Number(state.replyCount || 0),
    apiCalls: Number(state.apiCalls || 0),
    startedAt: state.startedAt || '',
    updatedAt: new Date().toISOString(),
    finishedAt: new Date().toISOString(),
    message: message || '',
    error: errorInfo || null
  };

  getUserProperties_().setProperty(
    YT_CFG.LAST_RESULT_PROP,
    JSON.stringify(result)
  );
}


function validateStateVersion_(state) {
  if (Number(state.version || 0) !== YT_CFG.STATE_VERSION) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_VERSION_MISMATCH',
      '이전 코드에서 시작된 수집 작업을 이어갈 수 없습니다.',
      '현재 Code.gs의 댓글 저장 구조가 이전 실행 상태와 다릅니다.',
      ['고정 결과 시트 또는 정렬 기준을 사용하던 이전 코드의 작업 상태가 남아 있습니다.'],
      [
        '사이드바에서 진행 중인 수집을 취소합니다.',
        '현재 코드로 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }
}


function normalizeState_(state) {
  state.currentReplyParentId = state.currentReplyParentId || '';
  state.nextReplyPageToken = state.nextReplyPageToken || '';
  state.nextThreadPageToken = state.nextThreadPageToken || '';
  state.threadDone = Boolean(state.threadDone);
  state.topCount = Number(state.topCount || 0);
  state.replyCount = Number(state.replyCount || 0);
  state.apiCalls = Number(state.apiCalls || 0);
  state.threadPages = Number(state.threadPages || 0);
  state.replyPages = Number(state.replyPages || 0);
  state.targetTopLevelCount = Number(state.targetTopLevelCount || 0);
  state.outputSheetId = Number(state.outputSheetId || 0);
  state.outputSheetName = String(state.outputSheetName || '');
  state.error = state.error || null;
}


function maskApiKey_(apiKey) {
  const key = String(apiKey || '');
  return '••••••••••••' + key.slice(-4);
}


function buildProgressForClient_(state, status) {
  const target = Number(state.targetTopLevelCount || 0);
  const top = Number(state.topCount || 0);
  const reply = Number(state.replyCount || 0);
  const percent = target > 0
    ? Math.min(100, Math.round((top / target) * 100))
    : 0;

  let stage = '대기 중';

  if (status === 'RUNNING') {
    if (state.currentReplyParentId) {
      stage = '답글 수집 중';
    } else if (!state.threadDone) {
      stage = '최상위 댓글 수집 중';
    } else {
      stage = '마무리 중';
    }
  } else if (status === 'COMPLETED') {
    stage = '완료';
  } else if (status === 'ERROR') {
    stage = '오류';
  } else if (status === 'CANCELLED') {
    stage = '취소됨';
  }

  return {
    status: status,
    stage: stage,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: target,
    topCount: top,
    replyCount: reply,
    totalRows: top + reply,
    apiCalls: Number(state.apiCalls || 0),
    percent: percent,
    startedAt: state.startedAt || '',
    updatedAt: state.updatedAt || '',
    message: state.message || '',
    error: state.error || null
  };
}


function buildServerProgressMessage_(state) {
  return (
    '최상위 댓글 ' +
    state.topCount +
    '/' +
    state.targetTopLevelCount +
    '개, 답글 ' +
    state.replyCount +
    '개를 저장했습니다.'
  );
}


function scheduleContinuation_() {
  deleteContinuationTriggers_();

  ScriptApp
    .newTrigger(YT_CFG.CONTINUE_HANDLER)
    .timeBased()
    .after(YT_CFG.CONTINUE_AFTER_MS)
    .create();
}


function deleteContinuationTriggers_() {
  ScriptApp.getProjectTriggers().forEach(function(trigger) {
    if (trigger.getHandlerFunction() === YT_CFG.CONTINUE_HANDLER) {
      ScriptApp.deleteTrigger(trigger);
    }
  });
}


/**
 * 한국어 모달용 오류 정보를 만듭니다.
 */
function buildErrorInfo_(code, title, summary, causes, steps, options) {
  const opts = options || {};

  return {
    code: String(code || 'UNKNOWN_ERROR'),
    title: String(title || '작업을 완료하지 못했습니다.'),
    summary: String(summary || '처리 중 문제가 발생했습니다.'),
    causes: Array.isArray(causes) ? causes.map(String) : [],
    steps: Array.isArray(steps) ? steps.map(String) : [],
    helpLabel: String(opts.helpLabel || ''),
    helpUrl: String(opts.helpUrl || ''),
    focusTarget: String(opts.focusTarget || ''),
    actionLabel: String(opts.actionLabel || '확인'),
    technical:
      opts.technical && typeof opts.technical === 'object'
        ? opts.technical
        : {}
  };
}


/**
 * 서버 오류를 Sidebar.html이 해석할 수 있는 구조화된 예외로 전달합니다.
 */
function throwStructuredError_(errorInfo) {
  throw new Error(
    YT_CFG.STRUCTURED_ERROR_PREFIX + JSON.stringify(errorInfo)
  );
}


function extractStructuredError_(rawText) {
  const raw = String(rawText || '');
  const markerIndex = raw.indexOf(YT_CFG.STRUCTURED_ERROR_PREFIX);

  if (markerIndex < 0) {
    return null;
  }

  const jsonText = raw.slice(
    markerIndex + YT_CFG.STRUCTURED_ERROR_PREFIX.length
  );

  try {
    return JSON.parse(jsonText);
  } catch (parseError) {
    return null;
  }
}


/**
 * Apps Script 자체 오류도 한국어 모달 정보로 변환합니다.
 */
function normalizeErrorInfo_(error, context) {
  const raw = error && error.message
    ? String(error.message)
    : String(error || '');

  const structured = extractStructuredError_(raw);

  if (structured) {
    return structured;
  }

  const lower = raw.toLowerCase();
  const technical = {
    context: String(context || '작업 실행'),
    originalMessage: raw
  };

  if (
    lower.indexOf('authorization is required') >= 0 ||
    lower.indexOf('you do not have permission') >= 0 ||
    lower.indexOf('permissions') >= 0 && lower.indexOf('required') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_AUTH_REQUIRED',
      'Google 권한 승인이 필요합니다.',
      '현재 계정이 스프레드시트 또는 외부 API 요청 권한을 아직 승인하지 않았습니다.',
      ['Apps Script를 처음 실행했거나 새로운 권한이 추가되었습니다.'],
      [
        '스프레드시트 메뉴에서 사이드바를 다시 엽니다.',
        '권한 검토 화면에서 현재 Google 계정을 선택합니다.',
        '요청되는 권한을 허용한 뒤 다시 실행합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('maximum execution time') >= 0 ||
    lower.indexOf('exceeded maximum execution time') >= 0 ||
    lower.indexOf('timed out') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_EXECUTION_TIMEOUT',
      '한 번의 실행 가능 시간을 초과했습니다.',
      '댓글 또는 답글 처리 시간이 길어 현재 실행 구간이 종료되었습니다.',
      ['대량 댓글 수집으로 한 번의 Apps Script 실행 시간이 길어졌습니다.'],
      [
        '사이드바를 다시 열어 진행 상태를 확인합니다.',
        '멈춘 경우 ‘중단 지점부터 실행’을 한 번 실행합니다.',
        '같은 문제가 반복되면 수집 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('service invoked too many times') >= 0 ||
    lower.indexOf('quota') >= 0 && lower.indexOf('apps script') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_SERVICE_QUOTA',
      'Apps Script 서비스 사용 한도를 초과했습니다.',
      '현재 Google 계정 또는 스크립트의 일일 서비스 사용량이 허용 범위를 넘었습니다.',
      ['짧은 시간에 많은 외부 요청이나 스프레드시트 쓰기 작업이 실행되었습니다.'],
      [
        '잠시 뒤 다시 실행합니다.',
        '같은 날 반복되면 다음 날 다시 실행합니다.',
        '한 번에 수집하는 댓글 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  return buildErrorInfo_(
    'UNEXPECTED_ERROR',
    '예상하지 못한 오류가 발생했습니다.',
    '오류 유형을 자동으로 판별하지 못했습니다.',
    [
      '네트워크, 권한, Google 서비스 상태 또는 실행 환경에서 문제가 발생했을 수 있습니다.'
    ],
    [
      '사이드바를 닫았다가 다시 열고 같은 작업을 한 번 더 실행합니다.',
      'Apps Script 편집기의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.',
      'API 키와 영상 주소를 다시 확인합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}

Sidebar.html

YouTube 댓글 수집기

YouTube Data API v3 → Google Sheets

1. API 키

YouTube Data API 키

최초 1회 저장합니다. 키는 사용자별 Apps Script 속성에 보관됩니다.

2. 수집 설정

API 키를 저장하면 수집 설정이 활성화됩니다.

YouTube 영상 주소

수집할 최상위 댓글 수

1~50,000개. 답글 포함 시 실제 저장 행 수가 이 값보다 많아질 수 있습니다.

대댓글도 모두 수집

새 수집을 시작할 때마다 ‘시트1’, ‘시트2’, ‘시트3’ 형식의 새 시트가 생성됩니다. 기존 수집 결과는 유지됩니다.

(3) 바른 API KEY 발급

(4) 민기쌤 생기부 도우미

Code.gs

// =================================================================
// [0] 초기 설정 및 메뉴
// =================================================================

function onOpen() {
  SpreadsheetApp.getUi().createMenu('민기쌤 생기부 도우미')
      .addItem('🚀 사이드바 열기', 'openSidebar') 
      .addToUi();
}

function renderView_(viewName) {
  var template = HtmlService.createTemplateFromFile('Sidebar');
  template.initialView = viewName || 'sidebar';
  return template.evaluate();
}

function openSidebar() {
  ensureBannedWordSheet_();
  var html = renderView_('sidebar')
      .setTitle('민기쌤 생기부 맞춤법 도우미')
      .setWidth(300); 
  SpreadsheetApp.getUi().showSidebar(html);
}

function openSpellCheckViewer() {
  var html = renderView_('spellcheck')
      .setWidth(1000) 
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '📝 Bareun 맞춤법 검사 및 수정');
}

function openBannedWordViewer() {
  var html = renderView_('banned')
      .setWidth(1000)
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '🚫 기재 금지어 점검');
}

// =================================================================
// [1] Bareun API 키 및 UI 설정
// =================================================================

function getBareunUserProperties_() {
  ensureBannedWordSheet_();
  var props = PropertiesService.getUserProperties();
  var currentPolicy = 'BAREUN_ONLY_KEYS_V3';
  var previousPolicy = props.getProperty('API_KEY_POLICY_VERSION');

  // 정책 변경 시 현재 기능에서 쓰지 않는 예전 사용자 설정을 한 번 정리합니다.
  if (previousPolicy !== currentPolicy) {
    var allowedProperties = {
      UI_STATE: true,
      API_KEY_POLICY_VERSION: true
    };
    // 바로 이전 사용자 입력형 정책에서 저장한 키만 보존합니다.
    if (previousPolicy === 'USER_SUPPLIED_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V2') {
      allowedProperties.USER_BAREUN_KEY = true;
    }
    Object.keys(props.getProperties()).forEach(function(propertyName) {
      if (!allowedProperties[propertyName]) props.deleteProperty(propertyName);
    });

    var previousUiState = {};
    try {
      previousUiState = JSON.parse(props.getProperty('UI_STATE') || '{}');
    } catch (e) {
      previousUiState = {};
    }
    var currentUiState = {};
    ['card-api', 'sub-api-settings', 'card-util'].forEach(function(id) {
      if (previousUiState[id]) currentUiState[id] = true;
    });
    props.setProperty('UI_STATE', JSON.stringify(currentUiState));
    props.setProperty('API_KEY_POLICY_VERSION', currentPolicy);
  }

  return props;
}

function saveUserBareunKey(bareunKey) {
  var props = getBareunUserProperties_();
  var cleanBareunKey = String(bareunKey || '').trim();

  if (!cleanBareunKey) {
    throw new Error('Bareun API 키를 입력해 주세요. 이 도우미는 API 키를 제공하지 않습니다.');
  }

  props.setProperty('USER_BAREUN_KEY', cleanBareunKey);
  return { hasBareun: true };
}

function checkUserBareunStatus() {
  var props = getBareunUserProperties_();
  return { hasBareun: !!props.getProperty('USER_BAREUN_KEY') };
}

function clearUserBareunKey() {
  var props = getBareunUserProperties_();
  props.deleteProperty('USER_BAREUN_KEY');
  return { hasBareun: false };
}

function getBareunKey() {
  var key = getBareunUserProperties_().getProperty('USER_BAREUN_KEY');
  if (!key) throw new Error("Bareun API 키가 없습니다. 사이드바 상단에서 등록해주세요.");
  return key;
}

// =================================================================
// [2] Bareun 맞춤법 검사
// =================================================================

function getSelectedDataForSpellCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");
  var rows = [];
  var startRow = range.getRow();
  var startCol = range.getColumn();
  var values = range.getValues();
  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var text = values[i][j].toString();
      if (text.trim() !== "") {
        rows.push({ sheetName: sheetName, row: startRow + i, col: startCol + j, original: text });
      }
    }
  }
  return rows;
}

function getBareunCorrection(text) {
  var userKey = getBareunKey();
  var result = callBareunApi(text, userKey); 
  return result; 
}

function applySpellCheckResults(updates) {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  updates.forEach(function(item) {
    var sheet = spreadsheet.getSheetByName(item.sheetName);
    if (!sheet) throw new Error('검사한 시트를 찾을 수 없습니다: ' + item.sheetName);
    sheet.getRange(item.row, item.col).setValue(item.text);
  });
  return updates.length;
}

function callBareunApi(text, userKey) {
  var url = "https://api.bareun.ai/bareun.RevisionService/CorrectError";
  var options = {
    "method": "post", "contentType": "application/json", "headers": { "api-key": userKey }, "muteHttpExceptions": true,
    "payload": JSON.stringify({ "document": { "content": text, "language": "ko-KR" }, "encoding_type": "UTF16" })
  };
  var response = UrlFetchApp.fetch(url, options);
  var result = JSON.parse(response.getContentText());
  
  if (response.getResponseCode() !== 200) {
    return { error: "API 오류: " + response.getResponseCode() };
  }
  return { revised: result.revised, helps: result.helps || {}, rawBlocks: result.revisedBlocks || result.revised_blocks || [], error: null };
}

// =================================================================
// [3] 기재 금지어 관리
// =================================================================

var BANNED_WORD_SHEET_NAME_ = '기재금지어관리';
var BANNED_WORD_HEADERS_ = ['번호', '기재 금지어'];
var LEGACY_BANNED_WORD_HEADERS_ = ['유형', '기재 금지어', '대체 표현'];
var ONE_COLUMN_BANNED_WORD_HEADERS_ = ['기재 금지어'];

function getLegacyBannedWordList_() {
  var saved = PropertiesService.getUserProperties().getProperty('BANNED_WORDS_DB');
  if (!saved) return getDefaultBannedList_();

  try {
    var parsed = JSON.parse(saved);
    if (!Array.isArray(parsed)) return getDefaultBannedList_();
    return parsed
      .map(function(item) {
        return String(item && item.k || '').trim();
      })
      .filter(function(keyword) { return keyword !== ''; });
  } catch (e) {
    return getDefaultBannedList_();
  }
}

function initializeBannedWordSheet_(sheet, list) {
  sheet.getRange(1, 1, 1, BANNED_WORD_HEADERS_.length)
    .setValues([BANNED_WORD_HEADERS_])
    .setBackground('#fce8e6')
    .setFontColor('#a50e0e')
    .setFontWeight('bold')
    .setHorizontalAlignment('center');

  var rows = list.map(function(keyword, index) {
    return [index + 1, keyword];
  });
  if (rows.length > 0) sheet.getRange(2, 1, rows.length, 2).setValues(rows);

  sheet.setFrozenRows(1);
  sheet.setColumnWidth(1, 60);
  sheet.setColumnWidth(2, 260);
  sheet.setTabColor('#d93025');
}

function migrateLegacyBannedWordSheet_(sheet) {
  var lastColumn = sheet.getLastColumn();
  var legacyColumn;
  var clearColumns;

  if (lastColumn >= 3 && sheet.getRange(1, 1, 1, 3).getDisplayValues()[0].join('|') === LEGACY_BANNED_WORD_HEADERS_.join('|')) {
    legacyColumn = 2;
    clearColumns = 3;
  } else if (sheet.getRange(1, 1, 1, 1).getDisplayValues()[0][0] === ONE_COLUMN_BANNED_WORD_HEADERS_[0]) {
    legacyColumn = 1;
    clearColumns = 1;
  } else {
    return false;
  }

  var lastRow = sheet.getLastRow();
  var keywords = lastRow < 2 ? [] : sheet.getRange(2, legacyColumn, lastRow - 1, 1)
    .getDisplayValues()
    .map(function(row) { return String(row[0] || '').trim(); })
    .filter(function(keyword) { return keyword !== ''; });

  var clearRows = Math.max(sheet.getLastRow(), 1);
  sheet.getRange(1, 1, clearRows, clearColumns).clearContent();
  initializeBannedWordSheet_(sheet, keywords);
  return true;
}

function ensureBannedWordSheet_() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  if (!spreadsheet) throw new Error('활성 스프레드시트를 찾을 수 없습니다.');

  var originalSheet = spreadsheet.getActiveSheet();
  var originalRange = spreadsheet.getActiveRange();
  var lock = LockService.getDocumentLock() || LockService.getScriptLock();
  lock.waitLock(30000);

  var sheet;
  try {
    sheet = spreadsheet.getSheetByName(BANNED_WORD_SHEET_NAME_);
    if (!sheet) {
      sheet = spreadsheet.insertSheet(BANNED_WORD_SHEET_NAME_);
      initializeBannedWordSheet_(sheet, getLegacyBannedWordList_());
    } else {
      // 이전 형식은 금지어만 보존하여 번호·기재금지어 두 열 목록으로 안전하게 바꿉니다.
      migrateLegacyBannedWordSheet_(sheet);
    }

    // 시트로 옮긴 뒤 예전 사용자별 저장값은 더 이상 별도 원본으로 남기지 않습니다.
    PropertiesService.getUserProperties().deleteProperty('BANNED_WORDS_DB');
    return sheet;
  } finally {
    if (originalSheet && sheet && originalSheet.getSheetId() !== sheet.getSheetId()) {
      spreadsheet.setActiveSheet(originalSheet);
      if (originalRange) spreadsheet.setActiveRange(originalRange);
    }
    lock.releaseLock();
  }
}

function openBannedWordManagementSheet() {
  var sheet = ensureBannedWordSheet_();
  sheet.activate();
  sheet.getRange('A1').activate();
  return sheet.getName();
}

function getDefaultBannedList_() {
  return [
    "MBTI", "커리어넷", "메이저맵", "패들렛", "띵커벨", "알로",
    "미리캔버스", "망고보드", "유튜버", "유튜브", "넷플릭스", "왓챠",
    "티빙", "네이버 폼", "구글 폼", "OECD", "UN", "유네스코", "WTO",
    "WHO", "그린피스", "앰네스티", "IMF", "인스타그램", "페이스북",
    "카카오톡", "네이버", "구글", "클래스 카드", "구글 클래스룸", "게더타운",
    "제페토", "아이패드", "갤럭시 탭", "비트코인", "TED", "반크", "TOEIC",
    "TOEFL", "TEPS", "대회", "수상", "한자능력검정"
  ];
}

function getBannedWordList_() {
  var sheet = ensureBannedWordSheet_();
  var header = sheet.getRange(1, 1, 1, 2).getDisplayValues()[0];
  if (header.join('|') !== BANNED_WORD_HEADERS_.join('|')) {
    throw new Error('기재금지어관리 시트의 1행은 "번호 | 기재 금지어" 순서여야 합니다.');
  }

  var lastRow = sheet.getLastRow();
  if (lastRow < 2) return [];

  var values = sheet.getRange(2, 1, lastRow - 1, 2).getDisplayValues();
  var seen = {};
  var list = [];

  values.forEach(function(row, index) {
    var rowNumber = index + 2;
    var number = String(row[0] || '').trim();
    var keyword = String(row[1] || '').trim();

    if (!number && !keyword) return;
    if (!/^[1-9]\d*$/.test(number)) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 번호(A열)는 1 이상의 정수여야 합니다.');
    }
    if (!keyword) throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어(B열)를 입력해 주세요.');

    var duplicateKey = normalizeBannedWord_(keyword);
    if (seen[duplicateKey]) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어가 ' + seen[duplicateKey] + '행과 중복됩니다: ' + keyword);
    }
    seen[duplicateKey] = rowNumber;
    list.push(keyword);
  });

  return list;
}

function runBannedWordCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  var values = range.getValues();
  var startRow = range.getRow();
  var startCol = range.getColumn();
  
  var db = getBannedWordList_();
  if (db.length === 0) return [];
  db.sort(function(a, b) { return normalizeBannedWord_(b).length - normalizeBannedWord_(a).length; });
  var canonicalByNormalizedKeyword = {};
  db.forEach(function(keyword) { canonicalByNormalizedKeyword[normalizeBannedWord_(keyword)] = keyword; });
  var combinedPattern = new RegExp('(' + db.map(buildWhitespaceInsensitivePattern_).join('|') + ')', 'gi');

  var results = [];

  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var original = values[i][j].toString();
      if (!original.trim()) continue;

      var hasIssue = false;
      var logs = [];

      var counts = {};
      var match;
      while ((match = combinedPattern.exec(original)) !== null) {
        var normalizedMatch = normalizeBannedWord_(match[0]);
        var keyword = canonicalByNormalizedKeyword[normalizedMatch];
        if (keyword) {
          hasIssue = true;
          counts[keyword] = (counts[keyword] || 0) + 1;
        }
      }

      Object.keys(counts).forEach(function(keyword) {
        logs.push({ k: keyword, count: counts[keyword] });
      });

      if (hasIssue) {
        results.push({
          sheetName: sheetName,
          row: startRow + i,
          col: startCol + j,
          original: original,
          logs: logs
        });
      }
    }
  }
  return results;
}

function escapeRegExp(string) {
  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); 
}

function normalizeBannedWord_(value) {
  return String(value || '').replace(/\s+/g, '').toLocaleLowerCase();
}

function buildWhitespaceInsensitivePattern_(keyword) {
  var compact = normalizeBannedWord_(keyword);
  if (!compact) throw new Error('비어 있는 기재 금지어는 검사할 수 없습니다.');
  return compact.split('').map(function(character) {
    return escapeRegExp(character);
  }).join('[\\s\\u00A0]*');
}

// =================================================================
// [4] 로컬 검토 유틸리티
// =================================================================

function unifyToStraightQuotes() {
  var range = SpreadsheetApp.getActiveRange();
  var ui = SpreadsheetApp.getUi();
  if (!range) throw new Error('선택된 셀이 없습니다.');
  var response = ui.alert('따옴표 변환', '선택 영역의 둥근 따옴표를 곧은 따옴표로 변환하시겠습니까?', ui.ButtonSet.YES_NO);
  if (response != ui.Button.YES) return;
  try {
    range.createTextFinder('[‘’]').useRegularExpression(true).matchEntireCell(false).replaceAllWith("'");
    range.createTextFinder('[“”]').useRegularExpression(true).matchEntireCell(false).replaceAllWith('"');
    SpreadsheetApp.flush();
    ui.alert('✅ 변환 완료');
  } catch (e) { ui.alert('오류: ' + e.toString()); }
}

// [신규] 선택 영역 스페이스바 실수(2칸 이상) 수정 함수
function fixDoubleSpaces() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  const values = range.getValues();
  let fixCount = 0; // 수정된 셀 개수 카운트

  const newValues = values.map(row => {
    return row.map(cell => {
      let str = String(cell);
      // 공백이 2번 이상 연속( /  +/)으로 있으면 1번으로 변경
      // 줄바꿈(\n)은 건드리지 않도록 일반 공백( )만 타겟팅
      if (/ {2,}/.test(str)) {
        fixCount++;
        return str.replace(/ {2,}/g, ' '); 
      }
      return cell;
    });
  });

  if (fixCount > 0) {
    range.setValues(newValues);
  }
  
  return fixCount;
}

// =================================================================
// [5] UI 상태 저장/불러오기
// =================================================================

function saveUiState(cardId, isExpanded) {
  var props = PropertiesService.getUserProperties();
  var state = JSON.parse(props.getProperty('UI_STATE') || '{}');
  state[cardId] = isExpanded;
  props.setProperty('UI_STATE', JSON.stringify(state));
}

function getUiState() {
  var props = PropertiesService.getUserProperties();
  return JSON.parse(props.getProperty('UI_STATE') || '{}');
}

Sidebar.html


= 0 ? initialView : "sidebar"; ?>



  
    
    
    
    
  
  
    
      
        🔑 Bareun API 키 설정
        expand_more
      
      
        
          
            내 Bareun API 키
            expand_more
          
          
            ⌛ API 키 설정 확인 중...
            
              
              Bareun API 키
              
              공용 키는 제공하지 않습니다. 키는 사용자별 설정에 저장되고 원문을 화면으로 다시 불러오지 않습니다.
              
              
            
          
        
      
    

    
      
        📝 선택 영역 검사 및 정리
        expand_more
      
      
        
        
        
        
        
        
      
    

    
  





  
    
    
    
    
    
  
  

    
      fact_check 맞춤법 검사 및 수정
      
        원본 오류
        수정 제안
      
    

    
      
        
        데이터를 불러오는 중입니다...
      
      
    

    
      
      
    

    
  





  
    
    
    
    
  
  

    
      block 기재 금지어 검사
      
        금지어 발견
        오른쪽 수정안에서 문맥에 맞게 직접 고쳐 주세요.
      
    

    
      
        
        데이터를 분석 중입니다...

(5) 빅데이터 분석 기반 융합수업

교안 및 학습자료

전북_상권정보.xlsx

(6) 설문조사, 지도안 작성

2026년 인공지능 활용 선도교사 연수 (충북 청주 - 7. 26.)

Sat, 25 Jul 2026 14:58:29 GMT

2026년 인공지능 활용 선도교사 연수 (충북 청주 - 7. 26.)

강사: 교사 김민기(민기쌤)
일시: 2026-07-26
장소: 청주 오스코

(1) 클로바노트 음성 전사

(2) 유튜브 댓글 수집

Code.gs

const YT_CFG = Object.freeze({
  API_BASE: 'https://www.googleapis.com/youtube/v3',

  API_KEY_PROP: 'YT_API_KEY',
  STATE_PROP: 'YT_COMMENT_COLLECTOR_STATE',
  LAST_RESULT_PROP: 'YT_COMMENT_COLLECTOR_LAST_RESULT',
  CANCEL_REQUEST_PROP: 'YT_COMMENT_COLLECTOR_CANCEL_REQUEST',

  OUTPUT_SHEET_PREFIX: '시트',
  INTERNAL_SHEET: '_댓글수집_내부',
  LEGACY_LOG_SHEET: '수집로그',

  CONTINUE_HANDLER: 'continueCommentCollection',
  STRUCTURED_ERROR_PREFIX: 'YT_STRUCTURED_ERROR::',
  STATE_VERSION: 4,

  // Apps Script의 일반 실행 제한 전에 상태를 저장하고 다음 실행으로 넘깁니다.
  MAX_RUN_MS: 4 * 60 * 1000 + 30 * 1000,
  CONTINUE_AFTER_MS: 60 * 1000,

  MIN_LIMIT: 1,
  MAX_LIMIT: 50000,

  HEADERS: [
    '번호',
    '채널명',
    '영상 제목',
    '댓글 작성자',
    '댓글 내용',
    '좋아요 수',
    '작성 시각',
    '글자수'
  ],

  // 숨김 내부 시트의 열 구조입니다.
  INTERNAL_HEADERS: [
    'comment_id',
    'parent_comment_id',
    'display_number',
    'comment_type',
    'reply_status',
    'next_reply_index',
    'total_reply_count',
    'reply_page_token'
  ],

  INTERNAL_COL: Object.freeze({
    COMMENT_ID: 1,
    PARENT_ID: 2,
    DISPLAY_NUMBER: 3,
    COMMENT_TYPE: 4,
    REPLY_STATUS: 5,
    NEXT_REPLY_INDEX: 6,
    TOTAL_REPLY_COUNT: 7,
    REPLY_PAGE_TOKEN: 8
  })
});


/**
 * 스프레드시트를 열 때 사용자 메뉴를 만듭니다.
 */
function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('YouTube 댓글 수집')
    .addItem('사이드바 열기', 'showYouTubeCommentSidebar')
    .addSeparator()
    .addItem('중단 지점부터 실행', 'continueCommentCollection')
    .addItem('진행 중인 수집 취소', 'cancelCommentCollection')
    .addToUi();
}


/**
 * 오른쪽 사이드바를 엽니다.
 */
function showYouTubeCommentSidebar() {
  const html = HtmlService
    .createHtmlOutputFromFile('Sidebar')
    .setTitle('YouTube 댓글 수집기');

  SpreadsheetApp.getUi().showSidebar(html);
}


/**
 * 사이드바 초기 상태를 반환합니다.
 */
function getSidebarState() {
  const props = getUserProperties_();
  const apiKey = props.getProperty(YT_CFG.API_KEY_PROP) || '';
  const activeState = loadState_();
  const lastResult = loadLastResult_();
  const cancelRequested =
    props.getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';

  const progress = activeState
    ? buildProgressForClient_(activeState, 'RUNNING')
    : lastResult
      ? buildProgressForClient_(lastResult, lastResult.status || 'COMPLETED')
      : null;

  if (progress && activeState && cancelRequested) {
    progress.stage = '취소 처리 중';
    progress.message = '현재 실행 구간이 끝나는 즉시 안전하게 중단됩니다.';
  }

  return {
    apiKeyConfigured: Boolean(apiKey),
    apiKeyMask: apiKey ? maskApiKey_(apiKey) : '',
    running: Boolean(activeState),
    cancelRequested: cancelRequested,
    progress: progress
  };
}


/**
 * API 키를 실제 YouTube Data API 요청으로 검증한 뒤 사용자별 속성에 저장합니다.
 */
function saveApiKey(apiKey) {
  const cleanedKey = String(apiKey || '').trim();

  if (!cleanedKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키를 입력해야 합니다.',
      'Google Cloud에서 발급한 YouTube Data API 키가 입력되지 않았습니다.',
      ['API 키 입력란이 비어 있습니다.'],
      [
        'Google Cloud Console에서 API 키를 발급합니다.',
        'API 키 전체를 사이드바 입력란에 붙여 넣습니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  if (cleanedKey.length < 20) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_FORMAT_INVALID',
      'API 키 형식을 확인해야 합니다.',
      '입력한 문자열이 일반적인 Google API 키 길이보다 짧습니다.',
      [
        'API 키 일부만 복사했을 수 있습니다.',
        '프로젝트 ID나 다른 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 값을 처음부터 끝까지 다시 복사하여 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력'
      }
    ));
  }

  validateApiKey_(cleanedKey);

  const props = getUserProperties_();
  props.setProperty(YT_CFG.API_KEY_PROP, cleanedKey);

  // 이전 API 키 오류 안내가 새 키 저장 뒤 다시 나타나지 않도록 정리합니다.
  const previous = loadLastResult_();
  if (previous && previous.status === 'ERROR') {
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
  }

  return getSidebarState();
}


/**
 * 저장된 API 키를 삭제합니다.
 */
function deleteApiKey() {
  if (loadState_()) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_DELETE_BLOCKED',
      '수집 중에는 API 키를 삭제할 수 없습니다.',
      '현재 댓글 수집 작업이 저장된 API 키를 사용하고 있습니다.',
      ['진행 중인 작업이 존재합니다.'],
      [
        '현재 수집을 완료하거나 취소합니다.',
        '수집 상태가 종료된 뒤 API 키를 삭제합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.API_KEY_PROP);
  props.deleteProperty(YT_CFG.LAST_RESULT_PROP);

  return getSidebarState();
}


/**
 * 사이드바 입력값으로 새 수집 작업을 준비합니다.
 * 실제 수집은 runCollectionNow 또는 시간 기반 트리거가 수행합니다.
 */
function startCollectionFromSidebar(formData) {
  const lock = LockService.getScriptLock();
  lock.waitLock(10000);

  try {
    const apiKey = getApiKey_();
    const input = normalizeSidebarInput_(formData);
    const ss = SpreadsheetApp.getActiveSpreadsheet();

    if (!ss) {
      throwStructuredError_(buildErrorInfo_(
        'SPREADSHEET_NOT_FOUND',
        '댓글을 저장할 스프레드시트를 찾지 못했습니다.',
        '현재 Apps Script가 스프레드시트와 연결된 상태인지 확인해야 합니다.',
        [
          '독립 실행형 Apps Script 프로젝트에서 코드를 실행했을 수 있습니다.',
          '스프레드시트가 닫히거나 접근 권한이 변경되었을 수 있습니다.'
        ],
        [
          '댓글을 저장할 Google 스프레드시트를 엽니다.',
          '‘확장 프로그램 → Apps Script’에서 이 코드를 실행합니다.',
          '스프레드시트를 새로고침하고 사이드바를 다시 엽니다.'
        ],
        { actionLabel: '확인' }
      ));
    }

    // 영상과 API 키가 정상인지 먼저 확인합니다.
    const videoId = extractVideoId_(input.videoUrl);
    const metadata = getVideoMetadataWithKey_(videoId, apiKey);

    deleteContinuationTriggers_();

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    // 새 수집은 기존 결과를 지우지 않고 새 결과 시트에 기록합니다.
    const outputSheet = createNextOutputSheet_(ss);
    ensureInternalSheet_(ss);
    resetInternalData_(ss);
    deleteLegacyLogSheet_(ss);

    const state = {
      version: YT_CFG.STATE_VERSION,
      status: 'RUNNING',
      spreadsheetId: ss.getId(),

      outputSheetId: outputSheet.getSheetId(),
      outputSheetName: outputSheet.getName(),

      videoId: videoId,
      videoTitle: metadata.title,
      videoChannelId: metadata.channelId,
      videoChannelTitle: metadata.channelTitle,
      reportedCommentCount: metadata.commentCount,

      targetTopLevelCount: input.limit,
      includeReplies: input.includeReplies,

      nextThreadPageToken: '',
      threadDone: false,

      currentReplyParentId: '',
      nextReplyPageToken: '',

      topCount: 0,
      replyCount: 0,
      threadPages: 0,
      replyPages: 0,
      apiCalls: 1,

      startedAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      message: outputSheet.getName() + '에서 수집을 시작했습니다.',
      error: null
    };

    saveState_(state);

    // 사이드바가 닫혀도 수집이 이어지도록 예비 트리거를 만듭니다.
    scheduleContinuation_();

    return getSidebarState();

  } finally {
    lock.releaseLock();
  }
}


/**
 * 사이드바가 첫 실행 구간을 즉시 시작할 때 호출합니다.
 */
function runCollectionNow() {
  continueCommentCollection();
  return getSidebarState();
}


/**
 * 저장된 상태에서 댓글 수집을 계속합니다.
 */
function continueCommentCollection() {
  const lock = LockService.getScriptLock();

  if (!lock.tryLock(5000)) {
    return;
  }

  let ss = null;
  let state = null;
  let commentsSheet = null;

  try {
    state = loadState_();

    if (!state) {
      return;
    }

    validateStateVersion_(state);
    normalizeState_(state);

    ss = SpreadsheetApp.openById(state.spreadsheetId);
    ensureInternalSheet_(ss);
    deleteLegacyLogSheet_(ss);

    commentsSheet = getOutputSheetForState_(ss, state);
    const internalSheet = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);
    const existingIds = getExistingCommentIds_(internalSheet);
    const existingCounts = getExistingCounts_(internalSheet);

    // 시트 기록 직후 상태 저장 전에 실행이 끊긴 상황을 보정합니다.
    state.topCount = existingCounts.top;
    state.replyCount = existingCounts.reply;

    const runStartedAt = Date.now();

    while (Date.now() - runStartedAt < YT_CFG.MAX_RUN_MS) {
      if (isCancelRequested_()) {
        finalizeCancellation_(ss, commentsSheet, state);
        return;
      }

      // 처리 중이던 답글 페이지가 있으면 먼저 이어서 처리합니다.
      if (state.currentReplyParentId) {
        processReplyPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      // 내부 시트에서 답글 수집이 필요한 최상위 댓글을 하나 선택합니다.
      const pendingReply = claimNextPendingReply_(internalSheet);

      if (pendingReply) {
        state.currentReplyParentId = pendingReply.commentId;
        state.nextReplyPageToken = pendingReply.pageToken || '';
        saveState_(state);
        continue;
      }

      // 답글 대기 항목이 없을 때 다음 최상위 댓글 페이지를 가져옵니다.
      if (!state.threadDone) {
        processThreadPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      finishCollection_(ss, commentsSheet, state);
      return;
    }

    state.updatedAt = new Date().toISOString();
    state.message = '실행 시간을 고려하여 진행 상태를 저장했습니다.';
    saveState_(state);
    scheduleContinuation_();

  } catch (error) {
    deleteContinuationTriggers_();

    const errorInfo = normalizeErrorInfo_(error, '댓글 수집');

    if (errorInfo.code === 'API_KEY_INVALID') {
      getUserProperties_().deleteProperty(YT_CFG.API_KEY_PROP);
    }

    if (commentsSheet) {
      try {
        finalizeCommentsSheet_(commentsSheet);
      } catch (formatError) {
        console.error(formatError);
      }
    }

    if (state) {
      state.status = 'ERROR';
      state.updatedAt = new Date().toISOString();
      state.message = errorInfo.summary;
      state.error = errorInfo;
      saveLastResult_(state, 'ERROR', errorInfo.summary, errorInfo);
    }

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    console.error(error);
    throwStructuredError_(errorInfo);

  } finally {
    lock.releaseLock();
  }
}


/**
 * 진행 중인 수집을 취소합니다.
 */
function cancelCommentCollection() {
  const props = getUserProperties_();
  const state = loadState_();

  if (!state) {
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
    deleteContinuationTriggers_();
    return getSidebarState();
  }

  props.setProperty(YT_CFG.CANCEL_REQUEST_PROP, 'true');
  deleteContinuationTriggers_();

  const lock = LockService.getScriptLock();

  // 다른 수집 실행이 없다면 이 호출에서 즉시 취소를 마무리합니다.
  if (lock.tryLock(200)) {
    try {
      const latestState = loadState_();

      if (latestState) {
        const ss = SpreadsheetApp.openById(latestState.spreadsheetId);
        ensureInternalSheet_(ss);
        const commentsSheet = getOutputSheetForState_(ss, latestState);
        finalizeCancellation_(ss, commentsSheet, latestState);
      }
    } finally {
      lock.releaseLock();
    }
  }

  return getSidebarState();
}


/**
 * 최상위 댓글 스레드 한 페이지를 처리합니다.
 */
function processThreadPage_(state, commentsSheet, internalSheet, existingIds) {
  const remaining = state.targetTopLevelCount - state.topCount;

  if (remaining <= 0) {
    state.threadDone = true;
    state.nextThreadPageToken = '';
    return;
  }

  const params = {
    part: state.includeReplies ? 'snippet,replies' : 'snippet',
    videoId: state.videoId,
    maxResults: Math.min(100, remaining),
    textFormat: 'plainText'
  };

  if (state.nextThreadPageToken) {
    params.pageToken = state.nextThreadPageToken;
  }

  const data = youtubeGet_('commentThreads', params);

  state.apiCalls += 1;
  state.threadPages += 1;

  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();
  const items = Array.isArray(data.items) ? data.items : [];

  let topAdded = 0;
  let replyAdded = 0;
  let nextTopNumber = state.topCount + 1;

  items.forEach(function(thread) {
    if (state.topCount + topAdded >= state.targetTopLevelCount) {
      return;
    }

    const threadSnippet = thread.snippet || {};
    const topComment = threadSnippet.topLevelComment;

    if (!topComment || !topComment.id) {
      return;
    }

    const topCommentId = String(topComment.id);

    if (existingIds.has(topCommentId) || batchIds.has(topCommentId)) {
      return;
    }

    const topNumber = String(nextTopNumber);
    nextTopNumber += 1;

    const totalReplyCount = Number(threadSnippet.totalReplyCount || 0);
    let replyStatus = 'DONE';
    let nextReplyIndex = 1;

    commentRows.push(
      commentToOutputRow_(state, topComment, topNumber)
    );

    batchIds.add(topCommentId);
    topAdded += 1;

    const inlineReplies =
      thread.replies && Array.isArray(thread.replies.comments)
        ? thread.replies.comments
        : [];

    if (state.includeReplies && totalReplyCount > 0) {
      if (inlineReplies.length === totalReplyCount) {
        inlineReplies.forEach(function(reply) {
          if (!reply || !reply.id) {
            return;
          }

          const replyId = String(reply.id);

          if (existingIds.has(replyId) || batchIds.has(replyId)) {
            return;
          }

          const displayNumber = topNumber + '_' + nextReplyIndex;
          nextReplyIndex += 1;

          commentRows.push(
            commentToOutputRow_(state, reply, displayNumber)
          );

          internalRows.push(
            buildInternalRow_(
              replyId,
              topCommentId,
              displayNumber,
              'reply',
              '',
              '',
              '',
              ''
            )
          );

          batchIds.add(replyId);
          replyAdded += 1;
        });
      } else {
        // commentThreads.list의 replies에는 전체 답글이 보장되지 않으므로
        // comments.list로 전체 답글을 다시 가져옵니다.
        replyStatus = 'PENDING';
        nextReplyIndex = 1;
      }
    }

    internalRows.push(
      buildInternalRow_(
        topCommentId,
        '',
        topNumber,
        'topLevel',
        replyStatus,
        nextReplyIndex,
        totalReplyCount,
        ''
      )
    );
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.topCount += topAdded;
  state.replyCount += replyAdded;

  const reachedTarget = state.topCount >= state.targetTopLevelCount;
  const hasNextPage = Boolean(data.nextPageToken);

  state.nextThreadPageToken =
    !reachedTarget && hasNextPage
      ? data.nextPageToken
      : '';

  state.threadDone = reachedTarget || !hasNextPage;
  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 특정 최상위 댓글의 답글 한 페이지를 처리합니다.
 */
function processReplyPage_(state, commentsSheet, internalSheet, existingIds) {
  const topRecord = findInternalRecordByCommentId_(
    internalSheet,
    state.currentReplyParentId
  );

  if (!topRecord) {
    // 내부 상태가 사라진 경우 현재 항목을 건너뛰고 다음 대기 항목을 찾습니다.
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
    return;
  }

  const params = {
    part: 'snippet',
    parentId: state.currentReplyParentId,
    maxResults: 100,
    textFormat: 'plainText'
  };

  const pageToken =
    state.nextReplyPageToken || topRecord.replyPageToken || '';

  if (pageToken) {
    params.pageToken = pageToken;
  }

  const data = youtubeGet_('comments', params);

  state.apiCalls += 1;
  state.replyPages += 1;

  const items = Array.isArray(data.items) ? data.items : [];
  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();

  let nextReplyIndex = Number(topRecord.nextReplyIndex || 1);
  let replyAdded = 0;

  items.forEach(function(reply) {
    if (!reply || !reply.id) {
      return;
    }

    const replyId = String(reply.id);

    if (existingIds.has(replyId) || batchIds.has(replyId)) {
      return;
    }

    const displayNumber =
      String(topRecord.displayNumber) + '_' + nextReplyIndex;

    nextReplyIndex += 1;

    commentRows.push(
      commentToOutputRow_(state, reply, displayNumber)
    );

    internalRows.push(
      buildInternalRow_(
        replyId,
        state.currentReplyParentId,
        displayNumber,
        'reply',
        '',
        '',
        '',
        ''
      )
    );

    batchIds.add(replyId);
    replyAdded += 1;
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.replyCount += replyAdded;

  const nextPageToken = data.nextPageToken || '';
  const nextStatus = nextPageToken ? 'IN_PROGRESS' : 'DONE';

  updateTopReplyProgress_(
    internalSheet,
    topRecord.rowNumber,
    nextStatus,
    nextReplyIndex,
    nextPageToken
  );

  if (nextPageToken) {
    state.nextReplyPageToken = nextPageToken;
  } else {
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
  }

  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 내부 시트에서 답글 수집 대기 중인 최상위 댓글 하나를 선택합니다.
 */
function claimNextPendingReply_(internalSheet) {
  const statusRange = internalSheet.getRange(
    2,
    YT_CFG.INTERNAL_COL.REPLY_STATUS,
    Math.max(internalSheet.getLastRow() - 1, 1),
    1
  );

  let found = statusRange
    .createTextFinder('IN_PROGRESS')
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    found = statusRange
      .createTextFinder('PENDING')
      .matchEntireCell(true)
      .useRegularExpression(false)
      .findNext();
  }

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  if (values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] === 'PENDING') {
    internalSheet
      .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS)
      .setValue('IN_PROGRESS');
  }

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    pageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 댓글 1건을 사용자가 보는 8열 행으로 변환합니다.
 */
function commentToOutputRow_(state, comment, displayNumber) {
  const snippet = (comment && comment.snippet) || {};
  const text = String(snippet.textDisplay || '');

  return [
    String(displayNumber),
    safeCellText_(state.videoChannelTitle || ''),
    safeCellText_(state.videoTitle || ''),
    safeCellText_(snippet.authorDisplayName || ''),
    safeCellText_(text),
    Number(snippet.likeCount || 0),
    apiDateToSheetValue_(snippet.publishedAt),
    calculateCommentBytes_(text)
  ];
}


/**
 * 숨김 내부 시트의 행을 만듭니다.
 */
function buildInternalRow_(
  commentId,
  parentCommentId,
  displayNumber,
  commentType,
  replyStatus,
  nextReplyIndex,
  totalReplyCount,
  replyPageToken
) {
  return [
    safeCellText_(commentId || ''),
    safeCellText_(parentCommentId || ''),
    String(displayNumber || ''),
    String(commentType || ''),
    String(replyStatus || ''),
    nextReplyIndex === '' ? '' : Number(nextReplyIndex || 1),
    totalReplyCount === '' ? '' : Number(totalReplyCount || 0),
    safeCellText_(replyPageToken || '')
  ];
}


/**
 * 댓글 행과 내부 관리 행을 각각 일괄 기록합니다.
 */
function appendCollectedRecords_(
  commentsSheet,
  internalSheet,
  commentRows,
  internalRows
) {
  if (commentRows.length !== internalRows.length) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_ROW_MISMATCH',
      '댓글 저장 구조를 확인해야 합니다.',
      '댓글 행과 내부 관리 행의 개수가 일치하지 않습니다.',
      ['수집 상태를 기록하는 내부 데이터가 일시적으로 어긋났습니다.'],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  if (commentRows.length === 0) {
    return;
  }

  commentsSheet
    .getRange(
      commentsSheet.getLastRow() + 1,
      1,
      commentRows.length,
      YT_CFG.HEADERS.length
    )
    .setValues(commentRows);

  internalSheet
    .getRange(
      internalSheet.getLastRow() + 1,
      1,
      internalRows.length,
      YT_CFG.INTERNAL_HEADERS.length
    )
    .setValues(internalRows);
}


/**
 * 내부 시트에서 특정 댓글 ID의 관리 행을 찾습니다.
 */
function findInternalRecordByCommentId_(internalSheet, commentId) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return null;
  }

  const found = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .createTextFinder(String(commentId || ''))
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    replyStatus: String(
      values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    replyPageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 최상위 댓글의 답글 수집 진행 정보를 갱신합니다.
 */
function updateTopReplyProgress_(
  internalSheet,
  rowNumber,
  status,
  nextReplyIndex,
  pageToken
) {
  internalSheet
    .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS, 1, 4)
    .setValues([[
      status,
      Number(nextReplyIndex || 1),
      internalSheet
        .getRange(rowNumber, YT_CFG.INTERNAL_COL.TOTAL_REPLY_COUNT)
        .getValue(),
      pageToken || ''
    ]]);
}


/**
 * 완료 처리
 */
function finishCollection_(ss, commentsSheet, state) {
  state.status = 'COMPLETED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = state.topCount < state.targetTopLevelCount
    ? '댓글 ' +
      state.topCount +
      '개와 대댓글 ' +
      state.replyCount +
      '개를 수집했습니다.'
    : '댓글 수집을 완료했습니다.';
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'COMPLETED', state.message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


function isCancelRequested_() {
  return getUserProperties_().getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';
}


/**
 * 취소 처리
 */
function finalizeCancellation_(ss, commentsSheet, state) {
  const message = '사용자가 수집을 취소했습니다. 이미 저장된 댓글은 유지됩니다.';

  state.status = 'CANCELLED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = message;
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'CANCELLED', message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


/**
 * API 키가 YouTube Data API 요청에 사용 가능한지 확인합니다.
 */
function validateApiKey_(apiKey) {
  youtubeGetWithKey_(
    'videos',
    {
      part: 'id',
      id: 'jNQXAC9IVRw'
    },
    apiKey
  );
}


/**
 * 영상 메타데이터를 조회합니다.
 */
function getVideoMetadataWithKey_(videoId, apiKey) {
  const data = youtubeGetWithKey_(
    'videos',
    {
      part: 'snippet,statistics',
      id: videoId
    },
    apiKey
  );

  if (!Array.isArray(data.items) || data.items.length === 0) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '입력한 영상 주소에 해당하는 공개 영상을 YouTube Data API에서 조회하지 못했습니다.',
      [
        '영상 주소나 11자리 영상 ID가 정확하지 않을 수 있습니다.',
        '영상이 삭제되었거나 비공개 상태일 수 있습니다.',
        '연령·지역·계정 권한에 따라 접근이 제한된 영상일 수 있습니다.'
      ],
      [
        '브라우저에서 해당 영상 주소가 정상적으로 열리는지 확인합니다.',
        '주소 표시줄의 영상 URL 전체를 다시 복사합니다.',
        '사이드바의 영상 주소를 교체한 뒤 수집을 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: { videoId: videoId }
      }
    ));
  }

  const item = data.items[0];
  const snippet = item.snippet || {};
  const statistics = item.statistics || {};

  return {
    title: snippet.title || '',
    channelId: snippet.channelId || '',
    channelTitle: snippet.channelTitle || '',
    commentCount: statistics.commentCount || ''
  };
}


/**
 * 저장된 API 키로 YouTube Data API를 호출합니다.
 */
function youtubeGet_(resource, params) {
  return youtubeGetWithKey_(resource, params, getApiKey_());
}


/**
 * YouTube Data API GET 요청을 수행합니다.
 */
function youtubeGetWithKey_(resource, params, apiKey) {
  const queryParams = Object.assign({}, params, { key: apiKey });

  const query = Object.keys(queryParams)
    .filter(function(key) {
      const value = queryParams[key];
      return value !== undefined && value !== null && value !== '';
    })
    .map(function(key) {
      return encodeURIComponent(key) + '=' + encodeURIComponent(queryParams[key]);
    })
    .join('&');

  const url = YT_CFG.API_BASE + '/' + resource + '?' + query;
  const transientCodes = [429, 500, 502, 503, 504];

  for (let attempt = 0; attempt < 3; attempt += 1) {
    let response;

    try {
      response = UrlFetchApp.fetch(url, {
        method: 'get',
        muteHttpExceptions: true,
        headers: { Accept: 'application/json' }
      });
    } catch (networkError) {
      if (attempt < 2) {
        Utilities.sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      throwStructuredError_(buildErrorInfo_(
        'NETWORK_REQUEST_FAILED',
        'YouTube 서버에 연결하지 못했습니다.',
        'Apps Script에서 YouTube Data API로 보내는 외부 요청이 완료되지 않았습니다.',
        [
          'Google 서비스 또는 네트워크에 일시적인 장애가 발생했을 수 있습니다.',
          'Apps Script의 외부 요청 권한이 승인되지 않았을 수 있습니다.'
        ],
        [
          '잠시 뒤 같은 작업을 다시 실행합니다.',
          'Apps Script 권한 승인 화면이 나타나면 요청된 권한을 허용합니다.',
          'Apps Script의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.'
        ],
        {
          actionLabel: '확인',
          technical: {
            resource: resource,
            originalMessage: String(networkError && networkError.message || networkError)
          }
        }
      ));
    }

    const statusCode = response.getResponseCode();
    const responseText = response.getContentText();

    if (statusCode >= 200 && statusCode < 300) {
      return responseText ? JSON.parse(responseText) : {};
    }

    if (transientCodes.indexOf(statusCode) >= 0 && attempt < 2) {
      Utilities.sleep(Math.pow(2, attempt) * 1000);
      continue;
    }

    const parsedError = parseYouTubeErrorResponse_(responseText);

    throwStructuredError_(classifyYouTubeApiError_(
      statusCode,
      parsedError.reason,
      parsedError.message,
      resource
    ));
  }

  throwStructuredError_(buildErrorInfo_(
    'YOUTUBE_REQUEST_REPEATED_FAILURE',
    'YouTube API 요청이 반복적으로 실패했습니다.',
    '일시적인 서버 장애가 재시도 후에도 계속되었습니다.',
    ['YouTube 또는 Google 네트워크 서비스가 불안정할 수 있습니다.'],
    [
      '잠시 뒤 같은 작업을 다시 실행합니다.',
      '반복되면 Apps Script의 ‘실행’ 기록을 확인합니다.'
    ],
    { actionLabel: '확인', technical: { resource: resource } }
  ));
}


function parseYouTubeErrorResponse_(responseText) {
  let reason = '';
  let message = String(responseText || '');

  try {
    const parsed = JSON.parse(responseText);

    if (parsed.error) {
      message = parsed.error.message || message;

      if (Array.isArray(parsed.error.errors) && parsed.error.errors[0]) {
        reason = parsed.error.errors[0].reason || '';
      }

      if (!reason && parsed.error.status) {
        reason = parsed.error.status;
      }
    }
  } catch (parseError) {
    // JSON이 아닌 오류 본문은 문자열 그대로 분류합니다.
  }

  return {
    reason: String(reason || ''),
    message: String(message || '')
  };
}


/**
 * YouTube API 오류를 한국어 모달용 정보로 분류합니다.
 */
function classifyYouTubeApiError_(statusCode, reason, message, resource) {
  const reasonText = String(reason || '');
  const messageText = String(message || '');
  const combined = (reasonText + ' ' + messageText).toLowerCase();
  const technical = {
    httpStatus: statusCode,
    apiReason: reasonText,
    resource: resource,
    originalMessage: messageText
  };

  if (
    combined.indexOf('keyinvalid') >= 0 ||
    combined.indexOf('api key not valid') >= 0 ||
    combined.indexOf('api_key_invalid') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_INVALID',
      'API 키를 사용할 수 없습니다.',
      '입력한 API 키가 정확하지 않거나 삭제·재발급되어 현재 요청에 사용할 수 없습니다.',
      [
        'API 키 일부가 누락되었을 수 있습니다.',
        'Google Cloud에서 기존 키가 삭제되거나 재발급되었을 수 있습니다.',
        'API 키가 아닌 다른 프로젝트 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 전체를 다시 복사합니다.',
        '사이드바에서 API 키를 다시 입력하고 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') >= 0 ||
    combined.indexOf('access not configured') >= 0 ||
    combined.indexOf('service_disabled') >= 0 ||
    combined.indexOf('api_disabled') >= 0 ||
    combined.indexOf('has not been used in project') >= 0 ||
    combined.indexOf('it is disabled') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_API_NOT_ENABLED',
      'YouTube Data API v3가 활성화되어 있지 않습니다.',
      'API 키가 속한 Google Cloud 프로젝트에서 YouTube Data API v3 사용 설정을 켜야 합니다.',
      [
        'API 키를 만든 프로젝트에서 YouTube Data API v3를 아직 활성화하지 않았습니다.',
        'API를 활성화한 프로젝트와 API 키를 발급한 프로젝트가 다를 수 있습니다.'
      ],
      [
        'Google Cloud Console에서 API 키를 만든 프로젝트를 선택합니다.',
        '‘API 및 서비스 → 라이브러리’로 이동합니다.',
        '‘YouTube Data API v3’를 검색하고 ‘사용’을 누릅니다.',
        '설정 반영을 위해 1~5분 기다린 뒤 API 키를 다시 저장합니다.'
      ],
      {
        helpLabel: 'YouTube Data API 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/library/youtube.googleapis.com',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('iprefererblocked') >= 0 ||
    combined.indexOf('referer') >= 0 && combined.indexOf('blocked') >= 0 ||
    combined.indexOf('api key restrictions') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_APPLICATION_RESTRICTION',
      'API 키의 애플리케이션 제한이 Apps Script 요청을 차단했습니다.',
      '현재 키에 설정된 웹사이트·IP 제한이 Apps Script의 UrlFetch 요청 방식과 맞지 않습니다.',
      [
        'HTTP 리퍼러 제한 또는 특정 IP 주소 제한이 적용되어 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키의 애플리케이션 제한을 확인합니다.',
        'Apps Script에서 사용할 수 있는 제한 방식으로 조정합니다.',
        'API 제한은 ‘YouTube Data API v3’로 유지합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') < 0 &&
    (
      combined.indexOf('forbidden') >= 0 &&
      combined.indexOf('api') >= 0 &&
      combined.indexOf('key') >= 0
    )
  ) {
    return buildErrorInfo_(
      'API_KEY_API_RESTRICTION',
      'API 키의 API 제한 설정을 확인해야 합니다.',
      '현재 API 키가 YouTube Data API v3 호출을 허용하지 않을 수 있습니다.',
      [
        'API 키의 ‘API 제한’ 목록에서 YouTube Data API v3가 빠져 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키를 선택합니다.',
        '‘API 제한’에서 YouTube Data API v3를 허용합니다.',
        '저장 후 1~5분 뒤 다시 실행합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('quotaexceeded') >= 0 ||
    combined.indexOf('dailylimitexceeded') >= 0 ||
    combined.indexOf('daily limit') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_QUOTA_EXCEEDED',
      'YouTube API의 오늘 할당량을 모두 사용했습니다.',
      '현재 Google Cloud 프로젝트에서 오늘 사용할 수 있는 YouTube Data API 할당량이 남아 있지 않습니다.',
      ['같은 프로젝트의 다른 프로그램에서도 YouTube API 할당량을 사용했을 수 있습니다.'],
      [
        'Google Cloud Console에서 YouTube Data API 사용량을 확인합니다.',
        '일일 할당량이 갱신된 뒤 다시 실행합니다.',
        '필요하면 다음 수집의 댓글 개수를 줄입니다.'
      ],
      {
        helpLabel: 'YouTube API 할당량 열기',
        helpUrl: 'https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas',
        actionLabel: '확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('ratelimitexceeded') >= 0 ||
    combined.indexOf('userratelimitexceeded') >= 0 ||
    statusCode === 429
  ) {
    return buildErrorInfo_(
      'YOUTUBE_RATE_LIMIT',
      '짧은 시간에 API 요청이 많이 발생했습니다.',
      'YouTube Data API가 일시적으로 요청 속도를 제한했습니다.',
      ['여러 수집 작업을 연속으로 실행했을 수 있습니다.'],
      [
        '현재 작업이 자동 재개되는지 확인합니다.',
        '몇 분 뒤 다시 실행합니다.',
        '동시에 여러 스프레드시트에서 같은 API 키를 사용하고 있다면 실행 횟수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (combined.indexOf('commentsdisabled') >= 0) {
    return buildErrorInfo_(
      'COMMENTS_DISABLED',
      '이 영상에서는 댓글을 수집할 수 없습니다.',
      '영상 게시자가 댓글 기능을 사용하지 않도록 설정했습니다.',
      ['영상의 댓글 기능이 꺼져 있거나 YouTube 정책에 따라 제한되었습니다.'],
      [
        '영상 페이지에서 댓글 영역이 표시되는지 확인합니다.',
        '댓글이 허용된 다른 영상 주소를 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('videonotfound') >= 0 ||
    combined.indexOf('video not found') >= 0
  ) {
    return buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '영상 주소가 잘못되었거나 영상이 삭제·비공개 상태일 수 있습니다.',
      [
        '영상 ID가 정확하지 않을 수 있습니다.',
        '영상 공개 상태가 변경되었을 수 있습니다.'
      ],
      [
        '브라우저에서 영상 주소가 정상적으로 열리는지 확인합니다.',
        '영상 URL 전체를 다시 복사해 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (statusCode >= 500) {
    return buildErrorInfo_(
      'YOUTUBE_SERVER_ERROR',
      'YouTube 서버에서 일시적인 오류가 발생했습니다.',
      'YouTube Data API 서버가 현재 요청을 정상적으로 처리하지 못했습니다.',
      ['YouTube 측의 일시적인 서비스 장애일 수 있습니다.'],
      [
        '잠시 뒤 같은 작업을 다시 실행합니다.',
        '진행 중인 수집이라면 자동 재개 여부를 확인합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (statusCode === 403) {
    return buildErrorInfo_(
      'YOUTUBE_ACCESS_FORBIDDEN',
      'YouTube 데이터에 접근할 수 없습니다.',
      'API 키 설정, 영상 공개 상태 또는 Google Cloud 프로젝트 권한을 확인해야 합니다.',
      [
        'API 키 제한 설정이 요청을 차단했을 수 있습니다.',
        '영상이 공개 API에서 접근할 수 없는 상태일 수 있습니다.'
      ],
      [
        'API 키의 API 제한과 애플리케이션 제한을 확인합니다.',
        '영상이 공개 상태인지 확인합니다.',
        'Google Cloud에서 YouTube Data API v3가 활성화되어 있는지 확인합니다.'
      ],
      {
        helpLabel: 'API 키 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (statusCode === 400) {
    return buildErrorInfo_(
      'YOUTUBE_BAD_REQUEST',
      'YouTube API 요청 형식을 확인해야 합니다.',
      '영상 주소 또는 요청 매개변수 중 하나를 YouTube API가 처리하지 못했습니다.',
      ['영상 주소가 올바르지 않거나 API 요청 값이 허용 범위를 벗어났을 수 있습니다.'],
      [
        '영상 주소를 다시 확인합니다.',
        '수집 개수와 정렬 기준을 확인합니다.',
        '같은 문제가 계속되면 새 수집으로 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '입력값 확인',
        technical: technical
      }
    );
  }

  return buildErrorInfo_(
    'YOUTUBE_API_ERROR',
    'YouTube API 요청을 완료하지 못했습니다.',
    'YouTube Data API가 요청을 거부하거나 처리하지 못했습니다.',
    ['API 키, 영상 공개 상태, 할당량 또는 네트워크 상태를 확인해야 합니다.'],
    [
      'API 키 설정과 YouTube Data API 활성화 여부를 확인합니다.',
      '영상 주소가 공개 영상인지 확인합니다.',
      '잠시 뒤 다시 실행합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}


/**
 * 영상 URL 또는 11자리 영상 ID에서 videoId를 추출합니다.
 */
function extractVideoId_(input) {
  const text = String(input || '').trim();

  if (/^[A-Za-z0-9_-]{11}$/.test(text)) {
    return text;
  }

  const patterns = [
    /[?&]v=([A-Za-z0-9_-]{11})/,
    /youtu\.be\/([A-Za-z0-9_-]{11})/,
    /youtube(?:-nocookie)?\.com\/(?:embed|shorts|live)\/([A-Za-z0-9_-]{11})/
  ];

  for (let i = 0; i < patterns.length; i += 1) {
    const match = text.match(patterns[i]);

    if (match) {
      return match[1];
    }
  }

  throwStructuredError_(buildErrorInfo_(
    'INVALID_VIDEO_URL',
    'YouTube 영상 주소를 확인해야 합니다.',
    '입력한 값에서 11자리 YouTube 영상 ID를 찾지 못했습니다.',
    [
      '영상 주소 일부가 빠졌을 수 있습니다.',
      '채널·재생목록 주소를 입력했을 수 있습니다.'
    ],
    [
      'YouTube에서 수집할 영상을 엽니다.',
      '브라우저 주소 표시줄의 영상 URL 전체를 복사합니다.',
      '사이드바의 영상 주소 입력란에 붙여 넣습니다.'
    ],
    {
      focusTarget: 'videoUrl',
      actionLabel: '영상 주소 다시 입력'
    }
  ));
}


/**
 * 사이드바 입력값을 검증합니다.
 */
function normalizeSidebarInput_(formData) {
  const form = formData || {};
  const videoUrl = String(form.videoUrl || '').trim();
  const limit = parseInt(form.limit, 10);

  if (!videoUrl) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_URL_REQUIRED',
      'YouTube 영상 주소를 입력해야 합니다.',
      '수집 대상 영상 주소가 비어 있습니다.',
      ['영상 주소 입력란에 값이 없습니다.'],
      ['수집할 YouTube 영상의 URL을 입력합니다.'],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 입력'
      }
    ));
  }

  if (!Number.isInteger(limit)) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_INVALID',
      '수집 개수를 정수로 입력해야 합니다.',
      '수집할 최상위 댓글 개수가 올바른 정수 형식이 아닙니다.',
      ['빈 값, 소수 또는 문자가 입력되었을 수 있습니다.'],
      ['1 이상의 정수를 입력합니다.'],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 입력'
      }
    ));
  }

  if (limit < YT_CFG.MIN_LIMIT || limit > YT_CFG.MAX_LIMIT) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_OUT_OF_RANGE',
      '수집 개수가 허용 범위를 벗어났습니다.',
      '수집 개수는 ' + YT_CFG.MIN_LIMIT + '개 이상 ' +
        YT_CFG.MAX_LIMIT + '개 이하로 입력해야 합니다.',
      ['입력한 개수가 코드에 설정된 운영 범위를 벗어났습니다.'],
      [
        YT_CFG.MIN_LIMIT + '~' + YT_CFG.MAX_LIMIT +
          ' 사이의 정수를 입력합니다.'
      ],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 수정'
      }
    ));
  }

  return {
    videoUrl: videoUrl,
    limit: limit,
    includeReplies: form.includeReplies === true
  };
}


/**
 * 결과 시트와 숨김 내부 시트를 준비합니다.
 */
function ensureInternalSheet_(ss) {
  let internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    internal = ss.insertSheet(YT_CFG.INTERNAL_SHEET);
  }

  ensureColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);

  if (internal.getLastRow() === 0) {
    internal
      .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
      .setValues([YT_CFG.INTERNAL_HEADERS]);
  }

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 새 수집에 사용할 결과 시트를 시트1, 시트2, 시트3 ... 순서로 만듭니다.
 *
 * 새 스프레드시트에 기본 빈 '시트1' 하나만 존재하는 경우에는 그 시트를
 * 첫 결과 시트로 사용합니다. 그 이후 수집부터는 항상 새 시트를 추가합니다.
 */
function createNextOutputSheet_(ss) {
  const sheets = ss.getSheets();

  if (
    sheets.length === 1 &&
    sheets[0].getName() === YT_CFG.OUTPUT_SHEET_PREFIX + '1' &&
    isSheetCompletelyBlank_(sheets[0])
  ) {
    prepareOutputSheet_(sheets[0]);
    return sheets[0];
  }

  let maxNumber = 0;
  const namePattern = new RegExp(
    '^' + escapeRegExp_(YT_CFG.OUTPUT_SHEET_PREFIX) + '(\\d+)$'
  );

  sheets.forEach(function(sheet) {
    const match = sheet.getName().match(namePattern);

    if (match) {
      maxNumber = Math.max(maxNumber, Number(match[1] || 0));
    }
  });

  let nextNumber = maxNumber + 1;
  let nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;

  while (ss.getSheetByName(nextName)) {
    nextNumber += 1;
    nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;
  }

  const sheet = ss.insertSheet(nextName);
  prepareOutputSheet_(sheet);
  return sheet;
}


function isSheetCompletelyBlank_(sheet) {
  return sheet.getLastRow() === 0 && sheet.getLastColumn() === 0;
}


function prepareOutputSheet_(sheet) {
  if (sheet.getFilter()) {
    sheet.getFilter().remove();
  }

  sheet.clear();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setValues([YT_CFG.HEADERS]);

  sheet.setFrozenRows(1);
  sheet.getRange('A:A').setNumberFormat('@');
  formatCommentsSheet_(sheet);
}


/**
 * 새 수집을 위해 숨김 내부 시트만 초기화합니다.
 * 이전 결과 시트의 내용은 변경하지 않습니다.
 */
function resetInternalData_(ss) {
  const internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_SHEET_NOT_FOUND',
      '내부 관리 시트를 준비하지 못했습니다.',
      '댓글 수집 상태를 저장하는 숨김 시트가 존재하지 않습니다.',
      ['내부 시트 생성 과정이 완료되지 않았습니다.'],
      ['사이드바를 닫았다가 다시 열고 새 수집을 시작합니다.'],
      { actionLabel: '확인' }
    ));
  }

  internal.clear();
  ensureExactColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);
  internal
    .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .setValues([YT_CFG.INTERNAL_HEADERS]);

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 현재 수집 상태에 연결된 결과 시트를 찾습니다.
 */
function getOutputSheetForState_(ss, state) {
  const expectedId = Number(state.outputSheetId || 0);
  let outputSheet = null;

  if (expectedId > 0) {
    outputSheet = ss.getSheets().find(function(sheet) {
      return sheet.getSheetId() === expectedId;
    }) || null;
  }

  if (!outputSheet && state.outputSheetName) {
    outputSheet = ss.getSheetByName(String(state.outputSheetName));
  }

  if (!outputSheet) {
    throwStructuredError_(buildErrorInfo_(
      'OUTPUT_SHEET_NOT_FOUND',
      '수집 결과 시트를 찾을 수 없습니다.',
      '현재 수집 작업과 연결된 결과 시트가 삭제되었거나 이름과 식별 정보가 변경되었습니다.',
      [
        '수집 중 결과 시트를 삭제했을 수 있습니다.',
        '스프레드시트 구조가 외부 작업으로 변경되었을 수 있습니다.'
      ],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }

  return outputSheet;
}


function escapeRegExp_(text) {
  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}


/**
 * 이전 버전이 만든 수집로그 시트를 제거합니다.
 */
function deleteLegacyLogSheet_(ss) {
  const logSheet = ss.getSheetByName(YT_CFG.LEGACY_LOG_SHEET);

  if (logSheet && ss.getSheets().length > 1) {
    ss.deleteSheet(logSheet);
  }
}


/**
 * 댓글 시트를 번호 순으로 정렬하고 최종 서식을 적용합니다.
 */
function finalizeCommentsSheet_(sheet) {
  sortCommentsByDisplayNumber_(sheet);
  formatCommentsSheet_(sheet);
}


function sortCommentsByDisplayNumber_(sheet) {
  const lastRow = sheet.getLastRow();

  if (lastRow <= 2) {
    return;
  }

  // 정렬용 임시 열 I, J를 만든 뒤 최상위 번호와 답글 번호로 정렬합니다.
  ensureColumnCount_(sheet, 10);

  const numberValues = sheet
    .getRange(2, 1, lastRow - 1, 1)
    .getDisplayValues();

  const sortKeys = numberValues.map(function(row) {
    const parts = String(row[0] || '').split('_');
    return [
      Number(parts[0] || 0),
      parts.length > 1 ? Number(parts[1] || 0) : 0
    ];
  });

  sheet
    .getRange(2, 9, sortKeys.length, 2)
    .setValues(sortKeys);

  sheet
    .getRange(2, 1, lastRow - 1, 10)
    .sort([
      { column: 9, ascending: true },
      { column: 10, ascending: true }
    ]);

  sheet.getRange(2, 9, lastRow - 1, 2).clearContent();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
}


function formatCommentsSheet_(sheet) {
  const lastRow = sheet.getLastRow();

  sheet.setFrozenRows(1);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setFontWeight('bold')
    .setWrap(true)
    .setVerticalAlignment('middle');

  sheet.getRange('A:A').setNumberFormat('@');

  if (lastRow > 1) {
    sheet
      .getRange(2, 7, lastRow - 1, 1)
      .setNumberFormat('yyyy-mm-dd hh:mm:ss');

    sheet
      .getRange(2, 5, lastRow - 1, 1)
      .setWrap(true)
      .setVerticalAlignment('top');

    sheet
      .getRange(2, 1, lastRow - 1, YT_CFG.HEADERS.length)
      .setVerticalAlignment('top');

    if (sheet.getFilter()) {
      sheet.getFilter().remove();
    }

    sheet
      .getRange(1, 1, lastRow, YT_CFG.HEADERS.length)
      .createFilter();
  }

  sheet.setColumnWidth(1, 90);
  sheet.setColumnWidth(2, 180);
  sheet.setColumnWidth(3, 260);
  sheet.setColumnWidth(4, 170);
  sheet.setColumnWidth(5, 520);
  sheet.setColumnWidth(6, 95);
  sheet.setColumnWidth(7, 155);
  sheet.setColumnWidth(8, 95);
}


/**
 * 숨김 내부 시트에 저장된 댓글 ID 집합을 만듭니다.
 */
function getExistingCommentIds_(internalSheet) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return new Set();
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .getDisplayValues();

  return new Set(
    values
      .map(function(row) {
        return row[0];
      })
      .filter(function(value) {
        return Boolean(value);
      })
  );
}


/**
 * 숨김 내부 시트 기준으로 실제 최상위 댓글·답글 수를 계산합니다.
 */
function getExistingCounts_(internalSheet) {
  const lastRow = internalSheet.getLastRow();
  const counts = { top: 0, reply: 0 };

  if (lastRow <= 1) {
    return counts;
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_TYPE, lastRow - 1, 1)
    .getDisplayValues();

  values.forEach(function(row) {
    if (row[0] === 'topLevel') {
      counts.top += 1;
    } else if (row[0] === 'reply') {
      counts.reply += 1;
    }
  });

  return counts;
}


/**
 * 댓글 글자수를 지정된 바이트 규칙으로 계산합니다.
 * - ASCII 영역(영문, 숫자, 공백, 일반 문장부호): 1바이트
 * - 한글을 포함한 비ASCII 유니코드 문자: 코드 포인트당 2바이트
 */
function calculateCommentBytes_(value) {
  const text = String(value || '');
  let bytes = 0;

  Array.from(text).forEach(function(character) {
    const codePoint = character.codePointAt(0);
    bytes += codePoint <= 0x7F ? 1 : 2;
  });

  return bytes;
}


/**
 * 외부 문자열이 시트 수식으로 실행되는 것을 방지합니다.
 */
function safeCellText_(value) {
  const text = value === undefined || value === null ? '' : String(value);
  return /^[=+\-@]/.test(text) ? "'" + text : text;
}


function apiDateToSheetValue_(value) {
  return value ? new Date(value) : '';
}


function ensureColumnCount_(sheet, requiredColumns) {
  const current = sheet.getMaxColumns();

  if (current < requiredColumns) {
    sheet.insertColumnsAfter(current, requiredColumns - current);
  }
}


function ensureExactColumnCount_(sheet, requiredColumns) {
  ensureColumnCount_(sheet, requiredColumns);

  const current = sheet.getMaxColumns();

  if (current > requiredColumns) {
    sheet.deleteColumns(requiredColumns + 1, current - requiredColumns);
  }
}


function getUserProperties_() {
  return PropertiesService.getUserProperties();
}


function getApiKey_() {
  const apiKey = getUserProperties_().getProperty(YT_CFG.API_KEY_PROP);

  if (!apiKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키 설정이 필요합니다.',
      '댓글 수집을 시작하기 전에 YouTube Data API 키를 저장해야 합니다.',
      ['현재 사용자 계정에 저장된 API 키가 없습니다.'],
      [
        '사이드바 상단의 API 키 입력란에 키를 입력합니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  return apiKey.trim();
}


function loadState_() {
  const text = getUserProperties_().getProperty(YT_CFG.STATE_PROP);
  return text ? JSON.parse(text) : null;
}


function saveState_(state) {
  state.updatedAt = new Date().toISOString();
  const text = JSON.stringify(state);
  const byteLength = Utilities.newBlob(text).getBytes().length;

  if (byteLength > 8500) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_STORAGE_LIMIT',
      '수집 진행 상태를 저장할 수 없습니다.',
      'Apps Script 사용자 속성의 안전 저장 크기를 초과했습니다.',
      ['진행 상태 데이터가 예상보다 커졌습니다.'],
      [
        '현재 수집을 취소합니다.',
        '댓글 수집 개수를 줄여 새로 실행합니다.'
      ],
      { actionLabel: '확인', technical: { byteLength: byteLength } }
    ));
  }

  getUserProperties_().setProperty(YT_CFG.STATE_PROP, text);
}


function loadLastResult_() {
  const text = getUserProperties_().getProperty(YT_CFG.LAST_RESULT_PROP);
  return text ? JSON.parse(text) : null;
}


function saveLastResult_(state, status, message, errorInfo) {
  const result = {
    status: status,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: Number(state.targetTopLevelCount || 0),
    topCount: Number(state.topCount || 0),
    replyCount: Number(state.replyCount || 0),
    apiCalls: Number(state.apiCalls || 0),
    startedAt: state.startedAt || '',
    updatedAt: new Date().toISOString(),
    finishedAt: new Date().toISOString(),
    message: message || '',
    error: errorInfo || null
  };

  getUserProperties_().setProperty(
    YT_CFG.LAST_RESULT_PROP,
    JSON.stringify(result)
  );
}


function validateStateVersion_(state) {
  if (Number(state.version || 0) !== YT_CFG.STATE_VERSION) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_VERSION_MISMATCH',
      '이전 코드에서 시작된 수집 작업을 이어갈 수 없습니다.',
      '현재 Code.gs의 댓글 저장 구조가 이전 실행 상태와 다릅니다.',
      ['고정 결과 시트 또는 정렬 기준을 사용하던 이전 코드의 작업 상태가 남아 있습니다.'],
      [
        '사이드바에서 진행 중인 수집을 취소합니다.',
        '현재 코드로 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }
}


function normalizeState_(state) {
  state.currentReplyParentId = state.currentReplyParentId || '';
  state.nextReplyPageToken = state.nextReplyPageToken || '';
  state.nextThreadPageToken = state.nextThreadPageToken || '';
  state.threadDone = Boolean(state.threadDone);
  state.topCount = Number(state.topCount || 0);
  state.replyCount = Number(state.replyCount || 0);
  state.apiCalls = Number(state.apiCalls || 0);
  state.threadPages = Number(state.threadPages || 0);
  state.replyPages = Number(state.replyPages || 0);
  state.targetTopLevelCount = Number(state.targetTopLevelCount || 0);
  state.outputSheetId = Number(state.outputSheetId || 0);
  state.outputSheetName = String(state.outputSheetName || '');
  state.error = state.error || null;
}


function maskApiKey_(apiKey) {
  const key = String(apiKey || '');
  return '••••••••••••' + key.slice(-4);
}


function buildProgressForClient_(state, status) {
  const target = Number(state.targetTopLevelCount || 0);
  const top = Number(state.topCount || 0);
  const reply = Number(state.replyCount || 0);
  const percent = target > 0
    ? Math.min(100, Math.round((top / target) * 100))
    : 0;

  let stage = '대기 중';

  if (status === 'RUNNING') {
    if (state.currentReplyParentId) {
      stage = '답글 수집 중';
    } else if (!state.threadDone) {
      stage = '최상위 댓글 수집 중';
    } else {
      stage = '마무리 중';
    }
  } else if (status === 'COMPLETED') {
    stage = '완료';
  } else if (status === 'ERROR') {
    stage = '오류';
  } else if (status === 'CANCELLED') {
    stage = '취소됨';
  }

  return {
    status: status,
    stage: stage,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: target,
    topCount: top,
    replyCount: reply,
    totalRows: top + reply,
    apiCalls: Number(state.apiCalls || 0),
    percent: percent,
    startedAt: state.startedAt || '',
    updatedAt: state.updatedAt || '',
    message: state.message || '',
    error: state.error || null
  };
}


function buildServerProgressMessage_(state) {
  return (
    '최상위 댓글 ' +
    state.topCount +
    '/' +
    state.targetTopLevelCount +
    '개, 답글 ' +
    state.replyCount +
    '개를 저장했습니다.'
  );
}


function scheduleContinuation_() {
  deleteContinuationTriggers_();

  ScriptApp
    .newTrigger(YT_CFG.CONTINUE_HANDLER)
    .timeBased()
    .after(YT_CFG.CONTINUE_AFTER_MS)
    .create();
}


function deleteContinuationTriggers_() {
  ScriptApp.getProjectTriggers().forEach(function(trigger) {
    if (trigger.getHandlerFunction() === YT_CFG.CONTINUE_HANDLER) {
      ScriptApp.deleteTrigger(trigger);
    }
  });
}


/**
 * 한국어 모달용 오류 정보를 만듭니다.
 */
function buildErrorInfo_(code, title, summary, causes, steps, options) {
  const opts = options || {};

  return {
    code: String(code || 'UNKNOWN_ERROR'),
    title: String(title || '작업을 완료하지 못했습니다.'),
    summary: String(summary || '처리 중 문제가 발생했습니다.'),
    causes: Array.isArray(causes) ? causes.map(String) : [],
    steps: Array.isArray(steps) ? steps.map(String) : [],
    helpLabel: String(opts.helpLabel || ''),
    helpUrl: String(opts.helpUrl || ''),
    focusTarget: String(opts.focusTarget || ''),
    actionLabel: String(opts.actionLabel || '확인'),
    technical:
      opts.technical && typeof opts.technical === 'object'
        ? opts.technical
        : {}
  };
}


/**
 * 서버 오류를 Sidebar.html이 해석할 수 있는 구조화된 예외로 전달합니다.
 */
function throwStructuredError_(errorInfo) {
  throw new Error(
    YT_CFG.STRUCTURED_ERROR_PREFIX + JSON.stringify(errorInfo)
  );
}


function extractStructuredError_(rawText) {
  const raw = String(rawText || '');
  const markerIndex = raw.indexOf(YT_CFG.STRUCTURED_ERROR_PREFIX);

  if (markerIndex < 0) {
    return null;
  }

  const jsonText = raw.slice(
    markerIndex + YT_CFG.STRUCTURED_ERROR_PREFIX.length
  );

  try {
    return JSON.parse(jsonText);
  } catch (parseError) {
    return null;
  }
}


/**
 * Apps Script 자체 오류도 한국어 모달 정보로 변환합니다.
 */
function normalizeErrorInfo_(error, context) {
  const raw = error && error.message
    ? String(error.message)
    : String(error || '');

  const structured = extractStructuredError_(raw);

  if (structured) {
    return structured;
  }

  const lower = raw.toLowerCase();
  const technical = {
    context: String(context || '작업 실행'),
    originalMessage: raw
  };

  if (
    lower.indexOf('authorization is required') >= 0 ||
    lower.indexOf('you do not have permission') >= 0 ||
    lower.indexOf('permissions') >= 0 && lower.indexOf('required') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_AUTH_REQUIRED',
      'Google 권한 승인이 필요합니다.',
      '현재 계정이 스프레드시트 또는 외부 API 요청 권한을 아직 승인하지 않았습니다.',
      ['Apps Script를 처음 실행했거나 새로운 권한이 추가되었습니다.'],
      [
        '스프레드시트 메뉴에서 사이드바를 다시 엽니다.',
        '권한 검토 화면에서 현재 Google 계정을 선택합니다.',
        '요청되는 권한을 허용한 뒤 다시 실행합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('maximum execution time') >= 0 ||
    lower.indexOf('exceeded maximum execution time') >= 0 ||
    lower.indexOf('timed out') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_EXECUTION_TIMEOUT',
      '한 번의 실행 가능 시간을 초과했습니다.',
      '댓글 또는 답글 처리 시간이 길어 현재 실행 구간이 종료되었습니다.',
      ['대량 댓글 수집으로 한 번의 Apps Script 실행 시간이 길어졌습니다.'],
      [
        '사이드바를 다시 열어 진행 상태를 확인합니다.',
        '멈춘 경우 ‘중단 지점부터 실행’을 한 번 실행합니다.',
        '같은 문제가 반복되면 수집 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('service invoked too many times') >= 0 ||
    lower.indexOf('quota') >= 0 && lower.indexOf('apps script') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_SERVICE_QUOTA',
      'Apps Script 서비스 사용 한도를 초과했습니다.',
      '현재 Google 계정 또는 스크립트의 일일 서비스 사용량이 허용 범위를 넘었습니다.',
      ['짧은 시간에 많은 외부 요청이나 스프레드시트 쓰기 작업이 실행되었습니다.'],
      [
        '잠시 뒤 다시 실행합니다.',
        '같은 날 반복되면 다음 날 다시 실행합니다.',
        '한 번에 수집하는 댓글 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  return buildErrorInfo_(
    'UNEXPECTED_ERROR',
    '예상하지 못한 오류가 발생했습니다.',
    '오류 유형을 자동으로 판별하지 못했습니다.',
    [
      '네트워크, 권한, Google 서비스 상태 또는 실행 환경에서 문제가 발생했을 수 있습니다.'
    ],
    [
      '사이드바를 닫았다가 다시 열고 같은 작업을 한 번 더 실행합니다.',
      'Apps Script 편집기의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.',
      'API 키와 영상 주소를 다시 확인합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}

Sidebar.html

YouTube 댓글 수집기

YouTube Data API v3 → Google Sheets

1. API 키

YouTube Data API 키

최초 1회 저장합니다. 키는 사용자별 Apps Script 속성에 보관됩니다.

2. 수집 설정

API 키를 저장하면 수집 설정이 활성화됩니다.

YouTube 영상 주소

수집할 최상위 댓글 수

1~50,000개. 답글 포함 시 실제 저장 행 수가 이 값보다 많아질 수 있습니다.

대댓글도 모두 수집

새 수집을 시작할 때마다 ‘시트1’, ‘시트2’, ‘시트3’ 형식의 새 시트가 생성됩니다. 기존 수집 결과는 유지됩니다.

(3) 바른 API KEY 발급

(4) 민기쌤 생기부 도우미

Code.gs

// =================================================================
// [0] 초기 설정 및 메뉴
// =================================================================

function onOpen() {
  SpreadsheetApp.getUi().createMenu('민기쌤 생기부 도우미')
      .addItem('🚀 사이드바 열기', 'openSidebar') 
      .addToUi();
}

function renderView_(viewName) {
  var template = HtmlService.createTemplateFromFile('Sidebar');
  template.initialView = viewName || 'sidebar';
  return template.evaluate();
}

function openSidebar() {
  ensureBannedWordSheet_();
  var html = renderView_('sidebar')
      .setTitle('민기쌤 생기부 맞춤법 도우미')
      .setWidth(300); 
  SpreadsheetApp.getUi().showSidebar(html);
}

function openSpellCheckViewer() {
  var html = renderView_('spellcheck')
      .setWidth(1000) 
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '📝 Bareun 맞춤법 검사 및 수정');
}

function openBannedWordViewer() {
  var html = renderView_('banned')
      .setWidth(1000)
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '🚫 기재 금지어 점검');
}

// =================================================================
// [1] Bareun API 키 및 UI 설정
// =================================================================

function getBareunUserProperties_() {
  ensureBannedWordSheet_();
  var props = PropertiesService.getUserProperties();
  var currentPolicy = 'BAREUN_ONLY_KEYS_V3';
  var previousPolicy = props.getProperty('API_KEY_POLICY_VERSION');

  // 정책 변경 시 현재 기능에서 쓰지 않는 예전 사용자 설정을 한 번 정리합니다.
  if (previousPolicy !== currentPolicy) {
    var allowedProperties = {
      UI_STATE: true,
      API_KEY_POLICY_VERSION: true
    };
    // 바로 이전 사용자 입력형 정책에서 저장한 키만 보존합니다.
    if (previousPolicy === 'USER_SUPPLIED_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V2') {
      allowedProperties.USER_BAREUN_KEY = true;
    }
    Object.keys(props.getProperties()).forEach(function(propertyName) {
      if (!allowedProperties[propertyName]) props.deleteProperty(propertyName);
    });

    var previousUiState = {};
    try {
      previousUiState = JSON.parse(props.getProperty('UI_STATE') || '{}');
    } catch (e) {
      previousUiState = {};
    }
    var currentUiState = {};
    ['card-api', 'sub-api-settings', 'card-util'].forEach(function(id) {
      if (previousUiState[id]) currentUiState[id] = true;
    });
    props.setProperty('UI_STATE', JSON.stringify(currentUiState));
    props.setProperty('API_KEY_POLICY_VERSION', currentPolicy);
  }

  return props;
}

function saveUserBareunKey(bareunKey) {
  var props = getBareunUserProperties_();
  var cleanBareunKey = String(bareunKey || '').trim();

  if (!cleanBareunKey) {
    throw new Error('Bareun API 키를 입력해 주세요. 이 도우미는 API 키를 제공하지 않습니다.');
  }

  props.setProperty('USER_BAREUN_KEY', cleanBareunKey);
  return { hasBareun: true };
}

function checkUserBareunStatus() {
  var props = getBareunUserProperties_();
  return { hasBareun: !!props.getProperty('USER_BAREUN_KEY') };
}

function clearUserBareunKey() {
  var props = getBareunUserProperties_();
  props.deleteProperty('USER_BAREUN_KEY');
  return { hasBareun: false };
}

function getBareunKey() {
  var key = getBareunUserProperties_().getProperty('USER_BAREUN_KEY');
  if (!key) throw new Error("Bareun API 키가 없습니다. 사이드바 상단에서 등록해주세요.");
  return key;
}

// =================================================================
// [2] Bareun 맞춤법 검사
// =================================================================

function getSelectedDataForSpellCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");
  var rows = [];
  var startRow = range.getRow();
  var startCol = range.getColumn();
  var values = range.getValues();
  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var text = values[i][j].toString();
      if (text.trim() !== "") {
        rows.push({ sheetName: sheetName, row: startRow + i, col: startCol + j, original: text });
      }
    }
  }
  return rows;
}

function getBareunCorrection(text) {
  var userKey = getBareunKey();
  var result = callBareunApi(text, userKey); 
  return result; 
}

function applySpellCheckResults(updates) {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  updates.forEach(function(item) {
    var sheet = spreadsheet.getSheetByName(item.sheetName);
    if (!sheet) throw new Error('검사한 시트를 찾을 수 없습니다: ' + item.sheetName);
    sheet.getRange(item.row, item.col).setValue(item.text);
  });
  return updates.length;
}

function callBareunApi(text, userKey) {
  var url = "https://api.bareun.ai/bareun.RevisionService/CorrectError";
  var options = {
    "method": "post", "contentType": "application/json", "headers": { "api-key": userKey }, "muteHttpExceptions": true,
    "payload": JSON.stringify({ "document": { "content": text, "language": "ko-KR" }, "encoding_type": "UTF16" })
  };
  var response = UrlFetchApp.fetch(url, options);
  var result = JSON.parse(response.getContentText());
  
  if (response.getResponseCode() !== 200) {
    return { error: "API 오류: " + response.getResponseCode() };
  }
  return { revised: result.revised, helps: result.helps || {}, rawBlocks: result.revisedBlocks || result.revised_blocks || [], error: null };
}

// =================================================================
// [3] 기재 금지어 관리
// =================================================================

var BANNED_WORD_SHEET_NAME_ = '기재금지어관리';
var BANNED_WORD_HEADERS_ = ['유형', '기재 금지어', '대체 표현'];

function getLegacyBannedWordList_() {
  var saved = PropertiesService.getUserProperties().getProperty('BANNED_WORDS_DB');
  if (!saved) return getDefaultBannedList_();

  try {
    var parsed = JSON.parse(saved);
    if (!Array.isArray(parsed)) return getDefaultBannedList_();
    return parsed
      .map(function(item) {
        return {
          k: String(item && item.k || '').trim(),
          v: String(item && item.v || '').trim(),
          t: item && item.t === 'ban' ? 'ban' : 'replace'
        };
      })
      .filter(function(item) { return item.k !== ''; });
  } catch (e) {
    return getDefaultBannedList_();
  }
}

function initializeBannedWordSheet_(sheet, list) {
  sheet.getRange(1, 1, 1, BANNED_WORD_HEADERS_.length)
    .setValues([BANNED_WORD_HEADERS_])
    .setBackground('#fce8e6')
    .setFontColor('#a50e0e')
    .setFontWeight('bold')
    .setHorizontalAlignment('center');

  var rows = list.map(function(item) {
    return [item.t === 'ban' ? '불가' : '대체', item.k, item.t === 'ban' ? '' : item.v];
  });
  if (rows.length > 0) sheet.getRange(2, 1, rows.length, 3).setValues(rows);

  sheet.setFrozenRows(1);
  sheet.setColumnWidth(1, 90);
  sheet.setColumnWidth(2, 180);
  sheet.setColumnWidth(3, 260);
  sheet.setTabColor('#d93025');

  if (sheet.getMaxRows() > 1) {
    var typeRule = SpreadsheetApp.newDataValidation()
      .requireValueInList(['대체', '불가'], true)
      .setAllowInvalid(false)
      .setHelpText('대체 또는 불가 중 하나를 선택하세요.')
      .build();
    sheet.getRange(2, 1, sheet.getMaxRows() - 1, 1).setDataValidation(typeRule);
  }
}

function ensureBannedWordSheet_() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  if (!spreadsheet) throw new Error('활성 스프레드시트를 찾을 수 없습니다.');

  var originalSheet = spreadsheet.getActiveSheet();
  var originalRange = spreadsheet.getActiveRange();
  var lock = LockService.getDocumentLock() || LockService.getScriptLock();
  lock.waitLock(30000);

  var sheet;
  try {
    sheet = spreadsheet.getSheetByName(BANNED_WORD_SHEET_NAME_);
    if (!sheet) {
      sheet = spreadsheet.insertSheet(BANNED_WORD_SHEET_NAME_);
      initializeBannedWordSheet_(sheet, getLegacyBannedWordList_());
    }

    // 시트로 옮긴 뒤 예전 사용자별 저장값은 더 이상 별도 원본으로 남기지 않습니다.
    PropertiesService.getUserProperties().deleteProperty('BANNED_WORDS_DB');
    return sheet;
  } finally {
    if (originalSheet && sheet && originalSheet.getSheetId() !== sheet.getSheetId()) {
      spreadsheet.setActiveSheet(originalSheet);
      if (originalRange) spreadsheet.setActiveRange(originalRange);
    }
    lock.releaseLock();
  }
}

function openBannedWordManagementSheet() {
  var sheet = ensureBannedWordSheet_();
  sheet.activate();
  sheet.getRange('A1').activate();
  return sheet.getName();
}

function getDefaultBannedList_() {
  return [
    { k: "MBTI", v: "성격 유형 검사", t: "replace" },
    { k: "커리어넷", v: "진로 정보 사이트", t: "replace" },
    { k: "메이저맵", v: "진로 정보망", t: "replace" },
    { k: "패들렛", v: "온라인 협업 도구", t: "replace" },
    { k: "띵커벨", v: "온라인 협업 플랫폼", t: "replace" },
    { k: "알로", v: "온라인 협업 플랫폼", t: "replace" },
    { k: "미리캔버스", v: "온라인 디자인 제작 플랫폼", t: "replace" },
    { k: "망고보드", v: "온라인 디자인 제작 플랫폼", t: "replace" },
    { k: "유튜버", v: "동영상 크리에이터", t: "replace" },
    { k: "유튜브", v: "동영상 공유 플랫폼", t: "replace" },
    { k: "넷플릭스", v: "온라인 동영상 서비스", t: "replace" },
    { k: "왓챠", v: "온라인 동영상 서비스", t: "replace" },
    { k: "티빙", v: "온라인 동영상 서비스", t: "replace" },
    { k: "네이버 폼", v: "온라인 설문조사", t: "replace" },
    { k: "구글 폼", v: "온라인 설문조사", t: "replace" },
    { k: "OECD", v: "경제 관련 국제 기구", t: "replace" },
    { k: "UN", v: "국제 기구", t: "replace" },
    { k: "유네스코", v: "교육 문화 국제 기구", t: "replace" },
    { k: "WTO", v: "무역 관련 국제 기구", t: "replace" },
    { k: "WHO", v: "보건 관련 국제 기구", t: "replace" },
    { k: "그린피스", v: "국제 환경 보전 단체", t: "replace" },
    { k: "앰네스티", v: "인권 관련 국제 비정부 기구", t: "replace" },
    { k: "IMF", v: "국제 통화 관련 기구", t: "replace" },
    { k: "인스타그램", v: "사회 관계망 서비스", t: "replace" },
    { k: "페이스북", v: "소셜 미디어 서비스", t: "replace" },
    { k: "카카오톡", v: "메신저 서비스", t: "replace" },
    { k: "네이버", v: "포털 사이트", t: "replace" },
    { k: "구글", v: "검색 엔진", t: "replace" },
    { k: "클래스 카드", v: "단어 학습 어플", t: "replace" },
    { k: "구글 클래스룸", v: "학습 플랫폼", t: "replace" },
    { k: "게더타운", v: "메타버스 플랫폼", t: "replace" },
    { k: "제페토", v: "메타버스 플랫폼", t: "replace" },
    { k: "아이패드", v: "태블릿 PC", t: "replace" },
    { k: "갤럭시 탭", v: "태블릿 PC", t: "replace" },
    { k: "비트코인", v: "가상 화폐", t: "replace" },
    { k: "TED", v: "온라인 강연", t: "replace" },
    { k: "반크", v: "사이버 외교 사절단", t: "replace" },
    { k: "TOEIC", v: "", t: "ban" },
    { k: "TOEFL", v: "", t: "ban" },
    { k: "TEPS", v: "", t: "ban" },
    { k: "대회", v: "", t: "ban" },
    { k: "수상", v: "", t: "ban" },
    { k: "한자능력검정", v: "", t: "ban" }
  ];
}

function getBannedWordList_() {
  var sheet = ensureBannedWordSheet_();
  var header = sheet.getRange(1, 1, 1, 3).getDisplayValues()[0];
  if (header.join('|') !== BANNED_WORD_HEADERS_.join('|')) {
    throw new Error('기재금지어관리 시트의 1행을 "유형 | 기재 금지어 | 대체 표현" 순서로 유지해 주세요.');
  }

  var lastRow = sheet.getLastRow();
  if (lastRow < 2) return [];

  var values = sheet.getRange(2, 1, lastRow - 1, 3).getDisplayValues();
  var seen = {};
  var list = [];

  values.forEach(function(row, index) {
    var rowNumber = index + 2;
    var type = String(row[0] || '').trim();
    var keyword = String(row[1] || '').trim();
    var replacement = String(row[2] || '').trim();

    if (!type && !keyword && !replacement) return;
    if (!keyword) throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어(B열)를 입력해 주세요.');
    if (type !== '대체' && type !== '불가') {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 유형(A열)은 대체 또는 불가여야 합니다.');
    }
    if (type === '대체' && !replacement) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 대체 표현(C열)을 입력하거나 유형을 불가로 바꿔 주세요.');
    }

    var duplicateKey = keyword.toLocaleLowerCase();
    if (seen[duplicateKey]) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어가 ' + seen[duplicateKey] + '행과 중복됩니다: ' + keyword);
    }
    seen[duplicateKey] = rowNumber;
    list.push({ k: keyword, v: type === '불가' ? '' : replacement, t: type === '불가' ? 'ban' : 'replace' });
  });

  return list;
}

function runBannedWordCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  var values = range.getValues();
  var startRow = range.getRow();
  var startCol = range.getColumn();
  
  var db = getBannedWordList_();
  db.sort((a, b) => b.k.length - a.k.length);

  var patterns = db.map(function(item) {
    return {
      regex: new RegExp(escapeRegExp(item.k), "gi"),
      v: item.v,
      t: item.t,
      k: item.k
    };
  });

  var results = [];

  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var original = values[i][j].toString();
      if (!original.trim()) continue;

      var revised = original;
      var hasIssue = false;
      var logs = [];

      for (var p = 0; p < patterns.length; p++) {
        var item = patterns[p];
        if (item.regex.test(revised)) {
          hasIssue = true;
          var alreadyLogged = false;
          for(var l=0; l {
    return row.map(cell => {
      let str = String(cell);
      // 공백이 2번 이상 연속( /  +/)으로 있으면 1번으로 변경
      // 줄바꿈(\n)은 건드리지 않도록 일반 공백( )만 타겟팅
      if (/ {2,}/.test(str)) {
        fixCount++;
        return str.replace(/ {2,}/g, ' '); 
      }
      return cell;
    });
  });

  if (fixCount > 0) {
    range.setValues(newValues);
  }
  
  return fixCount;
}

// =================================================================
// [5] UI 상태 저장/불러오기
// =================================================================

function saveUiState(cardId, isExpanded) {
  var props = PropertiesService.getUserProperties();
  var state = JSON.parse(props.getProperty('UI_STATE') || '{}');
  state[cardId] = isExpanded;
  props.setProperty('UI_STATE', JSON.stringify(state));
}

function getUiState() {
  var props = PropertiesService.getUserProperties();
  return JSON.parse(props.getProperty('UI_STATE') || '{}');
}

Sidebar.html


= 0 ? initialView : "sidebar"; ?>



  
    
    
    
    
  
  
    
      
        🔑 Bareun API 키 설정
        expand_more
      
      
        
          
            내 Bareun API 키
            expand_more
          
          
            ⌛ API 키 설정 확인 중...
            
              
              Bareun API 키
              
              공용 키는 제공하지 않습니다. 키는 사용자별 설정에 저장되고 원문을 화면으로 다시 불러오지 않습니다.
              
              
            
          
        
      
    

    
      
        📝 선택 영역 검사 및 정리
        expand_more
      
      
        
        
        
        
        
        
      
    

    
  





  
    
    
    
    
    
  
  

    
      fact_check 맞춤법 검사 및 수정
      
        원본 오류
        수정 제안
      
    

    
      
        
        데이터를 불러오는 중입니다...
      
      
    

    
      
      
    

    
  





  
    
    
    
    
  
  

    
      block 기재 금지어 검사
      
        금지어 발견
        대체어 제안
      
    

    
      
        
        데이터를 분석 중입니다...

(5) 설문조사, 지도안 작성

2026년 인공지능 활용 선도교사 연수 (충남 천안 - 7. 19.)

Thu, 11 Jun 2026 11:08:50 GMT

2026년 인공지능 활용 선도교사 연수 (충남 천안 - 7. 19.)

강사: 교사 김민기(민기쌤)
일시: 2026-07-19
장소: 신라스테이 천안

클로바노트 음성 전사

유튜브 댓글 수집

Code.gs

const YT_CFG = Object.freeze({
  API_BASE: 'https://www.googleapis.com/youtube/v3',

  API_KEY_PROP: 'YT_API_KEY',
  STATE_PROP: 'YT_COMMENT_COLLECTOR_STATE',
  LAST_RESULT_PROP: 'YT_COMMENT_COLLECTOR_LAST_RESULT',
  CANCEL_REQUEST_PROP: 'YT_COMMENT_COLLECTOR_CANCEL_REQUEST',

  OUTPUT_SHEET_PREFIX: '시트',
  INTERNAL_SHEET: '_댓글수집_내부',
  LEGACY_LOG_SHEET: '수집로그',

  CONTINUE_HANDLER: 'continueCommentCollection',
  STRUCTURED_ERROR_PREFIX: 'YT_STRUCTURED_ERROR::',
  STATE_VERSION: 4,

  // Apps Script의 일반 실행 제한 전에 상태를 저장하고 다음 실행으로 넘깁니다.
  MAX_RUN_MS: 4 * 60 * 1000 + 30 * 1000,
  CONTINUE_AFTER_MS: 60 * 1000,

  MIN_LIMIT: 1,
  MAX_LIMIT: 50000,

  HEADERS: [
    '번호',
    '채널명',
    '영상 제목',
    '댓글 작성자',
    '댓글 내용',
    '좋아요 수',
    '작성 시각',
    '글자수'
  ],

  // 숨김 내부 시트의 열 구조입니다.
  INTERNAL_HEADERS: [
    'comment_id',
    'parent_comment_id',
    'display_number',
    'comment_type',
    'reply_status',
    'next_reply_index',
    'total_reply_count',
    'reply_page_token'
  ],

  INTERNAL_COL: Object.freeze({
    COMMENT_ID: 1,
    PARENT_ID: 2,
    DISPLAY_NUMBER: 3,
    COMMENT_TYPE: 4,
    REPLY_STATUS: 5,
    NEXT_REPLY_INDEX: 6,
    TOTAL_REPLY_COUNT: 7,
    REPLY_PAGE_TOKEN: 8
  })
});


/**
 * 스프레드시트를 열 때 사용자 메뉴를 만듭니다.
 */
function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('YouTube 댓글 수집')
    .addItem('사이드바 열기', 'showYouTubeCommentSidebar')
    .addSeparator()
    .addItem('중단 지점부터 실행', 'continueCommentCollection')
    .addItem('진행 중인 수집 취소', 'cancelCommentCollection')
    .addToUi();
}


/**
 * 오른쪽 사이드바를 엽니다.
 */
function showYouTubeCommentSidebar() {
  const html = HtmlService
    .createHtmlOutputFromFile('Sidebar')
    .setTitle('YouTube 댓글 수집기');

  SpreadsheetApp.getUi().showSidebar(html);
}


/**
 * 사이드바 초기 상태를 반환합니다.
 */
function getSidebarState() {
  const props = getUserProperties_();
  const apiKey = props.getProperty(YT_CFG.API_KEY_PROP) || '';
  const activeState = loadState_();
  const lastResult = loadLastResult_();
  const cancelRequested =
    props.getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';

  const progress = activeState
    ? buildProgressForClient_(activeState, 'RUNNING')
    : lastResult
      ? buildProgressForClient_(lastResult, lastResult.status || 'COMPLETED')
      : null;

  if (progress && activeState && cancelRequested) {
    progress.stage = '취소 처리 중';
    progress.message = '현재 실행 구간이 끝나는 즉시 안전하게 중단됩니다.';
  }

  return {
    apiKeyConfigured: Boolean(apiKey),
    apiKeyMask: apiKey ? maskApiKey_(apiKey) : '',
    running: Boolean(activeState),
    cancelRequested: cancelRequested,
    progress: progress
  };
}


/**
 * API 키를 실제 YouTube Data API 요청으로 검증한 뒤 사용자별 속성에 저장합니다.
 */
function saveApiKey(apiKey) {
  const cleanedKey = String(apiKey || '').trim();

  if (!cleanedKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키를 입력해야 합니다.',
      'Google Cloud에서 발급한 YouTube Data API 키가 입력되지 않았습니다.',
      ['API 키 입력란이 비어 있습니다.'],
      [
        'Google Cloud Console에서 API 키를 발급합니다.',
        'API 키 전체를 사이드바 입력란에 붙여 넣습니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  if (cleanedKey.length < 20) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_FORMAT_INVALID',
      'API 키 형식을 확인해야 합니다.',
      '입력한 문자열이 일반적인 Google API 키 길이보다 짧습니다.',
      [
        'API 키 일부만 복사했을 수 있습니다.',
        '프로젝트 ID나 다른 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 값을 처음부터 끝까지 다시 복사하여 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력'
      }
    ));
  }

  validateApiKey_(cleanedKey);

  const props = getUserProperties_();
  props.setProperty(YT_CFG.API_KEY_PROP, cleanedKey);

  // 이전 API 키 오류 안내가 새 키 저장 뒤 다시 나타나지 않도록 정리합니다.
  const previous = loadLastResult_();
  if (previous && previous.status === 'ERROR') {
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
  }

  return getSidebarState();
}


/**
 * 저장된 API 키를 삭제합니다.
 */
function deleteApiKey() {
  if (loadState_()) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_DELETE_BLOCKED',
      '수집 중에는 API 키를 삭제할 수 없습니다.',
      '현재 댓글 수집 작업이 저장된 API 키를 사용하고 있습니다.',
      ['진행 중인 작업이 존재합니다.'],
      [
        '현재 수집을 완료하거나 취소합니다.',
        '수집 상태가 종료된 뒤 API 키를 삭제합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.API_KEY_PROP);
  props.deleteProperty(YT_CFG.LAST_RESULT_PROP);

  return getSidebarState();
}


/**
 * 사이드바 입력값으로 새 수집 작업을 준비합니다.
 * 실제 수집은 runCollectionNow 또는 시간 기반 트리거가 수행합니다.
 */
function startCollectionFromSidebar(formData) {
  const lock = LockService.getScriptLock();
  lock.waitLock(10000);

  try {
    const apiKey = getApiKey_();
    const input = normalizeSidebarInput_(formData);
    const ss = SpreadsheetApp.getActiveSpreadsheet();

    if (!ss) {
      throwStructuredError_(buildErrorInfo_(
        'SPREADSHEET_NOT_FOUND',
        '댓글을 저장할 스프레드시트를 찾지 못했습니다.',
        '현재 Apps Script가 스프레드시트와 연결된 상태인지 확인해야 합니다.',
        [
          '독립 실행형 Apps Script 프로젝트에서 코드를 실행했을 수 있습니다.',
          '스프레드시트가 닫히거나 접근 권한이 변경되었을 수 있습니다.'
        ],
        [
          '댓글을 저장할 Google 스프레드시트를 엽니다.',
          '‘확장 프로그램 → Apps Script’에서 이 코드를 실행합니다.',
          '스프레드시트를 새로고침하고 사이드바를 다시 엽니다.'
        ],
        { actionLabel: '확인' }
      ));
    }

    // 영상과 API 키가 정상인지 먼저 확인합니다.
    const videoId = extractVideoId_(input.videoUrl);
    const metadata = getVideoMetadataWithKey_(videoId, apiKey);

    deleteContinuationTriggers_();

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.LAST_RESULT_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    // 새 수집은 기존 결과를 지우지 않고 새 결과 시트에 기록합니다.
    const outputSheet = createNextOutputSheet_(ss);
    ensureInternalSheet_(ss);
    resetInternalData_(ss);
    deleteLegacyLogSheet_(ss);

    const state = {
      version: YT_CFG.STATE_VERSION,
      status: 'RUNNING',
      spreadsheetId: ss.getId(),

      outputSheetId: outputSheet.getSheetId(),
      outputSheetName: outputSheet.getName(),

      videoId: videoId,
      videoTitle: metadata.title,
      videoChannelId: metadata.channelId,
      videoChannelTitle: metadata.channelTitle,
      reportedCommentCount: metadata.commentCount,

      targetTopLevelCount: input.limit,
      includeReplies: input.includeReplies,

      nextThreadPageToken: '',
      threadDone: false,

      currentReplyParentId: '',
      nextReplyPageToken: '',

      topCount: 0,
      replyCount: 0,
      threadPages: 0,
      replyPages: 0,
      apiCalls: 1,

      startedAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      message: outputSheet.getName() + '에서 수집을 시작했습니다.',
      error: null
    };

    saveState_(state);

    // 사이드바가 닫혀도 수집이 이어지도록 예비 트리거를 만듭니다.
    scheduleContinuation_();

    return getSidebarState();

  } finally {
    lock.releaseLock();
  }
}


/**
 * 사이드바가 첫 실행 구간을 즉시 시작할 때 호출합니다.
 */
function runCollectionNow() {
  continueCommentCollection();
  return getSidebarState();
}


/**
 * 저장된 상태에서 댓글 수집을 계속합니다.
 */
function continueCommentCollection() {
  const lock = LockService.getScriptLock();

  if (!lock.tryLock(5000)) {
    return;
  }

  let ss = null;
  let state = null;
  let commentsSheet = null;

  try {
    state = loadState_();

    if (!state) {
      return;
    }

    validateStateVersion_(state);
    normalizeState_(state);

    ss = SpreadsheetApp.openById(state.spreadsheetId);
    ensureInternalSheet_(ss);
    deleteLegacyLogSheet_(ss);

    commentsSheet = getOutputSheetForState_(ss, state);
    const internalSheet = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);
    const existingIds = getExistingCommentIds_(internalSheet);
    const existingCounts = getExistingCounts_(internalSheet);

    // 시트 기록 직후 상태 저장 전에 실행이 끊긴 상황을 보정합니다.
    state.topCount = existingCounts.top;
    state.replyCount = existingCounts.reply;

    const runStartedAt = Date.now();

    while (Date.now() - runStartedAt < YT_CFG.MAX_RUN_MS) {
      if (isCancelRequested_()) {
        finalizeCancellation_(ss, commentsSheet, state);
        return;
      }

      // 처리 중이던 답글 페이지가 있으면 먼저 이어서 처리합니다.
      if (state.currentReplyParentId) {
        processReplyPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      // 내부 시트에서 답글 수집이 필요한 최상위 댓글을 하나 선택합니다.
      const pendingReply = claimNextPendingReply_(internalSheet);

      if (pendingReply) {
        state.currentReplyParentId = pendingReply.commentId;
        state.nextReplyPageToken = pendingReply.pageToken || '';
        saveState_(state);
        continue;
      }

      // 답글 대기 항목이 없을 때 다음 최상위 댓글 페이지를 가져옵니다.
      if (!state.threadDone) {
        processThreadPage_(state, commentsSheet, internalSheet, existingIds);
        saveState_(state);
        continue;
      }

      finishCollection_(ss, commentsSheet, state);
      return;
    }

    state.updatedAt = new Date().toISOString();
    state.message = '실행 시간을 고려하여 진행 상태를 저장했습니다.';
    saveState_(state);
    scheduleContinuation_();

  } catch (error) {
    deleteContinuationTriggers_();

    const errorInfo = normalizeErrorInfo_(error, '댓글 수집');

    if (errorInfo.code === 'API_KEY_INVALID') {
      getUserProperties_().deleteProperty(YT_CFG.API_KEY_PROP);
    }

    if (commentsSheet) {
      try {
        finalizeCommentsSheet_(commentsSheet);
      } catch (formatError) {
        console.error(formatError);
      }
    }

    if (state) {
      state.status = 'ERROR';
      state.updatedAt = new Date().toISOString();
      state.message = errorInfo.summary;
      state.error = errorInfo;
      saveLastResult_(state, 'ERROR', errorInfo.summary, errorInfo);
    }

    const props = getUserProperties_();
    props.deleteProperty(YT_CFG.STATE_PROP);
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);

    console.error(error);
    throwStructuredError_(errorInfo);

  } finally {
    lock.releaseLock();
  }
}


/**
 * 진행 중인 수집을 취소합니다.
 */
function cancelCommentCollection() {
  const props = getUserProperties_();
  const state = loadState_();

  if (!state) {
    props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
    deleteContinuationTriggers_();
    return getSidebarState();
  }

  props.setProperty(YT_CFG.CANCEL_REQUEST_PROP, 'true');
  deleteContinuationTriggers_();

  const lock = LockService.getScriptLock();

  // 다른 수집 실행이 없다면 이 호출에서 즉시 취소를 마무리합니다.
  if (lock.tryLock(200)) {
    try {
      const latestState = loadState_();

      if (latestState) {
        const ss = SpreadsheetApp.openById(latestState.spreadsheetId);
        ensureInternalSheet_(ss);
        const commentsSheet = getOutputSheetForState_(ss, latestState);
        finalizeCancellation_(ss, commentsSheet, latestState);
      }
    } finally {
      lock.releaseLock();
    }
  }

  return getSidebarState();
}


/**
 * 최상위 댓글 스레드 한 페이지를 처리합니다.
 */
function processThreadPage_(state, commentsSheet, internalSheet, existingIds) {
  const remaining = state.targetTopLevelCount - state.topCount;

  if (remaining <= 0) {
    state.threadDone = true;
    state.nextThreadPageToken = '';
    return;
  }

  const params = {
    part: state.includeReplies ? 'snippet,replies' : 'snippet',
    videoId: state.videoId,
    maxResults: Math.min(100, remaining),
    textFormat: 'plainText'
  };

  if (state.nextThreadPageToken) {
    params.pageToken = state.nextThreadPageToken;
  }

  const data = youtubeGet_('commentThreads', params);

  state.apiCalls += 1;
  state.threadPages += 1;

  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();
  const items = Array.isArray(data.items) ? data.items : [];

  let topAdded = 0;
  let replyAdded = 0;
  let nextTopNumber = state.topCount + 1;

  items.forEach(function(thread) {
    if (state.topCount + topAdded >= state.targetTopLevelCount) {
      return;
    }

    const threadSnippet = thread.snippet || {};
    const topComment = threadSnippet.topLevelComment;

    if (!topComment || !topComment.id) {
      return;
    }

    const topCommentId = String(topComment.id);

    if (existingIds.has(topCommentId) || batchIds.has(topCommentId)) {
      return;
    }

    const topNumber = String(nextTopNumber);
    nextTopNumber += 1;

    const totalReplyCount = Number(threadSnippet.totalReplyCount || 0);
    let replyStatus = 'DONE';
    let nextReplyIndex = 1;

    commentRows.push(
      commentToOutputRow_(state, topComment, topNumber)
    );

    batchIds.add(topCommentId);
    topAdded += 1;

    const inlineReplies =
      thread.replies && Array.isArray(thread.replies.comments)
        ? thread.replies.comments
        : [];

    if (state.includeReplies && totalReplyCount > 0) {
      if (inlineReplies.length === totalReplyCount) {
        inlineReplies.forEach(function(reply) {
          if (!reply || !reply.id) {
            return;
          }

          const replyId = String(reply.id);

          if (existingIds.has(replyId) || batchIds.has(replyId)) {
            return;
          }

          const displayNumber = topNumber + '_' + nextReplyIndex;
          nextReplyIndex += 1;

          commentRows.push(
            commentToOutputRow_(state, reply, displayNumber)
          );

          internalRows.push(
            buildInternalRow_(
              replyId,
              topCommentId,
              displayNumber,
              'reply',
              '',
              '',
              '',
              ''
            )
          );

          batchIds.add(replyId);
          replyAdded += 1;
        });
      } else {
        // commentThreads.list의 replies에는 전체 답글이 보장되지 않으므로
        // comments.list로 전체 답글을 다시 가져옵니다.
        replyStatus = 'PENDING';
        nextReplyIndex = 1;
      }
    }

    internalRows.push(
      buildInternalRow_(
        topCommentId,
        '',
        topNumber,
        'topLevel',
        replyStatus,
        nextReplyIndex,
        totalReplyCount,
        ''
      )
    );
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.topCount += topAdded;
  state.replyCount += replyAdded;

  const reachedTarget = state.topCount >= state.targetTopLevelCount;
  const hasNextPage = Boolean(data.nextPageToken);

  state.nextThreadPageToken =
    !reachedTarget && hasNextPage
      ? data.nextPageToken
      : '';

  state.threadDone = reachedTarget || !hasNextPage;
  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 특정 최상위 댓글의 답글 한 페이지를 처리합니다.
 */
function processReplyPage_(state, commentsSheet, internalSheet, existingIds) {
  const topRecord = findInternalRecordByCommentId_(
    internalSheet,
    state.currentReplyParentId
  );

  if (!topRecord) {
    // 내부 상태가 사라진 경우 현재 항목을 건너뛰고 다음 대기 항목을 찾습니다.
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
    return;
  }

  const params = {
    part: 'snippet',
    parentId: state.currentReplyParentId,
    maxResults: 100,
    textFormat: 'plainText'
  };

  const pageToken =
    state.nextReplyPageToken || topRecord.replyPageToken || '';

  if (pageToken) {
    params.pageToken = pageToken;
  }

  const data = youtubeGet_('comments', params);

  state.apiCalls += 1;
  state.replyPages += 1;

  const items = Array.isArray(data.items) ? data.items : [];
  const commentRows = [];
  const internalRows = [];
  const batchIds = new Set();

  let nextReplyIndex = Number(topRecord.nextReplyIndex || 1);
  let replyAdded = 0;

  items.forEach(function(reply) {
    if (!reply || !reply.id) {
      return;
    }

    const replyId = String(reply.id);

    if (existingIds.has(replyId) || batchIds.has(replyId)) {
      return;
    }

    const displayNumber =
      String(topRecord.displayNumber) + '_' + nextReplyIndex;

    nextReplyIndex += 1;

    commentRows.push(
      commentToOutputRow_(state, reply, displayNumber)
    );

    internalRows.push(
      buildInternalRow_(
        replyId,
        state.currentReplyParentId,
        displayNumber,
        'reply',
        '',
        '',
        '',
        ''
      )
    );

    batchIds.add(replyId);
    replyAdded += 1;
  });

  appendCollectedRecords_(
    commentsSheet,
    internalSheet,
    commentRows,
    internalRows
  );

  batchIds.forEach(function(id) {
    existingIds.add(id);
  });

  state.replyCount += replyAdded;

  const nextPageToken = data.nextPageToken || '';
  const nextStatus = nextPageToken ? 'IN_PROGRESS' : 'DONE';

  updateTopReplyProgress_(
    internalSheet,
    topRecord.rowNumber,
    nextStatus,
    nextReplyIndex,
    nextPageToken
  );

  if (nextPageToken) {
    state.nextReplyPageToken = nextPageToken;
  } else {
    state.currentReplyParentId = '';
    state.nextReplyPageToken = '';
  }

  state.updatedAt = new Date().toISOString();
  state.message = buildServerProgressMessage_(state);
}


/**
 * 내부 시트에서 답글 수집 대기 중인 최상위 댓글 하나를 선택합니다.
 */
function claimNextPendingReply_(internalSheet) {
  const statusRange = internalSheet.getRange(
    2,
    YT_CFG.INTERNAL_COL.REPLY_STATUS,
    Math.max(internalSheet.getLastRow() - 1, 1),
    1
  );

  let found = statusRange
    .createTextFinder('IN_PROGRESS')
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    found = statusRange
      .createTextFinder('PENDING')
      .matchEntireCell(true)
      .useRegularExpression(false)
      .findNext();
  }

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  if (values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] === 'PENDING') {
    internalSheet
      .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS)
      .setValue('IN_PROGRESS');
  }

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    pageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 댓글 1건을 사용자가 보는 8열 행으로 변환합니다.
 */
function commentToOutputRow_(state, comment, displayNumber) {
  const snippet = (comment && comment.snippet) || {};
  const text = String(snippet.textDisplay || '');

  return [
    String(displayNumber),
    safeCellText_(state.videoChannelTitle || ''),
    safeCellText_(state.videoTitle || ''),
    safeCellText_(snippet.authorDisplayName || ''),
    safeCellText_(text),
    Number(snippet.likeCount || 0),
    apiDateToSheetValue_(snippet.publishedAt),
    calculateCommentBytes_(text)
  ];
}


/**
 * 숨김 내부 시트의 행을 만듭니다.
 */
function buildInternalRow_(
  commentId,
  parentCommentId,
  displayNumber,
  commentType,
  replyStatus,
  nextReplyIndex,
  totalReplyCount,
  replyPageToken
) {
  return [
    safeCellText_(commentId || ''),
    safeCellText_(parentCommentId || ''),
    String(displayNumber || ''),
    String(commentType || ''),
    String(replyStatus || ''),
    nextReplyIndex === '' ? '' : Number(nextReplyIndex || 1),
    totalReplyCount === '' ? '' : Number(totalReplyCount || 0),
    safeCellText_(replyPageToken || '')
  ];
}


/**
 * 댓글 행과 내부 관리 행을 각각 일괄 기록합니다.
 */
function appendCollectedRecords_(
  commentsSheet,
  internalSheet,
  commentRows,
  internalRows
) {
  if (commentRows.length !== internalRows.length) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_ROW_MISMATCH',
      '댓글 저장 구조를 확인해야 합니다.',
      '댓글 행과 내부 관리 행의 개수가 일치하지 않습니다.',
      ['수집 상태를 기록하는 내부 데이터가 일시적으로 어긋났습니다.'],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '확인' }
    ));
  }

  if (commentRows.length === 0) {
    return;
  }

  commentsSheet
    .getRange(
      commentsSheet.getLastRow() + 1,
      1,
      commentRows.length,
      YT_CFG.HEADERS.length
    )
    .setValues(commentRows);

  internalSheet
    .getRange(
      internalSheet.getLastRow() + 1,
      1,
      internalRows.length,
      YT_CFG.INTERNAL_HEADERS.length
    )
    .setValues(internalRows);
}


/**
 * 내부 시트에서 특정 댓글 ID의 관리 행을 찾습니다.
 */
function findInternalRecordByCommentId_(internalSheet, commentId) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return null;
  }

  const found = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .createTextFinder(String(commentId || ''))
    .matchEntireCell(true)
    .useRegularExpression(false)
    .findNext();

  if (!found) {
    return null;
  }

  const rowNumber = found.getRow();
  const values = internalSheet
    .getRange(rowNumber, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .getValues()[0];

  return {
    rowNumber: rowNumber,
    commentId: String(values[YT_CFG.INTERNAL_COL.COMMENT_ID - 1] || ''),
    displayNumber: String(
      values[YT_CFG.INTERNAL_COL.DISPLAY_NUMBER - 1] || ''
    ),
    replyStatus: String(
      values[YT_CFG.INTERNAL_COL.REPLY_STATUS - 1] || ''
    ),
    nextReplyIndex: Number(
      values[YT_CFG.INTERNAL_COL.NEXT_REPLY_INDEX - 1] || 1
    ),
    replyPageToken: String(
      values[YT_CFG.INTERNAL_COL.REPLY_PAGE_TOKEN - 1] || ''
    )
  };
}


/**
 * 최상위 댓글의 답글 수집 진행 정보를 갱신합니다.
 */
function updateTopReplyProgress_(
  internalSheet,
  rowNumber,
  status,
  nextReplyIndex,
  pageToken
) {
  internalSheet
    .getRange(rowNumber, YT_CFG.INTERNAL_COL.REPLY_STATUS, 1, 4)
    .setValues([[
      status,
      Number(nextReplyIndex || 1),
      internalSheet
        .getRange(rowNumber, YT_CFG.INTERNAL_COL.TOTAL_REPLY_COUNT)
        .getValue(),
      pageToken || ''
    ]]);
}


/**
 * 완료 처리
 */
function finishCollection_(ss, commentsSheet, state) {
  state.status = 'COMPLETED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = state.topCount < state.targetTopLevelCount
    ? '댓글 ' +
      state.topCount +
      '개와 대댓글 ' +
      state.replyCount +
      '개를 수집했습니다.'
    : '댓글 수집을 완료했습니다.';
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'COMPLETED', state.message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


function isCancelRequested_() {
  return getUserProperties_().getProperty(YT_CFG.CANCEL_REQUEST_PROP) === 'true';
}


/**
 * 취소 처리
 */
function finalizeCancellation_(ss, commentsSheet, state) {
  const message = '사용자가 수집을 취소했습니다. 이미 저장된 댓글은 유지됩니다.';

  state.status = 'CANCELLED';
  state.updatedAt = new Date().toISOString();
  state.finishedAt = new Date().toISOString();
  state.message = message;
  state.error = null;

  finalizeCommentsSheet_(commentsSheet);
  saveLastResult_(state, 'CANCELLED', message, null);

  const props = getUserProperties_();
  props.deleteProperty(YT_CFG.STATE_PROP);
  props.deleteProperty(YT_CFG.CANCEL_REQUEST_PROP);
  deleteContinuationTriggers_();
}


/**
 * API 키가 YouTube Data API 요청에 사용 가능한지 확인합니다.
 */
function validateApiKey_(apiKey) {
  youtubeGetWithKey_(
    'videos',
    {
      part: 'id',
      id: 'jNQXAC9IVRw'
    },
    apiKey
  );
}


/**
 * 영상 메타데이터를 조회합니다.
 */
function getVideoMetadataWithKey_(videoId, apiKey) {
  const data = youtubeGetWithKey_(
    'videos',
    {
      part: 'snippet,statistics',
      id: videoId
    },
    apiKey
  );

  if (!Array.isArray(data.items) || data.items.length === 0) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '입력한 영상 주소에 해당하는 공개 영상을 YouTube Data API에서 조회하지 못했습니다.',
      [
        '영상 주소나 11자리 영상 ID가 정확하지 않을 수 있습니다.',
        '영상이 삭제되었거나 비공개 상태일 수 있습니다.',
        '연령·지역·계정 권한에 따라 접근이 제한된 영상일 수 있습니다.'
      ],
      [
        '브라우저에서 해당 영상 주소가 정상적으로 열리는지 확인합니다.',
        '주소 표시줄의 영상 URL 전체를 다시 복사합니다.',
        '사이드바의 영상 주소를 교체한 뒤 수집을 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: { videoId: videoId }
      }
    ));
  }

  const item = data.items[0];
  const snippet = item.snippet || {};
  const statistics = item.statistics || {};

  return {
    title: snippet.title || '',
    channelId: snippet.channelId || '',
    channelTitle: snippet.channelTitle || '',
    commentCount: statistics.commentCount || ''
  };
}


/**
 * 저장된 API 키로 YouTube Data API를 호출합니다.
 */
function youtubeGet_(resource, params) {
  return youtubeGetWithKey_(resource, params, getApiKey_());
}


/**
 * YouTube Data API GET 요청을 수행합니다.
 */
function youtubeGetWithKey_(resource, params, apiKey) {
  const queryParams = Object.assign({}, params, { key: apiKey });

  const query = Object.keys(queryParams)
    .filter(function(key) {
      const value = queryParams[key];
      return value !== undefined && value !== null && value !== '';
    })
    .map(function(key) {
      return encodeURIComponent(key) + '=' + encodeURIComponent(queryParams[key]);
    })
    .join('&');

  const url = YT_CFG.API_BASE + '/' + resource + '?' + query;
  const transientCodes = [429, 500, 502, 503, 504];

  for (let attempt = 0; attempt < 3; attempt += 1) {
    let response;

    try {
      response = UrlFetchApp.fetch(url, {
        method: 'get',
        muteHttpExceptions: true,
        headers: { Accept: 'application/json' }
      });
    } catch (networkError) {
      if (attempt < 2) {
        Utilities.sleep(Math.pow(2, attempt) * 1000);
        continue;
      }

      throwStructuredError_(buildErrorInfo_(
        'NETWORK_REQUEST_FAILED',
        'YouTube 서버에 연결하지 못했습니다.',
        'Apps Script에서 YouTube Data API로 보내는 외부 요청이 완료되지 않았습니다.',
        [
          'Google 서비스 또는 네트워크에 일시적인 장애가 발생했을 수 있습니다.',
          'Apps Script의 외부 요청 권한이 승인되지 않았을 수 있습니다.'
        ],
        [
          '잠시 뒤 같은 작업을 다시 실행합니다.',
          'Apps Script 권한 승인 화면이 나타나면 요청된 권한을 허용합니다.',
          'Apps Script의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.'
        ],
        {
          actionLabel: '확인',
          technical: {
            resource: resource,
            originalMessage: String(networkError && networkError.message || networkError)
          }
        }
      ));
    }

    const statusCode = response.getResponseCode();
    const responseText = response.getContentText();

    if (statusCode >= 200 && statusCode < 300) {
      return responseText ? JSON.parse(responseText) : {};
    }

    if (transientCodes.indexOf(statusCode) >= 0 && attempt < 2) {
      Utilities.sleep(Math.pow(2, attempt) * 1000);
      continue;
    }

    const parsedError = parseYouTubeErrorResponse_(responseText);

    throwStructuredError_(classifyYouTubeApiError_(
      statusCode,
      parsedError.reason,
      parsedError.message,
      resource
    ));
  }

  throwStructuredError_(buildErrorInfo_(
    'YOUTUBE_REQUEST_REPEATED_FAILURE',
    'YouTube API 요청이 반복적으로 실패했습니다.',
    '일시적인 서버 장애가 재시도 후에도 계속되었습니다.',
    ['YouTube 또는 Google 네트워크 서비스가 불안정할 수 있습니다.'],
    [
      '잠시 뒤 같은 작업을 다시 실행합니다.',
      '반복되면 Apps Script의 ‘실행’ 기록을 확인합니다.'
    ],
    { actionLabel: '확인', technical: { resource: resource } }
  ));
}


function parseYouTubeErrorResponse_(responseText) {
  let reason = '';
  let message = String(responseText || '');

  try {
    const parsed = JSON.parse(responseText);

    if (parsed.error) {
      message = parsed.error.message || message;

      if (Array.isArray(parsed.error.errors) && parsed.error.errors[0]) {
        reason = parsed.error.errors[0].reason || '';
      }

      if (!reason && parsed.error.status) {
        reason = parsed.error.status;
      }
    }
  } catch (parseError) {
    // JSON이 아닌 오류 본문은 문자열 그대로 분류합니다.
  }

  return {
    reason: String(reason || ''),
    message: String(message || '')
  };
}


/**
 * YouTube API 오류를 한국어 모달용 정보로 분류합니다.
 */
function classifyYouTubeApiError_(statusCode, reason, message, resource) {
  const reasonText = String(reason || '');
  const messageText = String(message || '');
  const combined = (reasonText + ' ' + messageText).toLowerCase();
  const technical = {
    httpStatus: statusCode,
    apiReason: reasonText,
    resource: resource,
    originalMessage: messageText
  };

  if (
    combined.indexOf('keyinvalid') >= 0 ||
    combined.indexOf('api key not valid') >= 0 ||
    combined.indexOf('api_key_invalid') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_INVALID',
      'API 키를 사용할 수 없습니다.',
      '입력한 API 키가 정확하지 않거나 삭제·재발급되어 현재 요청에 사용할 수 없습니다.',
      [
        'API 키 일부가 누락되었을 수 있습니다.',
        'Google Cloud에서 기존 키가 삭제되거나 재발급되었을 수 있습니다.',
        'API 키가 아닌 다른 프로젝트 값을 입력했을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '키 유형이 ‘API 키’인지 확인합니다.',
        'API 키 전체를 다시 복사합니다.',
        '사이드바에서 API 키를 다시 입력하고 저장합니다.'
      ],
      {
        helpLabel: 'API 키 관리 화면 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: 'API 키 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') >= 0 ||
    combined.indexOf('access not configured') >= 0 ||
    combined.indexOf('service_disabled') >= 0 ||
    combined.indexOf('api_disabled') >= 0 ||
    combined.indexOf('has not been used in project') >= 0 ||
    combined.indexOf('it is disabled') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_API_NOT_ENABLED',
      'YouTube Data API v3가 활성화되어 있지 않습니다.',
      'API 키가 속한 Google Cloud 프로젝트에서 YouTube Data API v3 사용 설정을 켜야 합니다.',
      [
        'API 키를 만든 프로젝트에서 YouTube Data API v3를 아직 활성화하지 않았습니다.',
        'API를 활성화한 프로젝트와 API 키를 발급한 프로젝트가 다를 수 있습니다.'
      ],
      [
        'Google Cloud Console에서 API 키를 만든 프로젝트를 선택합니다.',
        '‘API 및 서비스 → 라이브러리’로 이동합니다.',
        '‘YouTube Data API v3’를 검색하고 ‘사용’을 누릅니다.',
        '설정 반영을 위해 1~5분 기다린 뒤 API 키를 다시 저장합니다.'
      ],
      {
        helpLabel: 'YouTube Data API 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/library/youtube.googleapis.com',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('iprefererblocked') >= 0 ||
    combined.indexOf('referer') >= 0 && combined.indexOf('blocked') >= 0 ||
    combined.indexOf('api key restrictions') >= 0
  ) {
    return buildErrorInfo_(
      'API_KEY_APPLICATION_RESTRICTION',
      'API 키의 애플리케이션 제한이 Apps Script 요청을 차단했습니다.',
      '현재 키에 설정된 웹사이트·IP 제한이 Apps Script의 UrlFetch 요청 방식과 맞지 않습니다.',
      [
        'HTTP 리퍼러 제한 또는 특정 IP 주소 제한이 적용되어 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키의 애플리케이션 제한을 확인합니다.',
        'Apps Script에서 사용할 수 있는 제한 방식으로 조정합니다.',
        'API 제한은 ‘YouTube Data API v3’로 유지합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('accessnotconfigured') < 0 &&
    (
      combined.indexOf('forbidden') >= 0 &&
      combined.indexOf('api') >= 0 &&
      combined.indexOf('key') >= 0
    )
  ) {
    return buildErrorInfo_(
      'API_KEY_API_RESTRICTION',
      'API 키의 API 제한 설정을 확인해야 합니다.',
      '현재 API 키가 YouTube Data API v3 호출을 허용하지 않을 수 있습니다.',
      [
        'API 키의 ‘API 제한’ 목록에서 YouTube Data API v3가 빠져 있을 수 있습니다.'
      ],
      [
        'Google Cloud Console의 ‘API 및 서비스 → 사용자 인증 정보’를 엽니다.',
        '사용 중인 API 키를 선택합니다.',
        '‘API 제한’에서 YouTube Data API v3를 허용합니다.',
        '저장 후 1~5분 뒤 다시 실행합니다.'
      ],
      {
        helpLabel: 'API 키 제한 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        focusTarget: 'apiKey',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('quotaexceeded') >= 0 ||
    combined.indexOf('dailylimitexceeded') >= 0 ||
    combined.indexOf('daily limit') >= 0
  ) {
    return buildErrorInfo_(
      'YOUTUBE_QUOTA_EXCEEDED',
      'YouTube API의 오늘 할당량을 모두 사용했습니다.',
      '현재 Google Cloud 프로젝트에서 오늘 사용할 수 있는 YouTube Data API 할당량이 남아 있지 않습니다.',
      ['같은 프로젝트의 다른 프로그램에서도 YouTube API 할당량을 사용했을 수 있습니다.'],
      [
        'Google Cloud Console에서 YouTube Data API 사용량을 확인합니다.',
        '일일 할당량이 갱신된 뒤 다시 실행합니다.',
        '필요하면 다음 수집의 댓글 개수를 줄입니다.'
      ],
      {
        helpLabel: 'YouTube API 할당량 열기',
        helpUrl: 'https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas',
        actionLabel: '확인',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('ratelimitexceeded') >= 0 ||
    combined.indexOf('userratelimitexceeded') >= 0 ||
    statusCode === 429
  ) {
    return buildErrorInfo_(
      'YOUTUBE_RATE_LIMIT',
      '짧은 시간에 API 요청이 많이 발생했습니다.',
      'YouTube Data API가 일시적으로 요청 속도를 제한했습니다.',
      ['여러 수집 작업을 연속으로 실행했을 수 있습니다.'],
      [
        '현재 작업이 자동 재개되는지 확인합니다.',
        '몇 분 뒤 다시 실행합니다.',
        '동시에 여러 스프레드시트에서 같은 API 키를 사용하고 있다면 실행 횟수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (combined.indexOf('commentsdisabled') >= 0) {
    return buildErrorInfo_(
      'COMMENTS_DISABLED',
      '이 영상에서는 댓글을 수집할 수 없습니다.',
      '영상 게시자가 댓글 기능을 사용하지 않도록 설정했습니다.',
      ['영상의 댓글 기능이 꺼져 있거나 YouTube 정책에 따라 제한되었습니다.'],
      [
        '영상 페이지에서 댓글 영역이 표시되는지 확인합니다.',
        '댓글이 허용된 다른 영상 주소를 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (
    combined.indexOf('videonotfound') >= 0 ||
    combined.indexOf('video not found') >= 0
  ) {
    return buildErrorInfo_(
      'VIDEO_NOT_FOUND',
      '영상 정보를 찾을 수 없습니다.',
      '영상 주소가 잘못되었거나 영상이 삭제·비공개 상태일 수 있습니다.',
      [
        '영상 ID가 정확하지 않을 수 있습니다.',
        '영상 공개 상태가 변경되었을 수 있습니다.'
      ],
      [
        '브라우저에서 영상 주소가 정상적으로 열리는지 확인합니다.',
        '영상 URL 전체를 다시 복사해 입력합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 다시 입력',
        technical: technical
      }
    );
  }

  if (statusCode >= 500) {
    return buildErrorInfo_(
      'YOUTUBE_SERVER_ERROR',
      'YouTube 서버에서 일시적인 오류가 발생했습니다.',
      'YouTube Data API 서버가 현재 요청을 정상적으로 처리하지 못했습니다.',
      ['YouTube 측의 일시적인 서비스 장애일 수 있습니다.'],
      [
        '잠시 뒤 같은 작업을 다시 실행합니다.',
        '진행 중인 수집이라면 자동 재개 여부를 확인합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (statusCode === 403) {
    return buildErrorInfo_(
      'YOUTUBE_ACCESS_FORBIDDEN',
      'YouTube 데이터에 접근할 수 없습니다.',
      'API 키 설정, 영상 공개 상태 또는 Google Cloud 프로젝트 권한을 확인해야 합니다.',
      [
        'API 키 제한 설정이 요청을 차단했을 수 있습니다.',
        '영상이 공개 API에서 접근할 수 없는 상태일 수 있습니다.'
      ],
      [
        'API 키의 API 제한과 애플리케이션 제한을 확인합니다.',
        '영상이 공개 상태인지 확인합니다.',
        'Google Cloud에서 YouTube Data API v3가 활성화되어 있는지 확인합니다.'
      ],
      {
        helpLabel: 'API 키 설정 열기',
        helpUrl: 'https://console.cloud.google.com/apis/credentials',
        actionLabel: '설정 확인',
        technical: technical
      }
    );
  }

  if (statusCode === 400) {
    return buildErrorInfo_(
      'YOUTUBE_BAD_REQUEST',
      'YouTube API 요청 형식을 확인해야 합니다.',
      '영상 주소 또는 요청 매개변수 중 하나를 YouTube API가 처리하지 못했습니다.',
      ['영상 주소가 올바르지 않거나 API 요청 값이 허용 범위를 벗어났을 수 있습니다.'],
      [
        '영상 주소를 다시 확인합니다.',
        '수집 개수와 정렬 기준을 확인합니다.',
        '같은 문제가 계속되면 새 수집으로 다시 시작합니다.'
      ],
      {
        focusTarget: 'videoUrl',
        actionLabel: '입력값 확인',
        technical: technical
      }
    );
  }

  return buildErrorInfo_(
    'YOUTUBE_API_ERROR',
    'YouTube API 요청을 완료하지 못했습니다.',
    'YouTube Data API가 요청을 거부하거나 처리하지 못했습니다.',
    ['API 키, 영상 공개 상태, 할당량 또는 네트워크 상태를 확인해야 합니다.'],
    [
      'API 키 설정과 YouTube Data API 활성화 여부를 확인합니다.',
      '영상 주소가 공개 영상인지 확인합니다.',
      '잠시 뒤 다시 실행합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}


/**
 * 영상 URL 또는 11자리 영상 ID에서 videoId를 추출합니다.
 */
function extractVideoId_(input) {
  const text = String(input || '').trim();

  if (/^[A-Za-z0-9_-]{11}$/.test(text)) {
    return text;
  }

  const patterns = [
    /[?&]v=([A-Za-z0-9_-]{11})/,
    /youtu\.be\/([A-Za-z0-9_-]{11})/,
    /youtube(?:-nocookie)?\.com\/(?:embed|shorts|live)\/([A-Za-z0-9_-]{11})/
  ];

  for (let i = 0; i < patterns.length; i += 1) {
    const match = text.match(patterns[i]);

    if (match) {
      return match[1];
    }
  }

  throwStructuredError_(buildErrorInfo_(
    'INVALID_VIDEO_URL',
    'YouTube 영상 주소를 확인해야 합니다.',
    '입력한 값에서 11자리 YouTube 영상 ID를 찾지 못했습니다.',
    [
      '영상 주소 일부가 빠졌을 수 있습니다.',
      '채널·재생목록 주소를 입력했을 수 있습니다.'
    ],
    [
      'YouTube에서 수집할 영상을 엽니다.',
      '브라우저 주소 표시줄의 영상 URL 전체를 복사합니다.',
      '사이드바의 영상 주소 입력란에 붙여 넣습니다.'
    ],
    {
      focusTarget: 'videoUrl',
      actionLabel: '영상 주소 다시 입력'
    }
  ));
}


/**
 * 사이드바 입력값을 검증합니다.
 */
function normalizeSidebarInput_(formData) {
  const form = formData || {};
  const videoUrl = String(form.videoUrl || '').trim();
  const limit = parseInt(form.limit, 10);

  if (!videoUrl) {
    throwStructuredError_(buildErrorInfo_(
      'VIDEO_URL_REQUIRED',
      'YouTube 영상 주소를 입력해야 합니다.',
      '수집 대상 영상 주소가 비어 있습니다.',
      ['영상 주소 입력란에 값이 없습니다.'],
      ['수집할 YouTube 영상의 URL을 입력합니다.'],
      {
        focusTarget: 'videoUrl',
        actionLabel: '영상 주소 입력'
      }
    ));
  }

  if (!Number.isInteger(limit)) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_INVALID',
      '수집 개수를 정수로 입력해야 합니다.',
      '수집할 최상위 댓글 개수가 올바른 정수 형식이 아닙니다.',
      ['빈 값, 소수 또는 문자가 입력되었을 수 있습니다.'],
      ['1 이상의 정수를 입력합니다.'],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 입력'
      }
    ));
  }

  if (limit < YT_CFG.MIN_LIMIT || limit > YT_CFG.MAX_LIMIT) {
    throwStructuredError_(buildErrorInfo_(
      'COMMENT_LIMIT_OUT_OF_RANGE',
      '수집 개수가 허용 범위를 벗어났습니다.',
      '수집 개수는 ' + YT_CFG.MIN_LIMIT + '개 이상 ' +
        YT_CFG.MAX_LIMIT + '개 이하로 입력해야 합니다.',
      ['입력한 개수가 코드에 설정된 운영 범위를 벗어났습니다.'],
      [
        YT_CFG.MIN_LIMIT + '~' + YT_CFG.MAX_LIMIT +
          ' 사이의 정수를 입력합니다.'
      ],
      {
        focusTarget: 'limit',
        actionLabel: '수집 개수 수정'
      }
    ));
  }

  return {
    videoUrl: videoUrl,
    limit: limit,
    includeReplies: form.includeReplies === true
  };
}


/**
 * 결과 시트와 숨김 내부 시트를 준비합니다.
 */
function ensureInternalSheet_(ss) {
  let internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    internal = ss.insertSheet(YT_CFG.INTERNAL_SHEET);
  }

  ensureColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);

  if (internal.getLastRow() === 0) {
    internal
      .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
      .setValues([YT_CFG.INTERNAL_HEADERS]);
  }

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 새 수집에 사용할 결과 시트를 시트1, 시트2, 시트3 ... 순서로 만듭니다.
 *
 * 새 스프레드시트에 기본 빈 '시트1' 하나만 존재하는 경우에는 그 시트를
 * 첫 결과 시트로 사용합니다. 그 이후 수집부터는 항상 새 시트를 추가합니다.
 */
function createNextOutputSheet_(ss) {
  const sheets = ss.getSheets();

  if (
    sheets.length === 1 &&
    sheets[0].getName() === YT_CFG.OUTPUT_SHEET_PREFIX + '1' &&
    isSheetCompletelyBlank_(sheets[0])
  ) {
    prepareOutputSheet_(sheets[0]);
    return sheets[0];
  }

  let maxNumber = 0;
  const namePattern = new RegExp(
    '^' + escapeRegExp_(YT_CFG.OUTPUT_SHEET_PREFIX) + '(\\d+)$'
  );

  sheets.forEach(function(sheet) {
    const match = sheet.getName().match(namePattern);

    if (match) {
      maxNumber = Math.max(maxNumber, Number(match[1] || 0));
    }
  });

  let nextNumber = maxNumber + 1;
  let nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;

  while (ss.getSheetByName(nextName)) {
    nextNumber += 1;
    nextName = YT_CFG.OUTPUT_SHEET_PREFIX + nextNumber;
  }

  const sheet = ss.insertSheet(nextName);
  prepareOutputSheet_(sheet);
  return sheet;
}


function isSheetCompletelyBlank_(sheet) {
  return sheet.getLastRow() === 0 && sheet.getLastColumn() === 0;
}


function prepareOutputSheet_(sheet) {
  if (sheet.getFilter()) {
    sheet.getFilter().remove();
  }

  sheet.clear();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setValues([YT_CFG.HEADERS]);

  sheet.setFrozenRows(1);
  sheet.getRange('A:A').setNumberFormat('@');
  formatCommentsSheet_(sheet);
}


/**
 * 새 수집을 위해 숨김 내부 시트만 초기화합니다.
 * 이전 결과 시트의 내용은 변경하지 않습니다.
 */
function resetInternalData_(ss) {
  const internal = ss.getSheetByName(YT_CFG.INTERNAL_SHEET);

  if (!internal) {
    throwStructuredError_(buildErrorInfo_(
      'INTERNAL_SHEET_NOT_FOUND',
      '내부 관리 시트를 준비하지 못했습니다.',
      '댓글 수집 상태를 저장하는 숨김 시트가 존재하지 않습니다.',
      ['내부 시트 생성 과정이 완료되지 않았습니다.'],
      ['사이드바를 닫았다가 다시 열고 새 수집을 시작합니다.'],
      { actionLabel: '확인' }
    ));
  }

  internal.clear();
  ensureExactColumnCount_(internal, YT_CFG.INTERNAL_HEADERS.length);
  internal
    .getRange(1, 1, 1, YT_CFG.INTERNAL_HEADERS.length)
    .setValues([YT_CFG.INTERNAL_HEADERS]);

  internal.setFrozenRows(1);

  if (!internal.isSheetHidden()) {
    internal.hideSheet();
  }
}


/**
 * 현재 수집 상태에 연결된 결과 시트를 찾습니다.
 */
function getOutputSheetForState_(ss, state) {
  const expectedId = Number(state.outputSheetId || 0);
  let outputSheet = null;

  if (expectedId > 0) {
    outputSheet = ss.getSheets().find(function(sheet) {
      return sheet.getSheetId() === expectedId;
    }) || null;
  }

  if (!outputSheet && state.outputSheetName) {
    outputSheet = ss.getSheetByName(String(state.outputSheetName));
  }

  if (!outputSheet) {
    throwStructuredError_(buildErrorInfo_(
      'OUTPUT_SHEET_NOT_FOUND',
      '수집 결과 시트를 찾을 수 없습니다.',
      '현재 수집 작업과 연결된 결과 시트가 삭제되었거나 이름과 식별 정보가 변경되었습니다.',
      [
        '수집 중 결과 시트를 삭제했을 수 있습니다.',
        '스프레드시트 구조가 외부 작업으로 변경되었을 수 있습니다.'
      ],
      [
        '현재 수집을 취소합니다.',
        '사이드바에서 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }

  return outputSheet;
}


function escapeRegExp_(text) {
  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}


/**
 * 이전 버전이 만든 수집로그 시트를 제거합니다.
 */
function deleteLegacyLogSheet_(ss) {
  const logSheet = ss.getSheetByName(YT_CFG.LEGACY_LOG_SHEET);

  if (logSheet && ss.getSheets().length > 1) {
    ss.deleteSheet(logSheet);
  }
}


/**
 * 댓글 시트를 번호 순으로 정렬하고 최종 서식을 적용합니다.
 */
function finalizeCommentsSheet_(sheet) {
  sortCommentsByDisplayNumber_(sheet);
  formatCommentsSheet_(sheet);
}


function sortCommentsByDisplayNumber_(sheet) {
  const lastRow = sheet.getLastRow();

  if (lastRow <= 2) {
    return;
  }

  // 정렬용 임시 열 I, J를 만든 뒤 최상위 번호와 답글 번호로 정렬합니다.
  ensureColumnCount_(sheet, 10);

  const numberValues = sheet
    .getRange(2, 1, lastRow - 1, 1)
    .getDisplayValues();

  const sortKeys = numberValues.map(function(row) {
    const parts = String(row[0] || '').split('_');
    return [
      Number(parts[0] || 0),
      parts.length > 1 ? Number(parts[1] || 0) : 0
    ];
  });

  sheet
    .getRange(2, 9, sortKeys.length, 2)
    .setValues(sortKeys);

  sheet
    .getRange(2, 1, lastRow - 1, 10)
    .sort([
      { column: 9, ascending: true },
      { column: 10, ascending: true }
    ]);

  sheet.getRange(2, 9, lastRow - 1, 2).clearContent();
  ensureExactColumnCount_(sheet, YT_CFG.HEADERS.length);
}


function formatCommentsSheet_(sheet) {
  const lastRow = sheet.getLastRow();

  sheet.setFrozenRows(1);
  sheet
    .getRange(1, 1, 1, YT_CFG.HEADERS.length)
    .setFontWeight('bold')
    .setWrap(true)
    .setVerticalAlignment('middle');

  sheet.getRange('A:A').setNumberFormat('@');

  if (lastRow > 1) {
    sheet
      .getRange(2, 7, lastRow - 1, 1)
      .setNumberFormat('yyyy-mm-dd hh:mm:ss');

    sheet
      .getRange(2, 5, lastRow - 1, 1)
      .setWrap(true)
      .setVerticalAlignment('top');

    sheet
      .getRange(2, 1, lastRow - 1, YT_CFG.HEADERS.length)
      .setVerticalAlignment('top');

    if (sheet.getFilter()) {
      sheet.getFilter().remove();
    }

    sheet
      .getRange(1, 1, lastRow, YT_CFG.HEADERS.length)
      .createFilter();
  }

  sheet.setColumnWidth(1, 90);
  sheet.setColumnWidth(2, 180);
  sheet.setColumnWidth(3, 260);
  sheet.setColumnWidth(4, 170);
  sheet.setColumnWidth(5, 520);
  sheet.setColumnWidth(6, 95);
  sheet.setColumnWidth(7, 155);
  sheet.setColumnWidth(8, 95);
}


/**
 * 숨김 내부 시트에 저장된 댓글 ID 집합을 만듭니다.
 */
function getExistingCommentIds_(internalSheet) {
  const lastRow = internalSheet.getLastRow();

  if (lastRow <= 1) {
    return new Set();
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_ID, lastRow - 1, 1)
    .getDisplayValues();

  return new Set(
    values
      .map(function(row) {
        return row[0];
      })
      .filter(function(value) {
        return Boolean(value);
      })
  );
}


/**
 * 숨김 내부 시트 기준으로 실제 최상위 댓글·답글 수를 계산합니다.
 */
function getExistingCounts_(internalSheet) {
  const lastRow = internalSheet.getLastRow();
  const counts = { top: 0, reply: 0 };

  if (lastRow <= 1) {
    return counts;
  }

  const values = internalSheet
    .getRange(2, YT_CFG.INTERNAL_COL.COMMENT_TYPE, lastRow - 1, 1)
    .getDisplayValues();

  values.forEach(function(row) {
    if (row[0] === 'topLevel') {
      counts.top += 1;
    } else if (row[0] === 'reply') {
      counts.reply += 1;
    }
  });

  return counts;
}


/**
 * 댓글 글자수를 지정된 바이트 규칙으로 계산합니다.
 * - ASCII 영역(영문, 숫자, 공백, 일반 문장부호): 1바이트
 * - 한글을 포함한 비ASCII 유니코드 문자: 코드 포인트당 2바이트
 */
function calculateCommentBytes_(value) {
  const text = String(value || '');
  let bytes = 0;

  Array.from(text).forEach(function(character) {
    const codePoint = character.codePointAt(0);
    bytes += codePoint <= 0x7F ? 1 : 2;
  });

  return bytes;
}


/**
 * 외부 문자열이 시트 수식으로 실행되는 것을 방지합니다.
 */
function safeCellText_(value) {
  const text = value === undefined || value === null ? '' : String(value);
  return /^[=+\-@]/.test(text) ? "'" + text : text;
}


function apiDateToSheetValue_(value) {
  return value ? new Date(value) : '';
}


function ensureColumnCount_(sheet, requiredColumns) {
  const current = sheet.getMaxColumns();

  if (current < requiredColumns) {
    sheet.insertColumnsAfter(current, requiredColumns - current);
  }
}


function ensureExactColumnCount_(sheet, requiredColumns) {
  ensureColumnCount_(sheet, requiredColumns);

  const current = sheet.getMaxColumns();

  if (current > requiredColumns) {
    sheet.deleteColumns(requiredColumns + 1, current - requiredColumns);
  }
}


function getUserProperties_() {
  return PropertiesService.getUserProperties();
}


function getApiKey_() {
  const apiKey = getUserProperties_().getProperty(YT_CFG.API_KEY_PROP);

  if (!apiKey) {
    throwStructuredError_(buildErrorInfo_(
      'API_KEY_REQUIRED',
      'API 키 설정이 필요합니다.',
      '댓글 수집을 시작하기 전에 YouTube Data API 키를 저장해야 합니다.',
      ['현재 사용자 계정에 저장된 API 키가 없습니다.'],
      [
        '사이드바 상단의 API 키 입력란에 키를 입력합니다.',
        '‘API 키 확인 후 저장’을 누릅니다.'
      ],
      {
        focusTarget: 'apiKey',
        actionLabel: 'API 키 입력'
      }
    ));
  }

  return apiKey.trim();
}


function loadState_() {
  const text = getUserProperties_().getProperty(YT_CFG.STATE_PROP);
  return text ? JSON.parse(text) : null;
}


function saveState_(state) {
  state.updatedAt = new Date().toISOString();
  const text = JSON.stringify(state);
  const byteLength = Utilities.newBlob(text).getBytes().length;

  if (byteLength > 8500) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_STORAGE_LIMIT',
      '수집 진행 상태를 저장할 수 없습니다.',
      'Apps Script 사용자 속성의 안전 저장 크기를 초과했습니다.',
      ['진행 상태 데이터가 예상보다 커졌습니다.'],
      [
        '현재 수집을 취소합니다.',
        '댓글 수집 개수를 줄여 새로 실행합니다.'
      ],
      { actionLabel: '확인', technical: { byteLength: byteLength } }
    ));
  }

  getUserProperties_().setProperty(YT_CFG.STATE_PROP, text);
}


function loadLastResult_() {
  const text = getUserProperties_().getProperty(YT_CFG.LAST_RESULT_PROP);
  return text ? JSON.parse(text) : null;
}


function saveLastResult_(state, status, message, errorInfo) {
  const result = {
    status: status,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: Number(state.targetTopLevelCount || 0),
    topCount: Number(state.topCount || 0),
    replyCount: Number(state.replyCount || 0),
    apiCalls: Number(state.apiCalls || 0),
    startedAt: state.startedAt || '',
    updatedAt: new Date().toISOString(),
    finishedAt: new Date().toISOString(),
    message: message || '',
    error: errorInfo || null
  };

  getUserProperties_().setProperty(
    YT_CFG.LAST_RESULT_PROP,
    JSON.stringify(result)
  );
}


function validateStateVersion_(state) {
  if (Number(state.version || 0) !== YT_CFG.STATE_VERSION) {
    throwStructuredError_(buildErrorInfo_(
      'STATE_VERSION_MISMATCH',
      '이전 코드에서 시작된 수집 작업을 이어갈 수 없습니다.',
      '현재 Code.gs의 댓글 저장 구조가 이전 실행 상태와 다릅니다.',
      ['고정 결과 시트 또는 정렬 기준을 사용하던 이전 코드의 작업 상태가 남아 있습니다.'],
      [
        '사이드바에서 진행 중인 수집을 취소합니다.',
        '현재 코드로 같은 영상을 새로 수집합니다.'
      ],
      { actionLabel: '새 수집 필요' }
    ));
  }
}


function normalizeState_(state) {
  state.currentReplyParentId = state.currentReplyParentId || '';
  state.nextReplyPageToken = state.nextReplyPageToken || '';
  state.nextThreadPageToken = state.nextThreadPageToken || '';
  state.threadDone = Boolean(state.threadDone);
  state.topCount = Number(state.topCount || 0);
  state.replyCount = Number(state.replyCount || 0);
  state.apiCalls = Number(state.apiCalls || 0);
  state.threadPages = Number(state.threadPages || 0);
  state.replyPages = Number(state.replyPages || 0);
  state.targetTopLevelCount = Number(state.targetTopLevelCount || 0);
  state.outputSheetId = Number(state.outputSheetId || 0);
  state.outputSheetName = String(state.outputSheetName || '');
  state.error = state.error || null;
}


function maskApiKey_(apiKey) {
  const key = String(apiKey || '');
  return '••••••••••••' + key.slice(-4);
}


function buildProgressForClient_(state, status) {
  const target = Number(state.targetTopLevelCount || 0);
  const top = Number(state.topCount || 0);
  const reply = Number(state.replyCount || 0);
  const percent = target > 0
    ? Math.min(100, Math.round((top / target) * 100))
    : 0;

  let stage = '대기 중';

  if (status === 'RUNNING') {
    if (state.currentReplyParentId) {
      stage = '답글 수집 중';
    } else if (!state.threadDone) {
      stage = '최상위 댓글 수집 중';
    } else {
      stage = '마무리 중';
    }
  } else if (status === 'COMPLETED') {
    stage = '완료';
  } else if (status === 'ERROR') {
    stage = '오류';
  } else if (status === 'CANCELLED') {
    stage = '취소됨';
  }

  return {
    status: status,
    stage: stage,
    outputSheetId: Number(state.outputSheetId || 0),
    outputSheetName: state.outputSheetName || '',
    videoId: state.videoId || '',
    videoTitle: state.videoTitle || '',
    targetTopLevelCount: target,
    topCount: top,
    replyCount: reply,
    totalRows: top + reply,
    apiCalls: Number(state.apiCalls || 0),
    percent: percent,
    startedAt: state.startedAt || '',
    updatedAt: state.updatedAt || '',
    message: state.message || '',
    error: state.error || null
  };
}


function buildServerProgressMessage_(state) {
  return (
    '최상위 댓글 ' +
    state.topCount +
    '/' +
    state.targetTopLevelCount +
    '개, 답글 ' +
    state.replyCount +
    '개를 저장했습니다.'
  );
}


function scheduleContinuation_() {
  deleteContinuationTriggers_();

  ScriptApp
    .newTrigger(YT_CFG.CONTINUE_HANDLER)
    .timeBased()
    .after(YT_CFG.CONTINUE_AFTER_MS)
    .create();
}


function deleteContinuationTriggers_() {
  ScriptApp.getProjectTriggers().forEach(function(trigger) {
    if (trigger.getHandlerFunction() === YT_CFG.CONTINUE_HANDLER) {
      ScriptApp.deleteTrigger(trigger);
    }
  });
}


/**
 * 한국어 모달용 오류 정보를 만듭니다.
 */
function buildErrorInfo_(code, title, summary, causes, steps, options) {
  const opts = options || {};

  return {
    code: String(code || 'UNKNOWN_ERROR'),
    title: String(title || '작업을 완료하지 못했습니다.'),
    summary: String(summary || '처리 중 문제가 발생했습니다.'),
    causes: Array.isArray(causes) ? causes.map(String) : [],
    steps: Array.isArray(steps) ? steps.map(String) : [],
    helpLabel: String(opts.helpLabel || ''),
    helpUrl: String(opts.helpUrl || ''),
    focusTarget: String(opts.focusTarget || ''),
    actionLabel: String(opts.actionLabel || '확인'),
    technical:
      opts.technical && typeof opts.technical === 'object'
        ? opts.technical
        : {}
  };
}


/**
 * 서버 오류를 Sidebar.html이 해석할 수 있는 구조화된 예외로 전달합니다.
 */
function throwStructuredError_(errorInfo) {
  throw new Error(
    YT_CFG.STRUCTURED_ERROR_PREFIX + JSON.stringify(errorInfo)
  );
}


function extractStructuredError_(rawText) {
  const raw = String(rawText || '');
  const markerIndex = raw.indexOf(YT_CFG.STRUCTURED_ERROR_PREFIX);

  if (markerIndex < 0) {
    return null;
  }

  const jsonText = raw.slice(
    markerIndex + YT_CFG.STRUCTURED_ERROR_PREFIX.length
  );

  try {
    return JSON.parse(jsonText);
  } catch (parseError) {
    return null;
  }
}


/**
 * Apps Script 자체 오류도 한국어 모달 정보로 변환합니다.
 */
function normalizeErrorInfo_(error, context) {
  const raw = error && error.message
    ? String(error.message)
    : String(error || '');

  const structured = extractStructuredError_(raw);

  if (structured) {
    return structured;
  }

  const lower = raw.toLowerCase();
  const technical = {
    context: String(context || '작업 실행'),
    originalMessage: raw
  };

  if (
    lower.indexOf('authorization is required') >= 0 ||
    lower.indexOf('you do not have permission') >= 0 ||
    lower.indexOf('permissions') >= 0 && lower.indexOf('required') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_AUTH_REQUIRED',
      'Google 권한 승인이 필요합니다.',
      '현재 계정이 스프레드시트 또는 외부 API 요청 권한을 아직 승인하지 않았습니다.',
      ['Apps Script를 처음 실행했거나 새로운 권한이 추가되었습니다.'],
      [
        '스프레드시트 메뉴에서 사이드바를 다시 엽니다.',
        '권한 검토 화면에서 현재 Google 계정을 선택합니다.',
        '요청되는 권한을 허용한 뒤 다시 실행합니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('maximum execution time') >= 0 ||
    lower.indexOf('exceeded maximum execution time') >= 0 ||
    lower.indexOf('timed out') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_EXECUTION_TIMEOUT',
      '한 번의 실행 가능 시간을 초과했습니다.',
      '댓글 또는 답글 처리 시간이 길어 현재 실행 구간이 종료되었습니다.',
      ['대량 댓글 수집으로 한 번의 Apps Script 실행 시간이 길어졌습니다.'],
      [
        '사이드바를 다시 열어 진행 상태를 확인합니다.',
        '멈춘 경우 ‘중단 지점부터 실행’을 한 번 실행합니다.',
        '같은 문제가 반복되면 수집 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  if (
    lower.indexOf('service invoked too many times') >= 0 ||
    lower.indexOf('quota') >= 0 && lower.indexOf('apps script') >= 0
  ) {
    return buildErrorInfo_(
      'APPS_SCRIPT_SERVICE_QUOTA',
      'Apps Script 서비스 사용 한도를 초과했습니다.',
      '현재 Google 계정 또는 스크립트의 일일 서비스 사용량이 허용 범위를 넘었습니다.',
      ['짧은 시간에 많은 외부 요청이나 스프레드시트 쓰기 작업이 실행되었습니다.'],
      [
        '잠시 뒤 다시 실행합니다.',
        '같은 날 반복되면 다음 날 다시 실행합니다.',
        '한 번에 수집하는 댓글 개수를 줄입니다.'
      ],
      { actionLabel: '확인', technical: technical }
    );
  }

  return buildErrorInfo_(
    'UNEXPECTED_ERROR',
    '예상하지 못한 오류가 발생했습니다.',
    '오류 유형을 자동으로 판별하지 못했습니다.',
    [
      '네트워크, 권한, Google 서비스 상태 또는 실행 환경에서 문제가 발생했을 수 있습니다.'
    ],
    [
      '사이드바를 닫았다가 다시 열고 같은 작업을 한 번 더 실행합니다.',
      'Apps Script 편집기의 ‘실행’ 메뉴에서 실패 기록을 확인합니다.',
      'API 키와 영상 주소를 다시 확인합니다.'
    ],
    { actionLabel: '확인', technical: technical }
  );
}

Sidebar.html

YouTube 댓글 수집기

YouTube Data API v3 → Google Sheets

1. API 키

YouTube Data API 키

최초 1회 저장합니다. 키는 사용자별 Apps Script 속성에 보관됩니다.

2. 수집 설정

API 키를 저장하면 수집 설정이 활성화됩니다.

YouTube 영상 주소

수집할 최상위 댓글 수

1~50,000개. 답글 포함 시 실제 저장 행 수가 이 값보다 많아질 수 있습니다.

대댓글도 모두 수집

새 수집을 시작할 때마다 ‘시트1’, ‘시트2’, ‘시트3’ 형식의 새 시트가 생성됩니다. 기존 수집 결과는 유지됩니다.

바른 API KEY 발급

민기쌤 생기부 도우미

Code.gs

// =================================================================
// [0] 초기 설정 및 메뉴
// =================================================================

function onOpen() {
  SpreadsheetApp.getUi().createMenu('민기쌤 생기부 도우미')
      .addItem('🚀 사이드바 열기', 'openSidebar') 
      .addToUi();
}

function renderView_(viewName) {
  var template = HtmlService.createTemplateFromFile('Sidebar');
  template.initialView = viewName || 'sidebar';
  return template.evaluate();
}

function openSidebar() {
  ensureBannedWordSheet_();
  var html = renderView_('sidebar')
      .setTitle('민기쌤 생기부 맞춤법 도우미')
      .setWidth(300); 
  SpreadsheetApp.getUi().showSidebar(html);
}

function openSpellCheckViewer() {
  var html = renderView_('spellcheck')
      .setWidth(1000) 
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '📝 Bareun 맞춤법 검사 및 수정');
}

function openBannedWordViewer() {
  var html = renderView_('banned')
      .setWidth(1000)
      .setHeight(700);
  SpreadsheetApp.getUi().showModelessDialog(html, '🚫 기재 금지어 점검');
}

// =================================================================
// [1] Bareun API 키 및 UI 설정
// =================================================================

function getBareunUserProperties_() {
  ensureBannedWordSheet_();
  var props = PropertiesService.getUserProperties();
  var currentPolicy = 'BAREUN_ONLY_KEYS_V3';
  var previousPolicy = props.getProperty('API_KEY_POLICY_VERSION');

  // 정책 변경 시 현재 기능에서 쓰지 않는 예전 사용자 설정을 한 번 정리합니다.
  if (previousPolicy !== currentPolicy) {
    var allowedProperties = {
      UI_STATE: true,
      API_KEY_POLICY_VERSION: true
    };
    // 바로 이전 사용자 입력형 정책에서 저장한 키만 보존합니다.
    if (previousPolicy === 'USER_SUPPLIED_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V1' ||
        previousPolicy === 'BAREUN_ONLY_KEYS_V2') {
      allowedProperties.USER_BAREUN_KEY = true;
    }
    Object.keys(props.getProperties()).forEach(function(propertyName) {
      if (!allowedProperties[propertyName]) props.deleteProperty(propertyName);
    });

    var previousUiState = {};
    try {
      previousUiState = JSON.parse(props.getProperty('UI_STATE') || '{}');
    } catch (e) {
      previousUiState = {};
    }
    var currentUiState = {};
    ['card-api', 'sub-api-settings', 'card-util'].forEach(function(id) {
      if (previousUiState[id]) currentUiState[id] = true;
    });
    props.setProperty('UI_STATE', JSON.stringify(currentUiState));
    props.setProperty('API_KEY_POLICY_VERSION', currentPolicy);
  }

  return props;
}

function saveUserBareunKey(bareunKey) {
  var props = getBareunUserProperties_();
  var cleanBareunKey = String(bareunKey || '').trim();

  if (!cleanBareunKey) {
    throw new Error('Bareun API 키를 입력해 주세요. 이 도우미는 API 키를 제공하지 않습니다.');
  }

  props.setProperty('USER_BAREUN_KEY', cleanBareunKey);
  return { hasBareun: true };
}

function checkUserBareunStatus() {
  var props = getBareunUserProperties_();
  return { hasBareun: !!props.getProperty('USER_BAREUN_KEY') };
}

function clearUserBareunKey() {
  var props = getBareunUserProperties_();
  props.deleteProperty('USER_BAREUN_KEY');
  return { hasBareun: false };
}

function getBareunKey() {
  var key = getBareunUserProperties_().getProperty('USER_BAREUN_KEY');
  if (!key) throw new Error("Bareun API 키가 없습니다. 사이드바 상단에서 등록해주세요.");
  return key;
}

// =================================================================
// [2] Bareun 맞춤법 검사
// =================================================================

function getSelectedDataForSpellCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");
  var rows = [];
  var startRow = range.getRow();
  var startCol = range.getColumn();
  var values = range.getValues();
  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var text = values[i][j].toString();
      if (text.trim() !== "") {
        rows.push({ sheetName: sheetName, row: startRow + i, col: startCol + j, original: text });
      }
    }
  }
  return rows;
}

function getBareunCorrection(text) {
  var userKey = getBareunKey();
  var result = callBareunApi(text, userKey); 
  return result; 
}

function applySpellCheckResults(updates) {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  updates.forEach(function(item) {
    var sheet = spreadsheet.getSheetByName(item.sheetName);
    if (!sheet) throw new Error('검사한 시트를 찾을 수 없습니다: ' + item.sheetName);
    sheet.getRange(item.row, item.col).setValue(item.text);
  });
  return updates.length;
}

function callBareunApi(text, userKey) {
  var url = "https://api.bareun.ai/bareun.RevisionService/CorrectError";
  var options = {
    "method": "post", "contentType": "application/json", "headers": { "api-key": userKey }, "muteHttpExceptions": true,
    "payload": JSON.stringify({ "document": { "content": text, "language": "ko-KR" }, "encoding_type": "UTF16" })
  };
  var response = UrlFetchApp.fetch(url, options);
  var result = JSON.parse(response.getContentText());
  
  if (response.getResponseCode() !== 200) {
    return { error: "API 오류: " + response.getResponseCode() };
  }
  return { revised: result.revised, helps: result.helps || {}, rawBlocks: result.revisedBlocks || result.revised_blocks || [], error: null };
}

// =================================================================
// [3] 기재 금지어 관리
// =================================================================

var BANNED_WORD_SHEET_NAME_ = '기재금지어관리';
var BANNED_WORD_HEADERS_ = ['유형', '기재 금지어', '대체 표현'];

function getLegacyBannedWordList_() {
  var saved = PropertiesService.getUserProperties().getProperty('BANNED_WORDS_DB');
  if (!saved) return getDefaultBannedList_();

  try {
    var parsed = JSON.parse(saved);
    if (!Array.isArray(parsed)) return getDefaultBannedList_();
    return parsed
      .map(function(item) {
        return {
          k: String(item && item.k || '').trim(),
          v: String(item && item.v || '').trim(),
          t: item && item.t === 'ban' ? 'ban' : 'replace'
        };
      })
      .filter(function(item) { return item.k !== ''; });
  } catch (e) {
    return getDefaultBannedList_();
  }
}

function initializeBannedWordSheet_(sheet, list) {
  sheet.getRange(1, 1, 1, BANNED_WORD_HEADERS_.length)
    .setValues([BANNED_WORD_HEADERS_])
    .setBackground('#fce8e6')
    .setFontColor('#a50e0e')
    .setFontWeight('bold')
    .setHorizontalAlignment('center');

  var rows = list.map(function(item) {
    return [item.t === 'ban' ? '불가' : '대체', item.k, item.t === 'ban' ? '' : item.v];
  });
  if (rows.length > 0) sheet.getRange(2, 1, rows.length, 3).setValues(rows);

  sheet.setFrozenRows(1);
  sheet.setColumnWidth(1, 90);
  sheet.setColumnWidth(2, 180);
  sheet.setColumnWidth(3, 260);
  sheet.setTabColor('#d93025');

  if (sheet.getMaxRows() > 1) {
    var typeRule = SpreadsheetApp.newDataValidation()
      .requireValueInList(['대체', '불가'], true)
      .setAllowInvalid(false)
      .setHelpText('대체 또는 불가 중 하나를 선택하세요.')
      .build();
    sheet.getRange(2, 1, sheet.getMaxRows() - 1, 1).setDataValidation(typeRule);
  }
}

function ensureBannedWordSheet_() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  if (!spreadsheet) throw new Error('활성 스프레드시트를 찾을 수 없습니다.');

  var originalSheet = spreadsheet.getActiveSheet();
  var originalRange = spreadsheet.getActiveRange();
  var lock = LockService.getDocumentLock() || LockService.getScriptLock();
  lock.waitLock(30000);

  var sheet;
  try {
    sheet = spreadsheet.getSheetByName(BANNED_WORD_SHEET_NAME_);
    if (!sheet) {
      sheet = spreadsheet.insertSheet(BANNED_WORD_SHEET_NAME_);
      initializeBannedWordSheet_(sheet, getLegacyBannedWordList_());
    }

    // 시트로 옮긴 뒤 예전 사용자별 저장값은 더 이상 별도 원본으로 남기지 않습니다.
    PropertiesService.getUserProperties().deleteProperty('BANNED_WORDS_DB');
    return sheet;
  } finally {
    if (originalSheet && sheet && originalSheet.getSheetId() !== sheet.getSheetId()) {
      spreadsheet.setActiveSheet(originalSheet);
      if (originalRange) spreadsheet.setActiveRange(originalRange);
    }
    lock.releaseLock();
  }
}

function openBannedWordManagementSheet() {
  var sheet = ensureBannedWordSheet_();
  sheet.activate();
  sheet.getRange('A1').activate();
  return sheet.getName();
}

function getDefaultBannedList_() {
  return [
    { k: "MBTI", v: "성격 유형 검사", t: "replace" },
    { k: "커리어넷", v: "진로 정보 사이트", t: "replace" },
    { k: "메이저맵", v: "진로 정보망", t: "replace" },
    { k: "패들렛", v: "온라인 협업 도구", t: "replace" },
    { k: "띵커벨", v: "온라인 협업 플랫폼", t: "replace" },
    { k: "알로", v: "온라인 협업 플랫폼", t: "replace" },
    { k: "미리캔버스", v: "온라인 디자인 제작 플랫폼", t: "replace" },
    { k: "망고보드", v: "온라인 디자인 제작 플랫폼", t: "replace" },
    { k: "유튜버", v: "동영상 크리에이터", t: "replace" },
    { k: "유튜브", v: "동영상 공유 플랫폼", t: "replace" },
    { k: "넷플릭스", v: "온라인 동영상 서비스", t: "replace" },
    { k: "왓챠", v: "온라인 동영상 서비스", t: "replace" },
    { k: "티빙", v: "온라인 동영상 서비스", t: "replace" },
    { k: "네이버 폼", v: "온라인 설문조사", t: "replace" },
    { k: "구글 폼", v: "온라인 설문조사", t: "replace" },
    { k: "OECD", v: "경제 관련 국제 기구", t: "replace" },
    { k: "UN", v: "국제 기구", t: "replace" },
    { k: "유네스코", v: "교육 문화 국제 기구", t: "replace" },
    { k: "WTO", v: "무역 관련 국제 기구", t: "replace" },
    { k: "WHO", v: "보건 관련 국제 기구", t: "replace" },
    { k: "그린피스", v: "국제 환경 보전 단체", t: "replace" },
    { k: "앰네스티", v: "인권 관련 국제 비정부 기구", t: "replace" },
    { k: "IMF", v: "국제 통화 관련 기구", t: "replace" },
    { k: "인스타그램", v: "사회 관계망 서비스", t: "replace" },
    { k: "페이스북", v: "소셜 미디어 서비스", t: "replace" },
    { k: "카카오톡", v: "메신저 서비스", t: "replace" },
    { k: "네이버", v: "포털 사이트", t: "replace" },
    { k: "구글", v: "검색 엔진", t: "replace" },
    { k: "클래스 카드", v: "단어 학습 어플", t: "replace" },
    { k: "구글 클래스룸", v: "학습 플랫폼", t: "replace" },
    { k: "게더타운", v: "메타버스 플랫폼", t: "replace" },
    { k: "제페토", v: "메타버스 플랫폼", t: "replace" },
    { k: "아이패드", v: "태블릿 PC", t: "replace" },
    { k: "갤럭시 탭", v: "태블릿 PC", t: "replace" },
    { k: "비트코인", v: "가상 화폐", t: "replace" },
    { k: "TED", v: "온라인 강연", t: "replace" },
    { k: "반크", v: "사이버 외교 사절단", t: "replace" },
    { k: "TOEIC", v: "", t: "ban" },
    { k: "TOEFL", v: "", t: "ban" },
    { k: "TEPS", v: "", t: "ban" },
    { k: "대회", v: "", t: "ban" },
    { k: "수상", v: "", t: "ban" },
    { k: "한자능력검정", v: "", t: "ban" }
  ];
}

function getBannedWordList_() {
  var sheet = ensureBannedWordSheet_();
  var header = sheet.getRange(1, 1, 1, 3).getDisplayValues()[0];
  if (header.join('|') !== BANNED_WORD_HEADERS_.join('|')) {
    throw new Error('기재금지어관리 시트의 1행을 "유형 | 기재 금지어 | 대체 표현" 순서로 유지해 주세요.');
  }

  var lastRow = sheet.getLastRow();
  if (lastRow < 2) return [];

  var values = sheet.getRange(2, 1, lastRow - 1, 3).getDisplayValues();
  var seen = {};
  var list = [];

  values.forEach(function(row, index) {
    var rowNumber = index + 2;
    var type = String(row[0] || '').trim();
    var keyword = String(row[1] || '').trim();
    var replacement = String(row[2] || '').trim();

    if (!type && !keyword && !replacement) return;
    if (!keyword) throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어(B열)를 입력해 주세요.');
    if (type !== '대체' && type !== '불가') {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 유형(A열)은 대체 또는 불가여야 합니다.');
    }
    if (type === '대체' && !replacement) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 대체 표현(C열)을 입력하거나 유형을 불가로 바꿔 주세요.');
    }

    var duplicateKey = keyword.toLocaleLowerCase();
    if (seen[duplicateKey]) {
      throw new Error('기재금지어관리 시트 ' + rowNumber + '행의 기재 금지어가 ' + seen[duplicateKey] + '행과 중복됩니다: ' + keyword);
    }
    seen[duplicateKey] = rowNumber;
    list.push({ k: keyword, v: type === '불가' ? '' : replacement, t: type === '불가' ? 'ban' : 'replace' });
  });

  return list;
}

function runBannedWordCheck() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var sheetName = sheet.getName();
  var range = sheet.getActiveRange();
  if (!range) throw new Error("선택된 셀이 없습니다.");

  var values = range.getValues();
  var startRow = range.getRow();
  var startCol = range.getColumn();
  
  var db = getBannedWordList_();
  db.sort((a, b) => b.k.length - a.k.length);

  var patterns = db.map(function(item) {
    return {
      regex: new RegExp(escapeRegExp(item.k), "gi"),
      v: item.v,
      t: item.t,
      k: item.k
    };
  });

  var results = [];

  for (var i = 0; i < values.length; i++) {
    for (var j = 0; j < values[0].length; j++) {
      var original = values[i][j].toString();
      if (!original.trim()) continue;

      var revised = original;
      var hasIssue = false;
      var logs = [];

      for (var p = 0; p < patterns.length; p++) {
        var item = patterns[p];
        if (item.regex.test(revised)) {
          hasIssue = true;
          var alreadyLogged = false;
          for(var l=0; l {
    return row.map(cell => {
      let str = String(cell);
      // 공백이 2번 이상 연속( /  +/)으로 있으면 1번으로 변경
      // 줄바꿈(\n)은 건드리지 않도록 일반 공백( )만 타겟팅
      if (/ {2,}/.test(str)) {
        fixCount++;
        return str.replace(/ {2,}/g, ' '); 
      }
      return cell;
    });
  });

  if (fixCount > 0) {
    range.setValues(newValues);
  }
  
  return fixCount;
}

// =================================================================
// [5] UI 상태 저장/불러오기
// =================================================================

function saveUiState(cardId, isExpanded) {
  var props = PropertiesService.getUserProperties();
  var state = JSON.parse(props.getProperty('UI_STATE') || '{}');
  state[cardId] = isExpanded;
  props.setProperty('UI_STATE', JSON.stringify(state));
}

function getUiState() {
  var props = PropertiesService.getUserProperties();
  return JSON.parse(props.getProperty('UI_STATE') || '{}');
}

Sidebar.html


= 0 ? initialView : "sidebar"; ?>



  
    
    
    
    
  
  
    
      
        🔑 Bareun API 키 설정
        expand_more
      
      
        
          
            내 Bareun API 키
            expand_more
          
          
            ⌛ API 키 설정 확인 중...
            
              
              Bareun API 키
              
              공용 키는 제공하지 않습니다. 키는 사용자별 설정에 저장되고 원문을 화면으로 다시 불러오지 않습니다.
              
              
            
          
        
      
    

    
      
        📝 선택 영역 검사 및 정리
        expand_more
      
      
        
        
        
        
        
        
      
    

    
  





  
    
    
    
    
    
  
  

    
      fact_check 맞춤법 검사 및 수정
      
        원본 오류
        수정 제안
      
    

    
      
        
        데이터를 불러오는 중입니다...
      
      
    

    
      
      
    

    
  





  
    
    
    
    
  
  

    
      block 기재 금지어 검사
      
        금지어 발견
        대체어 제안
      
    

    
      
        
        데이터를 분석 중입니다...

구글 시트와 Apps Script로 반복 업무 자동화 심화

Sun, 19 Jul 2026 02:52:45 GMT

구글 시트와 Apps Script로 반복 업무 자동화 심화

강사: 교사 김민기(민기쌤)
일시: 2026-06-26
장소: 천안신당고등학교

구글 시트와 Apps Script를 활용해 학교 업무 자동화 웹 앱을 설계하고 확장하는 심화 실습 연수입니다.

강의 자료

[교안] 구글 시트와 Apps Script로 반복 업무 자동화 심화.pptx

과정중심 피드백의 이론과 방법

Sun, 19 Jul 2026 02:52:45 GMT

과정중심 피드백의 이론과 방법

강사: 교사 김민기(민기쌤)
일시: 2026-06-24
장소: 천안동중학교

학생의 학습과 성장을 지원하는 과정중심 피드백의 의미와 적용 방법을 다루는 연수입니다.

강의 자료

[교안] 과정중심 피드백의 이론과 방법.pptx

2026년 교장 자격연수 AI·디지털 도구의 활용 실습교육

Sun, 02 Aug 2026 01:32:50 GMT

2026년 교장 자격연수 AI·디지털 도구의 활용 실습교육

강사: 교사 김민기(민기쌤)
일시: 2026-06-23
장소: 한국교원대학교

구글 시트와 Apps Script로 반복 업무 자동화

Sun, 19 Jul 2026 02:52:45 GMT

구글 시트와 Apps Script로 반복 업무 자동화

강사: 교사 김민기(민기쌤)
일시: 2026-06-12
장소: 충청남도교육청교육과정평가정보원

입력·처리·출력 구조를 이해하고 구글 시트와 Apps Script로 학교 업무용 웹 앱을 만드는 실습 연수입니다.

강의 자료

[교안] 구글 시트와 Apps Script로 반복 업무 자동화.pptx

반복 업무 자동화를 위한 구글 시트와 Apps Script 활용 - 천안신당고등학교

Sun, 19 Jul 2026 02:52:45 GMT

반복 업무 자동화를 위한 구글 시트와 Apps Script 활용 - 천안신당고등학교

강사: 교사 김민기(민기쌤)
일시: 2026-05-29
장소: 천안신당고등학교

구글 시트와 Apps Script를 활용해 학교의 반복 업무를 자동화하는 교직원 실습 연수입니다.

강의 자료

[강의원고] 반복 업무 자동화를 위한 구글 시트와 Apps Script 활용.pdf

반복 업무 자동화를 위한 구글 시트와 Apps Script 활용 - 용남중학교

Sun, 19 Jul 2026 02:52:45 GMT

반복 업무 자동화를 위한 구글 시트와 Apps Script 활용 - 용남중학교

강사: 교사 김민기(민기쌤)
일시: 2026-05-27
장소: 용남중학교

구글 시트와 Apps Script를 활용해 학교의 반복 업무를 자동화하는 교직원 실습 연수입니다.

강의 자료

[교안] 반복 업무 자동화를 위한 구글 시트와 Apps Script 활용.pdf

데이터 분석 기반 AI 융합 수업 사례

Sun, 19 Jul 2026 02:52:45 GMT

데이터 분석 기반 AI 융합 수업 사례

강사: 교사 김민기(민기쌤)
일시: 2026-05-24
장소: 중앙교육연수원 원격연수

의사소통 데이터와 여론 데이터를 활용해 비판적 사고와 문제 해결을 촉진하는 AI 융합수업 사례 연수입니다.

강의 자료

[교안] 데이터 분석 기반 AI 융합 수업 사례.pdf

반복 업무 자동화를 위한 구글 시트와 Apps Script 활용

Sun, 19 Jul 2026 02:52:45 GMT

반복 업무 자동화를 위한 구글 시트와 Apps Script 활용

강사: 교사 김민기(민기쌤)
일시: 2026-05-22
장소: 충청남도교육청교육과정평가정보원

구글 시트와 Apps Script를 활용해 학교의 반복 업무를 구조화하고 자동화하는 실습 연수입니다.

강의 자료

[교안] 반복 업무 자동화를 위한 구글 시트와 Apps Script 활용.pdf

당진정보고등학교 교직원 연수

Sat, 18 Jul 2026 23:28:33 GMT

당진정보고등학교 교직원 연수

강사: 교사 김민기(민기쌤)
일시: 2026-04-23
장소: 당진정보고등학교

당진정보고등학교 교직원을 대상으로 진행한 학교 연수 기록입니다.

국어과 AI 융합교육 현장 사례 공유 - 천안동중 교직원 연수

Sun, 19 Jul 2026 02:52:45 GMT

국어과 AI 융합교육 현장 사례 공유 - 천안동중 교직원 연수

강사: 교사 김민기(민기쌤)
일시: 2026-04-22
장소: 천안동중학교

국어과 AI 융합수업의 설계 원리와 실제 수업 사례를 공유하는 교직원 연수입니다.

강의 자료

[강의원고] 국어과 AI 융합교육 현장 사례 공유.pptx

국어과 AI 융합교육 현장 사례 공유

Sun, 19 Jul 2026 02:52:45 GMT

국어과 AI 융합교육 현장 사례 공유

강사: 교사 김민기(민기쌤)
일시: 2026-04-20
장소: 서울대학교

국어과의 핵심 아이디어와 탐구 방법을 바탕으로 AI 융합수업 현장 사례를 살펴보는 연수입니다.

강의 자료

[강의원고] 국어과 AI 융합교육 현장 사례 공유.pdf

2026 학교관리자 디지털 역량강화 직무연수 2기

Fri, 10 Apr 2026 00:28:58 GMT

2026 학교관리자 디지털 역량강화 직무연수 2기

강사: 교사 김민기(민기쌤)
일시: 2026-04-10
장소: 충청남도교육청교육과정평가정보원

반복 업무 자동화를 위한 구글 시트와 앱스스크립트 활용 연수입니다.

강의 자료

[김민기] [큰 PDF] 반복 업무 자동화를 위한 구글 시트와 앱스스크립트 활용.pdf

효과적인 교육과정 평가 환류를 위한 업무 최적화

Sun, 19 Jul 2026 02:52:45 GMT

효과적인 교육과정 평가 환류를 위한 업무 최적화

강사: 교사 김민기(민기쌤)
일시: 2026-02-19
장소: 청양고등학교

교육과정 평가 결과를 효과적으로 환류하고 반복 업무를 최적화하는 교직원 연수입니다.

강의 자료

[교안] 효과적인 교육과정 평가 환류를 위한 업무 최적화.pdf

대한민국 교육박람회 AI 디지털 교육자료 세미나

Tue, 13 Jan 2026 21:06:12 GMT

대한민국 교육박람회 AI 디지털 교육자료 세미나

강사: 교사 김민기(민기쌤)
일시: 2026-01-23
장소: 서울 코엑스

대한민국 교육박람회 중 한국교과서협회가 주관하는 서울 코엑스 AI 디지털 교육자료 교사페스티벌 세미나 강의입니다.

강의 자료

[강의원고] 김민기.pptx

AI 융합수업 설계 이론(3)

Sun, 04 Jan 2026 00:38:27 GMT

AI 융합수업 설계 이론(3)

강사: 교사 김민기(민기쌤)
일시: 2026-01-19
장소: 서울대학교

09:00~13:00 서울대학교 사범대학

강의 자료

[AIEDAP] 전문성 강화 연수(수업 설계 심화형) 교안 통합본.pdf

2026 배움기 핵심과정 중등 학급운영 직무연수

Wed, 07 Jan 2026 03:25:14 GMT

2026 배움기 핵심과정 중등 학급운영 직무연수

강사: 교사 김민기(민기쌤)
일시: 2026-01-14
장소: 충남교육청교육연수원

✅ 안내
🗨️ 담임업무 최적화를 위한 디지털 인공지능도구 활용 분과입니다.
🗨️ 바른AI에 로그인할 때 '구글' 로그인이 응답하지 않는다면 '카카오톡' 로그인을 이용해 보세요.

강의 자료

공주대학교 AI 융합 수업의 사례 탐구 및 개발 실습 연수

Wed, 07 Jan 2026 07:45:39 GMT

공주대학교 AI 융합 수업의 사례 탐구 및 개발 실습 연수

강사: 교사 김민기(민기쌤)
일시: 2026-01-07
장소: 공주대학교

공주대학교 연수입니다.

서울대학교 사범대학 학부 계절학기

Tue, 06 Jan 2026 00:02:30 GMT

서울대학교 사범대학 학부 계절학기

강사: 교사 김민기(민기쌤)
일시: 2026-01-06
장소: 서울대학교

서울대학교 사범대학 학부 계절학기

강의 자료

음성 녹음 텍스트 전사본 샘플.txt

AI 융합수업 설계 이론(2)

Sun, 04 Jan 2026 00:35:23 GMT

AI 융합수업 설계 이론(2)

강사: 교사 김민기(민기쌤)
일시: 2025-12-28
장소: 서울대학교

09:00~13:00 서울대학교 사범대학 교육학과

교무 업무 최적화의 발달 단계

Sun, 19 Jul 2026 02:52:45 GMT

교무 업무 최적화의 발달 단계

강사: 교사 김민기(민기쌤)
일시: 2025-12-27
장소: 공주대학교

교무 업무 최적화가 발전하는 단계를 사례 중심으로 살펴보는 대학 발표입니다.

강의 자료

[발표자료] 교무 업무 최적화의 발달 단계.pdf

AI 융합수업 설계 이론(1)

Sun, 04 Jan 2026 00:37:33 GMT

AI 융합수업 설계 이론(1)

강사: 교사 김민기(민기쌤)
일시: 2025-12-21
장소: 서울대학교

09:00~13:00 서울대학교 사범대학 교육학과

서산중앙고등학교 교직원 연수

Sun, 19 Jul 2026 02:52:45 GMT

서산중앙고등학교 교직원 연수

강사: 교사 김민기(민기쌤)
일시: 2025-12-11
장소: 서산중앙고등학교

서산중앙고등학교 교직원을 대상으로 운영한 학교 연수 기록입니다.

앱스스크립트와 구글 도구를 활용한 업무 자동화

Sun, 19 Jul 2026 02:52:45 GMT

앱스스크립트와 구글 도구를 활용한 업무 자동화

강사: 교사 김민기(민기쌤)
일시: 2025-12-06
장소: 청양고등학교

Apps Script와 구글 도구를 활용해 학교의 반복 업무를 자동화하는 교직원 연수입니다.

강의 자료

[강의원고] 앱스스크립트와 구글 도구를 활용한 업무 자동화.pptx

구글 클래스룸 기반 수행평가 혁신 가이드 - 행정 효율화와 평가 공정성 확보를 위한 전략

Sun, 19 Jul 2026 02:52:45 GMT

구글 클래스룸 기반 수행평가 혁신 가이드 - 행정 효율화와 평가 공정성 확보를 위한 전략

강사: 교사 김민기(민기쌤)
일시: 2025-11-24
장소: 서산중앙고등학교

구글 클래스룸을 활용해 수행평가 행정의 효율성과 평가의 공정성을 높이는 전략을 다루는 연수입니다.

강의 자료

[강의원고] 구글 클래스룸 기반 수행평가 혁신 가이드.pdf

AI 시대가 요구하는 인재, 급변하는 대입 제도와 고교학점제로 읽다

Sun, 19 Jul 2026 02:52:45 GMT

AI 시대가 요구하는 인재, 급변하는 대입 제도와 고교학점제로 읽다

강사: 교사 김민기(민기쌤)
일시: 2025-11-19
장소: 구봉중학교

학부모를 대상으로 AI 시대의 인재상과 대입 제도, 고교학점제를 함께 살펴보는 연수입니다.

나무학교 수업 축제 - 업무 최적화

Sun, 19 Jul 2026 02:52:45 GMT

나무학교 수업 축제 - 업무 최적화

강사: 교사 김민기(민기쌤)
일시: 2025-11-08
장소: 나무학교

나무학교 수업 축제에서 학교 업무 최적화 아이디어와 실습 사례를 나누는 발표입니다.

AI 융합교육 사례 공유

Sun, 19 Jul 2026 02:52:45 GMT

AI 융합교육 사례 공유

강사: 교사 김민기(민기쌤)
일시: 2025-11-04
장소: 태안교육지원청

학교 현장에서 실천한 AI 융합교육 사례를 공유하는 교원 연수입니다.

강의 자료

[강의원고] AI 융합교육 사례 공유.pdf

Gemini API 활용 교직원 연수

Sun, 19 Jul 2026 02:52:45 GMT

Gemini API 활용 교직원 연수

강사: 교사 김민기(민기쌤)
일시: 2025-11-01
장소: 부석중학교

Gemini API를 활용한 학교 업무와 수업 지원 방법을 다루는 교직원 연수입니다.

AI 융합교육 사례 탐색 및 도구 실습

Sun, 19 Jul 2026 02:52:45 GMT

AI 융합교육 사례 탐색 및 도구 실습

강사: 교사 김민기(민기쌤)
일시: 2025-10-25
장소: 서울대학교

AI 융합교육 사례를 탐색하고 수업 설계에 필요한 도구를 실습하는 대학 연수입니다.

강의 자료

[강의원고] 국어과 AI 융합교육 사례 탐색 및 도구 실습.pptx

인공지능 활용 교직원 연수

Sun, 19 Jul 2026 02:52:45 GMT

인공지능 활용 교직원 연수

강사: 교사 김민기(민기쌤)
일시: 2025-10-14
장소: 삽교고등학교

학교 현장에서 인공지능을 활용하는 방법을 살펴보는 교직원 연수입니다.

강의 자료

[강의원고] 인공지능 활용 교직원 연수.pptx

교직원 업무 최적화

Sun, 19 Jul 2026 02:52:45 GMT

교직원 업무 최적화

강사: 교사 김민기(민기쌤)
일시: 2025-09-17
장소: 부석중학교

디지털 도구를 활용해 교직원의 반복 업무를 줄이고 협업을 개선하는 연수입니다.

강의 자료

[강의원고] 교직원 업무 최적화.pptx

대전구봉중학교 교직원 연수

Thu, 08 Jan 2026 01:08:31 GMT

대전구봉중학교 교직원 연수

강사: 교사 김민기(민기쌤)
일시: 2025-09-15
장소: 대전구봉중학교

AI · 디지털 기술을 활용한 학교 업무 최적화 및 반복 업무 경감

학부모 진로·진학 연수 - 고교 3년 로드맵과 대입 대비 활동 설계

Sun, 19 Jul 2026 02:52:45 GMT

학부모 진로·진학 연수 - 고교 3년 로드맵과 대입 대비 활동 설계

강사: 교사 김민기(민기쌤)
일시: 2025-09-11
장소: 태안고등학교

학부모를 대상으로 고교 3년 로드맵과 대입 대비 활동 설계를 안내하는 연수입니다.

부석중학교 교직원 연수

Wed, 07 Jan 2026 07:42:57 GMT

부석중학교 교직원 연수

강사: 교사 김민기(민기쌤)
일시: 2025-08-20
장소: 부석중학교

디지털 기반 교육혁신의 필요성

AIEDAP 마스터 교원 승급 연수

Wed, 07 Jan 2026 07:39:55 GMT

AIEDAP 마스터 교원 승급 연수

강사: 교사 김민기(민기쌤)
일시: 2025-08-02
장소: 서울교육대학교

교육부-서울대학교 AIEDAP 마스터 교원 승급 연수
D.E.E.P 수업모형을 활용한 데이터 기반 인공지능 융합 프로젝트

강의 자료

[강의원고] D.E.E.P 수업모형을 활용한 데이터 기반 인공지능 융합 프로젝트.pdf

AI 융합 수업의 사례 탐구 및 개발 실습 - AIEDAP 멘토링

Sun, 19 Jul 2026 02:52:45 GMT

AI 융합 수업의 사례 탐구 및 개발 실습 - AIEDAP 멘토링

강사: 교사 김민기(민기쌤)
일시: 2025-07-28
장소: 목원대학교

AIEDAP 멘토링 과정에서 AI 융합 수업 사례를 탐구하고 개발하는 대학 연수입니다.

강의 자료

[강의원고] AI 융합 수업의 사례 탐구 및 개발 실습.pptx

AI 융합 수업의 사례 탐구 및 개발 실습

Sun, 19 Jul 2026 02:52:45 GMT

AI 융합 수업의 사례 탐구 및 개발 실습

강사: 교사 김민기(민기쌤)
일시: 2025-07-28
장소: 공주대학교

AI 융합 수업 사례를 탐구하고 수업을 직접 개발하는 실습 중심 대학 연수입니다.

강의 자료

[강의원고] AI 융합 수업의 사례 탐구 및 개발 실습.pptx

빅데이터 활용 인공지능 융합 수업 설계

Sun, 19 Jul 2026 02:52:45 GMT

빅데이터 활용 인공지능 융합 수업 설계

강사: 교사 김민기(민기쌤)
일시: 2025-07-03
장소: 둔포중학교

빅데이터를 활용해 인공지능 융합 수업을 설계하는 교직원 연수입니다.

강의 자료

[강의원고] 빅데이터 활용 인공지능 융합 수업 설계.pptx

교사 김민기(민기쌤) 연수 아카이브 | 민기.한국

충청북도교육청 AI 레벨업 (성찰) 연수

충청북도교육청 AI 레벨업 (성찰) 연수

강의 자료

관련 링크

충남온수업 미래교육배움터 제미나이, 챗GPT

충남온수업 미래교육배움터 제미나이, 챗GPT

강의 자료

관련 링크

ChatGPT로 이미지 만들기

웹캠으로 찍은 교사 사진을 이모티콘 세트로 만들기

모의고사나 시험지용 흑백 삽화 만들기

학교 행사 포스터 만들기

충남교육청 AI 에듀테크 활용 역량강화 연수

충남교육청 AI 에듀테크 활용 역량강화 연수

강의 자료

관련 링크

생기부 점검

Code.gs

Sidebar.html

석림중학교 교직원 연수

석림중학교 교직원 연수

강의 자료

바른 API

Code.gs

Sidebar.html

성환중학교 교직원 연수

성환중학교 교직원 연수

강의 자료

2026 AI·디지털 교육 역량강화 연수(국어 심화) - 8. 12. 한서대학교

2026 AI·디지털 교육 역량강화 연수(국어 심화) - 8. 12. 한서대학교

관련 링크

(1차시) 마주온 활용

교안 및 학습자료

(2차시) 토의·토론

교안 및 학습자료

(3차시) AI 융합 수업 설계

Code.gs

Sidebar.html

YouTube 댓글 수집기

1. API 키

2. 수집 설정

진행 상태

Youtube Data API v3 KEY

교안 및 학습자료

관련 링크

(4차시) 앱스스크립트

교안 및 학습자료

(5차시) 바른 API로 생기부 검토

Code.gs

Sidebar.html

관련 링크

2026 AI·디지털 교육 역량강화 연수(국어 기초) - 8. 11. 공주대학교 천안캠퍼스

2026 AI·디지털 교육 역량강화 연수(국어 기초) - 8. 11. 공주대학교 천안캠퍼스

관련 링크

(1차시) 마주온 활용

교안 및 학습자료

(2차시) 토의·토론

교안 및 학습자료

(3차시) AI 융합 수업 설계

Code.gs

Sidebar.html

YouTube 댓글 수집기

1. API 키

2. 수집 설정

진행 상태

Youtube Data API v3 KEY

교안 및 학습자료

관련 링크

(4차시) 앱스스크립트

교안 및 학습자료

(5차시) 바른 API로 생기부 검토

Code.gs

Sidebar.html

관련 링크

AIEDAP 마스터 교원 전문성 강화 연수 - 교과 기반(국어 심화)

AIEDAP 마스터 교원 전문성 강화 연수 - 교과 기반(국어 심화)

강의 자료

관련 링크

유튜브 댓글 데이터 분석