본문으로 건너뛰기

JunkBox apps/track-api 가이드

업무 개요​

  • Track은 마지막으로 언제 처리했는지를 기억해야 하는 개인 관리 항목을 다룸. 항목마다 처리 이력을 남기고 최신 처리 후 경과 일수를 보여줌.
  • 핵심 개념은 관리 항목, 처리 이력, 선택적 주기(일수), 알림 규칙(도래 며칠 전·시각), 발송 중복 방지 상태임.
  • 주기를 설정한 항목만 다음 도래일과 알림을 사용함. 주기가 없는 항목은 이력과 경과 일수만 관리함.
  • 화면 메뉴는 챙김 기록과 챙김 관리임.

1. 역할과 책임 경계​

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

2. 런타임과 배포​

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

2.1 배포 계약​

  • 개발 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 변경을 감지함.

3. 데이터​

  • tb_track_item_m은 제목, 설명, 주기 사용 여부, 주기 일수, 알림 사용 여부, 사용자별 sort_order_no, 재활성화 가능한 is_active, 삭제 시각 deleted_at, 사용자 소유권을 저장함. 신규 항목은 활성 항목의 마지막 순서로 생성됨.
  • tb_track_notification_rule_n은 항목별 days_before, notification_time, 정렬 순서와 deleted_at을 저장함. 현재 규칙의 (track_item_id, days_before, notification_time) 중복은 WHERE deleted_at IS NULL 부분 고유 인덱스로 제한함.
  • tb_track_record_n은 실제 처리 일시, 비고, 사용자 소유권과 deleted_at을 저장함. 처리 이력 삭제는 deleted_at만 설정함.
  • tb_track_notification_delivery_n은 알림 규칙과 도래 시각의 조합을 기준으로 발송 상태를 저장해 중복 전달을 막음. delivery_status는 전달 성공 SENT와 채널 전달 실패 FAILED를 구분함.
  • 항목·규칙·이력 목록은 deleted_at IS NULL만 조회함. 항목의 is_active=false는 관리 화면에서 재활성화 가능한 상태이며 삭제와 구분함.
  • 목록 조회 인덱스는 항목 (user_id, deleted_at, is_active, sort_order_no), 규칙 (track_item_id, deleted_at, sort_order_no), 이력 (track_item_id, deleted_at, performed_at DESC)임. 현재 테이블 규모에서 deleted_at 단독 인덱스는 사용하지 않음.
  • 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 입력값은 현재 일시임.
  • 처리 일시의 기본 UI 입력값과 최신 처리 후 경과일·알림 시각 판단은 Asia/Seoul 기준임. UI는 shared-ui KST 유틸을 사용하고 API는 shared-core KST 시계를 사용함.
  • 처리 일시 API는 offset 포함 입력을 KST로 정규화하고 timezone 없는 입력은 KST 로컬 일시로 해석한 뒤 Track SQLite에 저장함.
  • 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보다 클 수 없음. 알림 사용에는 주기 관리와 하나 이상의 알림 규칙이 필요함.
  • interval_days는 13650, 알림 규칙의 days_before는 03650이며 알림 규칙은 항목당 20개 이하임. 제목은 앞뒤 공백을 제거한 뒤 1~100자여야 하고 공백뿐인 제목은 거절함.
  • 알림 점검 배치는 날짜 계산이 불가능한 비정상 값을 가진 규칙을 건너뛰고 나머지 규칙을 계속 처리함.

5. 연동​

  • 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, 항목 소유자의 owner_user_id를 전달함.
  • Message는 Telegram 등 채널 전달과 발송 이력을 소유함. Track은 Message SQLite를 직접 다루지 않음.
  • Message 응답 본문의 status가 SUCCESS가 아니면 delivery를 FAILED로 기록하고 다시 호출하지 않음. 같은 키는 Message가 재전달하지 않으며 실패는 Message의 실패 알림이 사용자에게 전달함.
  • 응답은 sent, failed 건수와 처리할 일이 없었는지를 뜻하는 noop을 포함함.