[파이썬] AI 활용 웹 서비스 개발 기록 : 2 controllers 설명

이전 내용

[파이썬] AI 활용 웹 서비스 개발 기록 : 1 - 서비스 화면 및 기능 소개

---

전체 디렉터리 구조

 

- 기술 스택

• FastAPI (비동기 REST API)
• SQLAlchemy (ORM)
• Pydantic (입력값 검증)
• PostgreSQL (RDBMS)
• 로깅 시스템 (logger): logging 모듈 기반 로그 기록
• 비밀번호 해싱: Passlib (bcrypt)
• 이메일 처리: SMTP + 커스텀 EmailService
• 유효성 검사: re 정규표현식, 수동 로직
• 백그라운드 작업: BackgroundTasks
• 세션 처리: FastAPI session middleware
• API 키 관리: dotenv (.env), st.secrets

- 구현 의도

• 단순한 CRUD API를 넘어서 실서비스에서 필요한 유효성 검사, 예외 처리, 중복 방지 등 실제 운영 환경에서 중요한 요소들을 고려해 설계.
• 실무에서 바로 사용 가능한 사용자 인증 API를 처음부터 끝까지 설계 및 개발
• DB 설계, 암호화, 유효성 검사, 예외처리, 이메일 전송 등 실무 요구 사항 반영
• 보안 및 사용자 경험을 모두 고려한 구조라는 점에서 팀 프로젝트 혹은 SaaS 백엔드 개발에 바로 투입 가능

---

디렉터리 구조 1: controllers

 

서비스가 실행되고 운영될 수 있는 핵심 기능들이 담겨 있는 디렉터리

---

◆ babies_controllers.py

- 아이의 등록/조회/삭제의 기능을 구현해 놓은 파일

- FastAPI + SQLAlchemy로 아이 정보를 DB에 추가하는 API 엔드포인트 구현

 

[주요 내용] 
해당 기능은 로그인된 사용자가 자신의 아이 정보를 입력하면, 중복 여부를 확인 후 DB에 저장.

• 사용자 유효성 검증 (존재하는 사용자만 등록 가능)
• 이름 중복 방지 (동일 사용자의 아이 이름 중복 차단)
• DB 커밋/롤백 처리 및 예외 관리
• 요청/응답 로깅 및 에러 로깅 구현

---

◆ dependencies.py

- 보안성이 중요한 사용자의 비밀번호를 안전하게 저장하고 검증하기 위해 'passlib' 라이브러리의 'bcrypt' 해시 알고리즘 적용

- 세션을 열고 닫는 구조를 'yield' 기반으로 구성하여 자원 관리와 예외 발생 시 안정성까지 고려

 

[주요 내용]

• 평문 비밀번호 → 암호화된 해시로 저장
• 로그인 시 해시된 비밀번호와 입력값 안전하게 비교
• SQLAlchemy 세션 안전하게 관리

[고도화 아이디어]

추가 기능	설명	포인트
JWT 로그인 연동	비밀번호 검증 후 JWT 토큰 발급	"Stateless 인증 방식으로 토큰 기반 로그인 구현 경험"
해시 알고리즘 관리	schemes=["bcrypt", "argon2"] 등 확장 가능	"해시 알고리즘 유연성 확보"
테스트 코드 작성	pytest로 유닛 테스트	"인증 기능에 대한 테스트 가능"

---

◆ music_controllers.py

- Jamendo Music API를 활용하여 테마에 맞는 자장가를 검색하고 추천해 주는 기능 수행

- 프론트엔드 사용자 경험을 고려해 음악 테마를 추상화된 키워드로 매핑하고,  그에 맞는 음원을 외부 API에서 동적으로 가져오는 구조로 설계

 

[주요 내용]

• 환경변수 관리: API 키와 같은 민감 정보를 코드에 직접 노출하지 않고, .env 파일로 안전하게 관리
• 에러 방어 코드: 필수 환경변수가 설정되지 않았을 경우를 대비해 방어 로직을 추가하여 신뢰성 향상
• 태그 기반 검색: 사용자가 선택한 테마를 Jamendo API의 태그로 매핑하여 개인화된 음악 추천 기능 구현
• 유연한 검색 기능: tag와 limit 파라미터 활용, 다양한 검색 옵션을 파라미터화하여 재사용성과 확장성을 고려한 함수형 설계

※ 함수형 설계
함수형 설계는 블랙박스처럼 작동하는 함수들을 만드는 프로그래밍 방법이다. 즉, 함수 안에서 무슨 일이 일어나는지 신경 쓸 필요 없이, 같은 입력값을 넣으면 항상 같은 결과를 돌려주고, 밖에 있는 다른 것들을 건드리지(변경하지) 않도록 코드를 짜는 방식이다. 이렇게 하면 코드가 훨씬 예측하기 쉽고, 고치거나 재사용하기도 편해진다.

---

◆ storage_s3.py

- 추후 aws 배포를 고려한 파일

- 생성된 이미지를 aws s3 버킷에 저장하고, 저장된 파일들을 불러올 수 있도록 구현

 

---

◆ story_controller.py

- 이 프로젝트의 서비스의 핵심 기능이 구현되는 파일

- 사용자 맞춤형(아이, 테마) 동화를 생성하고, 그에 맞는 삽화와 음성을 AI로 자동 생성

- 동화 생성 / 생성된 동화를 음성 파일, 이미지로 변환 / 이미지를 흑백 이미지로 변환

- 생성된 동화 및 이미지들을 볼 수 있는 갤러리를 위한 기능 구현

- 컨텐츠 생성/조회/삭제 기능 구현

 

