[FEAT] 폴더 편지 일괄 이동 및 추가 가능 목록 조회 API 구현

[ownue]

📌 PR 개요

• 폴더에 여러 편지를 일괄 추가/이동하는 API 구현
• 현재 폴더에 포함되지 않은 추가 가능 편지 목록을 조회하는 API 구현

---

🔗 관련 이슈

• Closes [FEAT] 변경사항에 맞춰 폴더 도메인 API 추가 #228
• Closes [REFACTOR] 편지 목록 DTO 변환 로직 공통화 #285

---

🛠 변경 사항

• POST /folders/{folderId}/letters 구현
  • 중복 편지 ID 제거 후 일괄 이동
  • 편지 중 하나라도 없거나 사용자 소유가 아니면 전체 요청 실패
• GET /folders/{folderId}/letters/available 구현
  • 현재 폴더에 포함된 편지를 제외하고 미소속/다른 폴더의 편지 조회
  • From, 좋아요, 키워드, 페이징 및 정렬 조건 적용
• 성공 응답 코드를 OK로 통일

---

⚠️ 리뷰 시 참고 사항

• 일괄 이동 전 편지 전체를 검증하는 흐름이 적절한지
• 추가 가능 편지 조회 조건이 적절한지

---

✅ 체크리스트

• 로컬에서 정상 실행됨
• 로그 / 네이밍 정리
• main / develop 직접 커밋 아님

Summary by CodeRabbit

• 새로운 기능

  • 여러 편지를 한 번에 폴더에 추가할 수 있습니다.
  • 폴더에 아직 추가되지 않은 편지를 목록으로 확인할 수 있습니다.
  • 발신자, 좋아요 여부, 키워드로 편지를 필터링하고 페이지 단위로 조회할 수 있습니다.
  • 편지 추가 처리 결과와 미리보기 정보를 확인할 수 있습니다.

• 개선

  • 중복 편지와 유효하지 않은 편지를 자동으로 검증합니다.
  • 편지 미리보기는 최대 100자까지 표시됩니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0664bb1a-6e35-4332-b857-2b70186bc97c

📥 Commits

Reviewing files that changed from the base of the PR and between 9576a7f and 93a6528.

📒 Files selected for processing (3)

• src/main/java/com/deare/backend/api/folder/service/FolderServiceImpl.java
• src/main/java/com/deare/backend/api/letter/mapper/LetterItemMapper.java
• src/main/java/com/deare/backend/api/letter/service/LetterServiceImpl.java

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

폴더에 여러 편지를 추가하는 POST API와 추가 가능한 편지를 조회하는 GET API를 추가했습니다. 서비스는 편지 검증, 폴더 소유권 확인, 조건 기반 페이지 조회를 수행합니다. 편지 항목 변환은 공통 Mapper로 통합했습니다.

Changes

폴더 편지 관리

Layer / File(s)	Summary
API 계약과 진입점 src/main/java/com/deare/backend/api/folder/controller/FolderController.java, src/main/java/com/deare/backend/api/folder/dto/..., src/main/java/com/deare/backend/api/folder/service/FolderService.java	요청·응답 DTO와 서비스 메서드를 추가했습니다. 편지 일괄 추가 및 추가 가능 편지 조회 엔드포인트를 추가했습니다.
편지 일괄 추가 처리 src/main/java/com/deare/backend/api/folder/service/FolderServiceImpl.java	중복 편지 ID를 제거합니다. 편지의 존재 여부, 삭제 여부, 사용자 소유권을 검증합니다. 검증된 편지를 폴더에 추가하고 처리 개수를 반환합니다.
추가 가능 편지 조회와 공통 변환 src/main/java/com/deare/backend/api/folder/service/FolderServiceImpl.java, src/main/java/com/deare/backend/domain/letter/repository/..., src/main/java/com/deare/backend/api/letter/mapper/LetterItemMapper.java, src/main/java/com/deare/backend/api/letter/service/LetterServiceImpl.java	활성 폴더 소유권을 검증합니다. 폴더에 포함되지 않은 편지를 조건과 페이지 정보로 조회합니다. LetterItemMapper가 편지 항목 변환을 처리하며 기존 목록 조회에도 적용됩니다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🔵 Low · up to 93a65

The bulk letter-move endpoint may mishandle null or empty ID lists and may reveal whether another user’s letter exists through different error responses. The change is mergeable with explicit owner confirmation or follow-up on request validation and error normalization.

Sequence Diagram(s)

sequenceDiagram
  actor Client
  participant FolderController
  participant FolderServiceImpl
  participant LetterRepositoryImpl
  participant LetterItemMapper
  Client->>FolderController: 추가 가능 편지 조회 요청
  FolderController->>FolderServiceImpl: 사용자·폴더·필터·페이지 정보 전달
  FolderServiceImpl->>FolderServiceImpl: 활성 폴더 소유권 검증
  FolderServiceImpl->>LetterRepositoryImpl: findAvailableLetters 호출
  LetterRepositoryImpl-->>FolderServiceImpl: 필터링된 Page<Letter> 반환
  FolderServiceImpl->>LetterItemMapper: 편지 항목 변환 요청
  LetterItemMapper-->>FolderServiceImpl: LetterItemDTO 반환
  FolderServiceImpl-->>FolderController: LetterListResponseDTO 반환
  FolderController-->>Client: 편지 목록 응답

Loading

Suggested reviewers: catomat0, hajimeong

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 폴더 편지 일괄 이동과 추가 가능 목록 조회라는 주요 변경사항을 명확하게 설명합니다.
Linked Issues check	✅ Passed	#228의 두 API 구현과 #285의 공통 Mapper 분리 및 적용 요구사항을 모두 반영했습니다.
Out of Scope Changes check	✅ Passed	모든 변경사항이 폴더 API 구현 또는 편지 목록 DTO 변환 공통화 목적과 직접 관련됩니다.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/#228-new-folder

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ownue]

@coderabbitai 리뷰 고

[coderabbitai]

@ownue 리뷰를 시작합니다.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[ownue]

@coderabbitai 중복 부분 Mapper로 처리하도록 수정했는데 이것도 포함해서 리뷰 부탁합니따~ 고칠 점 없을까용

[coderabbitai]

@ownue Mapper 리팩터링을 포함해서 최신 변경사항을 다시 리뷰하겠습니다. API 계약, 트랜잭션 처리, 조회 조건, Mapper 변환 범위를 확인합니다.

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[ownue]

@coderabbitai 이제 리밋 풀렸나요... 코드 리뷰 ㄱㄱ

[coderabbitai]

@ownue 최신 변경사항과 Mapper 리팩터링을 포함해서 PR #284를 리뷰합니다.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.