운영관리자 역할

• 운영관리자는 학교에서 송부한 검사지 또는 스캔 파일을 수집하고 판독 흐름을 관리합니다.
• 학교담당자는 학생 등록, 검사지 출력, 검사지 회수/송부, 결과 조회 중심으로 사용합니다.
• 운영관리자는 스캔 수집, QR/기준점 확인, AI 판독, 비교/검수, 공식 결과 반영을 담당합니다.

전체 업무 흐름

1. 프로젝트/학교 확인: 학교, 담당자, 학생 수, 설정을 확인합니다.
2. 검사지 수령 또는 스캔 파일 확보: 학교에서 회수한 원본 또는 스캔 파일을 준비합니다.
3. 스캔 수집: 운영기관에서 스캔 이미지를 업로드합니다.
4. QR / 기준점 / 정규화 확인: 학생, 페이지, A4 보정 상태를 확인합니다.
5. 판독 대기 상태 확인: AI 판독 준비 완료 학생과 차단 사유를 구분합니다.
6. AI 판독 실행: Mock, Dual Mock, Real AI를 목적에 맞게 선택합니다.
7. GPT/Gemini 결과 비교: 두 provider 결과의 일치와 불일치를 확인합니다.
8. 사람 검수: 불일치 또는 불확실 문항의 최종값을 선택합니다.
9. 최종 판독값 확정: 모든 검수 항목을 해결한 뒤 확정합니다.
10. 공식 결과 반영: 최종 판독값을 결과 검색에 사용할 공식 결과로 반영합니다.
11. 결과 조회/출력: 공식 결과를 확인하고 필요한 결과지를 출력합니다.

메뉴별 도움말

대시보드

• 전체 프로젝트와 학교별 진행 상태를 요약합니다.
• 스캔 대기, 판독 준비, AI 판독 중, 검수 필요, 반영 대기, 결과 완료를 확인합니다.
• 다음 작업 카드에서 지금 먼저 처리해야 할 일을 확인합니다.

프로젝트 관리

• 프로젝트, 학교, 학교담당자, 학생 수, 설정을 확인합니다.
• 학교담당자 수기입력 허용 ON/OFF를 여기서 관리합니다.
• 수기입력 ON은 소규모 학교가 직접 답안을 입력할 때만 사용합니다. 기본값은 OFF가 안전합니다.

스캔 수집

• 협회 또는 운영기관에서 스캔한 검사지 이미지를 업로드합니다.
• 학교담당자 기본 화면에서는 스캔 업로드를 맡지 않습니다.
• 업로드 후 QR, 기준점, 페이지 연결 상태를 확인합니다.
• 잘못 올린 파일은 AI 판독 전에 제외할 수 있습니다.

판독 대기

• AI 판독에 들어갈 준비가 된 학생과 막힌 학생을 확인합니다.
• 정상 조건은 QR 판독 성공, 기준점 인식 성공, A4 정규화 완료, page 1 / page 2 모두 존재, 중복·누락·혼합 출력본 문제 없음, AI 판독 이미지 정상 생성입니다.
• 막히는 조건은 QR 판독 실패, 기준점 인식 실패, page 누락, 중복 업로드, 혼합 출력본, crop/AI 이미지 품질 문제입니다.
• 1쪽/2쪽 미리보기로 AI에게 전달될 이미지를 반드시 확인할 수 있습니다.

AI 판독

• Mock AI는 가짜 판독으로 workflow 테스트용입니다.
• Dual Mock AI는 mock_gpt와 mock_gemini 결과를 만들어 비교 흐름을 테스트합니다.
• Real AI는 실제 GPT/Gemini 호출입니다.
• Real AI는 환경변수와 dry-run gate가 설정된 경우에만 사용합니다.
• 실제 호출 전에는 crop 미리보기에서 개인정보가 제거되었는지 확인해야 합니다.
• 실제 AI 호출은 비용과 quota가 발생할 수 있으므로 운영관리자가 신중히 실행합니다.

비교/검수

• GPT와 Gemini 결과가 모두 유효하면 비교가 생성됩니다.
• 두 AI가 같은 답을 낸 문항은 자동으로 통과할 수 있습니다.
• 불일치 또는 불확실 항목은 사람 검수로 이동합니다.
• 검수자는 문항번호, GPT 값, Gemini 값, 경고/불확실성을 보고 최종값을 선택합니다.
• 모든 검수 항목을 해결해야 최종 판독값을 확정할 수 있습니다.

공식 결과

• 최종 판독값을 공식 결과로 반영합니다.
• 공식 결과로 반영된 뒤 결과 검색에서 확인할 수 있습니다.
• 이미 반영된 결과는 중복 생성되지 않도록 주의해야 합니다.
• 결과 source는 dual_real_ai, dual_mock_ai, school_manual_entry처럼 구분될 수 있습니다.

