2026년 9월 6일 일요일

[행정/연구] 교무학사 원스톱 FAQ 포털 - 신규·전입 교사의 첫 주를 검색으로



신규 교사의 첫 주 질문이 카테고리 검색으로 끝난다 — 교무학사 원스톱 FAQ 포털 완전 정복

🏢 3월 신규·전입 교사가 겪는 나이스 권한 신청, 공문서 기안 결재선, 법인카드 사용 지침, 특별실 예약 규칙 — 교무 행정 질문 수백 개를 카테고리별로 검색하고 관련 공문 서식을 즉시 내려받는 교무부 전용 FAQ 포털. 선임 교사에게 매번 묻는 부담이 사라지고 인수인계가 표준화됩니다.

지식 베이스는 gviz/tq(구글 시트를 데이터베이스처럼 쓰는 공식 주소) — 담당 부서가 시트에 Q&A를 계속 누적하면 포털이 실시간으로 두꺼워집니다. 심기 모드(데이터 임베딩) 폴백으로 인트라넷 오프라인에서도 작동합니다.

📖 한 줄 정의

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

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

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
교무 Q&A 지식 베이스 시트 칸 5개(질문·답변·카테고리·담당 부서·서식링크) — 담당 부서가 직접 갱신하는 살아있는 인수인계 문서. Q&A 시트 누적 시작.
카테고리+키워드 조합 카테고리 필터(나이스·서무·예산·안전)로 좁히고 키워드로 찾는 2단 검색 — '법인카드' 한 단어로 답변·담당·서식이 함께 나옵니다. searchFaq 함수.
담당 부서 표기 답변 카드에 '담당: 교무부'가 함께 표시 — 문의가 필요하면 어디로 가야 하는지까지 한눈에. 담당 칸 채우기.

2. 핵심 아키텍처 해설

① gviz/tq Q&A 읽기 (래핑 처리 포함)

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, dept: (r.c[3] || {}).v,
             link: (r.c[4] || {}).v };
  });
}

② 카테고리+키워드 2단 검색

function searchFaq(word, cat, list) {
  return list.filter(function (f) {
    const hitWord = (f.q + " " + f.a).indexOf(word) > -1;
    const hitCat = cat === "전체" || f.cat === cat;
    return hitWord && hitCat;
  });
}

먼저 카테고리로 좁히고 키워드로 찾는 2단 구조 — 수백 개 Q&A에서도 정확한 답이 1초에 나옵니다.

③ 답변 카드(담당·서식 포함)

function answerCard(f) {
  // 질문 제목 + 답변 본문 + 담당 부서 표시 + 
  if (f.link) showDownload(f.link);   // 서식 내려받기
}

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

const EMBED_FAQ = [
  { q: "나이스 권한 신청은 어떻게?", a: "서무부 양식 작성 후 교감 결재",
    cat: "나이스", dept: "서무부", link: "https://..." }
];

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

인트라넷이 외부와 닫혀 있어도 포털이 멈추지 않습니다 — 학내망 원칙 정합 설계.

⑤ 원칙·정합

Q&A에는 학생 개인정보·급여·인사 등 민감 정보 일절 금지(운영 지식만). 배포는 교내 메신저·인트라넷 바로가기(학내망 경로) — 외부 공개 대신 내부 전용으로 운영.

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

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — Gemini의 질문 3가지(카테고리 체계, 갱신 담당, 배포 위치)에 답하면 설계가 확정됩니다.
  3. HTML 파일 실행 — 완성 코드를 '교무FAQ.html'로 저장 후 더블클릭 — 교내 메신저 바로가기로 등록하면 신규 교사 온보딩이 시작됩니다.

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

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

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 카테고리 체계는? (나이스·서무·예산·안전 / 우리 학교 조직 기준)
Q2. Q&A 갱신 담당은? (교무부 직접 / 부서별 분담)
Q3. 배포 위치는? (교내 메신저 / 인트라넷 바로가기)

🎯 에디터 한줄평

인수인계가 '사람에게만' 있으면 학교는 매년 3월마다 리셋됩니다. 이 포털은 교무 지식을 '누구나 검색하는 문서'로 바꿔, 신규 교사의 첫 주를 혼란이 아닌 탐색으로 바꿉니다. 답변마다 담당 부서가 붙어 있어 '물어볼 곳'까지 한눈에 보이는 설계 — 학교의 운영 지식이 자산이 되는 순간입니다.

📚 기술·교육 참고 링크

By 시간:
라벨: ,