Skip to main content

JunkBox apps/sipmon-ui 가이드

1. 공통 UI 계약​

1.1 모바일 선택과 입력​

  • 분류 아이콘, 주류의 분류, 기존 잔 기록 수정의 주류 선택은 로컬 Picker가 shared-ui BottomOptionPicker를 호출함. 옵션의 문자열 내용이 같으면 배열 참조를 유지해 매초 시계 갱신과 동일한 bootstrap 재조회로 시트의 임시 선택이 초기화되지 않음. 실제 옵션 내용이 바뀌면 표시명·목록을 갱신함.
  • 삭제된 주류를 참조하는 과거 기록의 선택 목록은 원래 record.drink_id를 옵션 식별자로 유지함. 대시보드의 분류 버튼 선택도 주기 갱신과 동일 데이터 재조회 중 유지됨.
  • 기준 입력은 g/h와 g가 순수 알코올량 비교값이며 안전량이 아님을 짧게 설명함. 별도 온보딩·오프라인 기록·통계·정밀 위험도 예측은 제공하지 않음.

1.2 쓰기 요청과 피드백​

  • 모든 변경은 App의 change(Action)을 통과함. Action.successMessage는 필수이며 초기화, 기준 저장, 세션 시작·종료·재개·삭제, 분류·주류 CRUD, 잔 기록 추가·수정·삭제, 시간 수정의 성공 문구를 지정함.
  • 서버 성공 응답 직후 shared-ui 성공 토스트를 한 번 표시하고, 후속 bootstrap 재조회가 끝나기 전에도 결과를 알림. 4xx 검증·충돌 오류는 오류 토스트로 표시함. 네트워크 오류나 5xx는 저장 여부를 단정하지 않고 오류 토스트와 같은 요청 재시도 UI를 제공함. 기록 요청 키가 있는 잔 기록은 GET /record-requests/{request_id}로 저장 여부를 확인할 수 있음. 이미 취소·삭제된 요청 키 결과는 중립 안내 토스트를 사용함.
  • 응답 대기 중 중복 입력은 잠금으로 막고, 결과 불확실 상태에서는 다른 쓰기 요청을 막음. 서버 응답이 확정되면 잠금을 풀고 화면을 갱신함. 사용자 노출 문장형 메시지는 소스의 하십시오체와 마침표를 사용함.

2. 화면 구조​

2.1 공통 구조​

  • apps/sipmon-ui/src/App.tsx가 BrowserRouter의 화면 라우트와 쓰기 요청 상태를 관리함. src/entries/sipmon.tsx는 서버 렌더링 앱 셸의 sipmon-ui-root에 앱을 마운트함.
  • 모바일 전용 다크 화면이며 Galaxy S23 Android Chrome 설치형 PWA를 기준으로 함. 공통 셸·폰트·CSS·선택 시트·토스트는 shared-ui 자산을 사용하고 앱 전용 CSS·inline style을 두지 않음. API 호출과 인증 실패(401·403) 시 Hub 로그인 복귀는 shared-ui의 createAuthedApi(모듈 SIPMON, 타임아웃 15초)를 사용함.
  • 사용자별 기본 주류 목록이 초기화되지 않은 상태에서는 진입 경로와 관계없이 나의 음주 기록 안내를 표시하고, 시작 준비 버튼을 하단 고정 액션바에 배치함. 버튼은 주류 목록 초기화 요청을 실행함.

2.2 대시보드 /dashboard​

  • /dashboard는 진행 중 세션의 평균 음주 속도와 누적 알코올량을 개인 설정 기준 대비 두 게이지로 표시함. 원터치 잔 기록과 확인 후 세션 종료를 제공함. 같은 공용 세션 화면의 잔 기록 카드에서 개별 수정·삭제를 제공함. 이 수치는 실제 안전도·취기 예측이 아님. 주류 선택 카드는 아이콘·이름 아래에 한 잔 용량 mL, 도수 %, 순수 알코올량 g을 각각 한 줄로 표시하고 세 수치 줄 사이에는 카드의 기본 항목 간격을 적용하지 않음. 숫자와 단위 기호는 띄어 씀.
  • 주류 분류 버튼의 맨 앞에는 가상 분류 ★ 즐겨찾기가 표시되며, 분류와 무관하게 즐겨찾기 주류를 이름 가나다순으로 모아 보여줌. 즐겨찾기 주류가 있으면 이 탭이 기본 선택이고 없으면 탭을 숨기고 첫 분류를 선택함. 선택한 즐겨찾기 탭은 주기 재조회 중에도 유지되며 즐겨찾기가 모두 사라지면 첫 분류로 돌아감.
  • 진행 중 세션이 없는 /dashboard는 현재 기록이 없음을 제목으로 알리고, 내 개인 기준 아래 음주 속도와 누적 알코올량 기준을 두 열로 표시함. 하단 고정 액션바 왼쪽에 개인 기준 변경, 오른쪽에 음주 시작을 같은 폭으로 표시함.

