학습 목표 연계 문제 은행 생성기 및 감사 시스템
이 저장소는 학습 목표(outcome)-연계 평가 문항을 생성, 감사, 저장 및 관리하는 풀스택 EdTech 시스템을 담고 있습니다.
시스템은 규칙 기반의 감사 파이프라인을 통해 Bloom’s Taxonomy 정렬을 강제하며, 현대적인 웹 인터페이스를 통해 생성 워크플로우와 쿼리 워크플로우 모두를 노출합니다.
본 프로젝트는 순수한 LLM(Large Language Model) 출력보다는 정확성, 감사 가능성, 시스템 설계에 중점을 두어 AI 지원 교육 콘텐츠 생성에 대한 프로덕션 지향적 접근 방식을 시연하는 것을 목표로 합니다.
문제 정의 (Problem Statement)
많은 교육 환경에서 평가 문항은 다음과 같은 측면에서 검증이 제한된 채 수동으로 작성됩니다:
- 강좌 성과(Course Outcomes, COs)와의 연계성
- 정확한 Bloom’s Taxonomy 수준
- 개념 범위 준수 여부
- 평가 간의 일관성
본 프로젝트는 이러한 격차를 해소하기 위해 자동화되고 감사 가능한 파이프라인을 도입하여, 생성된 모든 문항이 사용자에게 영구 저장되거나 제시되기 전에 미리 정의된 학술적 제약 조건을 충족하도록 보장합니다.
시스템 개요 (System Overview)
본 시스템은 세 가지 주요 계층으로 구성됩니다:
1. AI 및 규칙 기반 파이프라인 (AI & Rule-Based Pipeline)
- 학습 목표 사양 해석
- LLM을 사용하여 후보 문항 생성
- Bloom’s Taxonomy와 개념 제약 조건에 따라 문항 감사 수행
- 위반 사항 발생 시 자동으로 생성 재시도
- 비준수 문항은 결정론적으로 거부 처리
2. 백엔드 API (Backend API)
- FastAPI를 사용하여 구축됨
- 다음 기능을 위한 엔드포인트를 노출합니다:
- 문항 생성 및 감사 기능
- 저장된 문제 은행 조회 기능
- 승인된 문항만 영구 저장
- 추적 가능성을 위해 전체 감사 추적(audit trail)을 유지
3. 프론트엔드 대시보드 (Frontend Dashboard)
- React, TypeScript, Tailwind CSS로 구축됨
- 다음 기능을 위한 대시보드 스타일 인터페이스를 제공합니다:
- 대화형 문항 생성
- 감사 결과 조회
- 문제 은행 탐색 및 필터링
- 일반 사용자 대상 앱보다는 내부 학술/관리 도구처럼 보이도록 설계됨
핵심 기능 (Core Features)
- 학습 목표 연계 문제 생성
- Bloom의 분류학(Bloom’s Taxonomy) 적용
- 규칙 기반 검증 (LLM 출력은 절대 맹신하지 않음)
- 실패한 생성을 위한 자동 재작성 루프
- 감사 로그가 포함된 영구적인 문제 은행
- 검색 및 필터 기능
- 사용 편의성을 위한 대시보드 스타일 UI
통합 아키텍처 (Integration Architecture)
프론트엔드와 백엔드는 RESTful API를 통해 느슨하게 결합되어 있습니다.
연결 상세 정보 (Connection Details)
- 백엔드 오리진:
http://127.0.0.1:8000 (FastAPI 기본값)
- 프론트엔드 오리진:
http://localhost:5173 (Vite 기본값)
- 프로토콜: HTTP/JSON
설정 (Configuration)
- 프론트엔드 클라이언트: API 기본 URL은
frontend/src/api/client.ts에 정의되어 있습니다.
const API_BASE = "http://127.0.0.1:8000"
- CORS (Cross-Origin Resource Sharing): 백엔드는 프론트엔드 오리진의 요청을 수락하도록 구성되어 있습니다. 이는
app/main.py에서 CORSMiddleware를 사용하여 처리됩니다.
데이터 흐름 (Data Flow)
- 요청: 프론트엔드 컴포넌트(예:
usePaperGenerator 훅)가 src/api/의 함수들을 호출합니다.
- 실행: TypeScript 함수는
fetch를 사용하여 JSON 페이로드를 http://127.0.0.1:8000/<엔드포인트>로 전송합니다.
- 응답: 백엔드는 요청을 처리하고(문제 생성, DB 접근 등) JSON을 반환합니다.
- 상태 업데이트: 프론트엔드는 응답을 기반으로 React 상태(예: 문제 목록)를 업데이트합니다.
기술 스택 (Technology Stack)
백엔드 (Backend)
- Python
- FastAPI
- PostgreSQL
- SQLAlchemy
- Groq LLM API
프론트엔드 (Frontend)
- React
- TypeScript
- Vite
- Tailwind CSS
- REST 기반 API 아키텍처
- 환경 기반 설정(Environment-based configuration)
- Git 기반 버전 관리
API 엔드포인트 (API Endpoints)
POST /generate
제공된 학습 목표 사양에 따라 문제를 생성하고 감사합니다.
요청 페이로드 (예시):
{
"code": "CO1",
"topic": "데이터베이스 정규화",
...
}
동작 방식:
- 전체 AI + 감사 파이프라인을 실행합니다.
- Bloom 분류학 일치에 실패하면 생성을 재시도합니다.
- 승인된 경우에만 문제를 영구 저장소에 보관합니다.
GET /questions
문제 은행에서 저장된 질문을 검색합니다.
다음 기준으로 필터링을 지원합니다:
- 과정 성과(Course Outcome) 코드
- 블룸 수준(Bloom level)
- 난이도
데이터 모델 개요 (Data Model Overview)
백엔드는 세 가지 주요 테이블에 걸쳐 데이터를 영구 저장합니다:
course_outcomes — 성과 메타데이터를 저장합니다.
questions — 승인된 질문만 저장합니다.
audit_logs — 감사 결정 및 추론을 저장합니다.
거부된 질문은 의도적으로 저장하지 않습니다.
프로젝트 구조 (Project Structure)
outcome-qb-ai/
├── app/ # FastAPI 백엔드
│ ├── api/
...
로컬 환경에서 프로젝트 실행하기 (Running the Project Locally)
백엔드 (Backend)
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
...
프론트엔드 (Frontend)
cd frontend
npm install
npm run dev
설계 철학 (Design Philosophy)
- 창의성보다 정확성(Correctness over creativity)
- LLM에 대한 맹신보다는 규칙 기반 검증(Rule-based validation over blind trust in LLMs)
- 가능한 모든 곳에서 결정론적 동작(Deterministic behavior wherever possible)
- 관심사의 명확한 분리(Clear separation of concerns)
- 프로토타입 환경에서도 운영 지향적인 구조(Production-oriented structure even in a prototype setting)
이 프로젝트는 LLM을 권위자로 취급하는 것을 의도적으로 피하고, 대신 통제된 시스템 내의 보조 도구로 사용합니다.
예상 활용 사례 (Intended Use Cases)
- 학술 평가 준비(Academic assessment preparation)
- 내부 문제 은행 도구화(Internal question bank tooling)
- 에듀테크 플랫폼 프로토타이핑(EdTech platform prototyping)
- AI 거버넌스 패턴 시연(Demonstration of AI governance patterns)
- 풀스택 시스템 설계 전시(Full-stack system design showcase)
향후 개선 사항 (Future Enhancements)
- 블룸 커버리지 분석 및 차트(Bloom coverage analytics and charts)
- 내보내기 기능 (CSV / PDF)
- 인증 및 역할 기반 접근 제어(Authentication and role-based access)
- 대규모 페이지네이션 및 정렬(Pagination and sorting at scale)
- 배포 자동화(Deployment automation)
라이선스 (License)
이 프로젝트는 교육 및 시연 목적으로 사용됩니다.