feat: 문서 이동/순서 변경 API 추가

[hellonaeunkim]

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

• BE
• FE
• Infra
• Docs
• Test

---

#️⃣ 연관된 이슈

closes #31

---

🔎 작업 내용

1. 주요 변경 사항 요약

• 문서 수정 API와 분리된 문서 이동/순서 변경 API 추가 (POST /v1/documents/{documentId}/move)
• 문서 이동 시 부모 변경과 같은 부모 내 reorder를 지원하도록 구현
• targetParentId, afterDocumentId, beforeDocumentId 기반 위치 해석 및 sortKey 재계산 로직 추가
• 활성 문서/부모 검증, 같은 workspace 검증, 자기 자신 부모 지정 금지, 순환 이동 금지 로직 추가
• WebMvc / 서비스 단위 / 통합 테스트 추가
• docs/REQUIREMENTS.md에 move API 명세와 정책 반영

2. 상세 내용 (선택)

• PATCH /v1/documents/{documentId}는 메타데이터 수정 책임만 유지하고, 구조 변경은 POST /v1/documents/{documentId}/move로 분리했습니다.
• move API request body는 아래 3개 필드로 구성했습니다.
  • targetParentId
  • afterDocumentId
  • beforeDocumentId
• 위치 해석 규칙은 다음과 같이 구현했습니다.
  • targetParentId = null이면 루트 형제 집합 이동
  • afterDocumentId만 있으면 해당 문서 뒤 위치
  • beforeDocumentId만 있으면 해당 문서 앞 위치
  • 둘 다 없으면 대상 부모의 마지막 위치
  • 둘 다 있으면 두 문서 사이 위치
• afterDocumentId, beforeDocumentId가 동시에 오면 같은 부모 집합의 활성 형제 문서인지, 서로 인접한 위치인지 검증합니다.
• 이동 시 parentId, sortKey, updatedBy를 한 트랜잭션 안에서 반영하고, updatedAt은 JPA update 시점에 함께 갱신됩니다.
• 동일 위치 no-op 요청은 성공으로 허용하되 실제 DB 갱신은 생략합니다.
• 정렬 키 간격이 없으면 현재 프로젝트 정책에 맞춰 SORT_KEY_REBALANCE_REQUIRED를 반환합니다.

3. 프롬프트 경로

• /prompts/2026-03-20-document-move-api.md

---

💬 집중 리뷰 요청

• 기존 문서 수정 API와 분리하여 새로 추가한 문서 이동/순서 변경 API 관련 [docs/REQUIREMENTS.md](https://github.com/jho951/Block-server/pull/32/changes/86a7c9cab9c725046bc95cd7560ed1bbce8fe894) 반영 범위가 과하지 않은지 점검 부탁드립니다.
• [DocumentSortKeyGenerator](https://github.com/jho951/Block-server/pull/32/changes/9a90431e9075c02a94d06537039418b18ac237b0)에 추가한 move용 sortKey 계산 로직이 현재 요구사항과 정렬 정책에 맞게 구현되었는지 확인 부탁드립니다.

---

🧪 테스트 방법

1. 로컬 실행 방법

• 프로젝트 루트에서 아래 명령 실행
• ./gradlew --no-daemon :documents-api:test --tests com.documents.api.document.DocumentControllerWebMvcTest :documents-infrastructure:test --tests com.documents.service.DocumentServiceImplTest :documents-boot:test --tests com.documents.api.document.DocumentApiIntegrationTest

2. 테스트 시나리오

• move 요청 성공 시 성공 응답 반환 확인
• move 성공 시 parentId, sortKey, updatedBy, updatedAt 반영 확인
• 같은 부모 내 reorder 결과가 문서 목록 조회에 반영되는지 확인
• 다른 부모로 이동한 결과가 문서 목록 조회에 반영되는지 확인
• 존재하지 않는 문서 move 시 DOCUMENT_NOT_FOUND 응답/예외 확인
• 삭제된 문서 move 시 DOCUMENT_NOT_FOUND 응답/예외 확인
• 자기 자신 부모 지정 시 INVALID_REQUEST 응답/예외 확인
• 순환 이동 시 INVALID_REQUEST 응답/예외 확인
• 다른 workspace 부모 지정 시 INVALID_REQUEST 예외 확인
• 모순된 afterDocumentId / beforeDocumentId 요청 실패 확인
• 정렬 키 공간 부족 시 SORT_KEY_REBALANCE_REQUIRED 확인
• X-User-Id 헤더 누락 시 UNAUTHORIZED 응답 확인

---

✅ PR 체크리스트

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

[oneplast]

현재 요구사항과 비즈니스 정책에 따라 잘 구현해주신 것 같습니다.
이전에 명시적으로 공유해드리지 못해 죄송하고, 위 리뷰 내용대로 한 번만 수정 부탁드리겠습니다🙇‍♂️😭

[oneplast]

수정 내용 확인했습니다! 고생하셨습니다!!