2.3 설정 화면​

  • /settings는 개인 g/h·g 비교 기준, /settings/categories는 분류명·아이콘·순서, /settings/drinks는 주류명·분류·mL·도수·순서·즐겨찾기를 관리함. 분류·주류 목록 카드의 수정·삭제는 독립 아이콘 버튼이며 삭제는 빨간 버튼과 확인창을 사용함. 분류에 주류가 있으면 삭제를 막음.
  • 세 설정 화면의 저장 버튼은 각 화면의 jb-mobile-bottom-bar에 고정됨. 개인 기준 버튼은 내 기준 저장, 주류·분류 버튼은 저장으로 표시함. 버튼은 폼 바깥에 있지만 HTML form 속성으로 해당 폼의 기존 제출 흐름을 실행함.
  • 분류·주류 설정에서 기존 항목을 수정하는 동안에는 새 항목 고스트 버튼을 하단 저장 왼쪽에 표시함. 새 항목은 편집 대상을 해제하고 이름 입력을 비워 신규 등록 상태로 전환함.

2.4 세션 화면 /sessions​

  • /dashboard의 현재와 /sessions의 기록 메뉴는 같은 SessionEditor 화면을 사용함.
    • /sessions는 종료 세션 목록이며 시작 일시를 YYYY-MM-DD (요일) HH:mm 형식의 제목, 종료 일시를 보조 텍스트로 표시함.
    • 각 카드에는 총 시간·속도·누적 알코올량 뱃지를 이 순서로 표시하고, 30분 미만 세션의 속도는 집계 전으로 표시함.
    • /sessions/{sessionId}는 종료 세션을 공용 화면으로 열며 진행 중 세션으로 접근하면 /dashboard로 복귀함.
    • 공용 화면은 주류 아이콘 원터치 잔 추가, 잔 카드 수정·삭제, 시간 수정 모달을 제공함.
    • 종료 세션의 원터치 추가는 세션 종료 시각을 기록 시각으로 사용하고, 진행 중 세션은 현재 시각을 사용함.
    • 시간 수정 모달은 진행 중 세션의 시작 시각 또는 종료 세션의 시작·종료 시각을 한국 시간 기준 시·분 단위로 입력받음.
    • 사용자가 바꾸지 않은 시각의 원래 초·밀리초는 보존함.
    • 저장 버튼은 폼 제출(type="submit")로 동작하며 잔 기록 수정 폼의 저장도 같음.
    • 저장 전 화면에서 종료가 시작보다 늦은지, 시작·종료가 현재 시각(서버 보정)을 넘지 않는지, 세션의 잔 기록이 새 범위 안에 있는지를 먼저 확인해 위반하면 사유별 토스트로 알리고 요청하지 않음.
    • 서버가 같은 규칙(시작 < 종료 ≤ 현재, 기록 범위)을 다시 검증하며, 422 응답에 서버의 문구가 있으면 그 문구를 토스트로 표시하고 형식 오류(목록형 detail)일 때만 일반 입력 오류 문구를 표시함.
  • /sessions의 이전·다음 페이지 이동은 하단 고정 액션바의 같은 폭 화살표 아이콘 버튼을 사용함. 첫 페이지의 이전 버튼과 20건 미만 페이지의 다음 버튼은 비활성화하며 접근성 이름은 이전 기록, 다음 기록임.
  • 공용 세션 화면의 잔 기록 카드는 약 8px 간격의 목록이며 우측에 독립된 수정 아이콘과 빨간 삭제 아이콘을 표시함.
    • 진행 중 세션은 상단에 종료 버튼을 두지 않고 하단 고정 액션바에 시간 수정, 종료를 같은 폭으로 배치함.
    • 종료는 비가역 상태 전이이므로 노랑(jb-button-warning) 버튼으로 표시하고 확인창을 거쳐 처리함.
    • 종료 세션의 하단 액션바는 목록 아이콘, 빨간 세션 삭제 아이콘, 시간 수정, 기록 재개 순서임.
    • 기록 재개는 다른 진행 중 세션이 있으면 비활성화하며 성공 시 현재 화면으로 이동함.
    • 세션 삭제는 확인창을 거쳐 전체 삭제하고 목록으로 이동하며 잔 카드의 삭제는 해당 잔에만 적용함.

3. 검증​

  • 개발 UI는 Vite 15011, API는 18011임. sipmon:dev-all, sipmon:backend, sipmon:frontend, sipmon:build VS Code 작업과 just sipmon-frontend, just sipmon-backend, just sipmon-ui-build를 사용함.
  • npm run typecheck --prefix apps/sipmon-ui, npm run build --prefix apps/sipmon-ui로 검사함.
    • apps/sipmon-ui/tests/check_selectors.py는 3종 선택 UI, 대시보드 분류 선택, 지난 기록 재개·시간 입력을, check_action_toasts.py는 변경 액션의 성공·실패·결과 불확실 토스트를 실제 브라우저와 가짜 API 응답으로 검사함.
    • 두 브라우저 검사는 실행 중인 로컬 UI 15011을 요구하고 실제 사용자 DB를 변경하지 않음.