SFAAS Backend

현대오토에버 스마트팩토리 2기 백엔드 프로젝트

🛠️ 기술 스택

Java: OpenJDK 17+
Framework: Spring Boot 3.5.5
Database:
ORM: MyBatis
Build Tool: Gradle
Documentation:

📚 목차

📋 개발 컨벤션

커밋 컨벤션
브랜치 네이밍 규칙
Java 네이밍 컨벤션

🏗️ 프로젝트 구조

도메인별 패키지 구조
MVC 패턴 적용
MyBatis 매퍼 구조

🔄 개발 워크플로우

이슈 선택 및 개발 시작
로컬 개발 환경 설정
커밋 작성
Pull Request 생성
브랜치 전략
Jira 이슈 관리

🖥️ GitHub Desktop 가이드

템플릿 준비
커밋 작성 방법
상황별 사용법
효율적인 작업 꿀팁
전체 워크플로우

📋 개발 컨벤션

🔄 커밋 컨벤션

커밋 메시지 형식

{type}: {subject}

{body}

{footer}

커밋 타입

feat: 새로운 기능 추가
fix: 버그 수정
hotfix: 긴급 버그 수정
docs: 문서 변경
style: 코드 스타일 변경 (포매팅, 세미콜론 등)
refactor: 코드 리팩토링
test: 테스트 코드 추가/수정
chore: 빌드 도구, 패키지 매니저 설정 등
infra: CI/CD 설정 변경

커밋 메시지 예시

feat: add user authentication API

- Implement JWT token generation
- Add login/logout endpoints
- Include password encryption with BCrypt

SSFAS-123 #time 2h

fix: resolve database connection timeout issue

- Increase connection pool size to 20
- Add connection retry logic with exponential backoff
- Update hikari connection timeout to 30 seconds

SSFAS-124 #resolve #time 1h 30m

� 명령어 사용자를 위한 가이드

Git 커밋 템플릿 설정 (추천)

커밋 템플릿을 설정하면 일관된 커밋 메시지를 쉽게 작성할 수 있습니다.

프로젝트별 설정 방법 (추천):

# 1. 프로젝트 루트에 템플릿 파일 생성
echo "# {type}: {subject}
#
# - {변경사항 1}
# - {변경사항 2}
# - {변경사항 3}
#
# SSFAS-{이슈번호} #resolve #time {작업시간}
#
# 커밋 타입: feat, fix, docs, style, refactor, test, chore, infra
# 스마트 커밋: #resolve(완료), #time(시간), #comment(코멘트)" > .gitmessage

# 2. 현재 프로젝트에만 템플릿 설정
git config commit.template .gitmessage

전역 설정에서 프로젝트별 설정으로 변경:

# 전역 설정 제거
git config --global --unset commit.template

# 현재 프로젝트에만 적용
git config commit.template .gitmessage

사용 방법:

git commit (메시지 없이) 입력하면 에디터가 열림
템플릿을 참고하여 커밋 메시지 작성
또는 직접 메시지 입력: git commit -m "..."

자주 사용하는 Git Alias (선택사항)

# 빠른 커밋을 위한 alias 설정
git config --global alias.jcommit '!f() { git commit -m "$1

SSFAS-$2 #time $3"; }; f'

# 사용 예시
git jcommit "feat: 사용자 인증 API 구현" "123" "2h"

🏷️ 브랜치 네이밍 규칙

브랜치명 형식

{type}/{SSFAS-번호}-{도메인}-{설명}

브랜치 타입별 예시

# 기능 개발
feat/SSFAS-10-user-signup-api
feat/SSFAS-11-product-management

# 버그 수정
fix/SSFAS-12-user-login-validation
fix/SSFAS-13-product-search-error

# 프로젝트 설정
chore/SSFAS-14-project-initial-setup
chore/SSFAS-15-database-configuration

# 문서 작성
docs/SSFAS-16-api-documentation
docs/SSFAS-17-readme-update

# 테스트 추가
test/SSFAS-18-user-service-tests
test/SSFAS-19-integration-tests

