User Backend Service

유저 담당 MSA 서비스

기술 스택

항목	내용
Framework	Spring Boot 4.0.6
Language	Java 25
DB	PostgreSQL (JPA)
Cache	Redis (TTL 10분)
Auth	Keycloak (JWT OAuth2 Resource Server)
API Docs	SpringDoc OpenAPI (Swagger UI)

---

실행

# 로컬 (Security 비활성, NoOp Keycloak)
./gradlew bootRun --args='--spring.profiles.active=local'

Swagger UI: http://localhost:8081/swagger-ui/index.html

---

API 목록

User API (/api/users)

메서드	경로	설명	권한
GET	/api/users	전체 유저 목록 조회	ADMIN
POST	/api/users	유저 생성	ADMIN
GET	/api/users/{id}	유저 단건 조회	ADMIN
GET	/api/users/me	내 정보 조회 (JWT 기반)	인증된 사용자
PATCH	/api/users/{id}/status	유저 상태 변경 (활성/비활성)	ADMIN
PUT	/api/users/{id}	유저 전체 정보 수정	ADMIN

---

도메인 모델

User 엔티티

필드	타입	설명
id	Long	PK
keycloakId	String	Keycloak UUID
employeeNumber	String	사번 (unique)
name	String	이름
position	String	직책
role	Role	권한
tenancyType	TenancyType	소속 유형
tenancyName	String	소속명
status	Status	계정 상태
createdAt	LocalDateTime	생성일시

Enum

Role — ADMIN, HQ_MANAGER, HQ_STAFF, BRANCH_MANAGER, BRANCH_STAFF

Status — PENDING, ACTIVE, SUSPENDED

TenancyType — HQ, BRANCH

---

에러 응답 형식

RFC 9457 ProblemDetail 형식 사용.

{
  "status": 404,
  "title": "Not Found",
  "code": "USER_NOT_FOUND",
  "instance": "/api/users/99",
  "timestamp": "2026-06-07T03:56:08.162258+09:00"
}

코드	상태	설명
USER_NOT_FOUND	404	유저 없음
USER_DUPLICATE_EMPLOYEE_NUMBER	409	사번 중복

---

보안

• JWT 검증: Keycloak 발급 토큰
• Role 추출: realm_access.roles 클레임
• 로컬 개발: local 프로파일로 Security 전체 허용

---

Keycloak 연동 현황

기능	상태
JWT 검증 (Resource Server)	완료
유저 생성 시 Keycloak 등록	구현 예정
유저 수정 시 Keycloak 동기화	구현 예정
로그인/로그아웃/비밀번호 변경/토큰 갱신	구현 예정