api2/docs/security-and-response.md

보안 및 응답 규칙

예외와 응답

• 공통 예외 응답은 GlobalExceptionHandler에서 처리합니다.
• Controller는 ApiResponse.entity(...)와 ApiResponseCode 조합을 우선 사용합니다.
• 바이너리 파일 view/download처럼 필요한 경우만 ResponseEntity<Resource>를 직접 반환합니다.
• @Valid, 바인딩 실패, JSON 파싱 실패, 타입 오류는 CODE_4001로 통일합니다.

보안 구조

• admin과 front는 각각 독립된 SecurityConfig와 SecurityFilterChain을 가집니다.
• Swagger 경로는 HTTP Basic으로 별도 보호합니다.
• API는 JWT Bearer 토큰 또는 서버별 HttpOnly 쿠키를 사용합니다.
• admin JWT 필터는 ADMIN scope와 adminAccessToken만 인증합니다.
• front JWT 필터는 USER scope와 accessToken만 인증합니다.
• JWT 필터는 URL(/admin/** 등)로 서버 종류를 판단하지 않습니다.
• 각 서버의 공개 경로와 역할 정책은 해당 서버 SecurityConfig에서 관리합니다.
• admin/front는 물리적으로 분리되어 있으므로 API path에 /admin 또는 /front 접두어를 두지 않습니다. 서버 역할은 배포 대상과 SecurityConfig가 구분합니다.

서버별 정책

• admin API는 기본적으로 ADMIN 역할을 요구합니다.
• front API는 사용자 토큰을 인증 주체로 사용합니다.
• /actuator/health는 각 서버의 헬스체크 경로입니다.
• TUS는 admin 서버 이관 대상이며, front에는 TUS 공개 경로를 두지 않습니다.

응답 코드

응답 코드는 ApiResponseCode enum으로 관리합니다.

코드	HTTP Status	용도
CODE_200	200 OK	일반 성공
CODE_400	400 Bad Request	일반 클라이언트 오류
CODE_401	401 Unauthorized	인증 없음
CODE_403	403 Forbidden	권한 없음
CODE_404	404 Not Found	리소스 없음
CODE_405	405 Method Not Allowed	메서드 불일치
CODE_500	500 Internal Server Error	서버 오류
CODE_2001	200 OK	단건 조회 성공
CODE_2002	201 Created	등록 성공
CODE_2003	200 OK	조회 결과 없음
CODE_2004	409 Conflict	중복 데이터
CODE_4001	400 Bad Request	입력값, 바인딩, 타입 오류
CODE_4003	400 Bad Request	필수 요청 파라미터 누락