진단/설정

• QR 브라우저 진단, 기준점/정규화 진단, crop 미리보기 문제 확인, AI provider 환경변수 present/missing 확인을 다룹니다.
• 고급 진단은 기본적으로 접혀 있어야 합니다.
• API key 값은 절대 화면에 출력하지 않습니다.

주요 상태 용어

QR 판독 성공

검사지의 QR을 읽어 학생/페이지 식별 정보를 확인했습니다.

기준점 인식 성공

네 모서리 기준점을 찾아 A4 정규화 준비가 되었습니다.

정규화 완료

스캔 이미지를 표준 A4 좌표계로 보정했습니다.

인식 완료

QR, 기준점, 페이지 연결이 정상입니다.

판독 준비 완료

AI 판독에 필요한 page 1/page 2 이미지가 준비되었습니다.

중복 업로드 해결 필요

같은 학생의 같은 페이지가 여러 장 올라왔습니다.

혼합 출력본 확인 필요

같은 학생의 1쪽과 2쪽이 서로 다른 출력본일 수 있습니다.

page 누락

1쪽 또는 2쪽이 없습니다.

검수 필요

AI 결과가 불일치하거나 불확실해 사람이 확인해야 합니다.

최종 판독값

사람 검수까지 반영한 최종 답안입니다.

공식 결과

결과 검색과 결과지 출력에 사용되는 확정 결과입니다.

오류별 조치

QR 판독 실패

• 다시 스캔하거나 전체 페이지가 선명하게 보이는지 확인합니다.
• QR이 잘렸거나 흐리면 자동 식별이 어렵습니다.
• QR 실패라도 기준점과 응답코드 기반 fallback은 향후 보완 대상입니다.

기준점 인식 실패

• 네 모서리의 검은 기준점이 모두 보이는지 확인합니다.
• 페이지가 잘렸거나 너무 기울어졌으면 다시 스캔합니다.
• 배경 그래픽을 꺼도 기준점은 SVG 전경 요소라 출력되어야 합니다.

중복 업로드

• 같은 학생의 같은 pageNo가 여러 장 올라온 상태입니다.
• 사용할 페이지를 선택하거나 잘못 올린 페이지를 제외해야 합니다.
• 해결 전에는 AI 판독 대상에 포함되지 않습니다.

page 누락

• 1쪽 또는 2쪽이 빠졌습니다. 누락 페이지를 다시 업로드해야 합니다.

혼합 출력본

• 같은 학생의 1쪽과 2쪽이 서로 다른 출력본일 수 있으므로 운영관리자가 확인 후 사용할 페이지를 결정해야 합니다.

crop 이미지 없음

• crop record는 있으나 이미지 파일이 없을 수 있습니다. crop 재생성 또는 스캔 재업로드가 필요합니다.

Real AI 실패

• GPT/Gemini provider 오류를 확인합니다.
• Gemini 429는 quota/rate limit 문제일 수 있습니다.
• API key 값은 절대 표시하지 않습니다.
• 한 provider만 성공한 경우 comparison은 완성되지 않을 수 있습니다.

개인정보 및 보안

• AI에게 보내는 이미지는 학교, 이름, 성별, 생년월일, 학생정보 영역을 포함하면 안 됩니다.
• AI crop 또는 AI input preview에서 개인정보가 보이면 AI 판독을 실행하지 않습니다.
• API key는 환경변수로만 관리합니다.
• API key를 코드, DB, GitHub, 로그, 스크린샷에 남기지 않습니다.
• server-data/db.json은 로컬 테스트 데이터가 들어갈 수 있으므로 Git 커밋에 포함하지 않습니다.

실제 운영 체크리스트

스캔 전

• 검사지가 최신 양식인지 확인합니다.
• QR과 네 모서리 기준점이 출력되었는지 확인합니다.
• 페이지가 1쪽/2쪽 모두 있는지 확인합니다.

스캔 후

• 전체 페이지가 잘리지 않았는지 확인합니다.
• QR / 기준점 / 정규화 상태를 확인합니다.
• 누락/중복/혼합 출력본을 확인합니다.

AI 전

• 판독 대기에서 AI 준비 완료 학생만 선택합니다.
• crop preview를 확인합니다.
• 개인정보가 crop에 없는지 확인합니다.

AI 후

• GPT/Gemini 비교를 확인합니다.
• 검수 필요 문항을 해결합니다.
• 최종 판독값 확정 후 공식 결과에 반영하고 결과 검색에서 확인합니다.