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로 서빙함.
일정 관리 게이트웨이의 대상 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 권한으로 관리하며 저장소와 로그에 값을 기록하지 않음.
보호 웹 화면은 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 범위 검증을 적용함.
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와 이력을 사용하며 성공 이력은 그대로 반환하고 실패 이력은 해당 이력에서 전달을 재시도함.
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임.
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 계산, 실행 이력, 재시도 상태를 저장하거나 변경하지 않음.