# 리팩토링
refactor/SSFAS-20-user-service-cleanup
refactor/SSFAS-21-mapper-optimization

☕ Java 네이밍 컨벤션

📦 패키지명

소문자만 사용
점(.)으로 구분
도메인별 구조 적용

com.hyundai.sfaas.backend
├── equipment/               // 설비 도메인
│   ├── controller/
│   ├── service/
│   ├── repository/
│   ├── mapper/              // MyBatis 매퍼 인터페이스
│   ├── entity/
│   └── dto/
├── operation/               // 가동 도메인
│   ├── controller/
│   ├── service/
│   ├── repository/
│   ├── mapper/
│   ├── entity/
│   └── dto/
├── quality/                 // 품질 도메인
│   ├── controller/
│   ├── service/
│   ├── repository/
│   ├── mapper/
│   ├── entity/
│   └── dto/
├── global/                  // 공통 기능
│   ├── config/              // 설정 클래스
│   ├── exception/           // 예외 클래스
│   ├── util/               // 유틸리티 클래스
│   └── common/             // 공통 DTO, 응답 클래스
└── SfaasBackendApplication.java

🏗️ 클래스명

PascalCase 사용
명사형으로 작성
도메인 + 역할로 구성

📝 메서드명

camelCase 사용
동사로 시작
도메인 비즈니스 로직 반영

🔤 변수명

camelCase 사용
명사형으로 작성
도메인 컨텍스트 반영

🔄 개발 워크플로우 (Jira 연동)

📋 1. 이슈 선택 및 개발 시작

Jira에서 이슈 선택:

Jira Kanban Board에서 "To Do" 이슈 선택
이슈를 "In Progress"로 상태 변경
"Create branch" 버튼 클릭
브랜치명 형식: {type}/SSFAS-{번호}-{설명}
- 자세한 브랜치 네이밍 규칙은 브랜치 네이밍 규칙 참고

💻 2. 로컬 개발 환경 설정

# 원격 브랜치 가져오기
git fetch origin

# 생성된 브랜치로 체크아웃
git checkout feat/SSFAS-10-user-signup-api

# 또는 로컬에서 브랜치 생성
git checkout -b feat/SSFAS-10-user-signup-api

📝 3. 커밋 작성 (Jira 스마트 커밋)

기본 커밋 형식:

git commit -m "{type}: {subject}

{body}

SSFAS-{번호} #{스마트커밋명령어}"

실제 커밋 예시:

# 기본 커밋
git commit -m "feat: implement user signup API

- Add UserController with signup endpoint
- Implement UserService.createUser method
- Add email validation and password encryption

SSFAS-10"

# 작업 시간 포함
git commit -m "feat: add user signup validation

- Add email format validation
- Add password strength check
- Add duplicate email detection

SSFAS-10 #time 2h"

# 커멘트와 상태 변경 포함
git commit -m "feat: complete user signup API implementation

- Add comprehensive error handling
- Add integration tests
- Update API documentation

SSFAS-10 #time 1h 30m #comment 'API 개발 완료, 테스트 통과'"

스마트 커밋 명령어:

#time 2h 30m - 작업 시간 로깅
#comment "메시지" - Jira 이슈에 코멘트 추가
#transition "Done" - 이슈 상태 변경
#resolve - 이슈를 완료 상태로 변경

🔄 4. Pull Request 생성

PR 생성 전 체크리스트:

# 최신 develop 브랜치와 동기화
git checkout develop
git pull origin develop
git checkout feat/SSFAS-10-user-signup-api
git rebase develop

# 충돌 해결 후 푸시
git push origin feat/SSFAS-10-user-signup-api

리뷰 진행:

PR 생성 시 Jira 이슈 상태를 "Code Review"로 변경
리뷰어 지정 및 리뷰 진행
리뷰 피드백 반영 후 재커밋

머지 후 정리:

