hgzero/develop/dev/dev-backend.md

User Service 백엔드 개발 결과서

📋 개발 개요

• 서비스명: User Service
• 개발일시: 2025-10-24
• 개발자: 동욱
• 개발 가이드: 백엔드개발가이드 준수

✅ 구현 완료 항목

1. 기본 인증 API (100% 완료)

API	메서드	경로	설명	상태
로그인	POST	/api/v1/auth/login	LDAP 인증 + JWT 발급	✅
토큰 갱신	POST	/api/v1/auth/refresh	Refresh Token으로 Access Token 갱신	✅
로그아웃	POST	/api/v1/auth/logout	Refresh Token 삭제	✅
토큰 검증	GET	/api/v1/auth/validate	Access Token 유효성 검증	✅

2. 아키텍처 구현 (100% 완료)

• 패턴: Layered Architecture 적용
• 계층: Controller → Service → Repository → Entity → Domain
• 의존성 주입: Spring DI 활용
• 트랜잭션: @Transactional 적용

3. 보안 구성 (100% 완료)

• JWT 인증: JwtTokenProvider, JwtAuthenticationFilter, UserPrincipal
• Spring Security: SecurityConfig, CORS 설정
• LDAP 인증: LdapTemplate 기반 사용자 인증
• 계정 보안: 로그인 실패 횟수 관리, 계정 잠금

4. 🆕 Azure EventHub 통합 (새로 추가)

• 설정: EventHubConfig 클래스
• 서비스: EventPublishService 인터페이스 및 구현체
• 이벤트 발행: 로그인, 로그아웃, 토큰 갱신 이벤트
• Fallback: No-Op 구현체로 EventHub 미설정 시에도 정상 동작

5. 설정 및 문서화 (100% 완료)

• Swagger: OpenAPI 3.0 문서화
• 설정 표준: JWT, CORS, Actuator, Logging 표준 준수
• 환경변수: 모든 민감 정보 환경변수 처리

🔧 기술 스택

• Framework: Spring Boot 3.3.5, Spring Security, Spring Data JPA
• Authentication: LDAP, JWT
• Database: PostgreSQL + JPA/Hibernate
• Cache: Redis
• Messaging: Azure EventHub
• Documentation: Swagger/OpenAPI
• Build: Gradle

📂 패키지 구조

user/src/main/java/com/unicorn/hgzero/user/
├── config/
│   ├── EventHubConfig.java          # Azure EventHub 설정
│   ├── SecurityConfig.java          # Spring Security 설정  
│   ├── SwaggerConfig.java           # Swagger 설정
│   └── jwt/
│       ├── JwtAuthenticationFilter.java
│       ├── JwtTokenProvider.java
│       └── UserPrincipal.java
├── controller/
│   └── UserController.java          # 인증 API 컨트롤러
├── domain/
│   └── User.java                    # 사용자 도메인 모델
├── dto/                             # Request/Response DTO
├── repository/
│   ├── entity/UserEntity.java      # JPA 엔티티
│   └── jpa/UserRepository.java     # JPA Repository
├── service/
│   ├── EventPublishService.java    # 이벤트 발행 인터페이스
│   ├── EventPublishServiceImpl.java # EventHub 이벤트 발행 구현체
│   ├── NoOpEventPublishService.java # No-Op 구현체
│   ├── UserService.java            # 사용자 서비스 인터페이스
│   └── UserServiceImpl.java        # 사용자 서비스 구현체
└── UserApplication.java            # 메인 애플리케이션 클래스

🔄 Azure EventHub 이벤트 발행

로그인 이벤트

{
  "eventType": "USER_LOGIN",
  "userId": "user123",
  "username": "홍길동", 
  "timestamp": 1729740000000,
  "eventTime": "2024-10-24T02:00:00Z"
}

로그아웃 이벤트

{
  "eventType": "USER_LOGOUT",
  "userId": "user123",
  "timestamp": 1729740000000,
  "eventTime": "2024-10-24T02:00:00Z"
}

토큰 갱신 이벤트

