본문으로 건너뛰기

JunkBox apps/automation-api 가이드

1. 역할​

  • automation-api는 JunkBox 내부의 예약 실행, cron 정기 실행, 재시도, 실행 이력, 수동 실행을 독점적으로 소유하는 중앙 작업 실행 플랫폼임.
  • 새 배치·예약 작업은 각 앱에 scheduler loop를 추가하지 않고 Automation 작업 계약으로 등록함.
  • 수집, 동기화, 정리, 리포트와 메시지 작업은 같은 실행·재시도·이력 체계를 사용함.

2. 런타임과 배포​

  • API 엔트리포인트는 junkbox_automation_api.main:app, worker 엔트리포인트는 python -m junkbox_automation_api.worker임.
  • API와 worker는 같은 junkbox-automation 이미지의 별도 Compose 서비스임.
  • 로컬 API 포트는 18007, 운영 API 포트는 8007이며 worker는 외부 포트를 노출하지 않음.
  • API와 worker는 /health 또는 worker health command로 상태를 확인함.

3. 데이터 모델과 실행 보장​

  • SQLite 파일은 /sorc001/junkbox/db/automation.sqlite3이며 컨테이너 경로는 /app/db/automation.sqlite3임.
  • tb_automation_job_m은 작업 정의, 일정, 활성 상태, timeout, 재시도 정책, payload, 다음 실행 시각을 저장함.
  • tb_automation_job_revision_n은 작업 정의 수정 snapshot을 저장함.
  • tb_automation_execution_n은 예정 시각, 상태, 시도 수, worker, lease, 응답, 오류, retry 시각, idempotency key를 저장함.
  • 작업 정의 삭제는 soft delete로 처리하며 실행 이력은 유지함. 정의 생성·수정·활성화·비활성화·삭제 snapshot은 tb_automation_job_revision_n에 남김.
  • (job_id, scheduled_at)과 idempotency_key 유니크 제약으로 같은 예정 실행의 중복 생성을 방지함.
  • worker는 SQLite 원자 상태 전이와 lease 만료 회수로 at-least-once 실행을 제공함.
  • cron은 5필드 표현식과 Asia/Seoul 기준으로 계산함.
  • 네트워크 timeout과 재시도 가능 HTTP 오류는 작업별 최대 시도 횟수와 지수 backoff 정책으로 처리하며, 최대 시도 초과 실행은 최종 실패 상태로 남김.

4. 작업 대상과 인증​

  • 등록 가능한 job type은 코드 registry로 제한하며 임의 URL을 허용하지 않음.
  • notification.send는 Message internal API를 호출함.
  • notification-schedules, notification-recurrences 관리 API는 Message UI가 사용하는 notification.send 작업의 1회·cron 표현 계층임. 작업 정의와 다음 실행 시각은 Automation SQLite에만 저장함.
  • notification-schedules 요청의 메시지 내용은 notification.send payload로 저장하고 예약 시각은 작업 정의의 run_at으로만 저장함. 메시지 payload에는 실행 제어 필드를 저장하지 않음.
  • workout.medication-reminder-check는 Workout internal Job API를 호출함.
  • worker는 AUTOMATION_SERVICE_TOKEN, X-Junkbox-Service: automation, X-Junkbox-Job-Type, Idempotency-Key로 대상 앱을 호출함.
  • 대상 앱은 caller, token, job type을 검증함.
  • Automation은 대상 도메인 SQLite 또는 Message SQLite를 직접 읽거나 쓰지 않음.

5. 관리 API​

  • 관리 API 접두사는 /api/automation이며 Hub JWT의 HUB module 권한을 요구함.
  • 작업 등록·수정·삭제·활성화, 수동 실행, 실행 이력 조회, 수동 재시도를 제공함.
  • Message 일정 전용 API는 /notification-schedules, /notification-recurrences, /notification-recurrences/validate이며 모두 Hub JWT의 HUB module 권한을 요구함.
  • /notification-schedules는 1회 예약 메시지의 목록·등록·상세·수정·삭제를 제공함. /notification-recurrences는 cron 정기 메시지의 목록·등록·상세·수정·활성 상태·삭제를 제공함.
  • 작업 결과는 추후 관리 UI가 조회할 수 있도록 작업 정의와 실행 이력을 분리한 구조로 반환함.