[BE] 점검 관리 시스템 API

[jiva-z]

개요

점검 생성, 조회, 상태 변경 및 통계 조회를 위한 API를 개발합니다.
점검자-신고 매칭 검증 및 상태 전이 규칙을 적용합니다.

---

기능 요구사항

작업 내용

• 모델 설계
  • Inspection 엔티티와 상태 Enum 정의
  • Report-Inspector 간 1:N 관계 설정
• 점검 관리 API
  • 정기 점검 및 신고 점검 생성 API 구현
  • 점검 상태 변경 API 구현 (상태 전이 규칙 적용)
  • 점검자-신고 구역 일치 검증
• 조회 API
  • 점검 목록 조회 (타입 필터링)
  • 점검 상세 조회
  • 정기 점검 목록 조회
  • 신고 점검 목록 조회
• 통계 API
  • 점검자별 점검 상태 통계 조회
  • 지역별 점검 상태 통계 조회

API 스펙

// 점검 상태 변경 요청 DTO
public class InspectionStatusUpdateRequest {
    @NotNull
    private String status; // 한글 상태명 사용
}

// 점검 상세 응답 DTO
public class InspectionDetailResponse {
    private Long inspectionId;
    private String type;
    private String status;
    private LocalDate scheduleDate;
    private LocalDate endDate;
    private String inspectorName;
    private ReportInfo reportInfo;
}

---

예외 처리 정책

에러 유형	HTTP 상태코드	처리 방식
유효하지 않은 상태 변경	409 CONFLICT	상태 전이 규칙 위반 시
권한 없는 접근	403 FORBIDDEN	타 구역 점검 조작 시
리소스 없음	404 NOT_FOUND	존재하지 않는 점검/신고/점검자 요청 시
잘못된 요청	400 BAD_REQUEST	유효하지 않은 날짜 등 입력값 오류 시

---

성능 고려사항

1. N+1 문제 방지
   • 점검 조회 시 관련 엔티티 Fetch Join 사용
2. 통계 조회 최적화
   • 통계 데이터 집계를 위한 최적화된 쿼리 사용

---

기술적 결정 사항

1. 상태 관리 전략
   • Enum을 사용한 상태 관리 및 한글 설명 추가
   • 상태 변경 시 서비스 계층에서 유효성 검사
2. 권한 검증 방식
   • Spring Security의 @AuthenticationPrincipal 활용
   • 서비스 계층에서 점검자 소유권 검증
3. 응답 형식 통일
   • ApiResponse 클래스를 사용한 일관된 응답 형식