AfterNote-Server

마지막 순간의 온기를 전하다 - 애프터노트는 사후에 전달되는 편지 서비스입니다.

AfterNote 프로젝트의 백엔드 서버입니다.

📊 목차

• 기술 스택
• 시스템 아키텍처
• ERD (Entity Relationship Diagram)
• 프로젝트 구조
• 시작하기

---

🛠️ 기술 스택

• Backend: Java 17, Spring Boot 3.2.1
• ORM: Spring Data JPA, Hibernate 6.4.1
• Database: MySQL 8.4
• Authentication: JWT, Spring Security
• External APIs: Google Gemini, AWS S3
• Encryption: ChaCha20-Poly1305 (모바일 최적화)
• Build Tool: Gradle 8.12
• Containerization: Docker, Docker Compose
• Testing: JUnit 5, Mockito

---

🏗️ 시스템 아키텍처

현재 구조

아키텍처 선택 이유

컴포넌트	선택 이유
VPC (Virtual Private Cloud)	보안이 필요한 금융/개인 정보를 다루기 때문에 격리된 네트워크 필요, AWS 자유로운 설정 제공
NginX (리버스 프록시)	클라이언트 요청을 Spring 서버로 라우팅, SSL 인증서 관리(Certbot), 요청 분산 처리
Public Subnet	외부에서 접근 가능한 네트워크 영역, 모바일 클라이언트의 HTTPS 통신 지원
Spring Boot (EC2)	안정적인 Java 기반 애플리케이션, 비즈니스 로직 처리, 다양한 라이브러리 생태계
MySQL 8.4	ACID 준수로 데이터 무결성 보장, 복잡한 쿼리와 JOIN 연산 지원, 타임레터/감정 데이터의 신뢰성 필수
Redis	토큰(JWT Refresh) 빠른 조회/만료 관리 (TTL 설정), Gemini API 감정 분석 결과 캐싱 (1일), 세션 관리
AWS S3	대용량 미디어 파일(사진, 음악) 저장소로 EC2 스토리지 압박 해소, Presigned URL로 보안성 강화
ChaCha20-Poly1305	모바일 환경 최적화 + 보안: SNS 계정 정보 암호화, 경량이면서도 높은 보안성 제공

추후 구조

추후 아키텍처 변화

변경 사항	선택 이유
RDS (Managed Database)	EC2에서 직접 DB 관리 → AWS 자동 백업/업데이트/복구로 데이터 유실 위험 제거, 유언장 데이터 안전성 확보
ALB (Application Load Balancer)	공개되는 것은 ALB IP만으로 EC2 실제 IP 은닉 → 해커 직접 공격 어려움, DDoS 공격 방어
ALB를 통한 SSL 관리	인증서 관리를 ALB 한 곳에만 집중 → 만료로 인한 보안 구멍 위험 감소
WAF (Web Application Firewall) 연동	ALB 앞단에 WAF 적용 가능 → SQL Injection, 악의적 봇 공격 차단
수평 확장 준비	ALB로 여러 EC2 인스턴스에 트래픽 분산 가능 → 추후 트래픽 증가 시 확장성 확보

---

📊 ERD (Entity Relationship Diagram)

🎯 핵심 엔티티 관계도

📋 엔티티 상세 정보

테이블	주요 필드	설명
USERS	id, email, password, name, provider	사용자 계정 정보
RECEIVER	id, name, phone, email, relationship	수신자 정보
AFTERNOON_NOTE	id, category, title, leave_message	애프터노트 메인
AFTERNOON_SECURE_CONTENT	id, key_name, encrypted_value	암호화된 SNS 계정정보
AFTERNOON_RECEIVER	id, afternote_id, receiver_id	애프터노트-수신자 N:N
AFTERNOON_NOTE_PLAYLIST	id, atmosphere, memorial_photo_url	플레이리스트 정보
AFTERNOON_PLAYLIST_ITEM	id, playlist_id, song_id	플레이리스트 내 곡
TIMELETTER	id, title, content, send_at, status	타임레터 메인
TIMELETTER_MEDIA	id, s3_key	타임레터 미디어
TIMELETTER_RECEIVER	id, timeletter_id, receiver_id, delivered_at	타임레터-수신자 N:N
MIND_RECORD	id, content, song_id	마인드레코드
EMOTION	id, keyword	감정 키워드
DEEP_THOUGHT	id, content, category	깊은 생각
SONG	id, title, artist, cover_url	곡 정보
USER_RECEIVER	id, user_id, receiver_id	사용자-수신자 N:N

---

🔄 주요 관계

1:1 관계

• AFTERNOTE ↔ AFTERNOON_NOTE_PLAYLIST (1:1)

1:N 관계

• USERS → AFTERNOON_NOTE (1:N)
• USERS → TIMELETTER (1:N)
• USERS → MIND_RECORD (1:N)
• AFTERNOON_NOTE → AFTERNOON_SECURE_CONTENT (1:N)
• AFTERNOON_NOTE → AFTERNOON_PLAYLIST_ITEM (1:N)
• TIMELETTER → TIMELETTER_MEDIA (1:N)

N:N 관계 (중간 테이블 사용)

• AFTERNOON_NOTE ↔ RECEIVER (via AFTERNOON_RECEIVER)
• TIMELETTER ↔ RECEIVER (via TIMELETTER_RECEIVER)
• USERS ↔ RECEIVER (via USER_RECEIVER)
• AFTERNOON_NOTE_PLAYLIST ↔ SONG (via AFTERNOON_PLAYLIST_ITEM)

---

💾 데이터 흐름

1️⃣ 사용자 가입 USERS 테이블에 저장 RECEIVER 등록 가능

2️⃣ 애프터노트 생성 AFTERNOON_NOTE 생성 ├─ SOCIAL: SECURE_CONTENT에 암호화된 계정정보 ├─ GALLERY: 기본 정보 └─ PLAYLIST: PLAYLIST + PLAYLIST_ITEM 생성

3️⃣ 타임레터 작성 TIMELETTER 생성 ├─ TIMELETTER_MEDIA 저장 └─ TIMELETTER_RECEIVER로 수신자 등록

4️⃣ 마인드레코드 기록 MIND_RECORD 생성 ├─ EMOTION 감정 키워드 저장 └─ SONG 참조 (선택사항)

🟡 Domain Layer (비즈니스 로직)

모듈	설명	주요 클래스
auth/	회원가입, 로그인, 소셜 로그인	AuthController, AuthService, SocialLoginFactory
user/	사용자 관리 (프로필, 설정, 탈퇴)	UserController, UserService, UserRepository
afternote/	애프터노트 (SOCIAL/GALLERY/PLAYLIST)	AfternoteController, AfternoteService, AfternoteValidator
timeletter/	타임레터 (사후 발송 편지)	TimeLetterController, TimeLetterService
receiver/	수신자 관리	ReceiverController, ReceiverService
mindrecord/	마인드레코드 & 감정 분석	MindRecordService, EmotionService, GeminiService
image/	이미지/파일 처리 (S3)	ImageController, S3Service

🔵 Global Layer (공통 기능)

모듈	설명
jwt/	JWT 토큰 생성/검증 (JwtTokenProvider, JwtAuthenticationFilter)
util/	유틸 클래스 (ChaChaEncryptionUtil: ChaCha20-Poly1305)
service/	글로벌 서비스 (GeminiService, EmailService, TokenService)
config/	Spring 설정 (SecurityConfig, RestTemplateConfig, CacheConfig)
resolver/	Custom Resolver (@UserId 어노테이션 처리)
exception/	예외 처리 (CustomException, ErrorCode: 40+ 에러 코드)
common/	공통 응답 포맷 (ApiResponse)

---

📋 주요 패턴

Strategy Pattern (소셜 로그인)

auth/service/social/ ├── SocialLoginService (Interface) ├── KakaoLoginService (구현) ├── GoogleLoginService (구현) └── NaverLoginService (구현)

→ SocialLoginFactory가 런타임에 올바른 구현체 선택

Validator Pattern (데이터 검증)

afternote/service/ ├── AfternoteValidator - 카테고리별 필드 검증 ├── AfternoteService - 비즈니스 로직 └── AfternoteRelationService - 관계 데이터 처리

Repository Pattern (데이터 접근)

• Spring Data JPA를 사용한 자동 쿼리 생성
• JpaRepository 상속으로 기본 CRUD 제공

🚀 시작하기

환경 설정

1) 로컬 개발 환경 (앱 로컬 실행 + DB/Redis Docker)

1. DB/Redis 로컬 인프라를 먼저 실행합니다.

docker compose -f docker-compose.local.yml up -d

2. IntelliJ Run Configuration의 Environment variables에 아래 값을 넣습니다.

SPRING_PROFILES_ACTIVE=local
DB_HOST=localhost
DB_PORT=3306
DB_NAME=afternote-db
DB_USERNAME=admin
DB_PASSWORD=password
REDIS_HOST=localhost
REDIS_PORT=6379
JWT_SECRET=...
CHACHA20_SECRET_KEY=...
SERVER_PORT=8080
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
ADMIN_EMAIL=your-admin@example.com
ADMIN_PASSWORD=your-secure-password
APP_ANDROID_STORE_URL=https://play.google.com/store/apps/details?id=your.package

3. IntelliJ에서 애플리케이션을 직접 실행합니다.

• 로컬 프로파일: local
• Swagger UI: http://localhost:8080/swagger-ui.html

2) 배포 환경 (Docker + RDS)

운영 EC2의 ~/deploy/.env 는 레포의 deploy/production.env(로컬, gitignore) 를
GitHub Secret DEPLOY_PRODUCTION_ENV 로 올린 뒤, main Deploy 워크플로가 덮어쓴다.

cp deploy/production.env.example deploy/production.env   # 값 채우기 (Sentry DSN 포함)
./scripts/push-deploy-env-secret.sh                      # Secret 갱신
# 이후 main push → EC2 ~/deploy/.env 동기화 + 컨테이너 재기동

Afternote-BE는 public 레포라 DB/JWT 등 시크릿을 git에 커밋하지 않는다.
로컬에서 deploy/production.env만 수정하고, 배포 전에 위 스크립트로 Secret을 갱신하면 된다.

레거시 로컬 compose용:

cp .env.production.example .env.production
docker compose --env-file .env.production up -d

3) AWS 그린필드 + off-hours 스케줄 (Terraform)

VPC/EC2/RDS/EIP와 개발 off-hours(03:00~12:00 KST) Stop/Start를 Terraform으로 생성합니다.

설정·컷오버·구 리소스 폐기: infra/terraform/README.md

cd infra/terraform
cp terraform.tfvars.example terraform.tfvars   # key pair, ssh CIDR, db_password, alert_email
terraform init && terraform apply
terraform output elastic_ip      # DNS A + GitHub EC2_HOST
terraform output jdbc_url_hint   # .env.production DB_URL

실행 방법

로컬 인프라(DB/Redis) 실행:

docker compose -f docker-compose.local.yml up -d

로컬 앱 실행:

IntelliJ Run

로컬 인프라 중지:

docker compose -f docker-compose.local.yml down

배포 스택 실행:

docker compose --env-file .env.production up -d

테스트 실행:

./gradlew test

운영 로그 확인:

docker compose --env-file .env.production logs -f afternote-server

---

🔑 주요 기능

🔐 보안

• ✅ JWT 기반 인증
• ✅ ChaCha20-Poly1305 암호화 (SNS 계정정보)
• ✅ 소셜 로그인 (카카오, 구글)
• ✅ 생체 인증 연동 (준비 중)

📝 애프터노트

• ✅ SOCIAL: SNS 계정 관리
• ✅ GALLERY: 사진첩 관리
• ✅ PLAYLIST: 음악 플레이리스트

📬 타임레터

• ✅ 사후 자동 발송
• ✅ 스케줄 관리
• ✅ 다중 수신자 지원

🧠 감정 분석

• ✅ Gemini AI를 통한 감정 요약
• ✅ 7일 감정 통계
• ✅ Redis 캐싱

---

🚨 운영 모니터링 · 장애 플레이북

장애 메일/이상 징후가 보이면 이 순서로 본다.

1. CloudWatch 대시보드 — EC2 / RDS / Lambda 중 어디가 이상한지
   https://ap-northeast-2.console.aws.amazon.com/cloudwatch/home?region=ap-northeast-2#dashboards:name=afternote-ops
2. Sentry Issues — 예외 스택·URL·release
   https://sentry.io → 프로젝트 java-spring-boot → Issues → Feed
3. 앱 로그 — 이상 징후가 발생한 시각 전후의 stdout https://ap-northeast-2.console.aws.amazon.com/cloudwatch/home?region=ap-northeast-2#logsV2:log-groups/log-group/%2Fafternote%2Fapp
4. 헬스 — 앱·DB·Redis 분리
   GET https://afternote.kro.kr/actuator/health
db / redis 중 DOWN이면 그쪽부터 본다. (nginx-health는 리버스 프록시만 살아 있는지)

알람 메일: Terraform alert_email → SNS afternote-scheduler-alerts
env 변경: deploy/production.env 수정 → ./scripts/push-deploy-env-secret.sh → main 배포

---

📖 API 문서

• Swagger UI (local 프로파일): http://localhost:8080/swagger-ui.html
• 모든 API 엔드포인트는 JWT 인증 또는 OAuth 토큰 필요

소셜 로그인 이메일 정책 (#271, #290 이전)

• 이메일 없는 신규 가입은 #290 정책 확정 전까지 지원하지 않습니다. 이메일이 없거나 검증되지 않은 카카오 계정은 신규 가입/이메일 기반 연결 시 400 / 1222 SOCIAL_EMAIL_REQUIRED로 응답합니다. 카카오 이메일 제공 동의 후 재시도해야 합니다.
• 이미 연결된 소셜 계정은 provider + providerId로 우선 로그인하므로 카카오 이메일이 변경되거나 제공되지 않아도 기존 사용자로 로그인합니다.
• 이메일로 찾은 기존 사용자의 로그인 수단은 보존하고 해당 소셜 제공자와 ID를 추가합니다. 기존 동일 제공자에 다른 ID가 연결되어 있으면 409 / 1212로 거절합니다. 이전 데이터의 빈 providerId는 첫 정상 로그인 때 채웁니다.
• 카카오의 유효·검증 이메일 및 구글의 검증 이메일만 이메일 기반 가입/연결에 사용합니다.