콘텐츠로 이동

06. [종합] AI 수강신청 에이전트 완성 (Capstone)

"기획부터 배포까지, AI와 함께 만든 '진짜 결과물'을 세상에 선보입니다."

이제 우리 시스템은 사용자의 말을 알아듣고 복잡한 수강신청 업무를 대신 수행합니다. Gemini AI를 연동하여 대화형 인터페이스를 완성하고, 관리자 기능을 통해 시스템을 운영하는 전 과정을 완수해 봅시다.

1. AI Agent: Gemini와 대화하는 수강신청

단순한 버튼 클릭 대신, 사용자의 자연어(말)를 해석하여 기능을 수행하는 에이전트를 구현합니다.

🤖 에이전트의 작동 원리

  1. 사용자 입력: "파이썬 수업 남은 자리 있어? 있으면 신청해줘."
  2. Intent 파악 (Gemini): 사용자의 의도가 '강의 조회'와 '수강 신청'임을 파악합니다.
  3. Tool Calling: 에이전트가 우리가 만든 백엔드 함수(check_vacancy, enroll_course)를 직접 실행합니다.
  4. 응답 생성: "네, 파이썬 기초 강의는 현재 3자리 남아있어 신청을 완료했습니다!"

🛠️ MCP Tool Implementation

비즈니스 로직을 AI가 쓸 수 있는 도구(Tool)로 포장합니다. 백엔드에 구현된 CRUD 함수들을 MCP 프로토콜에 맞게 선언하여, Gemini가 이해하고 호출할 수 있도록 만듭니다.

2. Admin Dashboard: 권한 분리 (RBAC: Role-Based Access Control, 역할 기반 권한 제어)

모든 사용자가 관리자 페이지에 들어오면 안 됩니다. 로그인한 사용자의 역할을 구분하여 메뉴를 다르게 보여줍니다.

  • 학생 모드: 챗봇과 대화하며 수강신청 현황 확인.
  • 관리자 모드: 새로운 과목 개설, 수강생 통계 확인, 사용자 권한 부여.

👑 관리자 권한 설정 (Admin Setup)

초기 관리자 계정은 보안상 자동으로 생성되지 않으며, 백엔드 스크립트를 통해 수동으로 승격시켜야 합니다.

  1. Frontend에서 먼저 로그인하여 users 컬렉션에 문서를 생성합니다.
  2. Firebase Auth 또는 Firestore에서 본인의 UID를 확인합니다.
  3. 백엔드 스크립트 실행:
# 로컬 에뮬레이터 환경 (functions 폴더에서 실행)
# 사전에 환경변수 설정 필수 (export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080")

# 방법 1: UID 사용 (기존 방식)
python seed.py --admin "YOUR_USER_UID"

# 방법 2: 이메일 사용 (추천, @가 포함되면 자동으로 이메일로 검색)
python seed.py --admin "admin@example.com"

실행 후 에뮬레이터 또는 배포된 사이트에서 새로고침하면 관리자 메뉴 접근이 가능해집니다.

3. Voice Interface: 더 편한 UX (STT/TTS)

키보드 타이핑이 귀찮은 사용자를 위해 음성 기능을 추가합니다.

  • STT (Speech to Text): 브라우저의 마이크를 통해 사용자의 목소리를 텍스트로 변환.
  • TTS (Text to Speech): AI의 답변을 친절한 목소리로 읽어주기.

🎙️ Web Speech API 활용

// 음성 인식 (STT) 예시
const recognition = new window.webkitSpeechRecognition();
recognition.lang = "ko-KR";
recognition.onresult = (event) => {
  const transcript = event.results[0][0].transcript;
  sendMessage(transcript); // AI에게 전송
};
recognition.start();

// 음성 합성 (TTS) 예시
const utterance = new SpeechSynthesisUtterance(aiResponse);
utterance.lang = "ko-KR";
window.speechSynthesis.speak(utterance);

4. [Check] 최종 런칭 및 QA (Quality Assurance)

배포된 실제 URL에서 다음 시나리오가 완벽히 작동하는지 최종 점검합니다.

✅ 기능 검증 체크리스트

1. 로그인 및 사용자 생성

  • [ ] Google 로그인 버튼을 클릭하여 로그인이 정상적으로 되는가?
  • [ ] (에뮬레이터) Auth Emulator IDP Login Widget이 뜨고 계정 생성이 가능한가?
  • [ ] Firestore users 컬렉션에 내 UID로 된 문서가 생성되었는가? (기본 role: "student")

2. 권한 분리 확인 (학생)

  • [ ] 로그인 직후 상단 네비게이션 바에 '관리자' 메뉴가 보이지 않는가?
  • [ ] 주소창에 직접 /admin을 입력했을 때 /student 페이지로 리다이렉트 되는가?

3. 관리자 승격 및 접속

  • [ ] seed.py --admin 명령어가 에러 없이 실행되었는가?
  • [ ] Firestore에서 해당 유저의 role 필드가 "admin"으로 변경되었는가?
  • [ ] 새로고침 후 상단 네비게이션 바에 '관리자' 메뉴가 나타나는가?
  • [ ] '관리자' 메뉴 클릭 시 Admin Dashboard로 정상 진입하는가?

4. 관리자 기능 검증

  • [ ] (관리자 계정) 대시보드에 현재 개설된 과목 목록이 표시되는가?
  • [ ] 과목 생성: '과목 추가' 버튼을 눌러 새 과목(과목ID, 과목명, 교수명, 정원)을 추가할 수 있는가?
  • [ ] 과목 생성 시 과목ID는 중복되지 않아야 한다.: 과목ID가 중복되면 에러 메시지를 반환하고 생성을 중단해야 한다.
  • [ ] 과목 수정: '수정' 버튼을 눌러 과목명이나 정원을 변경하면 리스트에 반영되는가?
  • [ ] 과목 삭제: 목록에서 과목을 삭제하면 리스트에서 사라지는가?
  • [ ] (Firestore) courses 컬렉션에 데이터가 실제로 추가/삭제되었는가?

5. 관리자 화면 유저 관리 및 통계 검증

  • [ ] 유저 목록: 가입된 모든 유저의 목록이 표시되는가?
  • [ ] 관리자 승격: 특정 유저에게 UI에서 직접 '관리자' 권한을 부여할 수 있는가?
  • [ ] 통계 정확성: 상단 대시보드의 '총 수강생', '등록률' 등이 실제 데이터와 일치하는가?

6. 학생 채팅 및 수강신청 검증

  • [ ] (학생 계정) /student 페이지에 접속하여 채팅창이 뜨는가?
  • [ ] 채팅 테스트: "수강신청 가능한 과목 알려줘"라고 입력하면 Agent가 과목 답변을 주는가?
  • [ ] 수강신청 명령: "Python 과목 신청해줘"라고 입력하면 신청이 완료되는가?
  • [ ] 상태 반영: 신청 후 하단 '내 수강 목록' 테이블에 과목이 즉시 추가되는가?
  • [ ] 중복 신청 방지: 이미 신청한 과목을 다시 신청했을 때, Agent가 "이미 신청된 과목입니다"라고 안내하는가?

7. 음성 인터페이스 (Optional)

  • [ ] 마이크 버튼을 클릭하면 음성 인식이 시작되는가?
  • [ ] AI의 응답이 음성으로 재생되는가?

💡 개발 팁: AI와 함께하는 TDD 개발

위 체크리스트를 기반으로 더욱 견고한 코드를 작성하고 싶다면, AI에게 다음과 같이 요청해보세요.

AI 프롬프트 예시

넌 지금부터 시니어 프론트엔드 개발자야. 위 [QA 체크리스트]의 모든 항목을 검증할 수 있는 Vitest + React Testing Library 테스트 코드를 먼저 작성해줘. (Mocking이 필요한 API 호출은 vi.fn()으로 처리하고, 로딩/에러 상태와 접근성(ARIA)도 고려해줘.)

그 다음, 작성된 테스트를 100% 통과하는 완성도 높은 React 컴포넌트를 Typescript와 Tailwind CSS로 구현해줘.

5. Final Release: 운영 환경 배포 (Main Merge)

검증이 모두 완료되었다면, 이제 develop 브랜치에서 작업한 내용을 main 브랜치에 병합하여 전 세계 사용자에게 공개할 시간입니다.

  1. 로컬 스테이징: 모든 변경 사항을 develop 브랜치에 commit 하고 push 합니다.
  2. Pull Request 생성: GitHub 저장소에서 develop -> main으로의 PR을 생성합니다.
  3. Merge: PR을 승인하고 병합(Merge)하면, GitHub Actions가 자동으로 운영 환경(Production)으로 배포를 시작합니다.
  4. 확인: 배포가 완료되면 프론트엔드 URL과 백엔드 기능이 실제 main 환경에서도 완벽하게 작동하는지 확인합니다.

6. 핵심 정리 (6부 전체 요약)

과정 핵심 도구 달성 목표
01. Setup Firebase CLI, Git 클라우드 협업 환경 구축
02. Auth Google Login 안전한 사용자 인증 구현
03. Backend FastAPI, Firestore 비즈니스 로직 및 데이터 저장소 완성
04. Test Emulator, Pytest 배포 전 완벽한 품질 검증
05. CI/CD GitHub Actions 자동 배포 파이프라인 구축
06. AI Gemini API 지능형 에이전트 서비스 완성

런칭 축사

"여러분의 첫 번째 URL이 전 세계에 공개되었습니다." 처음에는 localhost:3000에서만 보이던 작은 코드가, 이제는 구글의 서버 위에서 AI와 함께 살아 움직입니다. 이 과정에서 겪은 수많은 에러와 삽질은 여러분을 '코더'에서 '엔지니어'로 성장시키는 밑거름이 되었을 것입니다. 이제 세상이 여러분의 코드를 사용할 차례입니다. 런칭을 진심으로 축하합니다! 🚀

마지막 과제: 완성된 서비스 링크를 소셜 미디어나 지인에게 공유하고, 실제 사용자의 피드백을 받아보세요. 피드백을 바탕으로 코드를 수정하고 push 하면, 여러분의 배포 비서가 즉시 업데이트를 도와줄 것입니다!