Skip to content

README.md

Latest commit

 

History

History
218 lines (163 loc) · 10.5 KB

README.md

File metadata and controls

218 lines (163 loc) · 10.5 KB
Raw

척척학사 Backend

📚 목차

  1. 프로젝트 소개
  2. 주요 기능
  3. API 문서
  4. 기술 스택
  5. 아키텍처
  6. ERD
  7. 개발 문서
  8. 관련 블로그 게시글

프로젝트 소개

척척학사는 학생들이 학교 포털과 연동하여 본인의 이수 현황과 졸업 요건을 손쉽게 확인하고 관리할 수 있도록 도와주는 서비스입니다.

기존에는 학생들이 졸업 요건을 직접 확인하며 수작업으로 비교해야 했지만,
척척학사는 이를 학교 포털과 비동기 연동, 자동 분석, 시각적 안내 기능으로 효율화합니다.

  • ✅ 6,000명 이상 수원대 재학생 사용 중
  • 🔁 학교 포털과 비동기 연동 + job_id 상태 조회
  • 🧠 졸업 요건 자동 분석 및 부족 항목 안내

주요 기능

IA 구조도
기능 소개1
기능 소개2

  • 포털 연동을 통한 학점·성적·커리큘럼 비동기 동기화
  • 졸업 요건과 사용자 학사 정보 자동 비교
  • 부족한 학점 및 조건 자동 분석 및 안내
  • job_id 기반 비동기 파이프라인: 요청 접수 -> Outbox 패턴으로 SQS에 발행 -> 비동기 처리 후 결과 반영

API 문서

👉 Swagger API 문서 보기

배포 환경 변수 (OIDC)

  • APP_KEY: 카카오 OIDC aud 검증에 사용하는 기본 키(REST API 키)
  • APP_NATIVE_KEY: 안드로이드 OIDC aud 검증에 사용하는 네이티브 앱 키 (선택)

GitHub Actions 배포 시 dev/prod 저장소 secrets에 APP_NATIVE_KEY를 함께 등록해야 합니다.

기술 스택

Back-end

  • Java 17
  • Spring Boot 3.2.5
  • Spring Security, OAuth2
  • JPA, Hibernate

Infra

  • AWS API Gateway (HTTP API v2) + AWS Lambda (Spring Boot) + Route53/ACM
  • AWS SQS + HMAC Callback 파이프라인 (스크래핑 워커 연동)
  • PostgreSQL (Supabase 연동) + Caffeine / Redis 캐시
  • Observability: Sentry, Grafana Cloud(OTLP), CloudWatch Logs
  • Docker 기반 Lambda 패키징 및 GitHub Actions 배포

Tools

  • Git, GitHub
  • Swagger (OpenAPI)
  • Gradle, Tomcat

아키텍처

flowchart LR
    Client["Web / Android Client"]
    APIGW["API Gateway (HTTP API v2)"]
    Lambda["AWS Lambda (Spring Boot)"]
    Domain["Domain & Graduation Analysis"]
    DB[(PostgreSQL)]
    Cache[(Caffeine / Redis)]
    Outbox["Scrape Job & Outbox"]
    SQS["AWS SQS Queue"]
    Worker["Scraping Worker"]
    Portal["University Portal"]

    Client --> APIGW --> Lambda
    Lambda --> Domain
    Domain --> DB
    Domain --> Cache
    Lambda -->|idempotent job_id| Outbox --> SQS --> Worker --> Portal
    Worker -- HMAC signed callback --> APIGW
    APIGW --> Lambda
Loading
  1. 사용자는 Idempotency-Key와 함께 비동기 포털 연동을 요청하고, Lambda는 job_id와 polling endpoint를 즉시 반환합니다.
  2. 스크래핑 요청은 Scrape Job Outbox -> AWS SQS -> 전용 워커 -> 학교 포털 순으로 전달되어 병목을 분리합니다.
  3. 워커는 HMAC 서명된 callback을 API Gateway로 보내고, Lambda는 이를 처리해 졸업 요건 데이터/캐시를 갱신한 뒤 상태/요약 API에 반영합니다.

핵심 로직 및 흐름

척척학사의 핵심 기능인 포털 동기화, 데이터 적재, 졸업 요건 분석 프로세스에 대한 시퀀스 다이어그램입니다.

1. 포털 동기화 시퀀스 (Click)
포털 동기화 시퀀스
2. 학업 데이터 적재 및 매핑 흐름 (Click)
학업 데이터 적재 및 매핑 흐름
3. 졸업 요건 조회 및 캐싱 흐름 (Click)
졸업 요건 조회 및 캐싱 흐름

ERD

ERD

개발 문서

README는 프로젝트 진입점입니다. 사람용 협업 규칙은 CONTRIBUTING.md, 개발·운영 상세 가이드와 ADR은 Wiki, AI Agent 실행 규칙은 AGENTS.md에서 관리합니다.

관련 블로그 게시글

👉 척척학사 블로그 시리즈 전체보기

성능 최적화 & 트러블슈팅
아키텍처 & 인프라
기능 구현 & 설계