프로젝트 개요
MVP 이후 대표·상담실장·강사가 쓰게 될 운영 콘솔 확장 프로젝트입니다. 접수 관리, 진단서와 반 배정, 출석부와 숙제 배포, AI 파이프라인 처리 이력과 재처리, 학부모 리포트 승인과 알림톡 발송 이력을 한 콘솔에서 다루며 역할별로 보이는 메뉴와 개인정보 범위가 달라지는 구조를 제안합니다.
작업 범위
- 접수·진단서·반 배정: 상담실장이 첫 화면에서 오늘 연락할 신청의 상태를 바꾸고, 응시를 마친 학생의 자동채점 결과와 진단서를 확인합니다. 대표는 제공 기준에 따른 권장 반을 최종 확정하고 진단서를 웹으로 열람하거나 출력합니다
- 숙제·출석: 강사가 반별 출석부에서 출결을 입력하고 해당 회차 커리큘럼을 확인합니다. 진단 기반 보충 숙제를 확인한 뒤 학생별·반별로 배포하고 제출 현황을 봅니다
- AI 파이프라인 이력: 운영자가 진단서·피드백·숙제·리포트를 만드는 AI 파이프라인의 요청 상태와 처리 결과, 오류 이력을 확인하고 실패 건을 재처리합니다. 룰·프롬프트·템플릿 버전도 이 화면에서 관리합니다
- 리포트 승인·발송 이력: 상담실장이 주 2회 생성된 학부모 리포트 초안을 확인·수정하고 승인합니다. 승인한 리포트는 카카오 알림톡으로 발송되며 발송 성공·실패 이력을 보고 실패 건을 재발송합니다
주요 업무
- 접수·진단서·반 배정 화면: 처리할 일 카드, 신청 목록과 상태 필터, 신청 상세 대화상자, 진단서 상세와 출력 미리보기, 권장 반 확정 대화상자, 반 정원과 수업 요일 표 구조를 설계합니다
- 숙제·출석 화면: 반별 출석부, 회차 커리큘럼 표시, 보충 숙제 연결 목록, 배포 확인 대화상자, 제출·미제출·완료 현황 표, 오답 피드백 초안 확인 구조를 설계합니다
- AI 파이프라인 이력 화면: 요청 목록과 상태 필터, 처리 결과·오류 상세, 재처리 확인 대화상자, 룰·프롬프트·템플릿 버전 표, 개인정보 제외 호출 확인 표시 구조를 설계합니다
- 리포트 승인·발송 이력 화면: 생성 일정 표, 리포트 초안 편집 화면, 승인 확인 대화상자, 발송 이력 표와 실패 사유, 재발송 처리, 역할별 접근 제한 안내 구조를 설계합니다



프로젝트 핵심 과제
파이프라인이 여러 개로 나뉘어 입출력 규격이 바뀔 수
요청·응답 버전 필드와 어댑터 계층 설계 필요
학생·문항·응답·생성 결과가 재처리 중에도 어긋나지 않
멱등 키와 식별자 연결 설계 필요
담당자별 개인정보 접근 범위가 학원 정책에 따라 달라질 수
설정 가능한 권한 구조 설계 필요
알림톡 템플릿 심사 결과에 따라 문구 변수가 바뀔 수
템플릿 버전 관리와 발송 이력 연결 설계 필요
주 2회 리포트 생성 일정과 승인 대기 건이 쌓일 때 담당자 확인 순서를 정하는 대기열 설계
핵심 기능 상세
접수·진단서·반 배정
상담실장이 첫 화면에서 오늘 연락할 신청의 상태를 바꾸고, 응시를 마친 학생의 자동채점 결과와 진단서를 확인합니다. 대표는 제공 기준에 따른 권장 반을 최종 확정하고 진단서를 웹으로 열람하거나 출력합니다.
- 상담 기록·레벨테스트 응답·채점 결과를 학생 ID 기준 통합 이력 화면으로 연결하는 조회 쿼리 설계
- 권장 반 계산 결과와 대표 확정값을 별도 컬럼으로 저장해 변경 사유를 이력으로 보관
- 반 정원과 수업 요일 충돌을 배정 시점에 서버에서 검증
신청부터 채점 결과·진단서·반 확정까지 한 학생의 기록을 식별자 하나로 연결하고, 권장 반과 확정 반을 분리 저장해 기준이 바뀌어도 확정 이력이 남도록 구현합니다.


