Skip to content
dino-productPublic

About

[Orbit] A/S 업체용 일정 공유 SaaS

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Orbit Server

Orbit(A/S·설치·점검 업체의 기사-사무실 공유 스케줄링 서비스)의 백엔드입니다. 하나의 JAR로 배포하는 Spring Modulith 모듈러 모놀리스이며, 비즈니스 모듈은 DDD 바운디드 컨텍스트로 나누고 모듈 안은 헥사고널 계층으로 나눕니다(아키텍처).

  • 기반: Java 21, Spring Boot, Spring Modulith, Gradle Kotlin DSL
  • 웹·보안: Spring MVC, Validation, Security, Actuator, springdoc OpenAPI
  • 데이터: Spring Data JPA, QueryDSL, PostgreSQL, Flyway, Spring Data Redis
  • 테스트: JUnit Jupiter, Mockito, Modulith Test, Testcontainers

버전은 버전 카탈로그와 빌드 설정이 관리합니다.

빠른 시작

JDK 21과 Docker(Compose 포함)가 필요합니다. Gradle은 Wrapper를 씁니다.

cp .env.example .env
docker compose --env-file .env up -d postgres redis localstack
set -a && source .env && set +a
./gradlew bootRun
주소 용도
http://localhost:8080/docs OpenAPI UI
http://localhost:9090/actuator/health Health. probe는 /actuator/health/liveness, /actuator/health/readiness
http://localhost:9090/actuator/prometheus Prometheus 수집
  • 프로필: 자동으로 고르지 않습니다. 위 명령은 .env의 SPRING_PROFILES_ACTIVE=local을 씁니다. 프로필별 규칙은 프로필과 실행 환경에 있습니다.
  • 스키마: 기동할 때 Flyway가 src/main/resources/db/migration을 대상 DB에 적용합니다(ADR-005). 에이전트가 로컬 Compose DB가 아닌 DB로 실행할 때는 승인 절차를 따릅니다.
  • 사진 저장소: 완료보고·현장 사진은 Compose의 LocalStack(S3 호환, http://localhost:4566)에 올라갑니다. 버킷 orbit-media-local은 컨테이너가 준비될 때 만들어집니다. 발급받은 업로드 주소로 PUT할 때는 응답의 requiredHeaders를 그대로 붙입니다(ADR-007).
  • 데이터 초기화: 로컬 DB는 재시작해도 데이터가 남습니다. 처음부터 다시 만들려면 docker compose down -v로 볼륨을 지우고 다시 띄웁니다. 예전 create-drop이 남긴 테이블 때문에 Flyway가 기동을 막을 때도 같습니다. 에이전트는 볼륨을 지우기 전에 데이터·볼륨 삭제 승인을 받습니다.

로그인·토큰 환경값

.env.example의 자리표시자로도 기동은 됩니다. 아래 값은 기본값이 없고 빈 값이면 기동에 실패합니다. 줄을 지우면 ${변수명} 문자열이 그대로 값이 되어 실패 없이 뜰 수 있으니 줄은 지우지 않습니다. 실제 키는 커밋하지 않으며, 변수별 설명은 Auth 설정과 .env.example 주석에 있습니다.

실제 로그인에 쓰는 값:

변수 넣을 값 자리표시자일 때
KAKAO_ALLOWED_AUDIENCES 카카오 개발자 콘솔의 네이티브 앱 키와 REST API 키 실제 앱의 id_token을 거부
KAKAO_ADMIN_KEY 같은 카카오 앱의 서비스 앱 어드민 키 탈퇴 시 카카오 연결 끊기가 실패해 재시도하다 7일 뒤 포기
KAKAO_REST_API_KEY, KAKAO_CLIENT_SECRET 같은 카카오 앱의 REST API 키와 그 클라이언트 시크릿. REST API 키는 현장 주소 좌표 조회(카카오 로컬 API)에도 씀 웹 카카오 로그인 실패, 현장 좌표 없이 저장
KAKAO_WEB_REDIRECT_URI, KAKAO_WEB_RETURN_URI 카카오 앱에 등록한 이 서버 콜백(/api/v1/auth/kakao/callback) 주소와 로그인 뒤 돌아갈 웹 주소 웹 카카오 로그인 실패
APPLE_ALLOWED_AUDIENCES Apple 클라이언트 목록(iOS Bundle ID, 웹 Services ID) 실제 id_token을 거부
APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_PRIVATE_KEY Team ID, Sign in with Apple 키 ID, 그 키의 .p8 내용 Apple 토큰 교환 실패
APPLE_SERVICES_ID, APPLE_WEB_REDIRECT_URI 웹용 Services ID, 그리고 그 Services ID에 등록한 이 서버 콜백(/api/v1/auth/apple/callback)의 HTTPS 주소 웹 Apple 로그인 실패
APPLE_WEB_RETURN_URI 로그인 뒤 돌아갈 웹 주소 .env.example의 로컬 주소(http://localhost:3000/login/apple)로 돌아감
  • 카카오 키는 같은 카카오 앱의 것만 넣습니다. 다른 앱의 키를 섞으면 서로 다른 사용자가 한 계정으로 합쳐질 수 있습니다. Apple 클라이언트도 같은 개발자 팀의 것만 넣습니다.
  • KAKAO_REST_API_KEY는 KAKAO_ALLOWED_AUDIENCES에, APPLE_SERVICES_ID는 APPLE_ALLOWED_AUDIENCES에도 넣어야 하며, 빠지면 기동에 실패합니다.
  • Apple은 HTTPS 공개 도메인의 콜백만 받으므로 로컬에서 웹 Apple 로그인을 하려면 HTTPS 터널 등이 필요합니다. Android 앱은 Apple 로그인을 노출하지 않습니다.

자리표시자로도 동작하지만 저장소에 공개된 값이라 배포 환경에서는 반드시 바꿀 비밀값:

변수 넣을 값
AUTH_JWT_SECRET 32바이트 이상 무작위 값. 짧으면 기동 실패
APPLE_REFRESH_TOKEN_ENCRYPTION_KEY openssl rand -base64 32로 만든 값. base64 32바이트가 아니면 기동 실패

인증과 접근

  • 인증 없이 부를 수 있는 경로는 카카오·Apple 로그인 경로, 토큰 재발급·로그아웃, 약관 조회(GET /api/v1/terms), 구조 예제 API, OpenAPI 문서(prod에서는 꺼짐), Health·Prometheus입니다. 그 밖의 API와 Info는 Bearer Access Token이 필요합니다.
  • 로그인 호출 순서는 카카오·Apple 로그인 흐름, 지원 범위는 Auth 책임과 범위에 있습니다.
  • 가입을 마치지 않았거나 개정된 필수 약관에 다시 동의하지 않은 계정은 허용 목록(프로필·인증·회사 확인 API) 밖에서 403 PROFILE-005를 받습니다(가입 공통 검사).
  • Health·Prometheus는 Actuator 포트(9090)에만 있습니다. 운영에서는 이 포트를 외부로 라우팅하지 않고 클러스터 안의 수집기·probe만 접근하게 둡니다(접근 정책).

프로젝트 구조

src/main/java/com/orbit/          애플리케이션과 모듈
src/main/resources/db/migration/  Flyway 마이그레이션
src/test/                         단위·모듈·API·아키텍처 테스트
docs/adr/                         아키텍처·에이전트 규칙 결정
docs/domain/                      모듈 책임과 공개 계약
docs/planning/                    기획 원본(Notion) 색인과 기준 버전
docs/troubleshooting/             반복 조사에서 얻은 문제 해결 사례
gradle/                           버전·의존성·품질·테스트 설정과 Wrapper
config/checkstyle/                코드 검사 규칙
docker/                           실행 JAR용 컨테이너 이미지
.github/                          CI, 이슈·PR 양식, 라벨 정의, 기여 안내
.claude/                          팀 공통 스킬(개발 계약은 references/), 서브에이전트, 권한·hook

아키텍처

com.orbit 바로 아래 패키지 하나가 Spring Modulith 모듈 하나입니다. 비즈니스 모듈은 업무 책임(바운디드 컨텍스트)으로 나누고, shared는 여러 모듈이 함께 쓰는 오류·OpenAPI·보안·영속성 계약만 @NamedInterface로 공개하고, 설정·공통 구현은 shared/internal에 둡니다. 모듈 목록은 도메인 지도에 있습니다.

비즈니스 모듈 하나는 아래처럼 생겼습니다.

{module}/
├── package-info.java   모듈 선언과 허용 의존성
├── *.java              다른 모듈에 공개하는 계약(인터페이스·이벤트·계약 DTO)
├── domain/             애그리게잇·값객체와 불변식
├── application/
│   ├── port/in/        유즈케이스(command: 상태 변경, query: 조회)
│   ├── port/out/       저장소·외부 연동 계약
│   ├── service/        유즈케이스 구현과 트랜잭션 조율
│   └── error/          모듈 오류 코드
└── adapter/
    ├── in/             HTTP, 이벤트·메시지 채널 구독, 주기 작업, 다른 모듈이 선언한 요구 인터페이스 구현 등
    └── out/            JPA 저장소, Redis, 외부 API, ACL로 정한 다른 모듈 호출 등

화살표는 의존 방향입니다. 포트와 어댑터도 domain 타입을 쓰지만 그림에서는 생략했습니다.

adapter/in ──▶ port/in ◀── service ──▶ port/out ◀── adapter/out
                              │
                              ├──▶ domain
                              └──▶ 다른 모듈의 공개 계약

다른 비즈니스 모듈과는 상대 모듈 루트의 공개 계약으로만 통신합니다. 지켜야 할 규칙은 아래 원본에 있습니다.

원본 내용
모듈 경계·모듈 내부 계층 패키지 구조, 계층별 의존 규칙, ModularityTest·ArchitectureTest가 검사하는 범위
모듈 간 통신 공개 인터페이스 호출·공개 이벤트·요구 인터페이스·ACL 중 무엇을 쓸지
트랜잭션 이벤트 이벤트를 언제, 어떤 트랜잭션에서 소비하는지와 전달 보장
ADR-001 이 구조를 고른 이유

검증

  • 전체 검증 명령은 검증과 완료에 있습니다. 전체 테스트는 Docker가 필요하며, Docker가 없어 건너뛰거나 --tests로 일부만 고른 실행은 전체 통과로 보지 않습니다.
  • ./gradlew test는 Testcontainers로 테스트 DB를 만들고 지우므로 에이전트는 실행 전에 DB 승인을 받습니다.
  • 변경에 맞는 검사만 고를 때는 집중 검사 표를 봅니다. CI 검사 범위와 보고서 보관은 완료 검증과 CI에 있습니다.
  • PR에서는 CI verify와 PR 규약 검사가 실행됩니다. 리뷰는 PR 전에 로컬 dino-review로 하고, 규약 검사는 본문의 리뷰 마커가 PR head와 같은지 확인합니다.

문서

찾는 내용 문서
제품 규칙(권한·상태·입력 제한) 기획 원본 색인 — Notion 정책서·기능명세와 기준 버전
모듈 목록·책임·공개 계약·허용 의존성 도메인 지도
구조를 그렇게 정한 이유 ADR 색인
작업별 개발 규칙·AI 작업 방식 AGENTS.md 읽기 경로, Claude Code 스킬은 스킬과 위임
커밋·이슈·PR 기여 기여 안내
문서 원본 위치와 관리 규칙 문서 관리
반복 문제 해결 사례 트러블슈팅

About

[Orbit] A/S 업체용 일정 공유 SaaS

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages