Skip to main content

JunkBox apps/track-ui 가이드

1. 역할과 실행

  • apps/track-ui는 Track API가 렌더링하는 모바일 전용 React + Vite SPA임.
  • Vite 개발 포트는 15008, build 결과는 track-api/track-ui 경로로 서빙함.
  • 개발 진입 경로 /track-ui///track-records로 이동함. 실제 웹 화면은 Track API의 /track-records 또는 /track-items 경로를 사용함.
  • BrowserRouter를 사용하며 앱 셸 링크의 junkbox:spa-navigate 이벤트를 수신해 React Router navigation으로 연결함.
  • 개발 모드에서 서버 템플릿은 Vite client, React refresh preamble, /track-ui/src/entries/track.tsx 엔트리를 주입함.

2. 화면 구조

  • /track-records는 활성 관리 항목을 저장된 sort_order_no 순서의 카드 목록으로 표시함. 최신 처리 이력 기준 경과 일수, 주기, 알림 상태는 jb-chip으로 표시함.
  • /track-records/{item_id}는 최신 처리 정보와 상단 처리 이력 등록·수정 폼, 그 아래 처리 이력 내림차순 카드 목록을 표시함. 신규 입력의 datetime-local 기본값은 브라우저 로컬 현재 시각임.
  • 상세 폼은 선택 이력이 없을 때 새 이력 등록 모드이며 저장 시 POST /items/{item_id}/records로 이력을 생성함. 이력 카드를 선택하면 처리 일시와 비고를 폼으로 불러온 이력 수정 모드가 되며 저장 시 PUT /items/{item_id}/records/{record_id}로 해당 이력을 갱신함.
  • 선택된 처리 이력 카드는 jb-mobile-card--selected 공통 클래스로 테두리와 내부 강조를 표시함. 카드 안에 선택 상태를 설명하는 별도 문구를 추가하지 않으며, 선택 버튼은 aria-pressed로 상태를 제공함.
  • 상세 화면의 처리 이력 카드는 실제 처리 일시와 비고를 표시하며 삭제 아이콘으로 확인 후 삭제할 수 있음. 삭제한 카드가 선택 상태이면 폼은 신규 입력 모드로 전환함.
  • 상세 하단 고정 액션바는 왼쪽부터 기록 목록으로 이동하는 IconMenu, 신규 이력 모드로 전환하는 IconPlus, 관리 화면으로 이동하는 관리, 저장을 확정하는 저장 순서임. IconPlus는 입력값을 현재 시각과 빈 비고로 초기화하며 저장소를 즉시 변경하지 않음.
  • /track-items는 관리 전용 목록임. 활성 카드는 저장된 순서로 표시하며 카드 앞쪽의 SortableDragHandle을 길게 눌러 순서를 바꾼 뒤 즉시 저장함. 비활성 항목은 별도 영역에 표시하며 드래그 대상이 아님.
  • /track-items/new, /track-items/{item_id}/edit는 동일 폼을 사용함. 제목, 설명, 사용 여부, 주기 관리, 주기 일수, 알림 설정과 알림 규칙을 편집함. 주기 일수와 알림 규칙 입력은 항상 표시하고 체크 상태에 따라 활성화함.
  • 챙김 관리 수정 화면 하단 고정 액션바의 제일 왼쪽은 관리 목록으로 이동하는 IconMenu 버튼임. 그 다음 삭제 IconTrash 버튼과 저장 버튼을 배치함. 삭제는 확인 후 항목과 연결 데이터를 실제 삭제함.
  • 알림 규칙은 도래 며칠 전, 알림 시각 라벨을 가진 카드로 표시함. 안내 문구는 소스의 한국어 문구로 직접 작성함.

3. 공통 UI 계약

  • 서버 앱 셸은 브랜드 Track, 약자 TR, 챙김 기록, 챙김 관리 내비게이션을 제공함.
  • 현재 SPA 경로에 따라 applyActiveNavState로 앱 셸의 활성 탭을 갱신함.
  • 모바일 본문, 카드, 입력, 하단 고정 액션바, 칩, 토스트, 목록·추가·삭제 아이콘은 shared-ui 공통 자산과 jb-* 클래스를 사용함.
  • TrackApp의 라우트 본문은 jb-mobile-bottom-bar-page 컨테이너 안에 렌더링함. 따라서 하단 고정 액션바를 사용하는 모든 Track 화면은 공통 --jb-mobile-bottom-bar-clearance와 모바일 고정 폭·좌우 여백을 적용받음.
  • 앱 전용 CSS, inline style, 앱별 폰트 선언을 사용하지 않음.
  • 저장·삭제·오류 메시지는 showToast를 사용함. 사용자 노출 문장형 메시지는 한국어 하십시오체와 마침표를 사용함.

4. 개발 작업과 검증

  • VS Code 작업은 track:dev-all, track:backend, track:frontend, track:build와 내부 _track-ui:build를 제공함.
  • track:dev-all은 FastAPI 18008과 Vite 15008을 병렬 실행함.
  • UI는 npm run typecheck, npm run build로 검증함.