[주요 내용]

• GPT-4o-mini 기반 동화 생성
• OpenAI TTS로 음성 동화 제공
• Stability AI 기반 동화 삽화 생성 (프롬프트 자동화)
• OpenCV로 흑백 라인 드로잉 자동 변환
• 캐시 기반 재사용 (속도 개선 및 비용 절감)
• 향후 배포를 고려하여 S3 / 로컬 저장소 이중화
• 사용자별 이미지 관리 및 삭제 기능
• Streamlit 기반 웹 UI 구현

[고도화 아이디어]

- 사용자 맞춤형

기능	설명
개인화된 일러스트	사용자가 직접 캐릭터 외형(머리색, 성별 등)을 고르면 이를 프롬프트에 반영하여 AI 그림 생성
다회차 스토리 저장	같은 캐릭터로 여러 편의 이야기를 생성하여 연속 동화 구성
다국어 지원	OpenAI 번역 기능 연동하여 영어/일본어/중국어 등으로도 동화 제공
음성 스타일 선택	아이 목소리, 엄마 목소리, 나레이션 등 다양한 스타일로 선택

 

- 기술 스택

항목	고도화 내용
Docker & 배포 자동화	FastAPI, DB, Streamlit 등을 Docker로 묶고 GitHub Actions + EC2로 자동 배포
테스트 도입	pytest로 기능별 단위 테스트 작성 (예: 동화 생성, 캐시 저장 등)
모니터링	Sentry, Prometheus, Grafana로 에러 추적 및 성능 모니터링
비동기 처리 전환	이미지, 오디오 요청을 await 기반으로 비동기화

▶ Streamlit은 완전한 비동기를 지원하지 않아, async def는 제한적으로만 작동하는 애로사항이 있었음.

---

◆ users_controller.py

- 사용자 회원가입, 로그인, 아이디/비밀번호 찾기, 비밀번호 변경, 회원 탈퇴 기능을 FastAPI 기반으로 구축한 RESTful API 모듈

- 실시간 유효성 검사, 보안 규칙 적용, 이메일 발송 자동화(BackgroundTasks), DB 연동 및 세션 기반 로그인 상태 유지 등 웹 서비스의 핵심 인증 기능 설계 및 구현.

- 이메일은 비동기 처리를 위해 FastAPI의 BackgroundTasks 기능을 활용하여 서버 응답 속도 저하 없이 처리

 

[주요 기능 및 특징]

• 회원가입 (Signup): 사용자명/비밀번호 규칙 검증, 중복 확인, 비밀번호 해싱 저장, 환영 이메일 자동 발송
• 로그인 (Login): 사용자 인증, 세션(session) 기반 로그인 상태 유지
• 아이디 찾기: 이메일 기반 사용자 이름 복구 후, 이메일 자동 발송
• 비밀번호 재설정: 임시 비밀번호 생성 → 이메일 발송 및 DB 반영
• 비밀번호 변경: 현재 비밀번호 검증 → 새 비밀번호 규칙 확인 → 이메일 알림 발송
• 회원 탈퇴: 사용자의 게시물/동화 삭제, 사용자 정보 삭제, 탈퇴 이메일 발송

[보안 및 유효성 검사]

항목	적용 내용
비밀번호 규칙	최소 10자, 대문자+소문자+숫자+특수문자 포함 정규식 검사
사용자명 규칙	영문 소문자+숫자만 허용 (정규식)
비밀번호 암호화	bcrypt 기반 해싱 처리 (passlib)
비밀번호 일치 확인	현재 비밀번호 검증 및 새 비밀번호 재확인
세션 관리	request.session을 통한 사용자 로그인 상태 추적
예외 처리 및 로깅	상황별 HTTPException, try-except, logger 활용하여 예외 추적 및 기록

 

[이메일 발송 (BackgroundTasks)]

이벤트	이메일 내용
회원가입	환영 이메일 전송 (send_welcome_email)
아이디 찾기	사용자명 포함 이메일 발송 (send_username_email)
비밀번호 재설정	임시 비밀번호 이메일 전송 (send_temp_pw_email)
비밀번호 변경	비밀번호 변경 안내 이메일 전송 (send_changed_pw_email)
회원 탈퇴	탈퇴 확인 이메일 발송 (send_bye_email)

 

[고도화 아이디어]

• OAuth 기반 소셜 로그인(Google, Kakao 등)으로 확장 가능
• 비밀번호 변경/인증 흐름을 WebSocket, 인증코드 기반으로 고도화 가능
• Celery + Redis 기반으로 이메일 발송을 더 안정적이고 확장성 있게 변경 가능
• 인증 토큰 방식(JWT)을 도입하여 API 보안 강화 가능

---

◆ video_controller.py

- 사용자가 선택한 동화/동요 테마에 맞는 음악을 유튜브에서 자동으로 검색하여, 관련된 영상 추천 리스트를 생성하는 기능.

- Google의 YouTube Data API v3를 활용하여 실시간으로 인기 키워드 기반 동요 영상을 가져오는 기능 구현.

 

[주요 기능]

• 테마 기반 검색: "잔잔한 피아노", "기타 멜로디" 등 키워드를 자동 매핑하여 유튜브 검색
• API 키 사용: .env 또는 st.secrets를 통한 보안 키 관리
• 동영상 정보 추출: 제목, URL, 썸네일 등을 포함한 결과 리스트 반환
• 예외 처리: API 호출 실패나 결과 없음에 대한 안정적인 처리 포함

---

다음 내용

[파이썬] AI 활용 웹 서비스 개발 기록 : 3 emails 설명