feat(report): RESTful 신고 관리 API 및 DTO 유효성 검사 구현 refs #4 #5 #16 #17

[DDINGJOO]

목적

• 프로필 신고 API([STORY] 게시글 신고 기능 #4, [STORY] 프로필 신고 기능 #5)와 게시글 신고 API를 통합하여 RESTful한 신고 관리 API를 구현했습니다.
• DTO 유효성 검사를 추가하여 API 레벨에서 데이터 무결성을 보장합니다.
• RESTful 원칙에 따라 리소스 중심의 직관적인 API 설계를 적용했습니다.
• 관련 Story: [STORY] 게시글 신고 기능 #4 [STORY] 게시글 신고 기능, [STORY] 프로필 신고 기능 #5 [STORY] 프로필 신고 기능
• 관련 Task: [TASK] 프로필 신고 API 구현 #16 [TASK] 프로필 신고 API 구현, [TASK] 신고 조회 API 구현 #17 [TASK] 신고 조회 API 구현

변경 요약

핵심 기능

1. 통합 신고 API 구현

   • 프로필, 게시글, 비즈니스 신고를 하나의 API로 통합
   • referenceType 필드로 신고 대상 타입 구분
   • RESTful한 URL 설계로 직관적인 API 제공

2. DTO 유효성 검사

   • Jakarta Validation 애노테이션 적용 (@notblank, @NotNull, @SiZe, @min, @max)
   • 필수 필드, 문자열 길이, 숫자 범위 검증
   • API 레벨에서 잘못된 요청 사전 차단

3. RESTful API 설계

   • 액션 기반 URL → 리소스 기반 URL 변경
   • HTTP 메서드를 의미있게 활용 (GET, POST, PATCH, DELETE)
   • 직관적이고 일관된 API 엔드포인트 구조

주요 파일/모듈

• Controller: ReportController (통합 신고 관리 API)
• DTO: ReportRequest, ReportSearchRequest, ReportStatusUpdateRequest
• Service: ReportService, ReportServiceImpl (메서드 오버로딩)
• Entity: Report (hold 메서드 추가)
• Test: ReportControllerTest (8개 테스트)

API 명세

1. 신고 등록 (POST /api/v1/reports)

통합 API: 프로필, 게시글, 비즈니스 신고 모두 처리

Request Body:

{
  "reporterId": "USER-001",
  "reportedId": "USER-002",
  "referenceType": "PROFILE",
  "reportCategory": "harassment",
  "reason": "욕설 및 비방"
}

Validation:

• reporterId: 필수 (NotBlank)
• reportedId: 필수 (NotBlank)
• referenceType: 필수 (NotNull), ENUM(PROFILE, ARTICLE, BUSINESS)
• reportCategory: 필수 (NotBlank)
• reason: 필수 (NotBlank), 최대 500자

Response (201 Created):

{
  "reportId": "REPORT-001",
  "reporterId": "USER-001",
  "reportedId": "USER-002",
  "referenceType": "PROFILE",
  "reportCategory": "harassment",
  "reason": "욕설 및 비방",
  "status": "PENDING",
  "reportedAt": "2025-10-16T16:00:00"
}

2. 신고 상세 조회 (GET /api/v1/reports/{reportId})

Response (200 OK):

{
  "reportId": "REPORT-001",
  "reporterId": "USER-001",
  "reportedId": "USER-002",
  "referenceType": "PROFILE",
  "reportCategory": "harassment",
  "reason": "욕설 및 비방",
  "status": "PENDING",
  "reportedAt": "2025-10-16T16:00:00",
  "processedAt": null
}

3. 신고 목록 검색 (GET /api/v1/reports)

Query Parameters:

• status: PENDING | REVIEWING | APPROVED | REJECTED | WITHDRAWN (선택)
• referenceType: PROFILE | ARTICLE | BUSINESS (선택)
• reportCategory: 카테고리명 (선택)
• sortType: STATUS | REPORTED_AT (기본값: REPORTED_AT)
• sortDirection: ASC | DESC (기본값: DESC)
• cursor: 커서 (선택)
• size: 페이지 크기 (기본값: 20, 최소: 1, 최대: 100)

Response (200 OK):

{
  "content": [
    {
      "reportId": "REPORT-001",
      "reporterId": "USER-001",
      "status": "PENDING",
      ...
    }
  ],
  "nextCursor": "2025-10-16T15:30:00",
  "size": 20,
  "hasNext": true
}

4. 신고 상태 변경 (PATCH /api/v1/reports/{reportId})

통합 API: 승인, 거절, 검토 시작, 보류 모두 처리

Request Body:

{
  "status": "APPROVED",
  "adminId": "ADMIN-001",
  "comment": "승인 처리"
}

Validation:

• status: 필수 (NotNull), ENUM(PENDING, REVIEWING, APPROVED, REJECTED, WITHDRAWN)
• adminId: 필수 (NotBlank)
• comment: 선택, 최대 500자

Response (200 OK):

{
  "reportId": "REPORT-001",
  "status": "APPROVED",
  "processedAt": "2025-10-16T16:10:00"
}

5. 신고 철회 (DELETE /api/v1/reports/{reportId})

Request Body:

{
  "reporterId": "USER-001",
  "reason": "실수로 신고함"
}

Response (200 OK):

{
  "reportId": "REPORT-001",
  "status": "WITHDRAWN"
}

수용 기준 검증

#4, #5 게시글/프로필 신고 기능 - AC 충족

• 사용자는 프로필/게시글/비즈니스에 대해 신고 카테고리를 선택할 수 있다
• 신고 시 80자 이상의 신고 내용을 입력할 수 있다 (최대 500자)
• 신고 데이터는 신고자, 신고항목, 신고내용, 대상 ID를 포함한다
• 신고 접수 시 적절한 응답을 반환한다 (201 Created)

추가 기능 요구사항

• DTO 유효성 검사로 데이터 무결성 보장
• RESTful API 설계로 직관적인 엔드포인트 제공
• 통합 API로 프로필, 게시글, 비즈니스 신고 처리
• 커서 기반 페이징으로 대용량 데이터 조회 성능 확보

테스트 커버리지

• 컨트롤러 테스트: 8개
  • 신고 등록 성공
  • 유효성 검사 실패 (신고자 ID 누락, 사유 길이 초과)
  • 신고 상세 조회 성공
  • 신고 목록 검색 성공
  • 신고 상태 변경 성공/실패
  • 신고 철회 성공
• 전체 테스트: 226+ 테스트 통과

브레이킹/마이그레이션

• URL 변경:
  • AS-IS: POST /api/v1/reports/{reportId}/approve
  • TO-BE: PATCH /api/v1/reports/{reportId} (body에 status: APPROVED)
  • AS-IS: POST /api/v1/reports/{reportId}/withdraw
  • TO-BE: DELETE /api/v1/reports/{reportId} (body에 reporterId, reason)
• 호환성: 기존 액션 기반 엔드포인트가 없었으므로 Breaking Change 없음
• 마이그레이션: 신규 API이므로 마이그레이션 불필요

테스트

단위 테스트

• DTO 검증 테스트: Jakarta Validation 애노테이션 동작 확인
• Controller 테스트: MockMvc로 HTTP 요청/응답 검증
• Service 레이어 통합: 기존 서비스 레이어 테스트 모두 통과

수동 검증 방법

# 1. 빌드 및 테스트
./gradlew clean build

# 2. 신고 등록 테스트
curl -X POST http://localhost:8080/api/v1/reports \
  -H "Content-Type: application/json" \
  -d '{
    "reporterId": "USER-001",
    "reportedId": "USER-002",
    "referenceType": "PROFILE",
    "reportCategory": "harassment",
    "reason": "욕설 및 비방"
  }'

