새김 · AI 생기부 도우미

관찰 기록과 키워드만 넣으면 학교생활기록부 초안을 만들고, 기재요령 위반을 검사해 주는 교사용 웹사이트입니다. 화면은 정적 페이지(public/), AI 호출은 Vercel 서버 함수(api/)가 맡습니다. Claude API 키는 서버 환경변수에만 있고 브라우저로 내려가지 않습니다.

기능

메뉴	내용
홈	서비스 소개, 기능 안내, 개인정보 원칙, 자주 묻는 질문
AI 생기부 생성 · 단일	행동특성, 교과세특, 자율·자치, 동아리, 진로, 비슷한 문장. 키워드 칩(5개 분류, 강점/보완), 성취기준·성취수준, 목표 바이트 슬라이더, 빠른 모드, 결과 수정 시 바이트 재계산, 목표 초과 시 자동으로 한 번 줄이기
AI 생기부 생성 · 다중	엑셀(.xlsx)·CSV 업로드 → 학생별 일괄 생성(3명씩 동시) → 표에서 수정 → 엑셀로 받기. 양식 파일 제공
AI 생기부 검사기	학교급·학년도·학년·영역 선택, 단일/다중 검사. 규칙 검사(대학명, 대회·수상, 상호명, 영문, 비교·과장, 반복, 부모 정보, 교외 활동, 종결 어미)는 즉시, AI 검토(맞춤법·문맥)는 이어서. 문제 구간 표시, 항목별 이유·근거·수정 제안, AI 수정본
내 생기부 기록	저장한 문장 검색·필터, 복사, 검사기로 보내기, 엑셀로 받기 (브라우저에 저장)
내 스타일	예시 문장 3개를 등록하면 그 문체를 따라 작성
AI 채팅	교사 업무 질문용 채팅
설정	학교급, 빠른 모드, 접속 비밀번호, 학생 명단(가림용), 추가로 가릴 단어, 가림 테스트

학생 개인정보 원칙

• AI 요청에는 생기부 재료만 들어갑니다. 서버 API에는 이름·번호·학년·반을 받는 칸이 아예 없습니다.
• "학생 표시"와 다중 생성의 이름 열은 결과를 맞추는 데만 쓰고 전송하지 않습니다. 번호·학년·반·연락처 열은 자동으로 빠집니다.
• 설정에 등록한 학생 명단의 이름이 입력란에 섞여 있으면 브라우저에서 "학생"으로 바꾼 뒤 보냅니다. 명단 자체는 서버로 가지 않습니다.
• 연락처, 이메일, 주민번호, "2학년 3반 5번" 같은 패턴은 브라우저와 서버에서 두 번 가립니다.
• 생성 화면의 보낼 내용 미리보기와 AI로 보낸 내용 보기로 실제 전송된 글을 확인할 수 있습니다.
• 기록·스타일·명단·채팅은 브라우저(localStorage)에만 저장되고, 서버는 요청 내용을 저장하거나 로그로 남기지 않습니다.
• 한계: 명단에 없는 이름(전학생, 별명 등)은 자동으로 잡지 못합니다. 설정의 "추가로 가릴 단어"에 넣어 주세요.

배포하기 (Vercel, 약 10분)

1. vercel.com에 GitHub 계정으로 가입합니다.

2. Add New → Project에서 이 저장소(kang-teacher/daehyun)를 Import 합니다. Framework Preset은 Other 그대로 둡니다.

3. Environment Variables에 아래 값을 넣습니다.

   이름	값	필수
   ANTHROPIC_API_KEY	Claude 콘솔에서 만든 API 키	예
   APP_PASSWORD	사이트 접속 비밀번호. 넣으면 비밀번호를 아는 사람만 AI를 쓸 수 있음	강력 권장
   MODEL	기본 모델. 비우면 claude-opus-5-5	아니요
   FAST_MODEL	빠른 모드 모델. 비우면 claude-haiku-5-5	아니요
   EFFORT / FAST_EFFORT	low / medium / high. 비우면 medium / low	아니요

4. Deploy를 누르면 https://프로젝트이름.vercel.app 주소가 생깁니다.

5. 사이트의 설정 메뉴에서 접속 비밀번호를 입력하고 연결 확인을 누릅니다.

APP_PASSWORD 없이 배포하면 주소를 아는 누구나 선생님의 API 키로 AI를 호출할 수 있습니다. 꼭 설정하세요. 저장소에 새 커밋을 푸시하면 Vercel이 자동으로 다시 배포합니다.

내 컴퓨터에서 실행하기

Node.js 20 이상이 필요합니다.

npm install
npm run dev:mock                          # 가짜 응답으로 화면만 확인 (API 키 불필요)
ANTHROPIC_API_KEY=sk-ant-... npm run dev  # 실제 Claude 호출
npm test                                  # 바이트 계산·개인정보 가림·규칙 검사 테스트

브라우저에서 http://localhost:3000 을 엽니다.

폴더 구조

public/            화면 (정적 파일)
  index.html
  css/style.css
  js/app.js        화면 로직 (라우팅, 생성, 다중 생성, 검사기, 채팅, 기록, 설정)
  js/core.js       나이스 바이트 계산, 개인정보 가림, 기재요령 규칙 검사 (서버와 공유)
  js/data.js       키워드, 종류, FAQ
api/
  ai.js            POST /api/ai  생성·비슷한 문장·검사·채팅
  config.js        GET  /api/config  서버 상태 (키 값은 내보내지 않음)
lib/
  claude.js        Claude API 호출 (Anthropic SDK)
  prompts.js       프롬프트와 출력 스키마
  http.js          접속 비밀번호 확인, JSON 응답
dev-server.js      로컬 실행용 서버

참고

• 바이트는 나이스 기준(한글 3, 영문·숫자·공백 1, 줄바꿈 2)으로 계산합니다. 처음에 나이스에 몇 문장을 붙여 넣어 숫자가 맞는지 확인해 주세요.
• 종류별 기본 목표 바이트는 행특·세특·자율·동아리 1500, 진로 2100입니다. 그해 기재요령에 맞게 화면에서 조정하세요.
• 검사기의 근거는 기재요령 일반 원칙을 요약한 것입니다. 해마다 바뀌는 세부 기준은 그해 교육부 기재요령으로 최종 확인하세요.
• AI 결과는 초안입니다. 최종 기재 책임은 교사에게 있습니다.