2026년 9월 6일 일요일

[학급 경영] 학급 FAQ 챗보드 - 3월 문의 폭풍을 검색창 한 줄로 끝내기



3월의 전화 요청 폭풍이 검색창 한 줄로 끝난다 — 학부모·학생 스마트 FAQ 챗보드 완전 정복

💬 교외체험학습 신청서 기한, 약 복용 의뢰서 양식, 학급 준비물, 급식 알레르기 수칙 — 담임교사에게 학기 초에 쏟아지는 단순 반복 문의를 키워드 검색 한 번으로 끝내는 24시간 학급 FAQ 챗보드. 담임이 구글 시트에 질문·답변을 정리해두면, 학부모가 검색창에서 즉시 답변과 양식을 확인합니다.

데이터 연결은 gviz/tq(구글 시트를 데이터베이스처럼 쓰는 공식 주소) — 시트를 수정하면 앱 수정 없이 FAQ가 실시간 갱신됩니다. FAQ는 개인정보 없는 공개 정보만 담고, 심기 모드(데이터 임베딩) 폴백(fallback)으로 오프라인에서도 작동합니다.

📖 한 줄 정의

심기 모드(데이터 임베딩): API 데이터를 미리 받아 HTML 파일 안 상수로 박아두는 방식(앱 실행 중 외부 통신 0).

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
FAQ 데이터 파이프 시트 칸 4개(질문·답변·분류·양식링크)만 채우면 앱이 자동으로 읽어옵니다 — 담임은 앱 코드를 건드리지 않고 시트에 한 줄씩 추가만. FAQ 시트 20개 채우기.
키워드 검색 매칭 '약 복용' 한 단어에 질문·답변·분류 전체를 훑어 관련 카드를 뽑아줍니다 — 완벽한 문장이 아니어도 답이 나옵니다. searchFaq 함수.
원클릭 양식 다운로드 시트의 '양식링크' 칸에 파일 주소를 넣으면, 답변 카드에 '서식 내려받기' 버튼이 자동으로 붙습니다. 링크 칸 채우기.

2. 핵심 아키텍처 해설

① gviz/tq FAQ 읽기 (래핑 처리 포함)

const SHEET = "https://docs.google.com/spreadsheets/d/{시트ID}/gviz/tq?tqx=out:json";

async function loadFaq() {
  const res = await fetch(SHEET);
  const raw = await res.text();
  const json = JSON.parse(raw.substring(raw.indexOf("{"),
    raw.lastIndexOf("}") + 1));   // JSONP 래핑 벗기기
  return json.table.rows.map(function (r) {
    return { q: (r.c[0] || {}).v, a: (r.c[1] || {}).v,
             cat: (r.c[2] || {}).v, link: (r.c[3] || {}).v };
  });
}

② 키워드 검색 매칭

function searchFaq(word, list) {
  return list.filter(function (f) {
    return (f.q + " " + f.cat + " " + f.a).indexOf(word) > -1;
  });
}

질문·분류·답변을 하나의 문자열로 이어 부분 일치를 찾습니다 — 초보 학부모의 짧은 키워드에도 답이 나옵니다.

③ 답변 카드 + 양식 버튼

function answerCard(f) {
  // 제목(질문), 본문(답변·분류), 그리고
  if (f.link) showDownload(f.link);   // 서식 내려받기 버튼
}

④ 심기 모드 폴백(오프라인 안전망)

const EMBED_FAQ = [
  { q: "약 복용 의뢰서는 어디서?", a: "보건실 알림장 공지 파일", cat: "건강", link: "https://..." }
];

async function loadFaq() {
  if (EMBED_FAQ.length > 0) return EMBED_FAQ;   // 심기 모드 우선
  ... (gviz/tq 읽기) ...
}

시트가 없거나 학내망이 닫혀 있을 때도 FAQ가 멈추지 않습니다 — 학내망 원칙 정합 설계.

⑤ 원칙·정합

FAQ 시트에는 학생 실명·연락처 일절 금지(공개 정보만). 배포는 학교가 검토·계약한 알림장 서비스(하이클래스 등) 공지사항 상단에 링크 고정 — 가정 접속 경로는 학교 정책 기준.

3. 초보자를 위한 바이브 코딩 실전 사용 예시

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — Gemini의 질문 3가지(FAQ 분류 체계, 갱신 담당, 배포 위치)에 답하면 설계가 확정됩니다.
  3. HTML 파일 실행 — 완성 코드를 '학급FAQ.html'로 저장 후 더블클릭 — 알림장 서비스에 링크를 고정하면 24시간 FAQ가 시작됩니다.

제미나이 전용 에러 제로 프롬프트

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·폰트·이미지 파일 없이 단일 HTML 파일로 완성한다 — 더블클릭 즉시 실행.
2. 사운드는 Web Audio API로 직접 합성한다: 검색 성공 '똑', 결과 없음 '삑'. 오디오 파일 사용 금지.
3. 파일 상단 EMBED_FAQ 상수에 자주 묻는 질문 15개를 심어두어(심기 모드 — 데이터 임베딩), 시트 없이도 앱이 완전히 동작하게 한다.
4. gviz/tq 연동 주소는 상수 SHEET로 분리하고, 응답 파싱은 '첫 {부터 마지막 }까지 잘라 JSON.parse' 방식으로 구현한다(JSONP 래핑 실측 대응).
5. 검색창에 키워드를 넣으면 질문·답변·분류에서 부분 일치 카드를 뽑아 표시하고, 분류별 필터 버튼을 함께 제공한다.
6. 시트의 양식링크 칸이 있으면 답변 카드에 '서식 내려받기' 버튼을 표시한다(원클릭 다운로드).
7. FAQ에 학생 실명·연락처·성적 등 개인정보를 담는 칸은 일절 만들지 않는다(학내망 개인정보 원칙).
8. 모바일 반응형: 학부모 스마트폰 360px에서 가로 스크롤 금지, 터치 영역 44px 이상.
9. // TODO, /* 생략 */ 같은 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. FAQ 분류는 무엇으로? (교외체험·건강·준비물·급식 / 우리 반 사정)
Q2. FAQ 갱신 담당은? (담임 직접 / 학급 자치 임원 정리)
Q3. 배포 위치는? (알림장 서비스 공지 상단 / 학급 홈페이지)

🎯 에디터 한줄평

3월 담임교사의 에너지는 30개 학부와의 '같은 질문 30번'에 쓰이다가 소진됩니다. FAQ 챗보드는 그 반복을 검색창 한 줄로 압축해, 담임의 에너지를 개별 학생에게 돌려줍니다. FAQ에 학생 개인정보를 절대 두지 않는 설계 경고까지 — 소통 도구의 안전장치가 먼저 세워진 글입니다.

📚 기술·교육 참고 링크

By 시간:
라벨: ,