Claude AI로 영어 단어 퀴즈 웹 앱 만들기 [7편]

Claude AI로 영어 단어 퀴즈 앱 만들기

Part 7: Python Flask로 전환하기 - 본격적인 개발의 시작

📚 시리즈 안내

← 이전 글: [Part 6] GAS 관리자 기능 완성하기

→ 다음 글: [Part 8] 학습 모드와 UI 개선

🐍 이번 편: Google Apps Script에서 Python Flask로 완전 전환!

🚀 들어가며: 왜 Python으로 전환하게 되었나?

6편까지 Google Apps Script(GAS)로 꽤 완성도 있는 웹앱을 만들었습니다. 관리자 기능까지 추가하고 실제로 학원에서 사용하기 시작했는데... 며칠 지나니 여러 가지 불편함이 느껴지기 시작했습니다.

 

Google Apps Script의 한계점

•      속도 문제: Google 서버를 거치다 보니 응답이 느릴 때가 있음

•      오프라인 사용 불가: 인터넷이 끊기면 아무것도 할 수 없음

•      배포 번거로움: 매번 웹 앱 URL을 공유해야 하고, 버전 관리가 어려움

•      디버깅 어려움: 에러가 발생해도 원인 파악이 힘듦

•      확장성 한계: 복잡한 기능을 추가할수록 코드 관리가 어려워짐

"EXE 파일로 설치 프로그램처럼 배포한다면 어떨까?"를 생각을 하고 Claude에 문의를 하니 Python으로 변환하면 좋다고 나왔습니다. 결국 결심했습니다. "Python Flask로 완전히 새로 만들자!"

Python으로 전환하면 나중에 EXE 파일로 빌드해서 설치 프로그램처럼 배포할 수도 있고, 더 다양한 기능을 추가할 수 있을 거라 기대했습니다.

💬 1단계: Claude에게 코드 변환 요청

기존 GAS 코드를 통째로 Claude에게 주고 Python으로 변환해 달라고 요청했습니다. Claude Pro의 장점이 여기서 빛을 발했어요. 긴 코드를 한 번에 분석하고 변환해 줄 수 있거든요.

 

💬 Claude에게 보낸 메시지

"이 코드를 가지고 python으로 작업해 줘" (기존 GAS 코드 전체 첨부)

🤖 Claude의 응답

이 Google Apps Script 코드를 Python으로 변환해 드리겠습니다.

Flask 웹 프레임워크와 Google Sheets API를 사용하여 구현하겠습니다.

 

📋 주요 변환 내용:

• doGet() → Flask 라우트

• google.script.run → REST API 엔드포인트

• SpreadsheetApp → Google Sheets API v4

 

Claude가 단순히 코드만 변환한 게 아니라, 어떤 부분이 어떻게 바뀌는지 설명까지 해주니까 이해하기가 훨씬 쉬웠습니다.

📦 2단계: Python 환경 설정

Python 개발을 위해 필요한 패키지들을 설치해야 합니다. Claude가 알려준 명령어를 그대로 따라 했습니다.

필요한 패키지 설치

 

# Flask - 웹 프레임워크

pip install flask

 

# Google API 인증 관련

pip install google-auth

pip install google-auth-oauthlib

pip install google-auth-httplib2

pip install google-api-python-client

 

패키지별 역할 설명

패키지	역할
flask	Python 웹 프레임워크. 웹 서버를 쉽게 만들 수 있게 해줌
google-auth	Google API 인증을 위한 기본 라이브러리
google-api-python-client	Google Sheets API를 Python에서 사용할 수 있게 해줌

 

🔐 3단계: Google API 인증 설정

GAS에서는 자동으로 Google Sheets에 접근할 수 있었지만, Python에서는 별도의 인증 파일(credentials.json)이 필요합니다. Claude에게 방법을 물어봤습니다.

 

💬 나의 질문

"JSON 키 다운로드는 어디서 하면 되는 거야?"

 

Claude가 단계별로 상세하게 알려주었습니다. 생각보다 복잡했지만, 차근차근 따라 하니 어렵지 않았어요.