# 머지 완료 후 Jira 이슈 상태를 "Done"으로 변경
# 로컬 브랜치 정리
git checkout develop
git pull origin develop
git branch -d feat/SSFAS-10-user-signup-api

🎯 5. 브랜치 전략

main (운영 환경)
├── develop (개발 통합 환경)
    ├── feat/SSFAS-10-user-signup-api
    ├── feat/SSFAS-11-jwt-auth-service
    ├── fix/SSFAS-12-login-bug-fix
    └── docs/SSFAS-13-api-docs

머지 규칙:

Feature/Fix 브랜치 → develop
develop → main (배포 시)
Hotfix는 main에서 직접 분기 가능

📊 6. Jira 이슈 관리

이슈 상태 플로우:

📝 To Do → 🔄 In Progress → 👀 Code Review → 🧪 Testing → ✅ Done

상태 변경 타이밍:

To Do → In Progress: 개발 시작 시 (수동)
In Progress → Code Review: PR 생성 시 (수동)
Code Review → Testing: PR 머지 시 (수동)
Testing → Done: 테스트 완료 시 (수동 또는 스마트 커밋)

🎯 실제 사용 예시

Jira for GitHub가 연동된 상황에서의 워크플로우:

# 1. Jira에서 브랜치 생성 (자동으로 생성됨)
# feat/SSFAS-10-user-signup-api

# 2. 로컬에서 브랜치 체크아웃
git checkout feat/SSFAS-10-user-signup-api

# 3. 개발 진행...

# 4. 커밋 (위의 커밋 컨벤션 참고)
git commit -m "feat: implement user signup validation

- Add email format validation
- Add password strength check
- Add duplicate email detection

SSFAS-10 #time 1h 30m"

# 5. PR 생성하면 자동으로 Jira 이슈와 연결됨

💡 권장사항

필수:

Jira for GitHub 앱 (이미 설치됨)
스마트 커밋 사용법 숙지

선택사항 (팀 상황에 따라):

커밋 템플릿 설정 (일관성 중요한 팀)
Git 별칭 설정 (편의성 추구 시)
자동화 스크립트 (반복 작업 많은 경우)

🖥️ GitHub Desktop 사용자 가이드

GitHub Desktop은 커밋 템플릿을 지원하지 않으므로, 아래 가이드를 따라 일관된 커밋 메시지를 작성하세요.

� 1단계: 템플릿 준비

다음 템플릿을 메모장에 저장해두세요:

개발 중 커밋용:

feat: [기능 제목]

- [변경사항 1]
- [변경사항 2]
- [변경사항 3]

SSFAS-[번호] #time [시간]

기능 완료 커밋용:

feat: [기능 제목]

- [변경사항 1]
- [변경사항 2]
- [변경사항 3]

SSFAS-[번호] #resolve #time [시간]

🚀 2단계: GitHub Desktop에서 커밋 작성

실제 작성 예시:

Summary (제목):

feat: 사용자 인증 API 구현

Description (상세 내용):

- JWT 토큰 생성 기능 추가
- 로그인/로그아웃 엔드포인트 구현
- 비밀번호 암호화 적용

SSFAS-10 #time 2h

📊 3단계: 상황별 사용법

상황	사용할 템플릿	스마트 커밋 예시
개발 진행 중	개발 중 커밋용	`SSFAS-10 #time 1h`
기능 완료	기능 완료 커밋용	`SSFAS-10 #resolve #time 2h`
간단한 수정	이슈 번호만	`SSFAS-10`

💡 효율적인 작업 꿀팁

브랜치명에서 이슈 번호 복사
- feat/SSFAS-10-user-auth → SSFAS-10
자주 사용하는 문구를 미리 저장
- "API 구현", "버그 수정", "테스트 추가", "문서 업데이트"
커밋 타이밍
- 개발 중간: #time만 사용
- 마지막 커밋: #resolve #time 사용 (이슈 완료)
시간 기록 형식
- #time 30m, #time 1h, #time 2h 30m

🔄 전체 워크플로우

1. Jira에서 "Create branch" 클릭
   ↓
