🎓 WishConnect — API Server

흩어진 장학금 정보를 한곳에, 나에게 맞는 장학금만 골라주는 장학금 큐레이팅 플랫폼 WishConnect 바로가기 · API 서버

대학생이 장학금을 놓치는 이유는 정보가 없어서가 아니라 너무 흩어져 있어서입니다. WishConnect는 한국장학재단 공공데이터와 전국 대학 장학공지를 매일 자동 수집·정제하고, 사용자의 학적·소득·관심분야에 맞는 공고만 추려서 보여줍니다. 지원까지 이어지도록 마감 알림, 스크랩 아카이빙, AI 자기소개서 작성, 면접 준비까지 한 흐름으로 묶었습니다.

📃 Contents

1. 📌 제출 자료 (ERD · API 명세서 · 아키텍처)
2. 🌱 Developers
3. 🌟 Services
4. 🗂 ERD
5. 📖 API 명세서
6. 💻 Architecture & Deploy
7. 🔧 Tech Stack
8. 🧱 프로젝트 구조
9. ⚙️ Getting Started

📌 제출 자료

자료	위치
ERD	바로가기 ↓ · 원본 이미지
API 명세서	바로가기 ↓ · Notion 명세서 (공개)
아키텍처 다이어그램	바로가기 ↓ · 원본 이미지

🌱 Developers

팀원	역할	주요 업무
윤기찬	BE (리드)	인증·온보딩·마이페이지 전 구간 (LOCAL/카카오/구글/네이버 로그인, JWT, 이메일 인증) 장학금 큐레이팅·검색·상세·달력·홈 요약 알림센터 및 알림 스케줄러 장학금 수집 파이프라인, 관리자 콘솔, 인프라·배포(EC2·RDS·CI/CD)
현종화	BE	대학 장학공지 LLM 파서 및 전용 수집기 레지스트리 중복 장학금 판정·병합 승인 큐 장학금별 자기소개서 문항 생성 면접 예상 질문·면접 준비 자료 생성
hahahanjihun	BE	장학금 검색 품질 개선 (유형 키워드 토큰화, 대학 축약어, 마감 공고 제외) 소셜 온보딩 기본정보 단계 보완 가구정보(household) 저장 정합성 수정
ajm6238	BE	인사이트 콘텐츠 자동 수집 파이프라인 및 목록 조회 API 아카이빙 목록 조회 API (상태 필터·페이지네이션·isScrapped) 장학금 검색 추천 키워드 API

🌟 Services

🔐 인증 · 온보딩

• LOCAL 회원가입(이메일 6자리 인증코드, AWS SES) + 카카오 / 구글 / 네이버 소셜 로그인 3종
• 모두 동일한 자체 JWT를 발급하고 (loginType, providerId)로 계정을 구분합니다.
• 온보딩 4단계 — 기본정보 → 학적정보 → 가구정보·관심사 → 완료. 단계별 저장이라 이어서 진행할 수 있습니다.

🎓 장학금 큐레이팅 · 검색

• 온보딩에서 받은 학적·소득분위·거주지역·관심분야로 조건을 판정해 자격이 되는 공고만 큐레이팅합니다.
• 상세 화면에서 조건별 충족/미충족 판정과 추천 이유를 함께 내려줍니다.
• 키워드·카테고리·정렬(마감임박/최신/금액/정확도) 검색, 추천 검색어, 월별 일정 달력을 제공합니다.
• 한국장학재단 공공 API + 전국 대학 장학공지 크롤링을 매일 배치로 수집하고, LLM으로 자격조건을 구조화합니다.

📁 아카이빙 · 알림

• 관심 공고를 스크랩해 진행 상태와 D-Day로 관리합니다.
• 마감 임박, 신규 맞춤 장학금, 작성 중 지원서 이어쓰기를 알림센터로 보내고 유형별로 켜고 끌 수 있습니다.

✍️ AI 자기소개서 · 면접 준비

• 공고 본문에서 그 장학금의 실제 문항을 뽑아내고, 없으면 기본 문항으로 대체합니다.
• STEP 1 사전 인터뷰 → STEP 2 초안 생성·수정·저장 → 완료의 3단계로 진행합니다.
• 면접이 있는 장학금은 예상 질문과 질문의도·답변 Tip·예시답변·구성가이드를 함께 생성합니다.

💡 인사이트

• 장학금 후기·정보·팁 콘텐츠를 외부에서 수집해 카테고리·출처·태그로 탐색합니다.

🛠 관리자 콘솔

• 수집 현황·이상 탐지·파싱 실패 원본 확인, 수기 등록/수정, 엑셀 일괄 반영, 오등록 신고 처리, 감사 로그.
• 관리자 화면은 인터넷에 열지 않고 SSH 터널로만 접근합니다. (deploy/README.md)

🗂 ERD

42개 엔티티로 구성되어 있습니다. 사용자(users·user_profile)를 중심으로 장학금(scholarship·raw_scholarship·scholarship_condition), 지원서(essay·essay_question·essay_answer·ai_interview), 아카이빙(scrap), 알림(notification), 인사이트(insight) 도메인이 연결됩니다.

이미지가 작게 보이면 클릭해서 원본 크기로 확인할 수 있습니다. → docs/images/erd.png

📖 API 명세서

• 📎 Notion API 명세서 (공통 규칙 · 도메인별 상세 Request/Response · 실패 케이스) → https://app.notion.com/p/API-a480adbca4ca824ba1ce810b83a1e6e7
• Swagger UI — /swagger-ui/index.html (Swagger 는 로컬·운영 모두 ADMIN 권한 뒤에 있습니다. /admin/login.html 에서 관리자 로그인 후 접근하세요. 외부 열람은 위 Notion 명세서를 사용해 주세요.)

공통 규칙

항목	규칙
Base URL	https://api.wish-connect.com (모든 엔드포인트는 /api/v1 하위)
인증	Authorization: Bearer {accessToken} — Access Token 30분 / Refresh Token 14일(Redis 저장)
응답 포맷	모든 응답을 ApiResponse<T> { success, data, message } 로 감쌈
에러 처리	CustomException + ErrorCode enum, 전역 @RestControllerAdvice
페이지네이션	page(1부터), size 쿼리 파라미터
네이밍	리소스는 소문자 복수형, 요청 DTO ~Request / 응답 DTO ~Response, 상태값은 대문자 Enum

도메인별 엔드포인트

🔐 인증 (Auth)

기능	메소드	엔드포인트
LOCAL 회원가입	POST	/api/v1/auth/signup
LOCAL 로그인	POST	/api/v1/auth/login
로그아웃	POST	/api/v1/auth/logout
토큰 재발급	POST	/api/v1/auth/refresh
카카오 / 구글 / 네이버 로그인	POST	/api/v1/auth/{kakao|google|naver}/login
이메일 중복 확인	GET	/api/v1/auth/email/check
이메일 인증코드 발송	POST	/api/v1/auth/email/verification-code
이메일 인증코드 확인	POST	/api/v1/auth/email/verify
비밀번호 재설정 요청	POST	/api/v1/auth/password/reset-request
비밀번호 재설정 코드 확인	POST	/api/v1/auth/password/verify
비밀번호 재설정	POST	/api/v1/auth/password/reset
로그인 아이디 중복 확인	GET	/api/v1/auth/login-id/check
아이디 찾기 요청 / 확인	POST	/api/v1/auth/login-id/find-request, /find

📝 온보딩 · 프로필 (Onboarding)

기능	메소드	엔드포인트
내 프로필 조회	GET	/api/v1/users/me/profile
STEP 1 기본 정보 저장	PUT	/api/v1/users/me/profile/basic
STEP 2 학적 정보 저장	PUT	/api/v1/users/me/profile/academic
STEP 3 가구 정보·관심사 저장	PUT	/api/v1/users/me/profile/household
STEP 4 온보딩 완료	POST	/api/v1/users/me/profile/complete
학교 검색 (자동완성)	GET	/api/v1/universities/search
전공 검색	GET	/api/v1/majors/search
시도 / 시군구 목록	GET	/api/v1/regions, /api/v1/regions/{regionId}/children

👤 마이페이지 (MyPage)

기능	메소드	엔드포인트
내 정보 조회	GET	/api/v1/users/me
비밀번호 변경	PATCH	/api/v1/users/me/password
이메일 중복 확인	POST	/api/v1/users/me/email/check
이메일 변경 인증코드 발송 / 확인	POST	/api/v1/users/me/email/verification, /email/verify
이메일 변경	PATCH	/api/v1/users/me/email
회원 탈퇴 (soft delete)	DELETE	/api/v1/users/me

🎓 장학금 (Scholarship)

기능	메소드	엔드포인트
맞춤 추천 목록 (메인)	GET	/api/v1/scholarships/curated
장학금 검색	GET	/api/v1/scholarships/search
추천 검색어	GET	/api/v1/scholarships/search/popular-keywords
장학금 상세	GET	/api/v1/scholarships/{scholarshipId}
장학금 일정 달력	GET	/api/v1/scholarships/calendar
홈 장학금 소식 요약	GET	/api/v1/scholarships/home-summary
추천 노출·클릭 기록	POST	/api/v1/scholarships/events
오등록 신고 / 내 신고 목록	POST / GET	/api/v1/scholarships/{scholarshipId}/reports, /my-reports
면접 예상 질문 조회·생성·삭제	GET / POST / DELETE	/api/v1/scholarships/{scholarshipId}/interview-questions