Step 1: Google Cloud 프로젝트 생성

1.     Google Cloud Console (console.cloud.google.com) 접속

2.     상단의 '프로젝트 선택' 클릭

3.     '새 프로젝트' 클릭 후 이름 입력 (예: vocab-quiz-app)

4.     '만들기' 버튼 클릭

Step 2: Google Sheets API 활성화

1.     왼쪽 메뉴에서 'API 및 서비스' → '라이브러리' 클릭

2.     검색창에 'Google Sheets API' 검색

3.     '사용 설정' 버튼 클릭

Step 3: 서비스 계정 생성 및 JSON 키 다운로드

1.     'API 및 서비스' → '사용자 인증 정보' 클릭

2.     '+ 사용자 인증 정보 만들기' → '서비스 계정' 선택

3.     서비스 계정 이름 입력 후 '완료' 클릭

4.     생성된 서비스 계정 클릭 → '키' 탭 이동

5.     '키 추가' → '새 키 만들기' → 'JSON' 선택

6.     📥 JSON 파일이 자동으로 다운로드됩니다!

 

⚠️ 매우 중요!

• 다운로드된 JSON 파일의 이름을 credentials.json으로 변경하세요

• 이 파일은 절대 GitHub 등에 업로드하면 안 됩니다!

• app.py와 같은 폴더에 저장해야 합니다

 

😱 4단계: 첫 번째 오류 - 로그인이 안 돼!

모든 설정을 마치고 python app.py 명령어로 서버를 실행했습니다. 브라우저에서 http://127.0.0.1:5000에 접속하니 화면은 뜨는데... 로그인이 안 됩니다!

 

💬 Claude에게 도움 요청

"로그인이 안 돼"

 

Claude가 문제 진단 방법을 알려주었습니다:

•      Flask 서버 터미널에서 에러 메시지 확인

•      브라우저 개발자 도구(F12) Console/Network 탭 확인

•      Google Sheets '계정' 시트에 데이터가 있는지 확인

•      서비스 계정에 시트 권한이 부여되었는지 확인

🔴 5단계: 두 번째 오류 - 404 NOT FOUND

F12를 눌러 개발자 도구를 확인해 보니,빨간색 에러가 떠 있었습니다.

 

❌ 에러 메시지

Failed to load resource: the server responded with a status of 404 (NOT FOUND)

🤖 Claude의 진단

404 에러는 Flask가 templates 폴더를 찾지 못해서 발생하는 문제입니다!

파일 구조를 확인해 보세요.

 

올바른 폴더 구조

your-project/

├── app.py

├── credentials.json

└── templates/          ← 이 폴더가 반드시 있어야 합니다!

    └── index.html

 

💡 중요 포인트

폴더 이름은 반드시 templates (소문자, 복수형)이어야 합니다! template(단수형)나 Templates(대문자)로 하면 안 됩니다.

📁 6단계: 세 번째 오류 - credentials.json을 찾을 수 없음

templates 폴더를 만들고 다시 실행했는데, 이번엔 터미널에 다른 에러가 떴습니다.

 

❌ 에러 메시지

시트 읽기 오류: [Errno 2] No such file or directory: 'credentials.json'

 

Claude가 바로 원인을 짚어주었습니다:

 

🤖 Claude의 해결책

문제를 찾았습니다! credentials.json 파일을 찾지 못하고 있습니다.

 

🔧 해결 방법:

1. credentials.json 파일이 app.py와 같은 폴더에 있는지 확인

2. 터미널에서 dir(Windows) 또는 ls(Mac)로 파일 목록 확인

3. 또는 app.py에서 절대 경로를 사용하도록 수정

 

확인해 보니,파일을 다른 폴더에 넣어뒀더라고요. 😅 app.py와 같은 폴더로 옮기니 드디어 작동했습니다!

📦 7단계: EXE 파일로 만들기

기본 동작이 확인되자, 바로 다음 질문을 했습니다.

 

💬 나의 질문