2. GitHub Desktop에서 "Fetch origin" 클릭
   ↓
3. 새 브랜치로 체크아웃
   ↓
4. 코드 개발 및 수정
   ↓
5. Changes 탭에서 변경사항 확인
   ↓
6. 메모장 템플릿 복사 → 수정하여 커밋 메시지 작성
   ↓
7. "Commit to [브랜치명]" 클릭
   ↓
8. "Push origin" 클릭
   ↓
9. GitHub에서 Pull Request 생성

⚠️ 주의사항

마지막 커밋에만 #resolve 사용
SSFAS 번호 반드시 포함
커밋 타입 정확히 사용 (feat, fix, docs, etc.)
의미있는 단위로 커밋
커밋 타입 정확히 사용 (feat, fix, docs, etc.)
의미있는 단위로 커밋

Step 2: GitHub Desktop에서 커밋 작성

Summary 필드 (제목):

feat: 사용자 인증 API 구현

Description 필드 (상세 내용):

- JWT 토큰 생성 기능 추가
- 로그인/로그아웃 엔드포인트 구현
- 비밀번호 암호화 적용

SSFAS-10 #time 2h

Step 3: 언제 어떤 템플릿을 사용할까?

상황	사용할 템플릿	예시
개발 중간 커밋	기본 템플릿	`SSFAS-10 #time 1h`
기능 완료 커밋	완료용 템플릿	`SSFAS-10 #resolve #time 2h`
작업 시간 미기록	이슈 번호만	`SSFAS-10`

� 빠른 작성을 위한 꿀팁

브랜치명에서 이슈 번호 복사: feat/SSFAS-10-user-auth → SSFAS-10
자주 쓰는 문구 저장: "API 구현", "버그 수정", "테스트 추가" 등
마지막 커밋에만 #resolve: 이슈가 완료될 때만 사용
시간 기록 습관화: #time 30m, #time 1h 30m 형식

🔄 GitHub Desktop 워크플로우

1. Jira에서 "Create branch" 클릭
2. GitHub Desktop에서 새 브랜치 Pull
3. 코드 변경 후 Changes 탭에서 커밋
4. Summary: 간단한 제목
5. Description: 상세 내용 + Jira 이슈 번호
6. "Commit to [브랜치명]" 클릭
7. "Push origin" 클릭
8. GitHub에서 PR 생성

Name		Name	Last commit message	Last commit date
.gemini		.gemini
.github		.github
gradle/wrapper		gradle/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmessage		.gitmessage
README.md		README.md
build.gradle		build.gradle
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Latest commit

History

Folders and files

Repository files navigation

SFAAS Backend

🛠️ 기술 스택

📚 목차

📋 개발 컨벤션

커밋 메시지 형식

커밋 타입

커밋 메시지 예시

� 명령어 사용자를 위한 가이드

Git 커밋 템플릿 설정 (추천)

자주 사용하는 Git Alias (선택사항)

브랜치명 형식

브랜치 타입별 예시

📦 패키지명

🏗️ 클래스명

📝 메서드명

🔤 변수명

🔄 개발 워크플로우 (Jira 연동)

📋 1. 이슈 선택 및 개발 시작

💻 2. 로컬 개발 환경 설정

📝 3. 커밋 작성 (Jira 스마트 커밋)

🔄 4. Pull Request 생성

🎯 5. 브랜치 전략

📊 6. Jira 이슈 관리

🎯 실제 사용 예시

💡 권장사항

🖥️ GitHub Desktop 사용자 가이드

� 1단계: 템플릿 준비

🚀 2단계: GitHub Desktop에서 커밋 작성

실제 작성 예시:

📊 3단계: 상황별 사용법

💡 효율적인 작업 꿀팁

🔄 전체 워크플로우

⚠️ 주의사항

Step 2: GitHub Desktop에서 커밋 작성

Step 3: 언제 어떤 템플릿을 사용할까?

� 빠른 작성을 위한 꿀팁

🔄 GitHub Desktop 워크플로우

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages