프로젝트 기획서

studentanalysis — 생기부 AI 분석 · 상담 서비스 기획서

교사가 학생 생기부를 입력하면 AI가 다단계로 분석하고, 결과를 기반으로 상담까지 이어지는 웹 서비스

1. 서비스 개요

한 줄 정의

교사가 학생의 생활기록부를 텍스트로 입력하면, OpenAI API가 실제 학생부종합전형 평가 기준에 따라 다단계 분석을 수행하고, 그 결과를 기반으로 상담 기록까지 관리할 수 있는 웹 서비스

배경 및 목적

기존 생기부 분석은 교사가 수작업으로 읽고 판단 → 시간 소모, 일관성 부재
학종 평가 기준(학업역량·진로역량·공동체역량)이 2024년부터 변경됨에도 반영이 어려움
분석 결과가 상담으로 자연스럽게 이어지는 통합 흐름 부재

핵심 가치

가치	설명
정확성	실제 입시 평가 기준(탐구연속성, 진로적합성, 서사일관성 등) 반영
연계성	분석 → 상담 기록이 하나의 흐름으로 연결
확장성	로그인·대학DB 등을 나중에 붙일 수 있는 구조

2. 대상 사용자 및 핵심 사용 흐름

대상 사용자

고등학교 교사 (담임 또는 진로 담당)

핵심 사용 흐름

학생 등록 (학년·반·번호·이름·목표대학·목표계열)
    ↓
학생 목록 조회 (학년·반 필터)
    ↓
학생 상세 페이지 진입
    ↓
기본 정보 입력 (생기부 원문 + 내신 + 모의고사)
    ↓
AI 5가지 항목 분석 요청
    ↓
분석 결과 확인 (역량 점수·추천 활동·서사 전략·대학 적합도)
    ↓
분석 결과 저장 → 이력 누적
    ↓
"이 분석으로 상담 시작" → 상담 카드 작성 → 상담 이력 관리

3. 핵심 기능 정의

3-1. 학생 관리

학생 등록: 이름, 학년(1~3), 반, 번호, 목표 대학, 목표 계열
학생 목록: 테이블 형식 (이름·학년·반·번호·희망대학·희망학과·관리), 학년·반·번호·이름 필터, 학번 정렬, 페이지네이션
학생 상세: 탭 기반 구성 — 기본정보 / 생기부 분석 / 상담 기록 / 대학 탐색

3-2. 내신 입력

입력 단위: 학기별 (1-1, 1-2, 2-1, 2-2, 3-1, 3-2)
입력 항목: 과목명, 등급 (1~9)
자동 계산: 학기별 평균 등급, 전체 평균 등급
UI: 입력하기 버튼 클릭 → 팝업 열림 → 입력 후 저장/취소

3-3. 모의고사 입력

입력 단위: 회차별 (연월 기준, 예: 2024-06)
입력 항목: 국어·수학·영어·탐구 각각 등급(1~~9) + 백분위(0~~100)
UI: 입력하기 버튼 클릭 → 팝업 열림 → 입력 후 저장/취소

3-4. 생기부 AI 분석 (5항목)

OpenAI API를 5회 병렬 호출하여 동시에 분석. 내신·모의고사 데이터가 있으면 프롬프트에 함께 주입.

이름	핵심 내용	max_tokens
역량 프로필	진로적합성·탐구연속성·서사일관성·심화잠재력 0~100점 + 근거 서술	3,500
종합 진단	활동 요약·강점 3개·보완점 3개·추천 전공 3~5개·대학 인재상 분석	2,800
활동 추천 A	안정형(기존 활동 연장) + 심화형(희망 전공 심층 탐구)	3,800
활동 추천 B	차별화형(독창적 문제의식) + 실천형(측정·실험·인터뷰 등)	3,800
서사 설계 전략	학생부 서사 전략(430~470자) + 추가 탐구 아이디어 6개	1,500

누락 방어 재시도 로직

각 항목 응답 후 필수 JSON 키 누락 또는 파싱 실패 시 해당 단계만 독립 재시도 (최대 1회). 재시도 실패 시 수동 재시도 버튼 노출.

3-5. 분석 결과 저장 및 조회

분석 완료 시 MongoDB에 결과 JSON 저장
학생 상세 페이지에서 분석 이력 목록 조회 (최신순)
분석 당시의 생기부 원문 스냅샷 함께 저장 → 과거 분석 결과 보존

4. 기술 스택

수업에서 배운 내용을 기반으로 선택. 처음부터 낯선 스택 도입을 최소화하여 개발 속도와 완성도에 집중.

전체 스택

구분	선택	선택 이유
Frontend	React + Vite	수업 내용 기반, HMR로 빠른 개발 환경
Routing	React Router v6	탭·페이지 전환 구조에 적합, 중첩 라우팅 지원
Backend	Node.js + Express	수업 내용 기반, 레이어드 아키텍처 적용 가능
DB	MongoDB Atlas	분석 결과 JSON 저장에 유연, 무료 클라우드 제공
AI	OpenAI API (gpt-4o-mini → gpt-4o)	개발 중 mini로 비용 절감, 데모 시 4o로 전환
배포	Vercel (FE) + Render (BE)	무료, GitHub 연동 자동 배포

AI

개발 중: gpt-4o-mini
데모: gpt-4o 전환 — 환경변수 OPENAI_MODEL 하나만 변경, 코드 수정 불필요

백엔드 아키텍처

Router (요청/응답)
  → Service (비즈니스 로직)
  → Repository (DB 접근)
  → Model (Mongoose Schema)

5. 데이터 구조 (MongoDB)

Student

{
  _id: ObjectId,
  teacherId: ObjectId,
  studentId: String,       // '010203' (학년+반+번호 각 2자리 조합)
  name: String,
  grade: Number,           // 1~3
  classNum: Number,
  number: Number,
  targetUniv: String,
  targetMajor: String,
  grades: [
    {
      semester: String,    // '1-1' | '1-2' | ...
      subjects: [{ name: String, grade: Number }],
      avgGrade: Number
    }
  ],
  mockExams: [
    {
      date: String,        // '2024-06'
      kor:  { grade: Number, percentile: Number },
      math: { grade: Number, percentile: Number },
      eng:  { grade: Number, percentile: Number },
      exp:  { grade: Number, percentile: Number }
    }
  ],
  createdAt: Date
}

Analysis

{
    _id: ObjectId,
    studentId: String,       // 학번 문자열 ('010203')
    inputText: String,       // 생기부 원문 스냅샷
    result: {
      competencyProfile: { careerFitScore, careerFitEvidence, continuityScore, ... },
      diagnosis:         { summary, strengths, weaknesses, suggestedMajors, ... },
      activityA:         { stable: {...}, intensive: {...} },
      activityB:         { differentiated: {...}, practical: {...} },
      narrative:         { narrative, ideas }
    },
    createdAt: Date
  }

Consultation

{
  _id: ObjectId,
  studentId: ObjectId,
  analysisId: ObjectId,    // 선택 — 없으면 독립 상담
  consultedAt: Date,
  type: String,            // '진로' | '학업' | '심리' | '기타'
  content: String,
  studentReaction: String,
  nextGoal: String,
  nextDate: Date,
  teacherId: ObjectId
}

6. API 설계

학생

Method	Path	설명
GET	`/api/students`	학생 목록 (grade, classNum 필터)
POST	`/api/students`	학생 등록
GET	`/api/students/:id`	학생 상세
PUT	`/api/students/:id`	학생 정보 수정 (내신·모의고사 포함)
DELETE	`/api/students/:id`	학생 삭제

분석

Method	Path	설명
POST	`/api/students/:id/analyze`	생기부 분석 요청 (5단계 병렬)
GET	`/api/students/:id/analyses`	분석 이력 목록
GET	`/api/analyses/:id`	분석 결과 상세

상담

Method	Path	설명
GET	`/api/students/:id/consultations`	상담 이력 목록
POST	`/api/consultations`	상담 기록 생성
PUT	`/api/consultations/:id`	상담 기록 수정

7. 화면 흐름 및 페이지 구성

홈 (/)
  서비스 소개
    ↓
학생 목록 (/students)
  ├── 학년·반 필터
  ├── 이름·번호 검색
  ├── 학생 등록 버튼 → 등록 폼 (/students/new)
  └── 학생 행 클릭
          ↓
학생 상세 (/students/:id)
  ├── [탭 1] 기본 정보
  │     ├── 이름·학년·반·번호·목표대학·목표계열
  │     ├── 생기부 원문 텍스트
  │     ├── 내신 (학기별 입력 팝업, 평균 자동 계산)
  │     └── 모의고사 (회차별 입력 팝업)
  │
  ├── [탭 2] 생기부 분석
  │     ├── 분석 시작 버튼
  │     ├── 분석 중 로딩 (5단계 진행 표시)
  │     ├── 분석 결과 (역량 차트·진단·활동 추천·서사 전략)
  │     └── 분석 이력 목록 (최신순)
  │
  ├── [탭 3] 상담 기록
  │     ├── 새 상담 카드 작성 폼
  │     └── 상담 이력 타임라인
  │
  └── [탭 4] 대학 탐색
        └── AI 추천 대학 및 학과 / 목표 대학 합격 가능성 분석

학생 상세 탭 상세

탭	주요 UI 요소
기본 정보	인적 사항 카드, 내신 성적 테이블, 모의고사 히스토리 테이블
생기부 분석	역량 프로필 차트, 5단계 분석 결과 섹션, 이력 목록
상담 기록	상담 작성 폼(일시·유형·내용·반응·다음 목표), 타임라인
대학 탐색	추천 대학 카드(매칭률), 목표 대학 합격 가능성, AI 입시 전략 팁

8. 저장소 및 개발 관리

저장소

Organization: boostcampwm-snu-2026
레포 이름: studentanalysis-jsh (public)

브랜치

main       ← 배포용 (dev → main PR은 배포 시점에만)
  └── dev  ← 개발 통합 (평소 작업 결과는 여기로)
        ├── feature/1-student-crud
        ├── feature/2-openai-analyze
        └── feature/3-consultation-record

기능 하나 = feature/이슈번호-기능명 브랜치
작업 완료 후 feature/* → dev PR 생성 후 머지

Task 관리

GitHub Issue로 기능 단위 Task 등록
브랜치 이름에 이슈 번호 포함 (예: feature/1-student-crud)
라벨: feature / bug / docs

문서 관리

GitHub Wiki: 기획서, Agent workflow, 회고록
README: 프로젝트 소개, 브랜치 전략, 실행 방법

9. 디자인 방향

상세 디자인 토큰은 DESIGN.md 참고

학생 목록	학생 등록
학생 상세 — 기본 정보	학생 상세 — 생기부 분석
학생 상세 — 상담 기록	학생 상세 — 대학 탐색

테마: Soft Blue Academy — 차분한 청색 계열, 고대비 타이포그래피
분위기: Modern Minimalism, 넓은 여백, 얇은 선 중심
주요 색상: Primary #476274, Surface #f9f9f9, 컨테이너 #ffffff
폰트: Montserrat (헤드라인 Bold/SemiBold, 본문 Regular · line-height 1.6)
컴포넌트: 1px 테두리 카드, 4px border-radius 기본, 8px base spacing unit

10. 향후 확장 계획

항목	현재	확장 시
인증	환경변수 `DEFAULT_TEACHER_ID` 하드코딩	`req.user.id`로 교체 (JWT 로그인)
대학 데이터	OpenAI 학습 지식 기반	`University` 컬렉션에 20~30개 대학 데이터 저장 후 프롬프트 주입
AI 모델	`gpt-4o-mini`	`gpt-4o` (환경변수 `OPENAI_MODEL` 변경만으로 전환)

Uh oh!