"이 파일을 웹 브라우저가 아닌 컴파일(exe) 파일로 실행할 수 있어?"

🤖 Claude의 답변

네! Flask 앱을 EXE 파일로 만들 수 있습니다.

PyInstaller를 사용하면 됩니다.

PyInstaller 사용법

# 1단계: PyInstaller 설치

pip install pyinstaller

 

# 2단계: EXE 빌드

pyinstaller --onefile --noconsole --add-data "credentials.json;." app.py

 

완성된 EXE의 특징

•      ✅ 더블클릭만으로 실행 - Python 설치 불필요

•      ✅ 자동으로 브라우저 오픈 - 실행하면 바로 게임 화면

•      ✅ credentials.json 내장 - 별도 파일 배포 불필요

•      ✅ 단일 파일 배포 - 설치 과정 없이 바로 실행

🎮 8단계: 게임 기능 대폭 업그레이드

기본 틀이 완성되자, 본격적으로 게임 기능을 추가하기 시작했습니다. 한 번에 세 가지를 요청했어요.

 

💬 나의 요청

1. 획득 점수: 초등 10점/중등 30점/고등 50점, 감점: 초등 5점/중등 15점/고등 25점

2. 5초 카운트다운 + 시간 초과 시 틀림 처리 + TTS 음성

3. 게임 종료 후 내 랭킹 + TOP 10 표시

적용된 기능들

학년	정답	오답	타이머
초등	+10점	-5점	5초
중등	+30점	-15점	5초
고등	+50점	-25점	5초

 

🔧 9단계: 추가 개선 사항들

기본 기능이 완성되자, 사용하면서 느낀 개선점들을 계속 요청했습니다.

점수 마이너스 방지

 

💬 요청: "최종 점수는 0점 이하로는 안 내려가게 해 주면 좋겠어"

✅ 적용 완료! 오답으로 점수가 마이너스가 되려 해도 0점에서 멈춤

 

오답 시 반복 학습 시스템

 

💬 요청: "문제를 틀리면 다음으로 넘어가지 않고, 맞을 때까지 반복하게 만들어줘"

✅ 새로운 학습 방식 적용!

 

•      오답 시: 버튼이 빨간색으로 변하고, 해당 버튼만 비활성화

•      타이머 리셋: 다시 5초 카운트다운 시작

•      점수 감점: 틀릴 때마다 점수 차감

•      정답까지 계속: 남은 선택지 중에서 정답을 찾을 때까지 반복

💡 이번 편에서 배운 것

1.     GAS → Python 전환: Claude에게 코드를 주면 한 번에 변환해 줌

2.     Google API 인증: 서비스 계정과 credentials.json 파일이 필요

3.     Flask 폴더 구조: templates 폴더(소문자, 복수형)가 반드시 필요

4.     에러 메시지 활용: 에러 메시지를 그대로 Claude에게 보여주면 해결책을 알려줌

5.     PyInstaller: Python 앱을 EXE 파일로 변환 가능

📌 다음 편 예고

Python Flask 버전의 기본이 완성되었습니다! 다음 편에서는 학습 모드를 추가하고, UI/UX를 개선하면서 더 완성도 높은 앱을 만들어갑니다.

➡️ 다음 글: [Part 8] 학습 모드와 UI 개선

📋 이번 편 요약

• Google Apps Script → Python Flask 완전 전환

• Python 패키지 설치 (flask, google-api-python-client 등)

• Google Cloud Console에서 API 인증 설정

• 404 에러 해결 (templates 폴더 생성)

• credentials.json 파일 위치 문제 해결

• PyInstaller로 EXE 파일 빌드 방법

• 학년별 점수 시스템 + 5초 타이머 + TTS 음성

• 점수 0점 미만 방지 + 오답 시 반복 학습 시스템

• 관리자 기능 추가 (랭킹/기록 초기화, 비밀번호 초기화)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Python으로 전환하니 할 수 있는 게 훨씬 많아졌어요! 🐍✨

이 글이 도움이 되셨다면 공감과 댓글 부탁드립니다! 🙏