본문으로 건너뛰기

JunkBox apps/message-api 가이드

업무 개요​

  • 여러 앱과 호스트 스크립트가 보내는 알림을 한 곳에서 실제 채널로 전달하고 이력을 남기는 것이 목적임.
  • 핵심 개념은 발송 요청, 채널 전달(Apprise·Telegram Bot API), 발송 이력, 재발송, 예약·정기 메시지임.
  • 사용자는 화면에서 메시지를 즉시 발송하거나 예약·정기 메시지를 등록하고 발송 이력을 확인함.
  • 도메인 앱, Automation, 호스트 백업 스크립트는 internal API로 전달을 요청함.
  • 예약·정기 메시지의 정의와 실행 시각 계산은 Automation이 소유하고 Message는 전달만 담당함.

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, 컨테이너 내부 포트는 8080임. 호스트 백업 스크립트용으로 127.0.0.1:8004:8080 loopback publish만 유지함. 규칙은 운영 컨테이너 포트 통일 규칙을 따름.
  • 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:8080을 사용함.
  • AUTOMATION_BASE_URL은 환경별 연결 대상이므로 .env.shared에 두지 않음.
  • 호스트 인프라 백업은 sleepzz 사용자 크론이 매일 08:00에 /home/sleepzz/scripts/backup-all.sh를 실행함. 백업 실행은 Automation의 도메인 작업 계약 밖에 있으며 완료 알림만 Message API로 전달함.
  • 저장소의 ops/backup/backup-all.sh, backup-message.sh, backup-message-template.py는 배포 작업이 호스트의 /home/sleepzz/scripts/로 설치하는 원본임. 호스트 전용 backup-message.conf는 Message API URL, timeout, 백업 토큰 파일 경로를 지정함.
  • 운영 Compose는 /sorc001/junkbox/secrets/backup-message-token을 junkbox-message의 /run/secrets/backup_message_token에 읽기 전용 secret으로 제공함. 호스트 토큰 파일은 0600 권한으로 관리하며 저장소와 로그에 값을 기록하지 않음.

3. 인증과 권한​

  • 보호 웹 화면은 Hub Cookie 또는 Bearer Header와 required_module=MESSAGE 로그인·복귀 흐름을 사용함.
  • 즉시 발송·이력·마스터데이터 API는 Hub JWT의 MESSAGE 권한을 요구함. 백업 서비스는 별도 토큰 인증 경로를 사용함.
  • MESSAGE_BACKUP_SERVICE_TOKEN_FILE은 백업 서비스 인증 토큰 파일 경로임. 파일 경로가 지정되면 파일 값을 MESSAGE_BACKUP_SERVICE_TOKEN보다 우선하여 요청마다 읽고, 파일을 읽을 수 없거나 토큰이 비어 있으면 백업 호출을 거부함. 운영에서는 Compose secret 경로를 사용함.
  • MESSAGE_BACKUP_OWNER_USER_ID는 백업 서비스 발송 이력 소유자를 지정하며 운영 값은 sleepzz임.
  • Automation internal API는 service-to-service 인증과 job type 범위 검증을 적용함.
  • Apprise 주소와 텔레그램 봇 인증 설정은 서버에서 관리함.

4. 데이터​

  • tb_message_log_n은 owner_user_id, 발송 요청, 시도, 전달 결과를 Message의 유일한 영속 데이터로 저장함. 발송 이력 목록·상세·재발송은 현재 사용자 소유 이력만 대상으로 함.
  • Message SQLite의 timezone 없는 발송·감사 일시는 KST 로컬 시각으로 해석해 조회 응답에 표시함. offset 포함 외부 입력은 KST로 변환함.
  • schedule_id, recurrence_id, recurrence_scheduled_at은 과거 발송 이력 호환용 컬럼임. 새 일정 정의 또는 실행 제어에 사용하지 않음.
  • Apprise 호출은 POST /notify/{config_key}와 title, body, 소문자 type, format=text payload를 사용함. 본문을 마크업으로 해석하지 않게 하기 위함임.
  • URL 버튼이 있는 알림은 Telegram Bot API로 전달함. MESSAGE_TELEGRAM_BOT_TOKEN·MESSAGE_TELEGRAM_CHAT_ID로 수신 대상을 설정하고 MESSAGE_TELEGRAM_TIMEOUT_SECONDS로 요청 제한 시간을 설정함.
  • 텔레그램 메시지는 첫 줄의 제목을 굵게 표시하고 바로 다음 줄에 본문을 표시함. URL 버튼의 라벨과 대상은 metadata_json에 저장하여 재발송에 사용함.
  • 버튼 알림을 보내는 Hub·WOW보다 Message API와 봇 설정을 먼저 적용함.
  • failure_alerted_at은 발송 실패를 사용자에게 알린 시각이며 알림이 성공한 실패 이력에만 기록함.
  • MESSAGE_APPRISE_DEFAULT_CONFIG_KEY는 요청별 config_key가 없을 때 적용함.
  • source=BACKUP 이력에는 external_request_id의 부분 고유 인덱스 uq_message_backup_request가 적용됨. 같은 백업 실행의 알림 재시도는 같은 요청 ID와 이력을 사용하며 성공 이력은 그대로 반환하고 실패 이력은 해당 이력에서 전달을 재시도함.

5. API와 화면 진입​

  • 업무 API 접두사는 /api/message임.
  • POST /messages는 MESSAGE 권한 사용자의 즉시 발송을 현재 사용자 소유 이력으로 저장하고 전달함. 백업 서비스 호출은 source=BACKUP, X-Junkbox-Service: backup, X-Junkbox-Backup-Token을 검증하고 설정된 백업 소유자에게 귀속함.
  • 백업 서비스 호출에는 비어 있지 않은 external_request_id가 필수임. Message가 전달 결과 SUCCESS를 얻지 못하면 HTTP 502를 반환하며 호스트 알림 스크립트는 같은 ID로 네트워크 오류·429·5xx를 제한적으로 재시도하고 응답의 SUCCESS 상태를 확인함.
  • GET /messages는 page, size query로 발송 이력을 조회하고 { items, page, size, total }를 반환함. size는 1~100 범위임.
  • GET /messages/{message_id}는 단일 이력을 조회함.
  • POST /messages/{message_id}/resend는 원본 이력을 보존한 새 발송 이력을 생성함.
  • 수동 재발송은 출처와 무관하게 새 이력의 external_request_id를 비워 원래 요청의 중복 방지 키와 분리함.
  • POST /internal/health/report-completed는 Health 리포트 완료 알림을 지정된 사용자와 봇 채팅으로 전달함. 기간과 인증된 Health 상세 링크를 보내며 리포트 본문은 Health가 제공함.
  • 완료 알림은 자동 리포트 ID 또는 수동 리포트 ID·버전을 키로 같은 발송 이력을 재사용함.
  • 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로 저장하고 같은 키의 기존 이력을 반환함. 호출 payload의 owner_user_id를 발송 이력 소유자로 저장함.
    • 채널 전달이 실패해도 이력을 남기고 2xx와 본문 status=FAILED로 응답함. 같은 키로 다시 호출해도 재전달하지 않으므로 호출자는 본문 status로 성공을 판정하고 실패를 재시도하지 않음.
    • 선택 필드 telegram_button은 버튼의 text와 HTTP(S) url을 받음.
    • 선택 필드 request_method_code(API, SCHEDULE, RECURRENCE)로 발송 이력의 요청 방식을 지정함. 없으면 API임.
  • POST /internal/automation/failure-alert-check는 message.failure-alert-check 전용 internal API임.
    • 5분 넘게 SENDING인 이력을 FAILED로 정리하고, 최근 24시간 안의 미통지 실패를 소유자별로 묶어 요약 알림 1건을 기본 설정 키로 보냄. 알림 이력은 metadata.kind=FAILURE_ALERT로 표시하며 다시 알림 대상이 되지 않음.
    • 알림이 SUCCESS일 때만 대상 이력에 failure_alerted_at을 기록하고, 실패하면 다음 점검에서 다시 시도함. 채널이 죽어 있을 때 실패한 알림 이력이 쌓이지 않도록 최근 30분 안에 알림을 시도했으면 건너뜀.
    • 원본 메시지는 재시도하지 않음. 실패 알림은 채널이 복구된 뒤 시스템에서 이력을 확인하게 하려는 지연 통지임.
  • /meta/sources, /meta/message-types, /meta/request-methods는 Hub master-data 활성 코드를 제공함.
  • /automation/{path}는 Message UI의 일정 관리 요청을 Automation API로 전달하는 인증 보존 HTTP 게이트웨이임.
    • 이 경로는 일정 정의·실행 상태를 저장하거나 scheduler를 실행하지 않음.
    • 게이트웨이는 MESSAGE 권한을 요구함. 요청 Cookie 또는 Authorization, 사용자 에이전트, 원 요청 IP를 Automation API에 전달하며, Automation의 Message 일정 API도 Hub JWT의 MESSAGE 권한과 사용자 소유권을 검증함.
    • 게이트웨이는 Automation 작업 정의, cron 계산, 실행 이력, 재시도 상태를 저장하거나 변경하지 않음.

5.1 UI와 문구​

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