차단·신고 API와 미디어 정리 스케줄러 추가 및 Swagger 전체 문서화

[cfcromn]

✨ 작업 내용

#30 의 세 항목 중 결정이 필요한 2번(암호화 모델)을 제외한 나머지를 구현하고, 누락되어 있던 Swagger 문서화를 함께 채웠습니다.

차단 API (/api/v1/blocks)

• POST / 차단, GET / 차단 목록 조회, DELETE /{memberId} 차단 해제를 추가하였습니다.
• 차단은 tbl_block 에 행 하나를 넣는 것이 전부이며, 친구 관계나 대기 중인 요청을 삭제하지 않습니다.
• 누락되어 있던 FriendRepository.findReceivedRequests / findSentRequests 의 차단 필터를 추가하였습니다.

신고 API (/api/v1/reports)

• POST / 신고 접수를 추가하였습니다. 회원·캡슐·방명록을 대상으로 하며 중복 신고를 차단합니다.
• Report.targetType 과 Report.reason 을 raw String 에서 ReportTargetType / ReportReason enum 으로 교체하였습니다. 컬럼이 이미 VARCHAR(30) 이라 마이그레이션은 필요하지 않습니다.

미디어 정리 스케줄러

• CleanUpMediaService 를 추가하여 캡슐에 첨부되지 않은 채 방치된 미디어 행과 S3 객체를 매일 04:00 에 정리합니다.
• 프로젝트 최초의 @Scheduled 라 SchedulingConfig 를 함께 추가하였습니다.

Swagger 전체 문서화

• AuthController, MemberController, MediaController, CapsuleController 의 23개 엔드포인트에 @Tag·@Operation·@ApiResponses 를 추가하였습니다. 기존에는 어노테이션이 하나도 없었습니다.
• auth, member, media, timecapsule 의 DTO 에 @Schema 를 추가하였습니다. 이 역시 기존에는 전무하였습니다.
• SwaggerConfig 에 API 제목·버전·인증 방법·공통 응답 형식 설명을 추가하였습니다.
• 최종적으로 컨트롤러 9개 / 엔드포인트 40개 / DTO 27개가 모두 문서화되었습니다.

---

🔍 리뷰 시 참고사항

차단을 "필터만" 방식으로 구현한 이유

차단 시 친구 관계를 끊는 방식도 검토했으나, 이 코드베이스는 이미 차단을 SQL 필터로 처리하는 방향을 택하고 있었습니다. findFriendships, searchSelectableByNickname, CapsuleAccessPolicy 가 모두 NOT EXISTS 로 차단 상대를 제외합니다. 같은 방식을 따르면 차단 시 부수적인 삭제 로직이 전혀 필요 없고, 차단을 해제하면 이전 상태가 그대로 복원됩니다.

작업 중 발견한 기존 결함

findReceivedRequests 와 findSentRequests 에는 차단 필터가 빠져 있었습니다. 그래서 상대를 차단해도 그가 보낸 친구 요청이 목록에 계속 보이고, 수락을 시도하면 RespondFriendRequestService 의 재검증에 걸려 BLOCKED_MEMBER 로 실패합니다. 사용자 입장에서는 처리할 수 없는 요청이 목록에 남아 있는 상태였습니다. findFriendships 와 동일한 NOT EXISTS 형태로 채웠습니다.

스케줄러가 다루는 범위

DB에 행이 남아 있는 미디어만 정리합니다. Presigned URL 만 발급받고 업로드 완료 등록을 하지 않은 경우는 pending/ 접두사 아래에 행 없는 S3 객체만 남는데, 이는 S3 라이프사이클 규칙으로 만료시키는 편이 적절하다고 판단해 애플리케이션 코드로 처리하지 않았습니다. 해당 판단은 코드에 주석으로 남겨두었습니다.

객체 삭제에 실패한 행은 삭제하지 않고 다음 실행으로 넘깁니다. 행이 객체를 가리키는 유일한 참조이므로, 행을 먼저 지우면 객체를 영영 찾을 수 없게 됩니다.

OpenAPI 문서 자체를 테스트로 검증하였습니다

Swagger 어노테이션은 빠뜨리기 쉬워서, 소스에 어노테이션이 있는지가 아니라 실제로 생성된 /v3/api-docs 문서를 검증하도록 OpenApiDocumentTest 를 추가하였습니다. 모든 엔드포인트가 summary 와 description 을 갖는지, 태그가 붙어 있는지, 9개 도메인 태그가 모두 존재하는지, bearer 인증 스킴이 등록되어 있는지를 확인합니다.

이 테스트를 작성하는 과정에서 SecurityConfigTest 의 @RestController 픽스처가 컴포넌트 스캔에 포함되어 문서에 섞여 들어오는 것을 발견하여, 테스트에서 제외하도록 처리하고 이유를 주석에 남겼습니다.

이번 PR에 포함하지 않은 것

#30 의 2번(Shamir's Secret Sharing / 암호화 모델)은 포함하지 않았습니다. 「🔐 암호화 설계」 문서의 클라이언트 사이드 E2E 모델과 현재 구현된 서버 사이드 봉투 암호화가 서로 다른 모델이라, 어느 쪽으로 갈지 결정이 필요합니다. 결정 후 별도 PR 로 진행하는 것이 적절하다고 판단하였습니다. 따라서 이번 PR 로 #30 이 닫히지는 않습니다.

테스트

전체 275개가 통과합니다. (기존 256개 + 이번 19개)

---

✅ 체크리스트

• 문서(README, .env.example 등) 변경이 필요한 경우 작성 또는 수정했나요?
• 작업한 코드가 정상적으로 동작하는 것을 직접 확인했나요?
• 필요한 경우 테스트 코드를 작성하거나 수정했나요?
• Merge 대상 브랜치를 올바르게 설정했나요?
• PR에 관련 없는 작업이 포함되지 않았나요?
• 적절한 라벨과 리뷰어를 설정했나요?

---

📎 관련 이슈(선택)

• feat: 차단/신고 API, 암호화 모델 결정, 스케줄러 정리 #30 (2번 암호화 모델 결정이 남아 있어 이 PR로는 닫히지 않습니다)