feat: 문서 휴지통 자동 삭제 기능 추가

[hellonaeunkim]

📝 Part (해당되는 것만 체크)

• BE
• FE
• Infra
• Docs
• Test

---

#️⃣ 연관된 이슈

closes #41

---

🔎 작업 내용

1. 주요 변경 사항 요약

• 기존 문서 삭제 API를 soft delete에서 hard delete로 변경
• 문서를 휴지통으로 보내는 별도 soft delete API를 추가
• 휴지통 문서 자동 영구 삭제 스케줄러 추가
• 워크스페이스 기준 휴지통 문서 목록 조회 API를 추가

2. 상세 내용 (선택)

• 삭제 정책 변경

  • DELETE /v1/documents/{documentId} 는 문서, 하위 문서, 각 문서 소속 블록을 즉시 물리 삭제합니다.
  • 기존 soft delete 역할은 휴지통 기능으로 분리했습니다.

• 휴지통 이동 API

  • PATCH /v1/documents/{documentId}/trash
  • 문서를 휴지통 상태로 바꾸고 deletedAt 을 기록합니다.
  • 하위 문서와 각 문서 소속 블록도 함께 soft delete 됩니다.

• 휴지통 복구 API

  • 기존 POST /v1/documents/{documentId}/restore 를 휴지통 복구 API로 사용합니다.
  • 휴지통 문서만 복구할 수 있습니다.
  • 현재 테스트 기준 deletedAt + 5분 이 지나면 복구할 수 없습니다.
  • 부모 문서가 삭제 상태면 자식 문서 단독 복구는 실패합니다.

• 자동 영구 삭제

  • 휴지통 문서는 현재 테스트 기준 deletedAt + 5분 이 지나면 자동 영구 삭제됩니다.
  • 대상 문서, 하위 문서, 각 문서 소속 블록까지 함께 삭제됩니다.
  • 현재 5분은 테스트 기준이고, 추후 정책에 따라 바뀔 수 있도록 문서화했습니다.

• 휴지통 조회 API

  • GET /v1/workspaces/{workspaceId}/trash/documents
  • 휴지통 문서 목록만 조회합니다.
  • 응답에는 documentId, title, parentId, deletedAt, purgeAt 를 포함합니다.
  • 휴지통으로 옮겨진 문서는 제목만 목록에서 확인하는 용도이고, 내부 블록이나 내용 조회는 허용하지 않습니다.

3. 프롬프트 경로

• /prompts/2026-03-25-document-trash-and-hard-delete.md

---

💬 집중 리뷰 요청

• Scheduler 기능이 현재 테스트 기준 5분 정책에 맞게 구현됐는지 확인 부탁드립니다!
  • 관련 커밋: b1fd9c6

---

🧪 테스트 방법

1. 로컬 실행 방법

• ./gradlew :documents-infrastructure:test --tests com.documents.service.DocumentServiceImplTest
• ./gradlew :documents-api:test --tests com.documents.api.document.DocumentControllerWebMvcTest
• ./gradlew :documents-boot:test --tests com.documents.api.document.DocumentApiIntegrationTest

2. 테스트 시나리오

• DELETE /v1/documents/{documentId} 호출 시 문서, 하위 문서, 소속 블록이 물리 삭제되는지 확인
• PATCH /v1/documents/{documentId}/trash 호출 시 문서, 하위 문서, 소속 블록이 휴지통 상태로 전환되는지 확인
• POST /v1/documents/{documentId}/restore 호출 시 5분 이내 문서만 복구되는지 확인
• GET /v1/workspaces/{workspaceId}/trash/documents 호출 시 휴지통 문서만 조회되는지 확인
• 현재 테스트 기준 5분이 지난 휴지통 문서는 자동 영구 삭제되는지 확인

---

✅ PR 체크리스트

• 불필요한 디버그 로그 / 주석 제거
• breaking change 여부 확인 및 문서화
• 신규/변경된 기능에 대한 테스트 코드 추가 또는 기존 테스트 통과
• 로컬에서 주요 시나리오 수동 테스트 완료
• 관련 문서(노션, README, API 문서 등) 업데이트

[Copilot]

Pull request overview

문서 삭제 정책을 hard delete(기본 DELETE)와 휴지통 이동(PATCH /trash)로 분리하고, 휴지통 복구 만료(5분) 및 자동 영구 삭제 스케줄러/조회 API까지 추가하는 변경입니다. 문서/블록/하위 문서의 수명주기를 일관되게 맞추면서, 휴지통 UX를 위한 조회 및 제목 유니크 정책도 함께 도입합니다.

Changes:

• DELETE /v1/documents/{documentId}를 hard delete로 전환하고, PATCH /v1/documents/{documentId}/trash 및 휴지통 조회 API를 추가
• 휴지통 복구 가능 시간(현재 테스트 기준 5분) 검증 및 만료 문서 자동 purge 스케줄러 추가
• 워크스페이스 내 문서 title 유니크 정책을 create/update/restore에 적용하고 테스트/문서 갱신

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
prompts/2026-03-25-document-trash-and-hard-delete.md	변경 단계/테스트 실행 기록 문서 추가
documents-infrastructure/src/test/java/com/documents/service/DocumentServiceImplTest.java	hard delete/휴지통 이동/복구 만료/purge/title 유니크 관련 서비스 테스트 보강
documents-infrastructure/src/main/java/com/documents/service/DocumentServiceImpl.java	hard delete 전환, trash/restore 만료 검증, purge 로직, title 유니크 검증 추가
documents-infrastructure/src/main/java/com/documents/repository/DocumentRepository.java	휴지통 목록/만료 trash root 조회 쿼리 및 title 중복 체크 메서드 추가
documents-core/src/main/java/com/documents/service/DocumentService.java	getTrash/trash/purgeExpiredTrash API 추가
documents-core/src/main/java/com/documents/domain/DocumentTrashPolicy.java	휴지통 보관 시간(5분) 정책 상수 추가
documents-boot/src/test/java/com/documents/api/document/DocumentApiIntegrationTest.java	휴지통 조회/삭제 정책/휴지통 이동/복구 만료/purge/title 유니크 통합 테스트 보강
documents-boot/src/main/java/com/documents/DocumentTrashPurgeScheduler.java	1분 fixedDelay purge 스케줄러 추가
documents-boot/src/main/java/com/documents/DemoApplication.java	스케줄링 활성화(@EnableScheduling)
documents-api/src/test/java/com/documents/api/document/DocumentControllerWebMvcTest.java	휴지통 조회/휴지통 이동/복구 만료/title 유니크 등 컨트롤러 슬라이스 테스트 추가
documents-api/src/main/java/com/documents/api/document/dto/TrashDocumentResponse.java	휴지통 목록 응답 DTO 추가(deletedAt/purgeAt 포함)
documents-api/src/main/java/com/documents/api/document/DocumentController.java	휴지통 목록 조회 및 휴지통 이동 엔드포인트 추가
documents-api/src/main/java/com/documents/api/document/DocumentApiMapper.java	TrashDocumentResponse 매핑(purgeAt 계산 포함) 추가
docs/runbook/DEBUG.md	hard delete/휴지통 이동/복구/조회/purge 디버깅 런북 보강
docs/roadmap/v2/documents/document-trash.md	문서 휴지통 v2 로드맵/운영 고려사항 추가
docs/discussions/2026-03-25-document-hard-delete-and-trash-endpoint-review.md	정책 검토 메모 문서 추가
docs/REQUIREMENTS.md	삭제/휴지통/복구 정책 및 title 유니크 요구사항 반영

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jho951]

document title 다시 중복 안되게 변경 부탁드릴게요.

[jho951]

reviewed these changes and approve the merge!

[hellonaeunkim]

document title 다시 중복 안되게 변경 부탁드릴게요.

반영하여 수정했습니다!

[jho951]

approve