본문으로 건너뛰기

JunkBox apps/track-api 가이드

1. 역할​

  • apps/track-api는 개인 관리 항목의 주기, 처리 이력, 알림 규칙을 소유하는 도메인 API임.
  • 주기 관리는 선택 사항임. 주기를 사용하지 않는 항목은 최신 처리 이력과 경과 일수만 관리함.
  • 알림은 주기 관리가 활성화된 항목에서만 사용함. Track은 알림 채널 전달이나 실행 일정을 소유하지 않음.

2. 런타임과 인증​

  • FastAPI 엔트리포인트는 junkbox_track_api.main:app이며 상태 확인 경로는 /health임.
  • 로컬 API 포트는 18008, 운영 포트는 8008임.
  • 데이터베이스 URL은 TRACK_DATABASE_URL이며 로컬 기본 SQLite 파일은 /sorc001/junkbox/db/track.sqlite3, 컨테이너 경로는 /app/db/track.sqlite3임.
  • 공개 API와 웹 화면은 Hub JWT Cookie 또는 Bearer Header를 검증하고 HUB module 권한을 요구함.
  • 로그인하지 않았거나 권한이 없으면 Hub 로그인 화면으로 redirect와 required_module=HUB를 전달해 복귀 흐름을 사용함.

3. 데이터 소유권​

  • tb_track_item_m은 제목, 설명, 주기 사용 여부, 주기 일수, 알림 사용 여부, 사용자별 sort_order_no, 활성 상태와 사용자 소유권을 저장함. 신규 항목은 활성 항목의 마지막 순서로 생성됨.
  • tb_track_notification_rule_n은 항목별 days_before, notification_time, 정렬 순서와 활성 상태를 저장함.
  • tb_track_record_n은 실제 처리 일시, 비고, 사용자 소유권을 저장함. 삭제는 is_active=0 soft delete로 처리함.
  • tb_track_notification_delivery_n은 알림 규칙과 도래 시각의 조합을 기준으로 발송 상태를 저장해 중복 전달을 막음.
  • Track SQLite는 Track API만 writer임. Hub, Automation, Message는 Track SQLite를 직접 읽거나 쓰지 않음.

4. 공개 API​

  • API 접두사는 /api/track임.
  • GET /items는 활성 관리 항목을 sort_order_no 오름차순으로 반환함. include_inactive=true는 관리 화면의 재활성화를 위해 비활성 항목도 함께 반환함.
  • POST /items, PUT /items/{item_id}, GET /items/{item_id}는 관리 항목과 알림 규칙을 생성·수정·조회함. 수정 payload의 is_active로 항목을 비활성화하거나 다시 활성화함.
  • PUT /items/order는 현재 사용자의 활성 항목 전체 식별자 순서를 받아 sort_order_no를 저장함.
  • DELETE /items/{item_id}는 항목과 연결된 알림 규칙, 처리 이력, 알림 delivery 이력을 실제 삭제함.
  • POST /items/{item_id}/records는 사용자가 지정한 실제 처리 일시와 비고로 이력을 생성함. 기본 UI 입력값은 현재 일시임.
  • PUT /items/{item_id}/records/{record_id}는 사용자가 지정한 실제 처리 일시와 비고로 활성 처리 이력을 수정하고 updated_at을 갱신함. record_id, item_id, 현재 사용자 소유권이 모두 일치하는 이력만 수정할 수 있음.
  • DELETE /items/{item_id}/records/{record_id}는 현재 사용자가 소유한 처리 이력을 soft delete함.
  • 주기 알림 규칙의 days_before는 항목의 interval_days보다 클 수 없음. 알림 사용에는 주기 관리와 하나 이상의 알림 규칙이 필요함.

5. Automation 및 Message 연동​

  • POST /api/track/internal/automation/notification-check는 track.notification-check 전용 internal Job API임.
  • internal API는 Automation caller, service token, job type, Idempotency-Key를 검증함.
  • Automation은 track.notification-check를 매분 실행하고 retry, timeout, 실행 이력, lease, idempotency를 Automation SQLite에서 소유함.
  • Track은 최신 처리 이력이 있는 항목만 최신 처리 일시, 주기, days_before, notification_time으로 실제 알림 시각을 계산함. days_before=0은 도래일 당일 지정 시각을 의미함.
  • 발송 시각이 도래하고 동일 규칙·도래일 조합의 delivery가 없을 때만 Message의 notification.send internal API를 호출함. 이 호출에는 Automation 인증 정보와 X-Junkbox-Job-Type: notification.send를 전달함.
  • Message는 Telegram 등 채널 전달과 발송 이력을 소유함. Track은 Message SQLite를 직접 다루지 않음.

6. 배포 계약​

  • 개발 Compose 서비스명은 junkbox-track, 운영 서비스명도 junkbox-track임.
  • 서비스는 Hub와 Message에 의존하며 MESSAGE_BASE_URL로 Message internal API에 연결함.
  • Automation API와 worker는 TRACK_BASE_URL로 Track internal Job API에 연결함.
  • Track Dockerfile은 track-ui/dist와 shared-ui 빌드 자산을 런타임 이미지에 포함함.
  • GitHub Actions selective build/deploy 서비스명은 junkbox-track이며 Track API/UI, shared-core, shared-ui, 운영 Compose 변경을 감지함.