아르봇(ARBOT) - 웹앱

**아르봇(ARBOT, ARgument chatBOT)**은 중·고등학생 대상 과학탐구 논증(Toulmin) 수업을 지원하는 AI 챗봇입니다. 구글 스프레드시트 + Apps Script(GAS)가 백엔드이고, 이 저장소는 그 백엔드를 호출하는 정적 프론트엔드입니다. 서버가 따로 학생 데이터나 API 키를 저장하지 않으므로, 여러 선생님이 이 프론트엔드 하나를 공유해서 써도 각자의 데이터는 각자의 스프레드시트에만 남습니다.

왜 이런 구조인가

• 프론트엔드(이 저장소)는 한 번만 배포하면 모든 선생님이 그대로 씁니다. Google Cloud 서비스 계정이나 API 인증 설정이 필요 없습니다.
• 각 선생님은 자기 스프레드시트에서 배포 → 웹 앱을 눌러 GAS 웹 앱 URL을 발급받고, 그 URL을 교사 콘솔에 한 번 입력하면 끝입니다.
• 학생에게 나눠주는 접속 링크에는 ?gas=... 형태로 그 선생님의 GAS 주소가 담겨 있어서, 학생은 링크(또는 QR)를 열고 선생님이 알려 준 수업 입장 코드만 입력하면 자기 반 스프레드시트에 연결됩니다.

학생 브라우저  ──POST──▶  선생님의 GAS 웹 앱 (Apps Script, 선생님마다 각자)
      ▲
      │ 정적 프론트엔드 (이 저장소, 모두가 공유하는 배포 1개)
      │ 브라우저 localStorage에 "이 기기가 어느 GAS와 연결되어 있는지" 저장

폴더 구조

• gas-source/ — 스프레드시트에 붙는 Apps Script 코드 원본 (clasp으로 관리). Code.js가 백엔드 로직 + JSON API, Templates.js가 페르소나·루브릭 템플릿 원본, Guide.html이 시트 메뉴 📖 사용 가이드 창(시트 구조·사용법 안내).
• public/ — 정적 프론트엔드
  • index.html — 교사 관리 콘솔 (사이트 첫 화면): 1 GAS 연동 → 2 기본 설정 → 3 주제 설정 → 4 학생 배부 링크·QR(+수업 입장 코드) → 5 대화 결과 확인·분석
  • student.html — 학생 화면: 수업 입장 코드 → 학급·모둠·주제 선택 → AI 튜터와 대화
  • js/gasClient.js — GAS 웹 앱과 통신하는 공통 모듈, js/argu-shared.js — 캐릭터·논증 단계 등 공통 부품, js/qrcode.js — QR 생성(MIT, 외부 CDN 없이 내장), js/credit-footer.js — 두 화면 아래의 제작자 크레딧 푸터와 안내 모달, js/pick-logic.js — 결과 분석의 학급 → 주제 → 모둠 단추 선택 규칙(화면 없이 시험 가능), js/material-samples.js — 탐구 주제 예시와 주제별 탐구 자료 예시(예시 채우기)
  • css/ — 공통 토큰, 교사 콘솔, 학생 화면 스타일
• server.js — public/을 서빙하는 아주 얇은 Express 정적 서버 (어떤 정적 호스팅에 올려도 무방)
• tests/ — 자동 테스트와 가짜 GAS 서버 (npm test)

1. 스프레드시트 준비 (선생님이 하는 일)