{
  "eventType": "TOKEN_REFRESH", 
  "userId": "user123",
  "timestamp": 1729740000000,
  "eventTime": "2024-10-24T02:00:00Z"
}

⚙️ 환경변수 설정

# 데이터베이스
DB_HOST=localhost
DB_PORT=5432
DB_NAME=userdb
DB_USERNAME=hgzerouser
DB_PASSWORD=your_password

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_password
REDIS_DATABASE=0

# JWT
JWT_SECRET=your_jwt_secret_key
JWT_ACCESS_TOKEN_VALIDITY=3600
JWT_REFRESH_TOKEN_VALIDITY=604800

# LDAP
LDAP_URLS=ldaps://ldap.example.com:636
LDAP_BASE=dc=example,dc=com
LDAP_USERNAME=your_ldap_user
LDAP_PASSWORD=your_ldap_password

# Azure EventHub
EVENTHUB_CONNECTION_STRING=your_connection_string
EVENTHUB_NAME=hgzero-eventhub-name

# CORS
CORS_ALLOWED_ORIGINS=http://localhost:*

# 로깅
LOG_LEVEL_APP=DEBUG
LOG_FILE=logs/user-service.log

🧪 테스트 방법

1. 서비스 시작

./gradlew user:bootRun

2. Swagger UI 접속

http://localhost:8081/swagger-ui.html

3. API 테스트 예시

# 로그인
curl -X POST http://localhost:8081/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"userId": "testuser", "password": "password"}'

# 토큰 검증
curl -X GET http://localhost:8081/api/v1/auth/validate \
  -H "Authorization: Bearer {access_token}"

🚀 빌드 및 컴파일 결과

• ✅ 컴파일 성공: ./gradlew user:compileJava
• ✅ 의존성 해결: Azure EventHub 라이브러리 추가
• ✅ 코드 품질: 컴파일 에러 없음

📝 백엔드개발가이드 준수 체크리스트

✅ 개발원칙 준수

• 개발주석표준에 맞게 주석 작성
• API설계서와 일관성 있게 설계
• Layered 아키텍처 적용 및 Service 레이어 Interface 사용
• 백킹서비스 연동 (PostgreSQL, Redis)
• Gradle 빌드도구 사용
• 설정 Manifest 표준 준용

✅ 개발순서 준수

• 참고자료 분석 및 이해
• 패키지 구조도 작성
• build.gradle 작성
• 설정 파일 작성 (application.yml)
• 공통 모듈 활용
• API 순차적 개발 (Controller → Service → Repository)
• 컴파일 및 에러 해결
• SecurityConfig 작성
• JWT 인증 처리 클래스 작성
• Swagger Config 작성

✅ 설정 표준 준수

• 환경변수 사용 (하드코딩 없음)
• spring.application.name 설정
• Redis Database 개별 설정
• JWT Secret Key 동일성 유지
• JWT, CORS, Actuator, OpenAPI, Logging 표준 적용

🎯 추가된 주요 기능

Azure EventHub 통합

1. 의존성 추가: Azure EventHub 클라이언트 라이브러리
2. 설정: EventHubConfig로 Producer Client 관리
3. 서비스: 인증 이벤트 자동 발행
4. 안전성: EventHub 미설정 시 No-Op 모드로 동작

이벤트 기반 아키텍처

• 느슨한 결합: EventHub 의존성을 인터페이스로 추상화
• 장애 격리: EventHub 장애 시에도 인증 서비스 정상 동작
• 확장성: 다른 서비스에서 사용자 인증 이벤트 구독 가능

📊 개발 완성도

• 기능 구현: 100% (4/4 API 완료)
• 가이드 준수: 100% (체크리스트 모든 항목 완료)
• 코드 품질: 우수 (컴파일 성공, 표준 준수)
• 확장성: 우수 (이벤트 기반 아키텍처 적용)

🔗 관련 문서

• API 설계서
• 외부 시퀀스 설계서
• 내부 시퀀스 설계서
• 데이터 설계서