VCBL Chatbot

AI 보조 학습(동영상 + 스캐폴딩 + 챗봇)을 위한 웹 애플리케이션입니다.

🎉 최신 업데이트 (v1.4.0 - 2025-01-06)

주요 기능 업데이트! 🚀

새로운 기능

✅ 채팅 파일 첨부 (이미지, PDF, 텍스트 - 멀티모달 AI 분석)
✅ 채팅 세션 PDF 내보내기 (학습 기록 저장)
✅ 관리자 채팅 모니터링 (학생 대화 내역 확인 및 관리)
✅ Gemini 비용 대시보드 (30일 트렌드, 모듈별 분석)
✅ 코드 구문 강조 (채팅 내 코드 블록 가독성 향상)

설정 개선

✅ 환경변수 리팩토링 (JWT 만료시간, Rate Limit, 가격 설정)
✅ 파일 크기 제한 (MAX_FILE_SIZE_MB, 기본 5MB)
✅ Node.js 20 업그레이드 (최신 LTS 버전)

이전 업데이트

✅ Context Caching 적용 (70-80% API 비용 절감)
✅ Vertex AI IAM 인증 (API 키 선택사항, 보안 강화)

🚀 빠른 시작

Windows 환경 (핫리로드 지원)

# 1. 환경 변수 설정 (최초 1회)
copy .env.example .env
# .env 파일에서 필수 환경 변수 설정!

# 2. 백엔드 실행 (PowerShell 터미널 1)
cd backend
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
python run.py

# 3. 프론트엔드 실행 (PowerShell 터미널 2)
cd frontend
npm install
npm run dev

# ✅ http://localhost:5173 접속

macOS/Linux 환경

# 1. 초기 설정 (최초 1회)
./scripts/dev_setup.sh

# 2. 백엔드 실행 (터미널 1)
cd backend && source venv/bin/activate && python run.py

# 3. 프론트엔드 실행 (터미널 2)
cd frontend && npm run dev

# ✅ http://localhost:5173 접속

코드 수정 시 즉시 반영됩니다! (Docker 재빌드 불필요)

📖 개발 워크플로우

로컬 개발 (권장) ⭐

용도: 일상적인 개발 (새 기능, 버그 수정, UI 조정)

장점:

✅ 핫리로드: 코드 저장 → 즉시 반영 (재시작 불필요)
✅ IDE 디버깅: VSCode 브레이크포인트, 단계별 실행
✅ 빠른 시작: Docker 이미지 빌드 불필요

준비 (최초 1회):

# Windows (PowerShell)
copy .env.example .env
cd backend
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
cd ..\frontend
npm install

# macOS/Linux (bash)
cp .env.example .env
./scripts/dev_setup.sh

매일 사용:

# 백엔드 실행 (터미널 1)
cd backend
source venv/bin/activate  # Windows: .\venv\Scripts\Activate.ps1
python run.py

# 프론트엔드 실행 (터미널 2)
cd frontend
npm run dev

접속:

프론트엔드: http://localhost:5173 (Vite Dev Server)
백엔드 API: http://localhost:8080/api
헬스체크: http://localhost:8080/health

작업 종료:

# Ctrl+C (백엔드, 프론트엔드 터미널에서 각각)

클라우드 배포 (GCP Cloud Run)

용도: 프로덕션 환경 배포

# 1. GCP 프로젝트 설정
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

# 2. 빌드 및 배포
gcloud builds submit --config cloudbuild.yaml

# 3. 배포 URL 확인
gcloud run services describe vcbl-chatbot \
  --region=asia-northeast3 \
  --format="value(status.url)"

자세한 배포 가이드: DEPLOYMENT.md 참고

📚 자주 사용하는 명령어

데이터베이스

cd backend
source venv/bin/activate  # Windows: .\venv\Scripts\Activate.ps1

# 마이그레이션 적용
flask db upgrade

# 새 마이그레이션 생성
flask db revision --message "설명"

# 관리자 계정 초기화
flask init-admin

코드 품질

# 프론트엔드 린트
cd frontend
npm run lint              # ESLint 검사

프론트엔드 빌드

cd frontend

# 의존성 설치
npm install

# 프로덕션 빌드 테스트
npm run build
npm run preview

🏗️ 프로젝트 구조

VCBL-Chatbot/
├── backend/              # Flask API 서버
│   ├── app/
│   │   ├── models/       # SQLAlchemy 모델
│   │   ├── routes/       # API 엔드포인트 (Blueprints)
│   │   ├── services/     # 비즈니스 로직
│   │   └── validators/   # Pydantic 스키마
│   ├── migrations/       # Alembic 마이그레이션
│   ├── run.py            # 개발 서버 진입점
│   └── requirements.txt  # Python 의존성
│
├── frontend/             # React/Vite SPA
│   ├── src/
│   │   ├── components/   # 재사용 컴포넌트
│   │   │   ├── charts/   # 차트 컴포넌트 (Bar, Line, Pie)
│   │   │   └── scaffolding/  # 스캐폴딩 모드 컴포넌트
│   │   ├── pages/        # 페이지 컴포넌트
│   │   ├── contexts/     # React Context (AuthContext)
│   │   └── services/     # API 통신 (axios)
│   └── package.json      # Node.js 의존성
│
├── Dockerfile            # 프로덕션 멀티스테이지 빌드
├── cloudbuild.yaml       # Google Cloud Build 설정
├── .env.example          # 환경 변수 예시 파일
├── README.md             # 프로젝트 메인 문서
└── TODO_HARDCODING.md    # 하드코딩 제거 작업 목록

🔧 환경 변수

로컬 개발 (.env 파일)

# 1. .env.example 파일을 복사
copy .env.example .env  # Windows
cp .env.example .env    # macOS/Linux

# 2. .env 파일에서 다음 값들을 설정
# 필수 - GCP 설정
GCP_PROJECT_ID=your-gcp-project-id
GCP_LOCATION=asia-northeast3
GCS_BUCKET_NAME=your-bucket-name

# 필수 - 보안 키
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-here

# 필수 - 관리자 계정 (flask init-admin용)
ADMIN_STUDENT_ID=9999000001
ADMIN_NAME=Admin
ADMIN_PASSWORD=your-admin-password

# 선택사항 (기본값 사용 가능)
MODEL_NAME=gemini-1.5-flash-002
DAILY_TOKEN_LIMIT=50000

Cloud Run 배포

배포시 Secret Manager를 통해 민감 정보를 관리합니다. Cloud Build를 통해 자동 빌드 및 배포가 진행됩니다.

🎯 개발 가이드

새 API 엔드포인트 추가

모델 정의 (backend/app/models/)
마이그레이션 생성 (flask db revision)
서비스 로직 (backend/app/services/)
라우트 추가 (backend/app/routes/)
Validator 정의 (backend/app/validators/)

새 페이지 추가

페이지 컴포넌트 (frontend/src/pages/)
라우트 등록 (frontend/src/App.jsx)
API 서비스 (frontend/src/services/api.js)
Context 활용 (필요시 AuthContext 등)

핫리로드 동작 방식

프론트엔드: Vite가 파일 변경 감지 → 브라우저 즉시 반영 (새로고침 불필요)
백엔드: Flask가 파일 변경 감지 → 서버 자동 재시작 (약 1초)

❓ 문제 해결

"포트가 이미 사용 중입니다"

# Windows (PowerShell - 관리자 권한)
# 5173 포트 (프론트엔드)
netstat -ano | findstr :5173
taskkill /PID <PID번호> /F

# 8080 포트 (백엔드)
netstat -ano | findstr :8080
taskkill /PID <PID번호> /F

# macOS/Linux
lsof -ti:5173 | xargs kill -9  # 프론트엔드
lsof -ti:8080 | xargs kill -9  # 백엔드

"핫리로드가 작동하지 않습니다"

# 프론트엔드: node_modules 재설치
cd frontend
rm -rf node_modules package-lock.json  # Windows: rmdir /s node_modules & del package-lock.json
npm install

# 백엔드: venv 재생성
cd backend
rm -rf venv  # Windows: rmdir /s venv
python -m venv venv
source venv/bin/activate  # Windows: .\venv\Scripts\Activate.ps1
pip install -r requirements.txt

"Python 가상환경이 활성화되지 않습니다"

# Windows (PowerShell)
cd backend
.\venv\Scripts\Activate.ps1

# macOS/Linux
cd backend
source venv/bin/activate

# 활성화 확인 (프롬프트에 (venv) 표시)

📦 주요 기술 스택

Backend

Framework: Flask 3.x
ORM: SQLAlchemy + Flask-Migrate
Auth: Flask-JWT-Extended (설정 가능한 토큰 만료시간)
Validation: Pydantic v2
Database: PostgreSQL 15
Cache: Flask-Caching (Simple)
AI:
- Google Vertex AI (Gemini 1.5 Flash)
- Context Caching - 70-80% 비용 절감
- File API - PDF/이미지/텍스트 멀티모달 지원
- 토큰 사용량 및 비용 추적
Storage: Google Cloud Storage (채팅 첨부파일 지원)
PDF Generation: Typst (채팅 세션 내보내기)
Server: Gunicorn (프로덕션)

Frontend

Framework: React 18
Build Tool: Vite 5
Runtime: Node.js 20 LTS
Styling: TailwindCSS 3
Animation: Framer Motion
Router: React Router v6
HTTP: Axios
Video Player: YouTube Player API
Charts: Recharts (비용 모니터링 대시보드)
Code Highlighting: react-syntax-highlighter
Markdown: react-markdown + remark/rehype plugins

Infrastructure

Cloud: Google Cloud Run
CI/CD: Google Cloud Build
Secrets: Google Secret Manager

📝 헬스 체크

루트 헬스체크: GET /health
API 헬스체크: GET /api/health

응답 예시:

{
  "status": "healthy",
  "database": "connected",
  "timestamp": "2025-01-01T00:00:00Z"
}

📄 라이선스

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 409 Commits
backend		backend
frontend		frontend
jobs		jobs
scripts		scripts
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
cloudbuild.yaml		cloudbuild.yaml
deploy.sh		deploy.sh

Folders and files

Latest commit

History

Repository files navigation

VCBL Chatbot

🎉 최신 업데이트 (v1.4.0 - 2025-01-06)

새로운 기능

설정 개선

이전 업데이트

🚀 빠른 시작

Windows 환경 (핫리로드 지원)

macOS/Linux 환경

📖 개발 워크플로우

로컬 개발 (권장) ⭐

클라우드 배포 (GCP Cloud Run)

📚 자주 사용하는 명령어

데이터베이스

코드 품질

프론트엔드 빌드

🏗️ 프로젝트 구조

🔧 환경 변수

로컬 개발 (.env 파일)

Cloud Run 배포

🎯 개발 가이드

새 API 엔드포인트 추가

새 페이지 추가

핫리로드 동작 방식

❓ 문제 해결

"포트가 이미 사용 중입니다"

"핫리로드가 작동하지 않습니다"

"Python 가상환경이 활성화되지 않습니다"

📦 주요 기술 스택

Backend

Frontend

Infrastructure

📝 헬스 체크

📄 라이선스

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages