feat: 블록 이동 및 순서 변경 API 구현

[hellonaeunkim]

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

• BE
• FE
• Infra
• Docs
• Test

---

#️⃣ 연관된 이슈

closes #34

---

🔎 작업 내용

1. 주요 변경 사항 요약

• 블록 이동 전용 API POST /v1/blocks/{blockId}/move 추가
• 블록 이동 요청 DTO MoveBlockRequest 추가
• BlockService, BlockServiceImpl에 블록 이동/순서 변경 로직 추가
• 블록 이동 시 부모 변경, 같은 부모 내 reorder, sortKey 재계산, version 충돌 검증 반영
• WebMvc 테스트, 서비스 단위 테스트, Boot 통합 테스트 추가

2. 상세 내용 (선택)

• 블록 수정 API와 분리된 이동 API로 구조 변경 책임을 분리했습니다.
• 요청 필드는 parentId, afterBlockId, beforeBlockId, version 으로 고정했습니다.
• 이동 대상 블록은 활성 블록만 허용하고, version 불일치 시 409 Conflict를 반환합니다.
• parentId가 있으면 같은 문서 소속 활성 블록인지 검증합니다.
• 자기 자신을 부모로 지정하거나 하위 블록을 부모로 지정하는 순환 이동은 400 Bad Request로 처리합니다.
• afterBlockId, beforeBlockId는 대상 부모 아래 활성 형제 집합 기준으로 검증합니다.
• 정렬 키 계산은 기존 OrderedSortKeyGenerator를 재사용했고, gap 부족 시 SORT_KEY_REBALANCE_REQUIRED로 변환했습니다.
• 동일 위치 요청은 no-op 성공으로 처리합니다.

요청 예시:

{
  "parentId": "new-parent-block-id",
  "afterBlockId": "blk-a",
  "beforeBlockId": null,
  "version": 0
}

3. 프롬프트 경로

• /prompts/2026-03-21-block-move-api.md

4. 참조 문서 경로 (ADR, discussions, roadMap ...)

• /docs/decisions/011-separate-block-update-from-move-api.md
• /prompts/explainers/ordered-sortkey-generator.md
• /docs/REQUIREMENTS.md

---

💬 집중 리뷰 요청

• BlockServiceImpl.move(...)의 검증 로직과 sortKey 계산 방식이 요구사항에 맞는지 확인부탁드립니다!

---

🧪 테스트 방법

1. 로컬 실행 방법

• 필요 시 ./gradlew :documents-boot:bootRun 실행
• 테스트만 확인할 경우 아래 명령 실행
  • ./gradlew --no-daemon :documents-api:test --tests com.documents.api.block.BlockControllerWebMvcTest
  • ./gradlew --no-daemon :documents-infrastructure:test --tests com.documents.service.BlockServiceImplTest
  • ./gradlew --no-daemon :documents-api:test --tests com.documents.api.block.BlockControllerWebMvcTest :documents-infrastructure:test --tests com.documents.service.BlockServiceImplTest :documents-boot:test --tests com.documents.api.block.BlockApiIntegrationTest

2. 테스트 시나리오

• POST /v1/blocks/{blockId}/move 호출 시 루트 이동이 정상 반영되는지 확인
• 같은 부모 아래 afterBlockId 기준 reorder 시 sortKey가 재계산되는지 확인
• 다른 부모 블록 아래로 이동 시 parentId, sortKey, updatedBy, version이 갱신되는지 확인
• 존재하지 않는 블록 이동 시 404 응답 확인
• 삭제된 블록 이동 시 404 응답 확인
• 낡은 version으로 이동 시 409 응답 확인
• 자기 자신 또는 하위 블록을 부모로 지정하면 400 응답 확인
• 다른 문서의 블록을 부모 또는 anchor로 사용하면 400 응답 확인

---

✅ PR 체크리스트

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

[oneplast]

고생하셨습니다!!