Home

Jump to bottom

SANGMIN PARK edited this page Jul 17, 2026 · 6 revisions

척척학사 Backend Wiki

척척학사 백엔드는 수원대학교 포털의 학사 데이터를 비동기로 가져오고, 학생별 이수 현황과 졸업 요건을 계산하는 Spring Boot 서비스입니다.

이 Wiki는 새로 합류한 백엔드 개발자가 로컬 실행부터 배포와 장애 대응까지 필요한 정보를 찾는 곳입니다. API의 최신 요청·응답 형식은 실행 중인 Swagger를 기준으로 확인하고, 이 Wiki는 구조와 작업 절차를 설명합니다.

처음 보는 개발자를 위한 순서

Getting Started에서 로컬 환경을 실행합니다.
Project Architecture에서 런타임과 패키지 구조를 확인합니다.
Architecture Decision Records에서 주요 기술 선택의 이유와 제약을 확인합니다.
Core Domain Flows에서 포털 연동과 졸업 진단 흐름을 읽습니다.
API and Authentication에서 인증과 API 영역을 확인합니다.
변경 전에 Development Guide를 읽습니다.
배포나 장애 대응이 필요하면 Deployment and Operations와 Troubleshooting을 사용합니다.

문서 안내

문서	다루는 내용
Getting Started	필수 도구, `.env`, 로컬 실행, 첫 검증
Project Architecture	Lambda 런타임, 외부 시스템, 패키지 책임
Architecture Decision Records	주요 기술 결정의 맥락, 대안, 결과, 재검토 조건
Core Domain Flows	포털 연동, Outbox·SQS, 콜백, 졸업 진단
API and Authentication	API 영역, JWT, Kakao·Apple OIDC, 내부 인증
Development Guide	브랜치, 테스트, API 문서, Flyway 변경 절차
Deployment and Operations	CI, dev·prod 배포, 관측, 롤백
Troubleshooting	증상별 진단, 로그·DB 확인, 해결, 재검증

주요 링크

문서의 기준

코드와 동작이 다르면 dev 브랜치의 코드와 테스트를 우선합니다.
API 요청·응답은 컨트롤러의 docs 인터페이스와 /v3/api-docs를 확인합니다.
dev·prod 스키마 변경은 src/main/resources/db/migration의 Flyway SQL만 사용합니다.
환경 변수의 값, 토큰, 포털 계정, DB 접속 정보는 Wiki와 Issue에 기록하지 않습니다.
주요 아키텍처 결정이 바뀌면 기존 ADR을 덮어쓰지 않고 대체 ADR을 추가합니다.
동작이 바뀐 PR은 관련 Wiki 페이지도 함께 갱신합니다.