feat: EditorOperationController 경계 도입 및 Editor save, move 공통화

[oneplast]

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

• BE
• FE
• Infra
• Docs
• Test

---

#️⃣ 연관된 이슈

closes #65

---

🔎 작업 내용

1. 주요 변경 사항 요약

• EditorOperationController 경계 도입 ( /editor-operations )
  • save , move 를 Editor 협업/쓰기 경계로 정리
  • 두 요청을 모두 EditorOperationOrchestrator 로 연결
• Editor save 구조를 EditorSave* 기준으로 정리
  • Legacy DocumentTransaction* 구조 제거
• 관리자 단건 블록 API를 EditorSave* 기준으로 정리
• save 경계의 flush 및 문서 version up 책임 재정리
• 관련 테스트 검증 및 문서 반영

2. 상세 내용 (선택)

1. 에디터 관련 쓰기 경계를 EditorOperationController 기준으로 정리하였습니다.

• EditorOperationController 를 문서/블록 엔티티 전반에서 공통으로 발생하는 에디터 협업 Write 작업을 받는 경계로 잡았습니다.
  • 추후 워크스페이스 등 다른 협업 리소스가 생기더라도, 유사한 성격의 공통 작업은 해당 경계 안에서 함께 다룰 수 있습니다.
• 공통화 기준은 엔티티(도메인) 종류 자체가 아닌, '에디터 편집 과정에서 문서나 블록에 대해 발생하는 operation 성격의 작업인가' 입니다.
• 아래와 같은 작업들은 모두 문서/블록 개별 Resource CRUD와는 다르게, 에디터 협업 과정에서 구조나 상태를 반영하는 공통 Write 흐름으로 판단했습니다.
  • 에디터 쓰기/저장
  • 문서/블록 이동
• 공통화 방식은 하나의 API를 통해 모든 작업을 분기하는 dispatcher 구조로 잡지 않고, 공통 Controller 아래에 각 operation의 의미가 명확히 드러나는 명시적 endpoint를 두는 방식으로 정리하였습니다.
• 결과적으로, EditorOperationController 는 문서/블록 엔티티에 걸친 에디터 협업 operation의 공통 진입점임과 동시에, 각 작업의 의미와 계약은 endpoint 수준에서 그대로 드러나도록 유지하였습니다.
  
  

2. save 구조를 Editor operation 문맥에 맞게 다시 정리하였습니다.

• save 를 기존 DocumentTransaction... 명명과 구조를 중심으로 사용하지 않고, EditorSave... 기준으로 정리하였습니다.
• 기존 저장 알고리즘은 그대로 사용하되, Editor 경계 안에서 더 자연스럽게 이해할 수 있는 구조로 재정리한 것입니다.
  
  

3. move를 Editor operation 경계 안에서 공통화하였습니다.

• 문서와 블록 이동은 모두 에디터 구조 변경과 관련된 Write 작업이며, 유사한 요청/응답 구조로 처리됩니다.
• 따라서 move 또한 Editor operation write 작업으로 공통화처리하였습니다.
• 단, save 는 배치 저장 유스케이스이고, move 는 구조 변경 유스케이스이므로, 실제 처리 방식은 다릅니다.
  • move는 오케스트레이터에서 분기한 뒤, 각 resource 성격에 맞는 기존 처리 경로를 재사용하는 방식으로 요청을 처리합니다.
    
    

4. 관리자 단건 블록 API도 Editor save 기준으로 재정리하였습니다.

• 기존 DocumentTransaction* 구조를 더 이상 중심으로 사용하지 않으므로, 관리자 단건 블록 API도 EditorSave* 기준으로 재정리하였습니다.
  
  

5. save 경계에서 flush와 문서 version up 책임을 재정리하였습니다.

• 이번 작업에서 중요한 변경점 중 하나는, '어디에서 최신 응답을 확정하고, 어디에서 문서 version up을 할 것인가' 였습니다.
• Block 관련 응답은 최신 version , sortKey , deletedAt 이 필요한 시점에만 확정되도록 정리하였으며, document version은 담당 컴포넌트를 추가하여 별도 정책으로 유지되도록 책임을 분리하였습니다.
  
  

6. Legacy Deprecated 구조와 문서를 변경된 구조 기준으로 정리하였습니다.

• 기존 DocumentTransaction* 구조는 더 이상 중심 경계가 아니므로 제거하였습니다.
• 완료된 작업 기준으로 문서들을 최신화하였습니다.

3. 프롬프트 경로

• /prompts/worklog/2026-04/2026-04-05-node-domain-abstraction-review.md

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

ADR

• /docs/decisions/021-adopt-editor-operation-controller-boundary.md

discussions

• /docs/discussions/2026-04-05-node-domain-abstraction-review.md

explainers

• /docs/explainers/editor-save-model.md

guides

• /docs/guides/editor/editor-guideline.md
• /docs/guides/editor/frontend-editor-guideline.md
• /docs/guides/editor/backend-editor-guideline.md

---

💬 집중 리뷰 요청

• 추가된 EditorOperationController 에서 묶어서 처리하는 기준이 자연스러운지 확인 부탁드립니다.
• 해당 Controller에서 처리하는 API 및 구현 방식을 확인해주시기 바랍니다.
• 프론트 코드 기준으로, 기존 Editor save/move 호출부가 아래 기준 변경을 자연스럽게 따라갈 수 있는지 확인 부탁드립니다.
  • save 호출
    • POST /documents/{documentId}/transactions -> POST /editor-operations/documents/{documentId}/save
  • save 요청/응답 기준
    • DocumentTransaction* -> EditorSave*
  • move 호출
    • 기존 문서/블록 move 개별 경로 -> POST /editor-operations/move
  • move 요청
    • resourceType , resourceId , targetParentId , afterId , beforeId , version
  • move 응답
    • resourceType , resourceId , parentId , version , documentVersion , sortKey
• 이전 프론트 코드가 예전 DocumentTransaction* , 개별 move 경로, 기존 요청/응답 명명에 의존하고 있었다면, 이번 리팩토링 이후 어떤 호출부와 상태 동기화 코드를 함께 변경해야 할지 확인 부탁드립니다.

---

🧪 테스트 방법

1. 로컬 실행 방법

• ./gradlew :documents-infrastructure:test --tests com.documents.service.AdminBlockOperationServiceImplTest --tests com.documents.service.EditorOperationOrchestratorImplTest --tests com.documents.service.BlockServiceImplTest --tests com.documents.service.DocumentServiceImplTest
• ./gradlew :documents-api:test --tests com.documents.api.editor.EditorOperationControllerWebMvcTest --tests com.documents.api.block.AdminBlockControllerWebMvcTest --tests com.documents.api.document.DocumentControllerWebMvcTest
• ./gradlew :documents-boot:test --tests com.documents.api.editor.EditorOperationApiIntegrationTest --tests com.documents.api.editor.EditorOperationConcurrencyIntegrationTest --tests com.documents.api.block.AdminBlockApiIntegrationTest --tests com.documents.api.block.DocumentBlocksApiIntegrationTest --tests com.documents.api.document.DocumentApiIntegrationTest

2. 테스트 시나리오

• editor save API 가 editor operation 경계 기준으로 정상 동작하는지 확인
• move API 가 문서 / 블록 이동 모두 정상 동작하는지 확인
• 관리자 단건 block API 가 editor save 기준 계약으로 정상 동작하는지 확인
• legacy deprecated 구조 제거 이후 기존 editor 계약 검증이 유지되는지 확인
• flush / document version 정책 정리 이후 현재 동시성 테스트가 유지되는지 확인

---

✅ PR 체크리스트

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

---

📈 이미지 / 캡처 (필요 시)

No response