생활기록부 점검프로그램(v1.3)

🤖 생기부 AI 기재요령 검증 시스템 (Student Record AI Inspector)

학교 현장의 선생님들을 위해, 미리 구축된 생활기록부 데이터베이스(record.db)를 바탕으로 교육부 기재 요령 위반 여부(금지어, 외부 기관명 등)를 AI가 자동으로 감사(Audit)하고, 그 결과를 엑셀 리포트 및 직관적인 GUI로 제공하는 Windows 데스크톱 애플리케이션입니다.

✨ 주요 기능

• 스마트 AI 검증 (Gemini API): 입력된 API 키를 바탕으로 사용 가능한 최신 모델(예: gemini-2.5-flash)을 실시간으로 불러오며, 강력한 텍스트 추론 능력을 통해 문맥 속 위반 사항을 정확히 짚어냅니다.
• 배치(Batch) 처리 최적화: 한 번에 검사할 과목 수를 1~5개로 조절할 수 있어 분석 속도 향상 및 API 비용 절감을 사용자가 직접 제어할 수 있습니다.
• 작업 제어 (Pause & Cancel): 수백 건의 대량 데이터 검사 중에도 언제든 안전하게 작업을 일시 정지(⏸️)하거나 취소(⏹️)할 수 있는 멀티스레딩 제어 환경을 제공합니다.
• 직관적인 대조 뷰어: 표의 행을 더블클릭하면 원본, 위반 의심 내용(Before), 수정 제안(After), 위반 사유를 한눈에 대조할 수 있는 상세 팝업창을 제공합니다.
• 실시간 지침 에디터: 툴 내부에서 바로 기재 유의사항(rules.txt)과 작업 프롬프트(task_prompt.txt)를 수정하고 즉각 반영할 수 있습니다.
• 스마트 엑셀 연동: 반별/개인별로 엑셀 파일을 분리하여 자동 저장(누적 이어쓰기 지원)하며, 기존에 작업했던 엑셀 파일을 다시 불러와 뷰어로 확인할 수도 있습니다.

🛠 기술 스택 (Tech Stack)

• Language: Python 3.12+
• Environment: uv (Fast Python package manager)
• AI Engine: Google Generative AI (gemini-2.5-flash 권장)
• Database: SQLite3
• GUI: CustomTkinter
• Data Processing: Pandas, Regex

 

 

⚙️ 시스템 아키텍처 (Data Flow)

1. Model (Data & AI):
   • db_manager가 record.db에서 검사 대상(반 전체 또는 개별 학생)의 데이터를 가져옵니다.
   • ai_validator가 데이터를 사용자가 지정한 Batch 크기(1~5)로 묶어 Gemini API로 전송하고, 반환된 JSON 텍스트를 파싱하여 구조화합니다.
2. View (GUI & Interaction):
   • 메인 스레드(GUI)가 멈추지 않도록 검사 작업은 Worker Thread로 분리됩니다.
   • 스레드 간 안전한 통신(threading.Event)을 통해 사용자의 일시중지/재개/취소 명령을 실시간으로 로직에 전달합니다.
3. Persistence (Save & Load):
   • 한 배치가 끝날 때마다 UI 표(Treeview)가 갱신되며, 모든 작업 완료 시 excel_manager를 통해 지정된 양식에 맞게 .xlsx 파일로 자동 저장(또는 병합)됩니다.

💡 트러블슈팅 (Troubleshooting)

• API 키 에러: 처음 실행 시 KeyError가 발생하지 않도록 코드가 방어적으로 작성되어 있습니다. 빈 화면에서 새 API 키를 입력하고 연결에 성공하면 자동으로 inspector_config.json이 생성됩니다.
• 엑셀 저장 권한 오류 (Permission Denied): 작업을 시작하기 전, 기존에 생성된 검토결과_...xlsx 파일이 켜져 있으면 파이썬이 파일을 덮어쓸 수 없습니다. 반드시 엑셀 창을 닫고[검사 시작]을 눌러주세요.

---

🔄 시스템 사용 흐름 (Workflow)

선생님들이 검증 작업을 수행할 때의 기본 시나리오입니다.

1. DB 불러오기: [📂 DB 연결 관리] 탭에서 이전에 완성해 둔 record.db를 불러옵니다. (한 번 불러오면 data/ 폴더에 복사되어 다음부터는 켜자마자 자동 로드됩니다.)
2. API 연결: Gemini API 키를 입력하고 [연결 & 모델로드]를 누릅니다. 성공 시 사용 가능한 모델 목록이 드롭다운에 뜹니다.
3. 검토 설정:
   • 반 전체 또는 개별 학생 모드를 선택합니다.
   • 배치(한 번에 처리할 과목 수)를 조절합니다. (권장: 3)
4. AI 검사 및 제어: [🚀 검사 시작] 버튼을 누르면 AI가 생기부를 읽고 8대 기재 금지 원칙(대학명, 상호명 등) 위반 여부를 검사합니다. 필요시 언제든 ⏸️ 일시중지 할 수 있습니다.
5. 결과 확인 및 엑셀 저장:
   • 검사가 완료되면 표에 결과가 출력되며, 검토결과_3학년_1반_전체.xlsx 형태로 자동 저장됩니다.
   • 표의 행을 더블클릭하면 왜 위반되었는지, 어떻게 고쳐야 하는지 상세 내용을 대조해 볼 수 있습니다.

---

💡 Tip (프롬프트/유의사항 수정): 교육부 지침이 변경되거나 AI가 너무 예민하게 반응할 경우, 좌측 사이드바의 [생기부 유의사항 수정] 또는 [작업 프롬프트 수정] 버튼을 눌러 즉시 규칙(rules.txt)을 업데이트하세요. 다음 검사부터 변경된 규칙이 즉각 반영됩니다.

 

 

자세한 내용은 첨부파일과 사용설명서를 확인해주시길 바랍니다.

 

https://docs.google.com/presentation/d/123Pi9RoCtq-IgMEAEqL_9kQ5sZIVBRR5Kd35rPcy14E/edit?usp=sharing

생활기록부 점검 프로그램 사용법(v1.3)

 

https://drive.google.com/file/d/1MwQfsJXElKOeH66VWKYTTnYEA1BL9kMY/view?usp=sharing

생기부_DB_생성기(v1.3).exe

 

https://drive.google.com/file/d/1PqDfsxqY5gi6k2_C4WoSyFysLoogOKfU/view?usp=sharing

생기부_AI_Inspector(v1.3).exe

 

 

 

※ 2026.5.24. 추가안내사항

학년이력 엑셀 데이터에서 '학과'가 있는 경우가 있습니다. 제가 근무하는 고등학교는 일반고등학교여서 학과가 따로 존재하지 않습니다. 따라서 '학과' 열을 삭제하시고 업로드 해 주시길 바랍니다.