본문으로 건너뛰기

JunkBox apps/message-api 가이드

1. 역할​

  • message-api는 메시지 채널 전달, 발송 이력, 즉시 발송, 수동 재발송을 담당함.
  • 예약 실행, cron 정기 실행, 다음 실행 시각, 재시도, 실행 이력, 수동 작업 실행은 automation-api가 소유함.
  • Message는 Automation DB를 직접 읽거나 쓰지 않으며 Automation도 Message DB를 직접 읽거나 쓰지 않음.

2. 런타임​

  • FastAPI 엔트리포인트는 junkbox_message_api.main:app이며 상태 확인 경로는 /health임.
  • 로컬 포트는 API 18004, Vite 15004이며 운영 서비스명은 junkbox-message, 포트는 8004임.
  • message-ui/dist와 shared-ui 자산을 각각 /message-ui, /shared-ui로 서빙함.
  • SQLite 경로는 로컬 /sorc001/junkbox/db/message.sqlite3, 컨테이너 /app/db/message.sqlite3임.
  • 일정 관리 게이트웨이의 대상 URL은 프로필별 AUTOMATION_BASE_URL로 설정함. .env.local은 http://localhost:18007, .env.prod는 Compose 내부 주소 http://junkbox-automation-api:8007을 사용함.
  • AUTOMATION_BASE_URL은 환경별 연결 대상이므로 .env.shared에 두지 않음.

3. 저장소와 전달​

  • tb_message_log_n은 발송 요청, 시도, 전달 결과를 Message의 유일한 영속 데이터로 저장함.
  • schedule_id, recurrence_id, recurrence_scheduled_at은 과거 발송 이력 호환용 컬럼임. 새 일정 정의 또는 실행 제어에 사용하지 않음.
  • Apprise 호출은 POST /notify/{config_key}와 title, body, 소문자 type payload를 사용함.
  • MESSAGE_APPRISE_DEFAULT_CONFIG_KEY는 요청별 config_key가 없을 때 적용함.

4. HTTP 계약​

  • 업무 API 접두사는 /api/message임.
  • POST /messages는 즉시 발송을 저장하고 전달함.
  • GET /messages는 page, size query로 발송 이력을 조회하고 { items, page, size, total }를 반환함. size는 1~100 범위임.
  • GET /messages/{message_id}는 단일 이력을 조회함.
  • POST /messages/{message_id}/resend는 원본 이력을 보존한 새 발송 이력을 생성함.
  • POST /internal/automation/notification-send는 notification.send 전용 internal API임.
    • X-Junkbox-Service: automation, AUTOMATION_SERVICE_TOKEN_HEADER, X-Junkbox-Job-Type: notification.send, Idempotency-Key가 필요함.
    • Idempotency-Key를 external_request_id로 저장하고 같은 키의 기존 이력을 반환함.
  • /meta/sources, /meta/message-types, /meta/request-methods는 Hub master-data 활성 코드를 제공함.
  • /automation/{path}는 Message UI의 일정 관리 요청을 Automation API로 전달하는 인증 보존 HTTP 게이트웨이임.
    • 이 경로는 일정 정의·실행 상태를 저장하거나 scheduler를 실행하지 않음.
    • 요청 Cookie 또는 Authorization, 사용자 에이전트, 원 요청 IP를 Automation API에 전달하며, Automation API가 Hub JWT와 HUB module 권한을 최종 검증함.
    • 게이트웨이는 Automation 작업 정의, cron 계산, 실행 이력, 재시도 상태를 저장하거나 변경하지 않음.

5. UI와 문구​

  • 웹 라우트는 /messages, /message-history, /message-schedules, /message-recurrences와 각 등록·상세 SPA 경로를 제공함.
  • 앱 셸 메뉴는 즉시 발송, 발송 이력, 예약 메시지, 정기 메시지를 제공함.
  • 예약·정기 화면의 정의 CRUD와 cron 검증은 Automation API가 소유하며, Message API는 UI 요청을 전달할 뿐임.
  • 사용자 노출 문구는 소스의 한국어로 작성하며 문장형 메시지는 하십시오체와 마침표를 사용함.
  • 공통 CSS, 폰트, 앱 셸은 shared-ui 자산을 사용하며 페이지 전용 CSS와 inline style을 사용하지 않음.

6. 인증 경계​

  • 즉시 발송과 이력 API는 기존 외부 호출 호환 계약을 유지함.
  • Automation internal API만 service-to-service 인증과 job type 범위 검증을 적용함.
  • Apprise 주소와 설정 키는 API 응답이나 UI에 노출하지 않음.