📁 아카이빙 (Archive)

기능	메소드	엔드포인트
아카이빙 목록 조회	GET	/api/v1/archive
장학금 스크랩	POST	/api/v1/archive/{scholarshipId}/scrap
스크랩 해제	DELETE	/api/v1/archive/{scholarshipId}/scrap

✍️ AI 자기소개서 (Application)

기능	메소드	엔드포인트
지원서 목록 조회	GET	/api/v1/applications
지원서 작성 시작	POST	/api/v1/applications
지원서 통합 상세 조회	GET	/api/v1/applications/{applicationId}
장학금 맞춤 문항 생성	POST	/api/v1/applications/{applicationId}/questions/generate
STEP 1 사전 인터뷰	POST	/api/v1/applications/{applicationId}/questions/{questionId}/interview
STEP 2 답변 관리 (draft/save/confirm)	PUT	/api/v1/applications/{applicationId}/questions/{questionId}/answer
면접 준비 자료 조회 / 예시답변 생성	GET / POST	/api/v1/applications/{applicationId}/interview-prep

🔔 알림 (Notification) · 💡 인사이트 (Insight) · 📮 문의

기능	메소드	엔드포인트
알림 목록	GET	/api/v1/notifications
알림 읽음 처리	PUT / PATCH	/api/v1/notifications/{notificationId}/read
알림 전체 삭제	DELETE	/api/v1/notifications
알림 설정 조회 / 변경	GET / PUT	/api/v1/notifications/settings
인사이트 목록 조회	GET	/api/v1/insights
콘텐츠 이용 문의 접수	POST	/api/v1/content-inquiries

🛠 관리자 (ADMIN 전용)

ROLE_ADMIN 토큰이 있어야 호출할 수 있습니다.