# 3. 신고 목록 조회
curl -X GET "http://localhost:8080/api/v1/reports?status=PENDING&size=20"

# 4. 신고 상태 변경
curl -X PATCH http://localhost:8080/api/v1/reports/REPORT-001 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "APPROVED",
    "adminId": "ADMIN-001",
    "comment": "승인 처리"
  }'

아키텍처 개선 사항

RESTful 설계 원칙 적용

1. 리소스 중심 URL: 액션(approve, reject) 대신 리소스(reports) 중심 설계
2. HTTP 메서드 의미 활용: POST(생성), GET(조회), PATCH(수정), DELETE(삭제)
3. 일관된 응답 형식: 모든 API가 동일한 응답 구조 사용
4. 자기 서술적 메시지: 상태 코드와 응답 본문으로 명확한 의미 전달

DTO 유효성 검사 계층화

• API 레벨: Jakarta Validation으로 요청 사전 검증
• 서비스 레벨: 비즈니스 로직 검증 (엔티티 메서드에서 처리)
• 엔티티 레벨: 도메인 규칙 검증 (예: 신고자만 철회 가능)

참조

• Closes [TASK] 프로필 신고 API 구현 #16 (프로필 신고 API 구현)
• refs [STORY] 게시글 신고 기능 #4 (게시글 신고 기능)
• refs [STORY] 프로필 신고 기능 #5 (프로필 신고 기능)
• refs [TASK] 신고 조회 API 구현 #17 (신고 조회 API 구현)
• 이전 PR: feat(report): 신고 조회 및 검색 API 구현, 성능 최적화 refs #17 #29 #32 (신고 조회 및 검색 API)