# Calendar Skill 기반 자동 휴일 감지 행동 제어 시스템 구축

**날짜**: 2026-02-14
**작성자**: happybell80
**관련 서비스**: rb8001, skill-calendar, robeing-monitor

---

## 1. 문제
- 스케줄러는 `mon-fri` cron 기준으로만 실행되어 공휴일을 배제하지 못한다.
- 연휴 중에도 평일 잡이 실행되어 운영 정책과 충돌한다.
- 현재 연휴 제어는 수동 비활성화에 의존한다.

## 2. 목표
- 목표 1: 상시 규칙으로 워킹데이(공휴일 제외) 실행을 자동화한다.
- 목표 2: 특정 기간(예: 설 연휴) 블랙아웃으로 즉시 실행 차단을 지원한다.
- 목표 3: 운영 API에서 상태 조회와 제어 이력을 확인한다.

## 3. 해결방안
- `skill-calendar`에 휴일 판정 API를 추가한다.
- `rb8001` 스케줄러 실행 경로에 공통 가드를 추가한다.
- DB에 스케줄 정책 필드를 추가하고 잡별 정책을 저장한다.
- `robeing-monitor` 설정 API에서 `schedule_type`, `schedule_days`를 실제 저장/조회로 전환한다.

## 4. 아키텍처
- 휴일 소스: Google Calendar의 공휴일 캘린더 + 수동 블랙아웃 기간.
- 판정 서비스: `skill-calendar`가 날짜별 `is_workday`, `is_blackout`, `reason`을 반환.
- 실행 가드: `rb8001` 잡 실행 직전 판정 API 호출 후 실행/스킵 결정.
- 운영 가시성: 스킵 로그를 activity 로그에 저장하고 모니터링 API로 조회.

## 5. Phase 작업
### Phase 1: 데이터 모델
- `scheduled_jobs`에 `schedule_policy` JSONB 컬럼을 추가한다.
- 기본 정책을 `{"mode":"workday","blackout_ranges":[]}`로 저장한다.
- Repository CRUD에서 `schedule_policy` 읽기/쓰기/수정 경로를 추가한다.

### Phase 2: skill-calendar 휴일 판정
- `skill-calendar`에 `GET /api/workday/check` 엔드포인트를 추가한다.
- 입력: `date`, `timezone`, `country`, `blackout_ranges`.
- 출력: `is_workday`, `is_blackout`, `should_run`, `reason`.
- 결과 캐시를 1일 단위로 저장해 반복 조회 부하를 줄인다.

### Phase 3: rb8001 실행 가드
- `db_loader`에서 잡 등록 시 policy를 실행 함수 인자로 전달한다.
- 각 `_run_*_with_logging` 진입점에서 공통 가드 함수를 먼저 호출한다.
- `should_run=false`면 작업 본문을 실행하지 않고 스킵 로그를 남긴다.

### Phase 4: 운영 API/관리 UI 정합화
- `rb8001 /api/scheduler/jobs` 응답에 `schedule_policy`를 포함한다.
- `rb8001 /api/scheduler/jobs/{name}` PATCH에 `schedule_policy` 업데이트를 포함한다.
- `robeing-monitor` preferences API에서 `schedule_type`, `schedule_days`를 DB 반영한다.

### Phase 5: 테스트/검증
- 단위 테스트: 휴일/평일/블랙아웃 케이스 판정 테스트.
- 통합 테스트: 잡 실행 시 스킵/실행 분기 테스트.
- 운영 검증: 연휴 날짜(2026-02-16~2026-02-18) `should_run=false` 확인.

## 6. 기대효과
- 연휴/공휴일 기간의 자동 실행 충돌을 제거한다.
- 수동 비활성화 절차를 상시 자동 제어로 대체한다.
- 정책 기반 운영으로 스케줄 변경 이력과 실행 근거를 명확히 유지한다.

## 7. 남은 작업
- Phase 1~5를 순차 구현한다.
- 구현 완료 시 본 문서를 `journey/plans/archive/`로 이동한다.
- 상세 구현/장애 내역은 `journey/troubleshooting/`에 분리 기록한다.