1. 아르봇(ARBOT) 스프레드시트를 파일 → 사본 만들기로 내 드라이브에 복사합니다 (Apps Script 코드가 이미 들어 있습니다).
2. 환경설정 탭 B1에 Gemini API 키를 입력합니다 (aistudio.google.com에서 발급). 교사 콘솔에서도 입력·변경할 수 있습니다.
3. 스프레드시트 상단 메뉴 🗣️ 아르봇(ARBOT) → 🔐 교사 비밀번호 설정에서 **교사 비밀번호(8자 이상)**를 정합니다. 비밀번호를 정하기 전에는 교사 콘솔의 설정·분석 메뉴가 열리지 않습니다. 이때 수업 입장 코드가 자동으로 만들어져 안내창에 보입니다.
4. 스프레드시트 상단 메뉴 확장 프로그램 → Apps Script → 우측 상단 배포 → 새 배포 → 유형 "웹 앱" 선택 → 액세스 권한을 "모든 사용자"로 설정 → 배포. (학생이 구글 로그인 없이 쓰려면 필요한 설정입니다. 보호는 비밀번호와 입장 코드가 맡습니다.)
5. 발급된 URL(https://script.google.com/macros/s/.../exec)을 복사해 둡니다.

학급·모둠·금지어는 교사 콘솔의 기본 설정에서, 탐구 주제 목록·주제별 페르소나/루브릭 연결·탐구 자료는 주제 설정에서 입력합니다. (처음 실행하면 페르소나 세부설정, 루브릭 세부설정, 주제 세부설정 탭이 시트에 자동으로 만들어지고 템플릿 5종이 들어갑니다. 탐구 주제 목록에 저장한 주제는 주제 세부설정 탭에 한 줄씩 자동으로 만들어지고, 비워 둔 칸은 기본 줄을 따릅니다. 시트에서 목록을 직접 고쳤다면 시트 메뉴 🔄 주제 세부설정 맞추기를 누르세요.)

⚠️ 코드를 나중에 수정하면 배포 → 배포 관리 → 연필 아이콘 → 새 버전으로 다시 배포해야 반영됩니다. (clasp을 쓰면 clasp push --force 후 clasp deploy -i <배포 ID>)

2. 교사 콘솔에서 수업 준비하기

1. 콘솔(/)에서 1 GAS 연동: 위에서 발급받은 URL 입력 → 연결 테스트 → 교사 비밀번호 입력. (비밀번호를 아직 안 정했다면 안내 카드가 먼저 나옵니다.)
2. 2 기본 설정, 3 주제 설정에서 학급·주제·페르소나·평가 루브릭 등을 정합니다.
3. 4 학생 배부 링크 & QR에서 링크/QR과 수업 입장 코드를 학생들에게 알려 줍니다. 교실 TV·인쇄 화면에는 QR과 코드가 함께 나옵니다. 반 밖으로 링크가 퍼졌거나 새 수업을 시작할 때는 새 코드 만들기를 누르면 이전 코드는 바로 쓸 수 없게 됩니다.
4. 수업 뒤 5 대화 결과 확인 & 분석에서 학급 → 탐구 주제 → 모둠 → 날짜 단추를 차례로 눌러(대화 기록이 없는 모둠은 "기록 없음"으로 표시되어 눌리지 않고, 같은 주제를 여러 날 했다면 날짜별로 따로 분석할 수 있어요) 분석 → 필요하면 HTML 보고서·CSV로 내려받습니다.

연동 정보(GAS URL)는 이 브라우저에만 저장됩니다. 교사 비밀번호는 이 브라우저 탭에 입력하는 동안만 임시로 남습니다.

3. 로컬에서 실행해보기

npm install
npm start          # http://localhost:3000  (교사 콘솔) / http://localhost:3000/student.html (학생 화면)
npm test           # 문법 검사 + 자동 테스트 전체 (실제 시트·Gemini를 건드리지 않음)

실제 시트 없이 화면을 눌러 보려면 node tests/fake_gas_server.js 를 실행하고 http://localhost:3101/ 을 여세요. 시험용 비밀번호와 코드는 tests/fake_gas_server.js 맨 위에 있습니다. 자세한 방법은 CLAUDE.md의 Commands를 보세요.

4. 배포하기

현재 배포 구성: 이 저장소(mrdoolee/arbot-project)의 main에 푸시하면 Vercel 프로젝트 arbot-trdoolee가 public/을 자동으로 프로덕션에 배포합니다(주소: https://arbot-trdoolee.vercel.app). 설정은 vercel.json에 있고(출력 폴더 public, 아래 보안 헤더 4종, /teacher.html → / 리다이렉트), Vercel 프로젝트의 프레임워크는 Other여야 합니다(package.json·server.js를 보고 Express로 자동 감지되면 정적 사이트가 깨집니다). 이 주소는 학생에게 나눠 준 링크·QR에 들어 있으니 프로젝트 이름이나 도메인을 바꾸지 마세요. Vercel 로그인 보호(Vercel Authentication)는 프리뷰 배포에만 걸려 있어 프로덕션 주소는 학생이 그대로 열 수 있습니다. 이 저장소는 공개이니 API 키·.env·.clasprc.json은 절대 커밋하지 마세요(테스트용 값은 모두 가짜입니다).

다른 곳에 올린다면 public/을 서빙할 수 있는 곳이면 어디든 됩니다 — Vercel, Netlify, GitHub Pages, Render 무엇이든 가능합니다. 딱 한 번만 배포해두면 모든 선생님이 같은 주소를 함께 씁니다. 다음 헤더를 걸 수 있다면 같이 걸어 주세요(server.js가 하는 일과 같습니다): X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: frame-ancestors 'none', Referrer-Policy: no-referrer. 각 페이지의 연결 제한(CSP)은 HTML 안의 <meta>에 들어 있습니다.

5. GAS 쪽 JSON API (참고용)

모든 호출은 POST이고 본문은 Content-Type: text/plain의 JSON 문자열입니다(CORS 프리플라이트를 피하려는 것). GET은 상태 한 줄만 돌려줍니다. 주소창에 비밀번호·코드가 남지 않게 하려는 설계입니다.

구분	action	필요한 것	설명
공개	testConnection	(비밀번호)	연결 확인. 시트 이름·주소는 비밀번호가 맞을 때만
학생 입구	getInitialData	accessCode	학급/모둠/주제 목록과 주제별 캐릭터·제한 시간
학생 입구	processChatMessage	accessCode	학생 메시지 처리 (입력 검증, 금지어 차단, Gemini 호출, 기록 저장)
교사	teacherAnalyze 외 설정·분석·키·코드 관련	pin	설정 읽기/쓰기, 분석, API 키, 수업 입장 코드 등

6. 보안 요약

• 교사 비밀번호는 필수입니다(최초 설정은 시트 메뉴에서만). 학생 링크에 들어 있는 GAS 주소만으로는 API 키·학생 대화에 접근할 수 없습니다.
• 수업 입장 코드가 없으면 학급·모둠 목록도, 대화방도 열리지 않습니다. 코드를 바꾸면 이미 퍼진 링크도 무효가 됩니다.
• API 키는 화면으로 원문이 내려오지 않고(AIza••••1234) Gemini에는 주소가 아니라 헤더로 보냅니다. 키는 스프레드시트 환경설정 B1과 API키 탭에 평문으로 있으니 스프레드시트를 공유하지 마세요.
• 학생 글·AI 응답은 화면에 코드가 아닌 글자로만 표시되고, 시트에도 수식으로 실행되지 않게 저장됩니다.
• Gemini 무료 키는 입력 내용이 구글 서비스 개선에 쓰일 수 있다는 약관이 있습니다(약관은 바뀔 수 있으니 확인). 학생에게 이름·전화번호를 쓰지 않도록 안내하고, 학기 말에는 채팅기록을 백업한 뒤 비우세요.
• 링크는 선생님이 직접 배부하세요. ?gas= 주소는 script.google.com/…/exec 형식만 확인할 수 있어서, 남이 만든 링크가 다른 스크립트로 연결될 수 있습니다.