JunkBox apps/message-ui 가이드
1. 역할과 실행
message-ui는 Message 즉시 발송·발송 이력과 Automation이 소유하는 메시지 일정 관리 화면을 제공하는 Vite 6 React + TypeScript SPA임.
- 개발 포트는
15004이며 message-api가 운영 산출물을 /message-ui로 서빙함.
BrowserRouter, spa_navigation=true, SpaRouteTransition, useSpaRouteSettling을 사용함.
2. 공통 UI 계약
- 모바일 고정 폭과
jb-mobile-* 공통 레이아웃을 사용함.
- 출처와 유형 선택은
BottomOptionPicker와 jb-select를 사용함.
- 정기 메시지의 실행 상태 선택은 네이티브 checkbox를 사용하지 않고
jb-select과 BottomOptionPicker로 활성·비활성을 선택함.
- 공통 CSS·아이콘·폰트는 shared-ui에서 공급받으며 앱 CSS, inline style, 앱별 font-family를 추가하지 않음.
- 문장형 사용자 메시지는 하십시오체와 마침표를 사용함.
- 발송·재발송 성공은
showToast로 알리고 오류만 NoticeCard로 표시함. 전달이 실패한 응답은 오류로 안내함.
- 발송·재발송·저장·삭제처럼 사용자가 시작한 비동기 작업은
LoadingModal을 표시하고 완료 시 닫음.
- 상태 뱃지는
shared-ui의 StatusBadge tone을 사용하고 라벨은 한글로 표시함. 발송 완료·활성은 성공, 발송 실패는 실패, 대기·발송 중은 진행 중, 취소·비활성은 판정 불가 색임.
3. 화면 구조
/messages는 출처, 제목, 본문, 메시지 유형, Apprise 설정 키를 입력하는 즉시 발송 화면임.
/message-history는 발송 이력을 카드 목록으로 표시하고 재발송을 제공함. 카드는 요청 방식(/meta/request-methods 명칭)과 상태 뱃지를 표시하고 펼치면 실패 사유를 보여줌. 재발송이 끝나면 목록을 다시 조회함.
/message-schedules와 /message-schedules/:scheduleId는 1회 예약 메시지의 목록·등록·조회·수정·삭제 화면임.
/message-recurrences와 /message-recurrences/:recurrenceId는 cron 정기 메시지의 목록·등록·수정·활성 상태·삭제 화면임.
- 예약·정기 메시지 수정 화면의 하단 삭제 휴지통은 공통
jb-button-danger의 빨간 배경을 사용함. 목록 아이콘·삭제 아이콘·저장 텍스트 버튼의 폭은 shared-ui 혼합형 자동 분배를 따름.
- 메시지
발송과 발송 이력의 재발송은 외부로 나가 회수할 수 없으므로 노랑(jb-button-warning) 버튼을 사용함. 예약·정기 메시지의 새 예약 메시지·새 정기 메시지는 신규 입력 화면으로 이동만 하므로 검정(jb-button-ghost)임.
- 화면은 예약·정기 실행 상태를 표시하지만 scheduler loop, 실행 이력, 재시도, 중복 방지 로직을 소유하지 않음.
- 예약 목록은 Automation이 반환한 1회 실행 상태를 우측 상단 고정 pill 뱃지로 표시함. 정기 목록은 활성·비활성 상태를 같은 위치의 상태별 pill 뱃지로 표시함.
- 예약·정기 목록 카드는 Automation이 반환한 최근 실행 결과(성공·실패와 완료 시각)를 한 줄로 함께 표시함.
- 정기 메시지의 활성·비활성은 Automation 작업 정의의
is_active를 편집하며 재활성화할 수 있음. 예약·정기 메시지의 삭제는 Automation 작업 정의의 deleted_at을 설정해 목록에서 제외함.
- 발송 이력, 예약 메시지, 정기 메시지는 Health 운동 기록과 같은 모바일 카드 목록·페이지네이션 패턴을 사용함. 상단에 총 건수와
10개, 20개, 50개 페이지 크기 SegmentedTabs를 표시하고 기본 크기는 10개임.
- 세 목록은 전체 페이지가 2 이상일 때만 하단에
이전, 현재 페이지 / 전체 페이지, 다음을 표시함. 페이지 크기를 바꾸면 첫 페이지를 조회함.
4. 데이터 계약
- Message SQLite 또는 Hub SQLite를 직접 읽지 않음.
- 즉시 발송·메타는
/api/message API를 소비함. 발송 이력은 GET /api/message/messages?page={page}&size={size}의 { items, page, size, total } 응답을 소비함.
- 예약·정기 화면은
page, size query를 포함한 /api/message/automation/notification-schedules, /api/message/automation/notification-recurrences를 소비함.
- 두 API는
{ items, page_info }를 반환하며 page_info는 current_page, page_size, total_elements, total_pages, has_next, has_previous를 포함함.
- 이 경로는 Automation API의 Hub JWT 보호 계약을 그대로 전달함.