영역	엔드포인트
관리자 인증	/api/v1/admin/auth/login, /logout
데이터 현황·수집 원본·이상 탐지	/api/v1/scholarships/admin/**
수집·보완·파싱 배치 수동 실행	/api/v1/scholarships/{sync|collect|enrich|parse|conditions}/**
중복 장학금 탐지·병합 승인	/api/v1/scholarships/merge/**
장학금 수기 등록·수정·삭제, 엑셀 일괄 반영	/api/v1/scholarships/manual/**, /admin/manual-excel
오등록 신고 처리	/api/v1/scholarships/reports/**
콘텐츠 문의 처리	/api/v1/admin/content-inquiries/**
배치 실행 이력 · 시스템 상태 · 감사 로그	/api/v1/admin/jobs, /admin/system/**, /admin/audit-log
학교·전공 동기화, 인사이트 수집	/api/v1/universities/sync, /api/v1/insights/sync

💻 Architecture & Deploy

구성	내용
CI/CD	GitHub Actions — main push 시 build · test → jar SCP → SSH 재기동
Compute	AWS EC2 (Ubuntu, ap-northeast-2) · systemd wishconnect.service · -Xms512m -Xmx1g
Web	Nginx :443 (Let's Encrypt) → Spring Boot :8080 리버스 프록시
DB	AWS RDS PostgreSQL
Cache	Redis (EC2 로컬) — Refresh Token, 이메일 인증코드 TTL, 분산 락
Storage / Mail	AWS S3 (포스터·첨부 이미지) · AWS SES (인증 메일)
DNS	Route 53 — wish-connect.com(Vercel, FE) / api.wish-connect.com(EC2, BE)
External	Anthropic Claude, 카카오·구글·네이버 OAuth, 네이버 검색, 한국장학재단 공공 API, 학술정보 API, 대학 공지 크롤링

운영 서버 설정(systemd·logrotate·스왑·관리자 SSH 터널)은 deploy/README.md에 정리되어 있습니다.

🔧 Tech Stack

구분	기술
Language	Java 17
Framework	Spring Boot 3.3.5 (Web, Data JPA, Security, Validation, Mail, Actuator)
Database	PostgreSQL · Redis
Auth	Spring Security + JWT (jjwt 0.12.6) · OAuth 2.0 (Kakao / Google / Naver)
AI	Anthropic Claude Java SDK
Docs	springdoc-openapi (Swagger UI) + therapi-runtime-javadoc
Infra	AWS EC2 · RDS · S3 · SES · Route 53 · Nginx · GitHub Actions
Etc	Jsoup(크롤링) · Apache POI(엑셀) · AWS SDK v2 · Lombok

🧱 프로젝트 구조

src/main/java/com/wishconnect
├── domain
│   ├── auth            # 회원가입·로그인·소셜·토큰·이메일 인증
│   ├── user            # 마이페이지·프로필·온보딩
│   ├── scholarship     # 수집·정제·큐레이팅·검색·상세·신고·관리자
│   ├── application     # AI 자기소개서(인터뷰·초안·면접 준비)
│   ├── archive         # 스크랩 아카이빙
│   ├── notification    # 알림센터·설정·스케줄러
│   ├── insight         # 인사이트 콘텐츠 수집·조회
│   ├── inquiry         # 콘텐츠 이용 문의
│   ├── search          # 추천 검색어
│   └── common          # 지역·학교·전공 마스터
└── global
    ├── config          # Security, CORS, Swagger, Scheduling
    ├── jwt             # 토큰 발급·검증 필터
    ├── exception       # CustomException · ErrorCode · 전역 핸들러
    ├── lock            # 배치 분산 락
    ├── audit           # 관리자 감사 로그
    ├── operation       # 배치 실행 이력·시스템 상태
    ├── common          # ApiResponse 등 공통 응답
    └── util

• Java 파일 417개 · 엔티티 42개 · 테스트 클래스 78개

---

sitemap.xml · robots.txt (검색엔진 색인)

네이버 서치어드바이저 웹마스터 가이드를 기준으로 맞췄다. 공고는 매일 수집 배치로 갈리므로 정적 파일 대신 DB 를 읽어 즉석에서 만든다.

엔드포인트	내용
GET /sitemap.xml	고정 페이지 + 장학금 상세 URL. 모집 중 priority 0.8, 마감분 0.3
GET /robots.txt	네이버 검색로봇(Yeti) 허용, 관리자·API 경로 차단, Sitemap: 위치 명시

둘 다 인증 없이 열려 있고(크롤러는 토큰이 없다), 결과는 서버에서 1시간 캐시한다. 설정은 app.sitemap.* / app.robots.* (application.yml). 프론트 라우팅이 바뀌면 SITEMAP_SCHOLARSHIP_PATH / SITEMAP_STATIC_PATHS 환경변수만 고치면 된다.

가이드에서 지킨 것:

• URL 도메인 일치 — 사이트맵 내 URL 이 소유확인한 호스트와 다르거나 상대경로면 네이버가 통째로 버린다. 그래서 app.sitemap.base-url 은 절대주소만 허용하고, 아니면 기동 시점에 예외로 막는다. www 유무까지 서치어드바이저에 등록한 호스트와 똑같이 맞춰야 한다.
• 용량·건수 상한 — 10MB 미만, 한 파일당 50,000 URL 미만. 상한에 닿으면 WARN 로그를 남긴다.
• 응답 속도 — 피드가 느리면 제출이 제한되므로 생성 결과를 캐시한다.
• lastmod — 네이버 예시와 같은 W3C Datetime(2026-08-18T01:13:19+09:00).
• 모든 URL 수록 권장 — 마감 공고도 상세 페이지가 살아 있으므로 담되 priority 를 낮춘다 (SITEMAP_INCLUDE_CLOSED=false 로 제외 가능).
• robots.txt 는 text/plain + 2xx — HTML 로 나가면 규칙이 무시되고, 5xx 면 사이트 전체가 수집 차단으로 해석된다. Yeti 그룹에도 같은 규칙을 반복해 적는다(표준상 가장 구체적인 그룹 하나만 적용되기 때문).

⚠️ 남은 작업은 백엔드 밖에 있다.

1. 프론트/nginx 프록시 — 두 파일 모두 사이트 루트에 있어야 한다. https://wish-connect.com/sitemap.xml, /robots.txt 요청을 이 엔드포인트로 rewrite 해야 한다. robots.txt 규칙은 호스트별로 적용되므로 API 도메인에만 있으면 프론트 수집에는 아무 영향이 없다.
2. 서치어드바이저 등록 — 사이트 등록 → 소유확인(meta 태그 또는 HTML 파일) → "요청-사이트맵 제출".
3. 프론트 HTML 마크업 — 페이지별 title·meta description, 표준 <a href> 링크, noindex/nofollow 미사용. 콘텐츠를 자바스크립트로만 그리면 수집되지 않으므로 상세 페이지는 SSR 이어야 한다.

RSS 피드는 만들지 않았다. 가이드도 "본문을 담아야 해서 URL 을 많이 넣기 어려우니 사이트맵을 우선 활용"하라고 권한다.