ai-code-app/docs/features/plan-schedule.md

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 기준 다음 실행 시각이 기대와 일치하는지 확인
• 비활성 스케줄이 자동 생성되지 않는지 확인
• 토큰 없는 사용자에게 저장/삭제가 제한되는지 확인