프로젝트 기간 | 2025.09.01 ~ ing
토토리는 난독 아동과 읽기에 어려움을 겪는 아동에게 관심사 기반 맞춤 동화, 수준별 읽기 학습, 취약 음운 퀴즈를 제공하는 모바일 학습 서비스입니다. 보호자와 특수교사는 정량화된 리포트를 통해 아동의 학습 현황과 오류 추세를 확인할 수 있습니다.
Totori_BE는 토토리의 중앙 API 및 데이터 서버입니다. iOS 앱의 요청을 인증하고 회원·동화·학습 데이터를 관리하며, AI 서버와 이미지·음성 생성 서비스를 하나의 학습 흐름으로 연결합니다.
- 일반 로그인, JWT 인증, Kakao OAuth
- 아동·보호자 회원 관리와 연결 코드 발급
- 맞춤 동화 생성 요청 및 콘텐츠 저장
- 낭독 결과·퀴즈·배지·출석 관리
- 주간·전체 학습 리포트 제공
| 정윤아 | 복지희 | 정유진 |
|---|---|---|
 |
 |
 |
@laura-jung |
@jettieb |
@nomellc |
| Backend Developer | Backend Developer | Backend·AI Developer |
| 동화 이미지 생성 외부 API 및 비동기 처리, elevenLabs API 연결, 뱃지 API 담당, 동화 낭독 완료 API S3 세팅 |
학습 리포트 조회 및 통계 데이터 API 구현, 동화 메인페이지 API 구현, 배포 및 서버 운영 환경 구축, S3 인스턴스 생성 |
AI 동화 생성 및 낭독 기능 개발, 퀴즈 학습 관련 백엔드 API 구현, 자체/소셜 로그인 기반 인증·인가 기능 구현, 회원 관리 및 아동-보호자 연결 기능 개발 |
- Java 17
- Spring Boot 3.5
- Spring Data JPA
- Spring Security·OAuth 2.0·JWT
- MySQL
- Redis
- Spring WebFlux
WebClient - AWS S3 SDK
- Springdoc OpenAPI
- Gradle Wrapper
Totori_BE/
├── src/main/java/ctrlS/totori/
│ ├── attendance/ # 출석
│ ├── auth/ # 로그인·회원가입·OAuth
│ ├── badge/ # 배지
│ ├── book/ # 동화 생성·조회·읽기 기록
│ ├── connect/ # 보호자와 아이 연결
│ ├── member/ # 회원 정보
│ ├── quiz/ # 퀴즈 생성·채점
│ ├── report/ # 주간·종합 학습 리포트
│ └── global/ # 보안, 예외, Redis, S3, 공통 응답
├── src/main/resources/
│ └── application.yml # 직접 생성, Git 추적 제외
├── src/test/
├── build.gradle
├── settings.gradle
└── gradlew
- Java 17
- MySQL 8
- Redis 7
- 실행 중인
Totori_AI서버
동화의 이미지·음성 기능까지 사용하려면 AWS S3, Stability AI, ElevenLabs 자격 증명이 필요합니다. Kakao 로그인을 사용할 경우 Kakao Developers 애플리케이션도 필요합니다.
백엔드의 기본 브랜치는 develop입니다.
git clone -b develop https://github.com/Team-CtrlS/Totori_BE.git
cd Totori_BE로컬 서비스를 사용하거나 Docker로 실행할 수 있습니다.
docker run --name totori-mysql \
-e MYSQL_ROOT_PASSWORD=totori \
-e MYSQL_DATABASE=totori \
-p 3306:3306 -d mysql:8
docker run --name totori-redis \
-p 6379:6379 -d redis:7-alpinesrc/main/resources/application.yml을 생성합니다. 이 파일과 환경별 설정 파일은 .gitignore에 포함되어 있습니다.
application.yml 파일의 예시는 아래 링크에서 확인 가능합니다.
application.yml
JWT 키는 256비트 이상의 값을 Base64로 인코딩해야 합니다.
openssl rand -base64 32출력값을 jwt.secret에 입력하세요.
Kakao 로그인을 사용한다면 Kakao Developers 콘솔에 아래 Redirect URI를 등록합니다.
http://localhost:8080/login/oauth2/code/kakao
AI 서버의 기본 주소는 http://localhost:8000입니다. 다른 호스트나 포트를 사용한다면 fastapi.base-url을 변경하세요.
./gradlew bootRun기본 포트는 8080입니다.
# 전체 빌드와 테스트
./gradlew clean build
# 테스트만 실행
./gradlew test
# 컴파일 확인
./gradlew classes주요 API 그룹:
/api/auth 인증·회원가입
/api/members 회원 정보
/api/connect 보호자·아이 연결
/api/books 동화
/api/quiz 퀴즈
/api/reports 학습 리포트
/api/badges 배지
/api/child/attendance 출석
| 서비스 | 용도 | 설정 |
|---|---|---|
| Totori_AI | 동화·퀴즈·음성 분석 | fastapi.base-url |
| AWS S3 | 이미지·오디오 저장 | cloud.aws.* |
| Stability AI | 동화 이미지 생성 | stability.api-key |
| ElevenLabs | TTS 오디오 생성 | elevenlabs.* |
| Kakao OAuth | 소셜 로그인 | spring.security.oauth2.* |
별도의 사전 구축 DB 덤프는 필요하지 않습니다. 빈 totori 데이터베이스를 생성하고 spring.jpa.hibernate.ddl-auto=update로 실행하면 JPA 엔티티를 기준으로 테이블이 만들어집니다. 회원과 학습 데이터는 앱 또는 Swagger API를 통해 생성합니다.
| 데이터 | 저장 위치 | 재현 방법 |
|---|---|---|
| 회원·동화·퀴즈·리포트 | MySQL | 빈 DB 생성 후 API 호출 |
| JWT·로그아웃 토큰·연결 코드 | Redis | Redis 실행 후 애플리케이션이 자동 생성 |
| 동화 이미지·음성 | AWS S3 | S3 버킷과 자격 증명 설정 |
| 읽기 분석 임시 결과 | AI 서버의 Redis | 낭독 분석 API 호출 |
동화 생성 과정에서 이미지 생성과 TTS 생성을 순차 처리하지 않고 병렬 처리하도록 개선했습니다.
| 항목 | 개선 전 | 개선 후 |
|---|---|---|
| 동화 생성 처리 시간 | 약 60초 | 약 42초 |
| 단축률 | - | 약 30% |
측정 시간은 발표자료의 개발 환경 기준이며, 외부 API 응답 시간과 네트워크 환경에 따라 달라질 수 있습니다.
OpenAI, AWS S3, Stability AI, ElevenLabs, Kakao OAuth의 실제 키와 생성 결과물은 보안 및 용량 문제로 저장소에 포함하지 않습니다. README의 application.yml 예시에 각자 발급한 값을 입력해야 전체 기능을 재현할 수 있습니다.
현재 저장소는 application.yml, application-local.yml, application-prod.yml을 추적하지 않습니다. src/main/resources/application.yml을 직접 생성했는지 확인하세요.
일반 문자열이 아니라 Base64로 인코딩된 충분히 긴 키가 필요합니다. openssl rand -base64 32로 새 키를 생성하세요.
Totori_AI가 실행 중인지 확인한 뒤 다음 주소를 호출해 보세요.
curl http://localhost:8000/백엔드의 fastapi.base-url과 AI 서버의 실제 주소도 일치해야 합니다.
FastApiStoryClient에는 /ai/story/generate 호출이 남아 있지만 현재 AI 저장소가 제공하는 음성 기반 동화 생성 경로는 /ai/story/make입니다. /generate를 사용하는 기능은 두 저장소의 계약을 먼저 맞춰야 합니다.
현재 별도의 라이선스 파일이 없습니다.