본문으로 건너뛰기

JunkBox apps/automation-api 가이드

업무 개요​

  • 서버에서 정해진 시각에 또는 주기적으로 실행해야 하는 모든 작업을 한 곳에서 실행·재시도·기록하는 것이 목적임. 앱마다 스케줄러를 두면 실행 이력과 중복 방지 책임이 흩어지기 때문임.
  • 핵심 개념은 작업 유형(job_type), 작업 정의(1회·cron·수동), 실행(execution), claim/lease, 재시도, idempotency key임.
  • Automation은 언제 무엇을 호출할지만 소유함. 업무 조건의 판정과 도메인 데이터는 호출 대상 앱이 소유함.
  • 사용자 앱 화면은 없으며 Message UI의 예약·정기 메시지 화면이 Automation의 작업 정의를 조회·수정함.

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, 운영 컨테이너 내부 포트는 8080이며 worker는 외부 포트를 노출하지 않음.
  • API와 worker는 /health 또는 worker health command로 상태를 확인함.

3. 인증과 권한​

  • 등록 가능한 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에는 실행 제어 필드를 저장하지 않음.
  • track.notification-check는 Track internal Job API를 호출하는 매분 cron 작업임. Track이 자기 SQLite에서 도래 시각과 발송 중복 여부를 판정하고 Message internal API에 전달함.
  • chess.game-sync는 Chess internal Job API를 호출해 연결된 Lichess 계정의 종료 대국 동기화를 실행함. Automation은 작업 정의·일정·claim/lease·timeout·재시도·idempotency key·실행 이력을 소유하고, Chess는 자기 SQLite의 연결 계정·수집 cursor·게임 중복 여부를 판정함.
  • chess.ai-review는 MANUAL 작업으로 Chess의 복기 배치 internal Job API를 호출함. 동일 대국의 PENDING·RUNNING 실행을 재사용하고 성공한 배치의 다음 실행을 한 트랜잭션으로 등록함. 기본 timeout은 3300초이며 실행당 한 번만 시도함. 실패·timeout·중단은 최종 FAILED로 기록하고 대기 후 자동 재시도하지 않음. 코칭 대상·확정 결과·사용량은 Chess SQLite에서 관리함.
  • questlog.finalize-period는 QuestLog internal Job API를 호출하는 매시 5분(KST) cron 작업임. 미션마다 시작 시각이 달라 매시 호출하며, QuestLog가 미션별 시작 요일·시작일·시작 시각 기준으로 막 끝난 기간을 판정해 사용자별 결과를 기록함. Automation은 시각·재시도·실행 이력만 소유함. 기본 timeout은 600초, 최대 시도 횟수는 3회, 재시도 backoff는 60초임. 시작 시 작업 정의를 코드로 등록함.
  • message.failure-alert-check는 Message internal Job API를 호출하는 매분 cron 작업임. Message가 자기 이력에서 미통지 발송 실패를 판정해 요약 알림을 보내며 Automation은 시각·실행 이력만 소유함. timeout은 60초, 최대 시도 횟수는 1회이고 시작 시 작업 정의를 코드로 등록함.
  • automation.execution-cleanup은 Automation API 자신의 internal Job API를 호출하는 매일 04:30(KST) cron 작업임. 계약은 3.3절을 따름.
  • raid.recruitment-scan은 WOW 앱의 레이드 internal Job API를 호출하는 10분 tick cron 작업(3-59/10 * * * *)임. WOW 앱이 알림 시간·프로필 수집 주기·차단 상태를 판정해 해당하지 않으면 noop으로 응답하고, 해당하면 목록 수집, 신규 게시글 분석, 프로필 매칭, 묶음 리포트 발송을 수행함.
  • raid.recruitment-deliver-pending은 WOW 앱의 레이드 internal Job API를 호출하는 5분 cron 작업(*/5 * * * *)임. WOW 앱이 프로필별 알림 시간대와 처리 대기 보류를 판정하고 Message internal API로 전달함.
  • 공대 구인 예약 작업의 기본 timeout은 수집 300초, 발송 점검 60초이며 최대 시도 횟수는 3회, 재시도 backoff는 60초임.
  • raid.recruitment-rejudge는 선택한 구인글을 재판정하는 MANUAL 작업임. timeout은 3300초이며 실행당 한 번 시도함.
  • raid.companions-sync는 WOW 앱의 /api/raid/internal/automation/companions-sync를 호출하는 MANUAL 작업임. 기본 작업명은 raid-companions-sync이며 cron·다음 실행 시각이 없음. timeout은 3600초, 최대 시도 횟수는 3회, 재시도 backoff는 60초임.
  • hub.audiobook-convert는 MANUAL 작업으로 Hub의 오디오북 변환 internal Job API를 호출함. 계약은 3.4절을 따름.
  • raid.* 작업 유형의 registry 대상 모듈 키는 wow이며 기능 경로의 /api/raid/*는 유지함.
  • worker는 대상 모듈의 internal_base_url이 있으면 이를 호출 origin으로 쓰고, 없거나 비어 있으면 base_url을 씀. 운영에서는 compose가 WOW_·CHESS_·HEALTH_INTERNAL_BASE_URL에 컨테이너 내부 주소를 주어 Cloudflare 등 공개 프록시를 거치지 않게 함. 공개 프록시는 오래 걸리는 동기 호출(raid.companions-sync)을 약 100초에 524로 끊기 때문임.
  • worker는 AUTOMATION_SERVICE_TOKEN, X-Junkbox-Service: automation, X-Junkbox-Job-Type, Idempotency-Key로 대상 앱을 호출함.
  • 대상 앱은 caller, token, job type을 검증함. Raid의 함께한 공대원 수집은 사용자별 보고서 revision과 처치 결과를 WOW 앱 SQLite에서 관리함.
  • Automation은 대상 도메인 SQLite 또는 Message SQLite를 직접 읽거나 쓰지 않음.

3.1 Raid 수동 수집 실행 계약​

  • POST /api/automation/internal/raid-companions/runs는 X-Junkbox-Service: wow와 AUTOMATION_SERVICE_TOKEN 인증을 요구하고 별도 요청 body 없이 빈 payload로 실행을 등록함. PENDING·RUNNING·RETRY_WAIT 실행이 있으면 새 실행을 만들지 않고 기존 실행을 반환함.
  • GET /api/automation/internal/raid-companions/runs/latest는 최신 실행 상태를 반환함. 실행 이력과 재시도·lease는 Automation SQLite에만 저장함.
  • POST /api/automation/internal/raid-recruitment-rejudge/runs는 WoW 인증으로 profile_id, match_ids, user_id를 받아 등록하며 해당 프로필의 활성 실행을 재사용함. 같은 경로의 /latest는 프로필별 최신 실행을 반환함.
  • 등록된 job_type은 Automation API와 worker의 JOB_TARGETS에 모두 존재해야 실행 가능함. API·worker 런타임 버전은 같은 작업 registry를 제공해야 함.

3.2 Chess AI 복기 실행 계약​

  • POST /api/automation/internal/chess-ai-review/runs는 Chess 서비스 인증을 요구하고 대국 ID로 chess.ai-review 실행을 등록함. 같은 대국의 활성 실행이 있으면 기존 실행을 반환함.
  • GET /api/automation/internal/chess-ai-review/runs/latest?game_id=...는 해당 대국의 최신 실행 상태를 반환함. worker는 등록된 Chess internal endpoint만 호출하며 Chess SQLite를 직접 열지 않음.
  • LLM 응답 검증과 실패한 착수의 재생성은 Chess가 한 배치 실행 안에서 처리함. Automation은 해당 배치의 실행 상태와 다음 배치 등록을 관리함.
  • 기존 Chess 복기의 RETRY_WAIT와 lease가 만료된 RUNNING 실행은 초기화 시 FAILED로 정리함. 다른 작업 유형의 재시도 정책과 공통 실행 컬럼은 유지함.

3.3 실행 결과·이력 정리 계약​

  • automation.execution-cleanup은 Automation API 자신의 internal Job API를 호출하는 매일 04:30(KST) cron 작업임. 완료된 실행 이력만 정리하며 진행 중 실행과 작업 정의·수정 이력은 지우지 않음. 시작 시 작업 정의를 코드로 등록함.
    • 보존 기간은 성공 30일, 실패 90일임. 한 번의 실행은 종류별로 5,000건씩 최대 40배치까지 삭제함.
    • 삭제로 줄어든 SQLite 파일 크기는 자동으로 회수하지 않으며 필요할 때 VACUUM을 수동으로 실행함.
  • message.* 작업 유형의 대상 모듈 키는 message, automation.* 작업 유형의 대상 모듈 키는 automation임. worker는 automation.* 작업에 AUTOMATION_BASE_URL의 내부 주소를 사용함.
  • 조회성 작업이 매분 실행돼도 이력이 쌓이지 않도록 대상 앱은 처리할 일이 없었던 성공 응답 본문에 "noop": true를 담음.
    • Automation은 이 응답으로 성공한 실행을 기록한 뒤 같은 작업의 이전 noop 성공 이력을 삭제해 최신 1건만 남김. 마지막 정상 실행 시각을 확인하기 위함임.
    • 실패·재시도·실제 처리 이력과 noop 표시가 없는 성공 이력은 삭제하지 않음.
    • 현재 Track 알림 점검, Chess 대국 동기화, WOW 수집·발송 대기 점검, Message 실패 알림 점검, 실행 이력 정리가 이 응답을 사용함.
  • notification.send 응답 본문의 status가 SUCCESS가 아니면 채널 전달 실패이므로 재시도 없이 최종 FAILED로 기록함. Message 연결 실패·5xx·타임아웃은 작업의 재시도 정책을 따름.
  • worker는 notification.send 호출 payload에 작업의 일정 유형으로 정한 request_method_code(ONCE는 SCHEDULE, CRON은 RECURRENCE)를 더함. 저장된 작업 payload는 바꾸지 않음.

3.4 Hub 오디오북 변환 실행 계약​

  • hub.audiobook-convert의 대상 모듈 키는 hub, 대상은 /api/hub/internal/automation/audiobook-convert임. 기본 timeout은 1,800초이고 실행당 한 번만 시도하며 자동 재시도하지 않음. 시작 시 작업 정의를 코드로 등록함.
  • POST /api/automation/internal/hub-audiobook/runs는 X-Junkbox-Service: hub와 AUTOMATION_SERVICE_TOKEN 인증으로 audiobook_job_id의 실행을 등록함. 같은 변환의 PENDING·RUNNING 실행이 있으면 새로 만들지 않고 기존 실행을 반환함.
  • GET /api/automation/internal/hub-audiobook/runs/latest?audiobook_job_id=는 최신 실행 상태를 반환함. Hub가 자기 작업 상태와 대조하는 데 씀.
  • Hub는 한 호출에서 시간 예산만큼 일하고 남으면 continue_conversion=true와 progress_token을 응답함. Automation은 성공 실행을 완료하는 같은 트랜잭션에서 after_token을 담은 후속 실행을 등록함. 토큰이 비었거나 직전 after_token과 같으면 실행을 실패 처리함.
  • 연쇄 작업은 코드의 CHAINED_JOBS가 정의하며 chess.ai-review와 hub.audiobook-convert가 같은 방식을 씀. 대상 항목 ID 키, 계속 키, 후속 실행 멱등 키 접두사를 작업별로 가지며 재시도하지 않음.
  • 멱등성은 Hub의 구간 캐시가 소유하므로 같은 실행이 다시 호출돼도 이미 만든 구간은 재합성하지 않음. 변환 상태와 사용량은 Hub SQLite가 소유하며 Automation은 읽지 않음.

3.5 Hub 프로 레슬링 뉴스 실행 계약​

  • hub.pro-wrestling-digest 작업에 한국 시간 기준 일일 cron을 저장함. 초기 시각은 07:00임. 일정 변경은 활성 상태와 재시도 정책을 보존하고, 시각이 달라지면 다음 도래 시각을 계산함. 시작 시 작업 이름을 이관하면서 작업 ID와 실행 이력을 보존함.
  • Hub 서비스 인증으로 /internal/hub-pro-wrestling/settings에서 일정과 텔레그램 발송 옵션을 조회·수정하고, /internal/hub-pro-wrestling/runs에서 수동 실행을 등록함. 수동 요청 키와 소유자로 중복 등록을 막고 실행 상태를 소유자별로 조회함.
  • 예약·수동 실행을 같은 작업에서 종료 기준 시각 순으로 처리함. 재시도 대기 중인 앞 실행을 추월하지 않음. 동시 실행 1건, timeout 300초, 최대 3회 시도, 재시도 backoff 60초를 기본으로 사용함.
  • 예약 실행을 등록할 때 작업의 발송 옵션을 실행 payload에 복사하고 재시도에도 같은 옵션을 사용함. 자동 발송 기본값은 켜짐이며 0건 발송은 꺼짐임. 수동 실행은 건별로 받은 발송 선택을 사용함.
  • Hub 내부 API 호출에 실행 키, 종료 기준 시각, 자동·수동 구분, 발송 선택을 전달함. 리포트 수집·저장은 guide-apps-hub-api.md 7.12절을 따름.

3.6 Health 주간 리포트 실행 계약​

  • health.report-tick과 health.report-notification-tick은 각각 1분마다 Health internal Job API를 호출함. 기본 timeout은 생성 55초, 완료 알림 점검 35초임.
  • Health가 사용자별 예약·생성·알림 중복 여부와 작업 재시도를 판정함. Automation은 Health SQLite와 Message SQLite에 접근하지 않음.

4. 데이터​

  • SQLite 파일은 /sorc001/junkbox/db/automation.sqlite3이며 컨테이너 경로는 /app/db/automation.sqlite3임.
  • tb_automation_job_m은 작업 정의, 일정, 활성 상태, timeout, 재시도 정책, payload, 다음 실행 시각과 Message 일정의 owner_user_id를 저장함. 공통 내부 작업의 소유자 값은 비어 있을 수 있음.
  • tb_automation_job_revision_n은 작업 정의 수정 snapshot을 저장함.
  • tb_automation_execution_n은 예정 시각, 상태, 시도 수, worker, lease, 응답, 오류, retry 시각, idempotency key를 저장함.
  • tb_automation_job_m의 is_active는 재활성화 가능한 실행 상태이고, 삭제는 deleted_at 시각으로만 판정함. 작업 정의 삭제 시 next_run_at을 비우고 미완료 실행을 실패 처리하며 기존 실행 이력은 유지함. 정의 생성·수정·활성화·비활성화·삭제 snapshot은 tb_automation_job_revision_n에 남김.
  • 소유자별 메시지 일정 목록은 (owner_user_id, job_type, schedule_type, deleted_at, job_id DESC) 인덱스를 사용함. worker의 도래 작업 조회는 (is_active, next_run_at) 인덱스를 사용함. 소유자 없는 별도 메시지 일정 인덱스와 deleted_at 단독 인덱스는 사용하지 않음.
  • (job_id, scheduled_at)과 idempotency_key 유니크 제약으로 같은 예정 실행의 중복 생성을 방지함.
  • worker는 SQLite 원자 상태 전이와 lease 만료 회수로 at-least-once 실행을 제공함.
  • cron은 5필드 표현식과 Asia/Seoul 기준으로 계산함.
  • cron 작업을 재활성화할 때 저장된 next_run_at이 과거이면 현재 이후의 다음 도래 시각으로 다시 계산해 비활성 기간의 실행이 즉시 발생하지 않게 함.
  • 새 작업 정의의 timezone은 Asia/Seoul만 허용하며 내부 작업 생성과 cron 계산에서도 같은 값을 검증함.
  • run_at, next_run_at, last_run_at, scheduled_at, claim·lease·retry·완료 시각과 감사 일시는 모두 KST(UTC+9) 기준으로 Automation SQLite에 저장함. API 입력의 offset 포함 일시는 KST로 정규화하고, timezone 없는 입력은 KST 로컬 일시로 해석함.
  • Automation의 시계와 입력 일시 정규화는 shared-core의 now_kst_naive()·as_kst_naive()를 사용하며 cron의 기준 시각도 KST로 해석함.
  • 네트워크 timeout과 재시도 가능 HTTP 오류는 작업별 최대 시도 횟수와 지수 backoff 정책으로 처리하며, 최대 시도 초과 실행은 최종 실패 상태로 남김.

5. API와 화면 진입​

  • 관리 API 접두사는 /api/automation이며 Hub JWT의 HUB module 권한을 요구함.
  • 작업 등록·수정·삭제·활성화, 수동 실행, 실행 이력 조회, 수동 재시도를 제공함.
  • Message 일정 전용 API는 /notification-schedules, /notification-recurrences, /notification-recurrences/validate이며 모두 Hub JWT의 MESSAGE module 권한을 요구함. 일정 생성 시 현재 사용자 ID를 정의와 발송 payload에 보관하고 목록·상세·수정·삭제는 같은 owner_user_id로 제한함. 일반 작업 관리 API는 계속 HUB 권한을 사용함.
  • /notification-schedules는 1회 예약 메시지의 목록·등록·상세·수정·삭제를 제공함. /notification-recurrences는 cron 정기 메시지의 목록·등록·상세·수정·활성 상태·삭제를 제공함.
  • 두 목록 API는 page(기본 1), size(기본 10, 1~100) query를 사용함. notification.send와 각각 ONCE 또는 CRON 조건을 Automation SQLite에서 필터링하고 LIMIT/OFFSET으로 현재 페이지를 조회함.
  • 두 목록의 각 항목은 최근 실행의 last_execution_status, last_execution_finished_at, last_execution_error를 포함함. 예약 항목은 마지막 실행이 실패이면 상태를 FAILED로 표시함.
  • 목록 응답은 { items, page_info } 구조임. page_info는 current_page, page_size, total_elements, total_pages, has_next, has_previous를 포함함.
  • 작업 결과는 추후 관리 UI가 조회할 수 있도록 작업 정의와 실행 이력을 분리한 구조로 반환함.