Runnect-Spring-Boot-Server

점과 점으로, 코스와 코스로 연결되는 너와 나의 러닝 경험

---

☝ 서비스 핵심 기능

1. 코스 그리기

코스 그리기로 달리기 전 목표를 설정하고 실시간 트래킹으로 코스르 따라 잘 달리고 있는지 확인합니다.

2. 코스 발견

코스 발견을 통해 나에게 맞는 코스를 추천 받거나 다른 유저가 공유한 코스를 검색하고 스크랩합니다. 코스를 직접 업로드할 수 도 있습니다.

3. 코스 보관함

코스 보관함에서 내가 그린 코스와 스크랩 코스를 관리합니다.

4. 마이페이지

마이페이지에서 프로필과 활동 기록, 업로드한 코스를 확인하고 목표 보상으로 동기를 강화합니다.

---

🧑‍🔧 Tech Stack

Backend

DB

CI/CD

Deploy

Develop Tool

Communicate Tool

---

🏠 server architecture

---

💽 DB ERD

---

📄 API(+ Non - API) Docs

---

🙆‍♀️ 역할분담

담당자	담당 내용
유수화	EC2, publicCourse & stamp 관련 api, 인프라 구축
전선희	RDS, course & user 관련 api, 인프라 구축
박수린	S3, record & scrap 관련 api, 인프라 구축

---

🗣️️ 컨벤션

💡 동료들과 말투를 통일하기 위해 컨벤션을 지정합니다. 오합지졸의 코드가 아닌, 한 사람이 짠 것같은 코드를 작성하는 것이 추후 유지보수나 협업에서 도움이 됩니다. 내가 코드를 생각하면서 짤 수 있도록 해주는 룰이라고 생각해도 좋습니다!

👩‍💻 Coding Conventions

명명규칙(Naming Conventions)

1. 이름으로부터 의도가 읽혀질 수 있게 쓴다.

2. 단수를 기본형으로 한다.

   • 기능 자체에서 단수, 복수를 구분하는 경우에만 복수 사용 ex. 다중삭제, 단일삭제

3. DB의 테이블, 클래스에는 PascalCase를 사용한다.

4. 변수, 메소드에는 camelCase를 사용한다.

5. DB의 테이블의 칼럼에는 snake_case를 사용한다.

6. 상수, enum에는 UPPER_SNAKE_CASE를 사용한다.

7. 메소드는 crud + http method(동사) + 명사 형태로 작성한다.

   • c : ex. createUser
   • r : ex. getUser
   • u : ex. updateUser
   • d : ex. deleteUser

8. 약어 사용은 최대한 지양한다.

9. 이름에 네 단어 이상이 들어가면 팀원과 상의를 거친 후 사용한다.

주석(Comment)

1. 해당 메소드가 어디에 쓰이는지 설명한다.

2. 해당 분기문이 어떤 분기인지 설명한다.

3. 반복문에서 어떤 조건에서 반복되는지 설명한다.

4. 정렬하고 필터링할때 어떤 조건의 정렬과 필터링인지 설명한다.

---

🌳 Branch

🌱 Trunk-Based Development

main branch : 유일한 trunk. 항상 배포 가능한 상태를 유지하며, 운영 서버와 staging 서버 모두 이 branch에서 배포된다.

feature branch: 각 작업 단위의 짧은 수명 branch. main에서 분기해 하루~수일 내에 PR로 병합한다.

• main에서 분기, feat/#issue번호-작업요약 형식으로 branch 생성
  • 브랜치명이 test/...로 시작하면 GitHub ref 경로 충돌이 나므로 테스트 관련 branch는 tests/...(복수형) 사용
• 작업 완료 후 PR 생성 (base: main)
  • CI(build status check)를 통과해야 병합 가능
  • 미완성 기능은 브랜치를 오래 살려두지 말고, feature flag로 감싸 main에 빠르게 합친다
• 리뷰 완료 후 squash merge, 병합된 branch는 삭제

과거에는 dev/main 두 개의 장수 branch를 cherry-pick으로 동기화하는 방식이었으나, 두 branch가 내용상 계속 어긋나는 문제(cherry-pick hell)가 반복되어 폐기했다.

🚀 배포 전략 (Continuous Delivery)

main은 항상 배포 가능한 상태를 유지하되, staging과 상용의 배포 트리거는 분리했다 — merge 즉시 상용까지 나가면 검증 없이 바로 노출되는 문제가 있어서다.

환경	트리거	방식
staging (Render)	main push	자동 배포
상용 (AWS CodeDeploy)	v* 형식의 git tag push	수동 승격

merge → staging에서 자동 확인 → 문제 없으면 상용 배포. 태그를 로컬에서 직접 만들 필요 없이, GitHub Actions의 Promote to Production workflow(workflow_dispatch)를 실행하면 다음 semver 태그를 자동 계산해 push까지 해준다.

# Actions 탭에서 "Promote to Production" → Run workflow 버튼으로도 가능
gh workflow run promote-to-prod.yml -f bump=patch   # patch | minor | major

이 태그 push가 prod-cd.yml의 트리거를 실행시켜 상용 배포로 이어진다.

🚩 Feature Flag

미완성/위험도 있는 기능을 브랜치에 오래 묵히지 않고 main에 먼저 merge한 뒤, 배포 이후 원하는 시점에 켤 수 있게 하는 최소 구현이다. (org.runnect.server.config.featureflag)

# application.yml (environment별로 값이 다를 수 있음)
feature-flags:
  flags:
    new-run-summary: false

@RequiredArgsConstructor
public class SomeService {
    private final FeatureFlags featureFlags;

    public void doSomething() {
        if (featureFlags.isEnabled("new-run-summary")) {
            // 새 로직
        }
        // 기존 로직
    }
}

yml에 키가 없으면 기본값은 비활성(false)이다.

✅ Diff Coverage 게이트

PR에서 새로 추가/수정된 라인이 테스트로 커버되는지 CI(build job)가 자동으로 확인한다 — 로직을 고쳤는데 관련 테스트가 안 따라오는 경우를 기계적으로 잡기 위함. 전체 커버리지가 아니라 이번 PR에서 바뀐 라인만 대상으로 하며, 기준은 70%다.

# CI에서 실행되는 것과 동일한 방식으로 로컬에서 직접 확인
./gradlew jacocoTestReport
pip install diff-cover
diff-cover build/reports/jacoco/test/jacocoTestReport.xml --compare-branch=origin/main

---

🧵 Commit Convention

📍 git commit message convention

ex) feat(변경한 파일) : 변경 내용 (/#issue num)

- ✨ feat:      새로운 기능 구현
- 🐛 fix:       버그, 오류 해결
- 🧹 chore:     src 또는 test 파일을 수정하지 않는 기타 변경 사항 ( 새로운 파일 생성, 파일 이동, 이름 변경 등 )
- ♻️ refactor:  버그 수정이나 기능 추가가 없는 코드 변경 ( 코드 구조 변경 등의 리팩토링 )
- 💎 style:     코드의 의미에 영향을 미치지 않는 변경 사항 ( 코드 형식, 세미콜론 추가: 비즈니스 로직에 변경 없음 )
- 🏗️ build:    빌드 시스템 또는 외부에 영향을 미치는 변경 사항 종속성 ( 라이브러리 추가 등 )
- 📈 perf:      성능을 향상 시키기 위한 코드 변경
- 🧪 test:      테스트 추가 또는 이전 테스트 수정
- 📝 docs:      README나 WIKI 등의 문서 개정
- ⏪️ revert:    이전 커밋을 되돌리는 경우
- 📦 ci:      CI 구성 파일 및 스크립트 변경
- Merge: 다른브렌치를 merge하는 경우
- Init : Initial commit을 하는 경우