👩‍💻 팀 컨벤션

Git 컨벤션

브랜치 전략

• Github Flow
  • 다른 팀원의 작업 진행 상황을 파악하기 용이하며, 프로젝트의 규모를 고려했을 때 지속적인 배포가 편리하다 판단하여 선택
• rebase 아닌 일반 merge 사용, 머지 완료한 브랜치는 이후 삭제

PR 컨벤션

• API 단위로 개발 후 커밋
• PR 머지 전 반드시 테스트코드 통과를 확인 후 머지함
• 팀원 5명중 3명 이상 approve시 머지 가능
  • 가능한 모든 팀원이 코드리뷰 하였으며, 실시간으로 전원 확인 체크 후 머지하였음
• 이슈 생성 후 브랜치를 생성해 작업을 시작함
• 복잡한 내용의 PR content에는 팀원의 이해를 돕기 위한 설명 작성
• P0-P6 코드 리뷰 템플릿 사용
• 다른 팀원의 PR에 단 코멘트는 코멘트를 작성한 본인이 직접 반영 확인 후 resolve

커밋 메시지 컨벤션

• 대문자로 시작하는 커밋 유형 뒤 간단한 명사형 설명
  • ex: Feat: DocService 구현
• PR과 이슈 제목 일치
• 제목은 한글 기준 20자 이내로

커밋 유형	의미
Feat	새로운 기능 추가
Fix	버그 수정
Docs	문서 수정
Style	코드 formatting, 세미콜론 누락, 코드 자체의 변경이 없는 경우
Refactor	코드 리팩토링
Test	테스트 코드, 리팩토링 테스트 코드 추가
Chore	패키지 매니저 수정, 그 외 기타 수정 ex) .gitignore
Design	CSS 등 사용자 UI 디자인 변경
Comment	필요한 주석 추가 및 변경
Rename	파일 또는 폴더 명을 수정하거나 옮기는 작업만인 경우
Remove	파일을 삭제하는 작업만 수행한 경우
!BREAKING CHANGE	커다란 API 변경의 경우
!HOTFIX	급하게 치명적인 버그를 고쳐야 하는 경우

Code 컨벤션

• Google Java Style Guide 적용
• 모든 Dto는 record로 사용
  • 생성자는 매개변수가 1개라면 from 을 사용하고, 그 이상이면 of를 사용
• 모든 dto-entity 변환은 Mapper 클래스 사용
  • 이름은 (도메인이름)Mapper
  • 도메인별 util 패키지 하위에 위치
  • 메서드명은 toEntity(), toGraphCreateResponse()
• 모든 곳에 Setter 사용 지양, 메서드로 대체
• entity에서는 매개변수 개수에 상관 없이 일관성 있는 Builder 사용

패키지 구조

• 도메인형 설계 적용
• 구조적 장점:
  • 모듈 확장 용이성: 기능 단위로 묶여 있어 새로운 도메인을 추가하거나 특정 도메인만 분리해 모듈화(MSA 등)하기 쉬움
  • 코드 응집도 증가: 동일 도메인 내의 모든 계층이 한 곳에 위치하여 관리가 편리함
  • MSA 전환 기반 확보: 도메인 단위 서비스 분리 시 구조를 그대로 계승 가능
• 구조적 한계:
  • 현재 모듈간 결합도가 낮지 않으며 일부 도메인 간 직접 참조가 존재함
  • 장기적으로 MSA 아키텍처를 목표로 한다면 서비스 경계를 더 명확히 분리하는 것이 좋을 것으로 보임
  • 추후 의존성 분리, 공통 모듈화, 이벤트 기반 정합성 설계등의 개선 작업 필요

com.ejangs.docsa
├── DocsaApplication.java
├── domain
│   ├── auth
│   │   ├── api         # 인증 관련 컨트롤러
│   │   ├── app         # 인증 로직, 메일 전송
│   │   ├── dto         # 인증 요청/응답 DTO
│   │   ├── model       # 인증 관련 모델(enum 등)
│   │   ├── swagger     # Swagger 문서
│   │   └── util        # 인증 코드 생성기 등 유틸
│   ├── commit
│   │   ├── api, app, dao.mongodb/mysql
│   │   ├── document    # MongoDocument
│   │   ├── dto, entity, swagger, util
│   ├── doc
│   │   ├── api, app, dao, dto (그래프/요약 응답 포함)
│   │   ├── entity, model, swagger, util
│   ├── save
│   │   ├── api, app, dao.mongodb/mysql
│   │   ├── document, dto, entity, swagger, util
│   └── user
│       ├── api, app, dao, dto, entity
│       ├── security   # Spring Security 설정
│       ├── swagger, util
├── global
│   ├── common         # 공통 엔티티 (e.g., BaseEntity)
│   ├── config         # 설정 클래스들 (Security, JPA, Mail 등)
│   ├── exception
│   │   ├── handler, ErrorResponse
│   │   └── errorcode  # 기능별 에러 코드 정의
│   ├── init           # 초기 데이터 설정
│   ├── mongo.deletion # Mongo DB 삭제 실패 처리 로직
│   └── util           # 공통 유틸

네이밍 전략

• 메서드 명은
• DTO 명은 (도메인이름)(목적)Request/Response, 구분이 애매한 것은 Dto로
  • ex: GraphCreateRequest, GraphCreateDto
• 변수명
  • 변수명은 카멜 케이스(userName, totalNumber)

규칙	예시
단일 객체는 단수형 사용	coffee, order
컬렉션은 복수형 사용	coffees, orders
변수명에 타입은 포함하지 않음	✅ createdOrder, ❌ orderListArray
의미가 드러나는 의도 기반 네이밍	createdOrder, updatedCoffee
Boolean은 접두사 has 사용	updated, hasCredential
Optional은 optional 접두사 사용	optionalUser