수험생 개인 응원 책상 서비스의 production backend입니다.
- Spring Boot / JPA / MySQL 프로젝트 기반
- 개인 책상 도메인
- 비회원 guest identity와 1년 HttpOnly cookie
- Supporter token 기반 개인 책상 조회
- 비회원 편지 작성
- 편지별 public/private 저장
nickname_override기반 작성자 표시 계약- 카드 payload schema version 및 최대 3페이지 검증
- 책상 object 배치 저장
- Daily / Time Capsule unlock 계산
- unlock된 public 편지 조회
- 카카오 인가 코드 기반 로그인 및 회원 자동 가입
- JWT access token과 회전형 refresh token (HttpOnly 쿠키 지원)
- 로그인 회원 편지 작성 및 닉네임 fallback
- 로그인 사용자의 개인 책상 생성·설정·접수 관리
- 잠금 보호를 포함한 받은 편지 조회·읽음·삭제·바구니 이동
- S3 presigned URL 이미지 업로드 및 완료 검증
- 광고 기간·위치 관리와 노출·시청·클릭 기록, 광고 시청으로 편지지·소품 해제
- 반응·답장·신고·작성자 숨기기, 보낸 응원 목록과 삭제
- 상품 가격표 기반 주문·승인(개발용 mock)과 유료 요소(아크릴 부적·보석) 결제 검증
- 찰떡(충전식 포인트): 토스페이먼츠 충전 승인, 잔액·내역, 구매 시 결제 완료 주문 발급
- 책상 설정 변경 시 아직 열리지 않은 편지의 공개 시각 재계산
- 회원·비회원 트래픽 이벤트 및 운영자 집계
교실 단위 응원은 Post-MVP 범위이며 구현하지 않았습니다.
부하 시험에는 loadtest 또는 prod 프로필에서 /api/load-test/accounts를 사용할 수 있습니다. 운영 서버에서는 32자 이상의 LOAD_TEST_PROVISION_KEY를 설정해야 시험 회원과 JWT·리프레시 토큰이 발급되며, 키가 없으면 403을 반환합니다. 시험 계정은 TEST 제공자로 구분됩니다. 실행 절차는 ../chak-sim/README.md를 참고하세요.
- Java 17
- Spring Boot 4.0.6
- Spring Web MVC / Data JPA
- MySQL, Flyway, H2(test)
- Lombok, springdoc-openapi
- AWS SDK for Java 2.x / S3
MySQL에 chak database를 만든 뒤 실행합니다.
스키마는 Flyway가 관리하며 자동 baseline은 기본적으로 꺼져 있습니다. 빈 DB는 그대로 실행하면 V1부터 적용됩니다.
기존 Hibernate 자동 생성 DB를 처음 전환할 때는 먼저 백업하고 아래 중복 데이터를 확인합니다.
SELECT owner_id, COUNT(*)
FROM personal_desks
WHERE owner_id IS NOT NULL
GROUP BY owner_id
HAVING COUNT(*) > 1;결과가 없어야 하며, 기존 테이블이 V1 스키마와 일치하는지 확인한 배포에서만 FLYWAY_BASELINE_ON_MIGRATE=true를 한 번 사용합니다. 성공 후에는 즉시 false로 되돌립니다. V2는 다른 변경보다 먼저 사용자당 개인 책상 하나의 고유 제약을 추가하므로 중복이 있으면 기능 스키마를 건드리기 전에 중단됩니다.
export DB_URL='jdbc:mysql://localhost:3306/chak?serverTimezone=Asia/Seoul&characterEncoding=UTF-8'
export DB_USERNAME='root'
export DB_PASSWORD='your-password'
export KAKAO_CLIENT_ID='your-kakao-rest-api-key'
export KAKAO_CLIENT_SECRET='your-client-secret-if-enabled'
export GOOGLE_CLIENT_ID='your-google-oauth-client-id'
export GOOGLE_CLIENT_SECRET='your-google-oauth-client-secret'
export JWT_SECRET='at-least-32-byte-production-secret'
export S3_BUCKET='chak-media'
export AWS_REGION='ap-northeast-2'
# 개발: PAYMENT_PROVIDER 기본값은 mock(실제로 돈이 오가지 않는 가짜 결제)
# 운영자 알림: DISCORD_WEBHOOK_URL(디스코드 웹훅, 비우면 로그로만), ALERT_ENVIRONMENT(알림 제목에 붙는 환경 이름)
# prod에서는 AWS 시크릿 chak/prod/app의 모든 문자열 키를 시작 시 설정으로 읽는다(환경변수가 우선, CHAK_SECRETS_ID로 변경)
# 찰떡 충전: CHALTTEOK_PROVIDER=mock(기본)|toss|none, 토스는 TOSS_SECRET_KEY 필요
# 운영: 아래 프로필을 켜면 기본 JWT 시크릿으로는 기동 실패, 쿠키 Secure 기본 true, Swagger 기본 비활성,
# 결제 기본값 none(승인 거부). 실제 PG 연동 전에는 결제를 열지 마세요.
# export SPRING_PROFILES_ACTIVE=prod
export ADMIN_KAKAO_IDS='123456789,987654321'
# export ADMIN_GOOGLE_IDS='google-sub-1,google-sub-2'
./gradlew bootRunSwagger UI: http://localhost:8080/swagger-ui/index.html
상세 요청·응답 및 프론트 연동 규칙: docs/API.md
DB 구조: docs/DATABASE.md
배포(AWS, 자동 업데이트): docs/DEPLOYMENT.md
프론트와 API가 서로 다른 도메인이면 CORS_ALLOWED_ORIGINS에 프론트 Origin을 추가하고, 비회원 쿠키와 리프레시 쿠키를 위해 GUEST_COOKIE_SAME_SITE=None, REFRESH_COOKIE_SAME_SITE=None, GUEST_COOKIE_SECURE=true, REFRESH_COOKIE_SECURE=true(HTTPS)를 설정합니다. 같은 사이트(서브도메인 포함)면 기본값 Lax를 유지합니다.
./gradlew testGET /api/public/desks/{supporterToken}
GET /api/public/desks/{supporterToken}/messages?page=0&size=20
POST /api/public/desks/{supporterToken}/messages
GET /api/public/health
GET /api/public/messages/mine
DELETE /api/public/messages/{messageId}
PUT /api/public/messages/{messageId}/reaction
POST /api/public/messages/{messageId}/report
GET /api/public/replies/mine
POST /api/public/payments/orders
POST /api/public/unlocks
GET /api/public/ads?placement=DESK
POST /api/public/ads/{advertisementId}/events
POST /api/public/analytics/events
비회원 편지 작성 시 chak_guest_id cookie가 없으면 서버가 새 guest identity를 만들고 HttpOnly cookie를 발급합니다.
{
"nickname": "민준",
"kind": "CARD",
"visibility": "PUBLIC",
"schemaVersion": 1,
"card": {"pages": [{"id": "page-1", "elements": []}]},
"object": {
"representationType": "LETTER",
"assetId": "letter-basic",
"color": "cream",
"x": 50,
"y": 50,
"rotation": 0,
"scale": 1,
"zIndex": 1,
"metadata": {}
}
}card와 object.metadata는 frontend renderer와 합의할 versioned JSON입니다. 현재 schemaVersion=1, 카드 1~3페이지만 허용합니다.
- 소셜 로그인:
POST /api/auth/kakao,POST /api/auth/google - 토큰 재발급:
POST /api/auth/refresh - 로그아웃:
POST /api/auth/logout - 내 정보:
GET /api/users/me - 개인 책상 생성·관리: 로그인 필수
- 개인 Supporter link 조회/편지 작성: 비로그인 허용
- 회원 편지:
author_user_id+ 선택적nickname_override - 비회원 편지:
author_guest_id+ 필수nickname_override - 표시 이름:
nickname_override우선, 없으면 회원의 현재display_name