숙제·출석
강사가 반별 출석부에서 출결을 입력하고 해당 회차 커리큘럼을 확인합니다. 진단 기반 보충 숙제를 확인한 뒤 학생별·반별로 배포하고 제출 현황을 봅니다.
- 반·회차 단위로 출결을 일괄 저장하고 결석 사유와 보강 여부를 함께 기록하는 스키마 구성
- 진단 결과에 연결된 보충 숙제를 강사 확인 후 학생별로 배포하는 승인 단계 구현
- 숙제 제출 현황을 반별 집계 쿼리로 구성해 미제출 학생을 바로 걸러 보도록 설계
AI가 만든 보충 숙제와 오답 피드백을 강사 확인 단계 뒤에만 배포하도록 상태로 제어해, 확인되지 않은 내용이 학생에게 나가지 않도록 구현합니다.


AI 파이프라인 이력
운영자가 진단서·피드백·숙제·리포트를 만드는 AI 파이프라인의 요청 상태와 처리 결과, 오류 이력을 확인하고 실패 건을 재처리합니다. 룰·프롬프트·템플릿 버전도 이 화면에서 관리합니다.
- 파이프라인 요청을 큐 테이블로 관리하고 상태(대기·진행·성공·실패)와 시도 횟수를 기록
- AI 호출 전 학생 이름·연락처·학교명을 제외하고 학생 ID만 담은 요청 본문을 서버에서 생성
- 실패 건 재처리를 멱등 키로 구분해 같은 요청이 중복 저장되지 않도록 구성
요청·응답·생성 결과를 학생 ID와 요청 ID로 연결하고 재처리를 멱등 키로 제어해, 데이터가 꼬이지 않는 파이프라인 연동 구조로 구현합니다.


리포트 승인·발송 이력
상담실장이 주 2회 생성된 학부모 리포트 초안을 확인·수정하고 승인합니다. 승인한 리포트는 카카오 알림톡으로 발송되며 발송 성공·실패 이력을 보고 실패 건을 재발송합니다.
- 리포트 상태를 초안·수정·승인·발송으로 정의하고 승인된 건만 발송 큐에 적재
- 알림톡 발송 결과 수신 값을 발송 이력 테이블에 저장하고 실패 사유별로 분류
- 역할 기반 접근 제어를 라우트·API·화면 요소 3단계로 적용해 담당자별 개인정보 범위 제한
승인된 리포트만 발송 큐에 들어가도록 상태 전이를 서버에서 제한하고, 발송 결과를 이력으로 남겨 실패 건을 재발송으로 이어지게 구현합니다.


프로젝트 진행 단계
역할 권한 체계와 통합 이력 데이터 설계 · 2026.11
대표·상담실장·강사 접근 범위, 학생 통합 이력, 요청·응답 식별자 테이블 정의
접수·반 배정·출결 API 구현 · 2026.11
신청 상태 전이, 권장 반 확정, 반 정원 검증, 출결 일괄 저장 API 구현
파이프라인 연동 API와 재처리 큐 구현 · 2026.11
개인정보 제외 요청 생성, 결과 수신·저장, 멱등 키 기반 재처리 큐와 오류 이력 구현
리포트 승인·알림톡 발송과 콘솔 화면 구현 · 2026.11
초안 편집·승인 상태 전이, 발송 큐·이력·재발송과 역할별 콘솔 화면, Docker 실행 환경 구성
개발 결과
기술적 주안점
- 신청부터 채점 결과·진단서·반 확정까지 한 학생의 기록을 식별자 하나로 연결하고, 권장 반과 확정 반을 분리 저장해 기준이 바뀌어도 확정 이력이 남도록 구현합니다
- AI가 만든 보충 숙제와 오답 피드백을 강사 확인 단계 뒤에만 배포하도록 상태로 제어해, 확인되지 않은 내용이 학생에게 나가지 않도록 구현합니다
- 요청·응답·생성 결과를 학생 ID와 요청 ID로 연결하고 재처리를 멱등 키로 제어해, 데이터가 꼬이지 않는 파이프라인 연동 구조로 구현합니다