# Plan 스케줄 사용법

## 목적

반복적으로 등록되는 자동화 요청을 수동 입력 없이 생성하기 위한 스케줄 화면 사용법과 제약을 정리합니다.

## 구현 위치

- 화면: `src/features/planBoard/PlanSchedulePage.tsx`
- API: `src/features/planBoard/api.ts`

## 제공 기능

- 스케줄 목록 조회
- 신규 스케줄 등록
- 기존 스케줄 수정/삭제
- 즉시 실행 옵션 설정
- 활성/비활성 전환
- 반복 주기 또는 매일 실행 시간 설정
- 다음 실행 예정 시각 계산 표시

## 입력 항목

- `workId`: 반복 등록할 작업 ID
  - 스케줄이 실제 자동화 접수로 Plan을 만들 때 이 값을 베이스 ID로 사용합니다.
  - 생성되는 Plan 작업 ID는 `workId-1`부터 `workId-999` 범위의 suffix를 붙여 유니크하게 관리합니다.
- `note`: 매번 생성될 요청 메모
- `automationType`: 자동화 유형
  - 자동화 유형 관리를 통해 등록된 항목을 그대로 선택합니다.
  - 스케줄 실행 시 선택한 자동화 유형 ID를 유지한 채 자동화 작업메모를 등록하고 즉시 접수합니다.
- `releaseTarget`: 반영 대상 브랜치
- `jangsingProcessingRequired`: 기능동작확인 필요 여부
- `autoDeployToMain`: main 자동 반영 대상 여부
- `enabled`: 스케줄 사용 여부
- `immediateRunEnabled`: 생성 직후 바로 등록 허용 여부
- `refreshContextSnapshotOnNextRun`: 다음 자동 실행 1회에 한해 프로젝트 구조/관련 소스를 다시 읽고 `.auto_codex/schedule/<id>/` 아래 Markdown 문서를 재정리할지 여부
- `executionMode`: `codex` 또는 `managed-service`
  - `managed-service`를 선택하면 스케줄 PK가 포함된 `.auto_codex/schedule/<id>/managed-service/...` 경로에 서비스 패키지 번들을 생성해 구분합니다.
  - 스케줄 삭제 시 해당 디렉터리도 함께 삭제합니다.
- `recreateManagedServiceOnNextSave`: 관리형 서비스 패키지를 저장 시 다시 생성할지 여부

## 스케줄 모드

### 1. 반복 주기

`interval` 모드입니다.

- 값 + 단위로 반복 주기 설정
- 단위: `minute`, `hour`, `day`, `week`, `month`
- 내부 저장은 `repeatIntervalMinutes` 기준

### 2. 매일 시간

`daily` 모드입니다.

- `HH:mm` 형식 시간 사용
- 시간 계산은 `Asia/Seoul` 기준
- 하루 1회 등록에 적합

## 유효성 규칙

현재 화면에서 다음 검사를 수행합니다.

- 작업 ID 필수
- 메모 필수
- 같은 작업 ID 중복 금지
- `interval` 모드 최소 10분 이상
- 비활성 스케줄은 자동 등록되지 않음을 경고

## 다음 실행 시각 계산

다음 실행 시각은 화면에서 즉석 계산해 보여줍니다.

- 비활성 상태면 `중지`
- 직전 등록 이력이 없고 즉시 실행이 켜져 있으면 현재 시각 기준
- `daily`는 오늘 KST 실행 여부를 보고 오늘 또는 다음 날 시각 결정
- `interval`은 마지막 등록 시각 또는 생성 시각 기준으로 다음 주기를 계산

## 추천 운영 방식

- 자주 반복되는 운영 작업은 고정 `workId`로 등록
- 사람이 검토해야 하는 작업은 `autoDeployToMain`을 끄고 release 검수 단계에서 확인
- 단순 알림성/반복성 작업은 `immediateRunEnabled`를 켜서 누락 없이 시작
- 기존 스케줄 참조 문서를 다시 만들고 싶으면 `refreshContextSnapshotOnNextRun`을 켠 뒤 저장하면 다음 실행 1회 후 자동 해제
- 외부 프로그램으로 확장할 예정인 작업은 `managed-service`로 분리해 두면 스케줄 PK 기준 서비스 키와 패키지 경로를 고정할 수 있음
- 짧은 주기 스케줄은 10분 이상으로 유지해 중복 생성 위험을 낮춤

## API 경로 메모

스케줄 API는 서버 구현 차이를 흡수하기 위해 여러 경로를 순차 시도합니다.

- `/plan/scheduled-tasks`
- `/plan/schedule/tasks`
- `/plan/schedule`
- `/plan/schedules`
- `/plans/...` 변형 경로

서버 경로가 고정되면 후보 경로를 줄여도 됩니다.

## 테스트 포인트

- interval/daily 전환 시 값 보존이 자연스러운지 확인
- 같은 `workId` 중복 저장이 막히는지 확인
- KST 기준 다음 실행 시각이 기대와 일치하는지 확인
- 비활성 스케줄이 자동 생성되지 않는지 확인
- 토큰 없는 사용자에게 저장/삭제가 제한되는지 확인
