[Docs] Worker 등록 및 Heartbeat 상세 설계 보강

[Gimini-3]

작업 내용

• Worker 등록 및 Heartbeat 설계 문서를 실제 구현 기준의 상세 설계로 확장했습니다.
• Worker 역할명과 실행 인스턴스 식별자의 차이를 구체화했습니다.
• 애플리케이션 시작, Heartbeat, 정상 종료, 비정상 종료 흐름을 정리했습니다.
• Heartbeat와 종료가 경쟁할 때 조건부 UPDATE로 STOPPED 상태를 보호하는 원리를 설명했습니다.
• 저장 상태와 Heartbeat 기반 실질 상태를 분리하고 DEAD 판정 규칙을 명시했습니다.
• 관리자 API의 처리 흐름, 응답, 권한 오류와 빈 목록 계약을 추가했습니다.
• Migration, 장애 시나리오, 후속 Job 처리 계약, 계층별 테스트와 완료 기준을 보강했습니다.

변경 이유

기존 문서는 구현 범위와 핵심 규칙만 요약하고 있어 Worker가 시스템에서 언제 등록되고 어떤 방식으로 생존·종료 상태를 관리하는지 전체 흐름을 파악하기 어려웠습니다. 코드와 운영 동작을 함께 이해할 수 있도록 문서만 읽어도 생명주기와 동시성 설계를 확인할 수 있게 정리했습니다.

검증

• Markdown 제목 구조 확인
• 코드 블록 시작·종료 개수 확인
• git diff --check
• 실제 Worker Entity, Lifecycle, Scheduler, Repository, Query Service, Migration과 내용 대조

Related to #39

Summary by CodeRabbit

• 문서화
  • Worker 등록 및 Heartbeat 기능의 상세 설계 문서를 보강했습니다.
  • Worker 식별, 상태 및 재시작 처리 규칙을 명확히 정리했습니다.
  • Heartbeat 갱신, 정상 종료, 장애 및 DEAD 판정 기준을 문서화했습니다.
  • 관리자 조회 API의 응답 형식과 권한 요구사항을 추가했습니다.
  • 데이터베이스 마이그레이션, 예외 상황, 테스트 범위 및 완료 기준을 구체화했습니다.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 69e17c34-b4a8-4d0b-a7d4-0c0351ba028f

📥 Commits

Reviewing files that changed from the base of the PR and between 976c347 and 52e6ee2.

📒 Files selected for processing (1)

• docs/design/gimin-#39-worker-node-heartbeat.md

---

📝 Walkthrough

Walkthrough

Worker 노드 Heartbeat 설계 문서를 확장해 식별 모델, 등록·종료 생명주기, 조건부 갱신, DEAD 판정, 관리자 API, 마이그레이션, 장애 대응, 테스트와 완료 기준을 구체화했다.

Changes

Worker 노드 Heartbeat 설계

Layer / File(s)	Summary
식별 모델과 상태 정책 docs/design/gimin-#39-worker-node-heartbeat.md	worker_name과 instance_id를 분리하고, 설정 검증·상태 모델·instance_id 제약 및 마이그레이션 절차를 정의했다.
등록과 Heartbeat 생명주기 docs/design/gimin-#39-worker-node-heartbeat.md	애플리케이션 준비 완료 시 등록하고, 조건부 Heartbeat 갱신과 정상 종료 시 STOPPED 기록 및 동시성 방지 규칙을 명시했다.
실질 상태와 관리자 조회 docs/design/gimin-#39-worker-node-heartbeat.md	Heartbeat 시각에 따른 DEAD 계산, 장애·경계 상황, /admin/workers 응답과 후속 Job 처리 계약을 문서화했다.
테스트와 완료 기준 docs/design/gimin-#39-worker-heartbeat.md	Entity, Repository, Service, 생명주기, Scheduler, Controller 테스트 범위와 완료 체크리스트를 추가했다.

Estimated code review effort: 2 (Simple) | ~15 minutes

Suggested reviewers: kangcheolung

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/39-worker-heartbeat-design-details

---

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.}