[Feat] 프롬프트 상세 조회 및 댓글 CRUD API 계약 및 Swagger 명세 작성

[KunHeeLee7]

어떤 기능인가요?

프론트엔드 연동을 위해 프롬프트 상세 조회와 댓글 CRUD 및 대댓글 작성 API 계약을 정의하고 Swagger에 노출합니다.

이번 이슈는 Controller 골격, Request/Response DTO, OpenAPI 명세와 계약 테스트를 범위로 합니다. 실제 비즈니스 로직, 영속성, 결제 권한 판별 및 워터마크 연동은 후속 작업에서 구현합니다.

관련 도메인

• prompt
• community
• user
• commerce

API 범위

• GET /api/v1/prompts/{promptId}: 프롬프트 상세 조회
• GET /api/v1/prompts/{promptId}/comments: 댓글 목록 조회
• POST /api/v1/prompts/{promptId}/comments: 댓글 작성
• PATCH /api/v1/comments/{commentId}: 댓글 수정
• DELETE /api/v1/comments/{commentId}: 댓글 삭제
• POST /api/v1/comments/{commentId}/replies: 대댓글 작성

요구사항

공통

• 사용자 식별자는 요청 DTO가 아닌 인증 정보에서 가져온다.
• 상세 조회와 댓글 목록 조회는 비회원도 요청할 수 있다.
• 댓글 작성·수정·삭제 및 대댓글 작성은 로그인 사용자만 요청할 수 있다.
• 공통 ApiResponse 형식을 사용한다.
• Swagger에 요청·응답 예시와 주요 오류 응답을 작성한다.
• 미구현 비즈니스 로직에서 가짜 응답을 반환하지 않는다.

프롬프트 상세 조회

• 응답에 프롬프트 기본 정보, 작성자, 본문 접근 상태, 이미지, 태그, 통계 및 생성·수정 시간을 포함한다.
• 콘텐츠 타입은 FREE, PREMIUM만 사용한다.
• PREMIUM 가격은 서버에서 관리하는 고정값을 반환한다.
• 작성자 정보의 공개 여부는 관리자 숨김 상태와 별도로 관리한다.
• 삭제되거나 숨김 처리되어 조회할 수 없는 프롬프트는 반환하지 않는다.

본문 접근 정책

• 비회원에게는 promptBody를 빈 문자열로 반환한다.
• 로그인 사용자는 FREE 콘텐츠의 원문 전체를 조회할 수 있다.
• PREMIUM 미결제 사용자에게는 원문의 앞부분 10%, 최대 200자만 반환한다.
• PREMIUM 결제 완료 사용자와 프롬프트 작성자에게는 원문 전체를 반환한다.
• 응답에 access.locked, access.reason을 포함하여 로그인 또는 결제 필요 여부를 전달한다.
• 권한 없는 사용자에게 원문 전체를 전달한 뒤 프론트엔드에서 필터링하지 않는다.

이미지

• 모든 프롬프트 결과 이미지에는 워터마크를 필수로 적용한다.
• 워터마크 처리가 완료된 이미지만 프롬프트에 사용할 수 있다.
• 상세 조회에는 워터마크 이미지의 Presigned URL만 반환한다.
• 원본 이미지 URL, S3 Key 및 버킷 경로는 클라이언트에 노출하지 않는다.

댓글 목록 조회

• 댓글은 별도의 페이지네이션 없이 전체 목록을 한 번에 반환한다.
• 댓글과 대댓글은 작성 시간 내림차순으로 정렬하여 최신 댓글을 먼저 반환한다.
• 댓글 응답에 작성자의 공개 이름과 프로필 이미지 정보를 포함한다.
• 현재 로그인 사용자의 댓글인지 나타내는 mine을 포함한다.
• 대댓글은 부모 댓글의 replies에 포함한다.
• 삭제된 부모 댓글에 대댓글이 남아 있으면 부모 댓글의 위치를 유지한다.

댓글 작성·수정·삭제

• 작성 및 수정 요청 DTO에는 content만 포함한다.
• 댓글 내용은 필수이며 공백만 입력할 수 없다.
• 댓글 작성 성공 시 201 Created를 반환한다.
• 댓글 작성자 본인만 댓글을 수정하거나 삭제할 수 있다.
• 댓글은 논리 삭제한다.
• 댓글 삭제 성공 시 200 OK와 공통 ApiResponse를 반환한다.

대댓글

• 최상위 댓글에는 대댓글을 작성할 수 있다.
• 대댓글에는 추가 대댓글을 작성할 수 없다.
• 대댓글 작성 성공 시 201 Created를 반환한다.
• 존재하지 않거나 삭제된 댓글에는 대댓글을 작성할 수 없다.

주요 오류 응답

• 인증이 필요한 요청에 인증 정보가 없으면 401 Unauthorized를 반환한다.
• 다른 사용자의 댓글을 수정하거나 삭제하면 403 Forbidden을 반환한다.
• 프롬프트 또는 댓글이 존재하지 않으면 404 Not Found를 반환한다.
• 요청 값이 유효하지 않으면 400 Bad Request를 반환한다.

TODO

• PromptController 상세 조회 엔드포인트 골격 작성
• PromptControllerDocs Swagger 명세 작성
• CommentController 엔드포인트 골격 작성
• CommentControllerDocs Swagger 명세 작성
• 프롬프트 상세 조회 Response DTO 작성
• 댓글 Request/Response DTO 작성
• Bean Validation 및 OpenAPI Schema 설명 추가
• Controller 계약 테스트 작성

참고 자료

• API 명세서
• FE·BE 통합 회의록
• 프롬프트 상세 화면 기획 시안
• 댓글 및 대댓글 화면 기획 시안

제출 전 확인사항

• 비회원 응답에 프롬프트 원문이 포함되지 않는지 확인했습니다.
• 프리미엄 미결제 사용자에게 원문의 10%, 최대 200자만 반환하도록 명세했는지 확인했습니다.
• 원본 이미지 정보가 응답에 포함되지 않는지 확인했습니다.
• 댓글 수정 및 삭제 권한이 작성자 본인으로 제한되는지 확인했습니다.
• 적절한 라벨과 Assignee를 설정했습니다.