본문으로 건너뛰기

JunkBox apps/questlog-ui 가이드

1. 화면 구조​

1.1 공통 구조​

  • apps/questlog-ui/src/App.tsx는 BrowserRouter의 /quests, /history, /builtin-missions, /builtin-missions/:code, /custom-missions, /custom-missions/:code 라우트만 관리하고 src/entries/questlog.tsx가 서버 렌더링 앱 셸의 questlog-ui-root에 마운트함.
    • 화면은 pages/(QuestsPage, HistoryPage, 기본·커스텀 관리가 kind로 공유하는 MissionListPage·MissionDetailPage)와 components/(MissionCard, MissionSummaryCard, CustomCreateModal, CustomEntryModal, MissionStatusBadge, OptionSelectField, PeriodStartPicker)로, API 호출과 로드 훅은 api.ts(shared-ui의 createAuthedApi·useAuthedLoader 사용), 이름·기간·방식(MODE_NAME)·시작 요일·시작일·시작 시각 문구와 날짜 표기는 labels.ts, 관리 화면의 종류별 경로·API와 입력 규칙은 components/missionSetting.ts, SPA 화면 전환은 hooks/useQuestlogNavigate.ts로 나눔.
    • 상단 메뉴는 서버 셸의 미션, 이력, 기본 미션 관리, 커스텀 미션 관리이며 spa_navigation 이벤트로 이동함.
  • 모바일 전용 다크 화면이며 공통 셸·폰트·CSS·토스트·로딩 모달은 shared-ui 자산을 사용함. 앱 전용 CSS·inline style·앱별 font-family를 두지 않음. 진행 막대(ProgressBar)와 상태 배지(StatusBadge)는 shared-ui 컴포넌트를 사용하며 색은 공통 UI 가이드 7.10 상태 색 표준(진행 파랑·달성 초록·실패 빨강·판정 불가 회색)을 따름. 결과 용어는 기본·커스텀 미션 모두 진행 중·달성·실패로 통일함.

1.2 미션 현황 /quests​

  • /quests는 일간, 주간, 월간 구획에 활성 미션 카드(이름, 상태 배지, 현재값/목표, 진행 막대, 판정 불가 사유)를 표시함.
    • 해당 기간에 활성 미션이 없으면 그 구획은 제목까지 숨기고, 세 기간이 모두 비면 구획 없이 NoticeCard(empty)로 진행 중인 미션이 없습니다. 기본 미션 관리나 커스텀 미션 관리에서 미션을 켜 주십시오. 한 줄만 표시함.
    • 일간 미션의 기준일이 같으면 구획 제목 오른쪽에 YYYY-MM-DD (요일)을 한 번 표시하고, 서로 다르면 각 카드에 기준일을 표시함. 주간·월간은 시작 요일·시작일이 미션마다 달라 각 카드의 제목 아래에 자기 기간 MM-DD (요일) ~ MM-DD (요일)을 표시하며 /history의 기간도 같은 형식임(공통 UI 가이드 날짜 표기 표준, shared-ui 날짜 함수 사용).
    • 하단 고정 액션바(jb-mobile-bottom-bar)의 새로고침 버튼이 현황을 다시 조회하며 LoadingModal을 표시함.
    • 새로고침 버튼과 카드의 이동 버튼은 jb-button-ghost(어두운 바탕)를 사용함.
  • 주간 평균 열량 카드 제목은 평균 산정 기준을 서버가 준 basisNote로 덧붙여 주간 평균 열량 (오늘 제외), 한도를 넘겨 실패하면 (오늘 포함)으로 표시함. 지난 날이 없으면 평균은 -임. 이하 미션 카드는 진행 막대 아래에 서버의 guide.text(남은 N일 · 하루 평균 X kcal 이하 또는 달성 불가 문구)를 표시하며 문구를 UI가 계산하지 않음. 미션 이름은 이력·기본 미션 관리에서 괄호 없이 표시함.
  • 진행 막대는 판정 상태가 색을 정하고 shared-ui의 progressGeometry로 길이를 계산함.
    • 목표 이하이면 막대 끝이 목표이고 표시선이 없으며, 값(예정 포함)이 목표를 넘으면 막대가 끝까지 차고 목표 위치에 텍스트 없는 표시선을 그림.
    • 이하 미션은 넘으면 빨강(FAIL), 이상 미션은 달성하면 초록이며 목표를 초과 달성하면 목표 지점에 표시선이 생김.
    • 주간 평균은 평균이 목표를 넘어도 주간 한도 이내이면 파랑과 표시선임.
    • 일일 열량에 아직 먹지 않은 예정분이 있으면 첫 줄에 합계(먹은 양 + 예정)와 목표를 2,100 kcal / 목표 1,850 kcal로 표시하고(합계는 강조), 다음 줄에 Hub 대시보드와 같은 (900 kcal 예정 포함)을 연한 작은 글씨로 따로 표시함. 막대에는 먹은 구간 뒤에 옅은 색 구간을 이어 그리며, 판정은 먹은 양만 사용함.
    • 수치 줄 오른쪽의 방식 라벨(이하 유지·이상 달성)은 폭이 모자라도 줄어들거나 줄바꿈되지 않고 항상 한 줄로 표시하며, 줄바꿈은 왼쪽 수치 묶음에서만 일어남.
  • 미션 카드 하단에는 구분선 아래 전체 폭 버튼 줄이 있으며, 카드 본문은 터치 반응 없이 정보만 표시함.
    • 버튼은 API가 내려주는 links(label·app·path)를 UI가 page_props.appLinks의 앱 주소와 합쳐 만드는 새 탭 일반 <a>(target="_blank", rel="noopener noreferrer")이며, 권한 없는 앱의 링크는 서버가 내려주지 않아 버튼이 숨겨짐.
    • 현재 일일 열량 유지는 오늘 식단, 주간 평균 열량은 식단, 주간 운동·러닝은 운동·러닝, 주간 체스는 체스임.
    • 설치형 PWA에서 새 탭 링크가 설치된 앱으로 열리는지는 기기·Chrome 버전에 따라 다르며 실기기에서 확인해야 함.
    • 탭 복귀(visibilitychange)와 bfcache 복원(pageshow의 persisted) 때 현황을 자동으로 다시 조회함.
  • 카드 본문은 값 소스가 아니라 서버가 준 mode로 결정함. 단순 체크는 상태 배지와 비고만 표시하며 비고가 없으면 비고 영역을 비워 두고(비고가 없습니다. 같은 대체 문구를 표시하지 않음), 이상 달성·이하 유지는 기본 미션과 같은 수치(현재값 / 목표)·진행 막대 블록을 쓰고 비고가 있으면 아래에 표시함.
    • 직접 입력 미션은 버튼 줄의 첫 버튼(단순 체크는 결과 입력, 이상·이하는 값 입력)이 CustomEntryModal을 엶.
    • 모달은 shared-ui FormModal로 단순 체크는 결과(진행 중·달성·실패, 선택 색은 해당 상태 배지와 같음), 이상·이하는 진척값 (단위) 숫자 입력(기간당 한 건을 덮어쓰며 기본값은 현재 값 또는 0)을 받고 공통으로 비고(500자)를 입력받음.
    • 저장 시 모달을 닫고 LoadingModal을 표시하며 실패하면 입력을 유지한 채 다시 엶.

1.3 이력 /history​

  • /history는 일간·주간·월간 탭으로 기록된 이력을 30건씩 더 보기로 표시함. 이력은 읽기 전용이며 기간이 끝나는 시점에 서버가 기록한 값을 그대로 보여 줌.
    • 같은 기간 시작일의 항목을 기간 머리글(일간 YYYY-MM-DD (요일), 주간·월간 MM-DD (요일) ~ MM-DD (요일)) 아래 한 카드의 행으로 묶고, 행은 미션 이름, 수치(실제값 / 목표, 단순 체크 제외)와 비고(없으면 비워 둠), 오른쪽 세로 중앙의 결과 배지만 보여 줌.
    • 수치(실제값 / 목표)는 mode가 단순 체크가 아닌 행에 소스와 무관하게 표시함. 이름·방식·단위·목표는 기록 당시 값이라 이후 설정이나 미션 이름을 바꿔도 달라지지 않음.
    • 행을 눌러 수정하거나 재평가하는 동작, 하단 고정 액션바, 이력 삭제 기능은 없음.
    • 기록된 이력이 없으면 NoticeCard(empty)로 기록된 이력이 없습니다. 기간이 끝나면 이곳에 기록됩니다.를 표시함.

1.4 미션 관리 목록 /builtin-missions, /custom-missions​

  • 기본 미션 관리와 커스텀 미션 관리 목록은 같은 MissionListPage와 MissionSummaryCard를 쓰며 목록에서는 값을 편집하거나 저장하지 않음. 카드를 누르면 상세(1.5절)로 이동함.
    • 카드는 CardButton으로 이름과 사용 상태 배지(StatusBadge의 dot 옵션, 사용 중 초록·꺼짐 회색)를 한 줄에, 그 아래에 색 없는 뱃지 한 줄을 표시함.
    • 하단 뱃지는 기간, 시작 기준(일간 매일 HH:mm, 주간 요일 HH:mm, 월간 N일 HH:mm), 방식, 목표(값과 단위를 합친 1,850 kcal)이며 해당하지 않는 항목(단순 체크의 목표)은 뺌. 크기·톤은 Health 운동 기록 목록의 하단 뱃지와 같음.
    • 하단 고정 액션바는 기본 미션 관리에는 없고 커스텀 미션 관리에만 커스텀 미션 추가 버튼 하나가 있음. 커스텀 미션이 없으면 NoticeCard(empty)를 표시함.
  • 추가 모달(CustomCreateModal, FormModal)은 이름(30자), 기간, 시작 기준(주간 요일·월간 1~28일, 모든 기간의 시작 시각), 방식, 이상·이하의 단위(10자)와 목표 순으로 받음. 기간·방식·시작 요일·시작일은 OptionSelectField(SelectTrigger와 BottomOptionPicker)로, 시작 시각은 type="time" 입력으로 받으며 기간을 바꾸면 시작 요일·시작일을 1로 되돌리고 시각은 유지함.
    • 저장 시 모달을 닫고 LoadingModal을 표시하며 실패하면 입력을 유지한 채 다시 엶.

1.5 미션 관리 상세 /builtin-missions/:code, /custom-missions/:code​

  • 상세(MissionDetailPage)는 기본·커스텀 미션이 같은 화면에서 사용 여부, 시작 요일·시작일·시작 시각, 목표를 편집하고 커스텀 미션은 이름·단위 수정과 삭제를 더함. GET /missions/{code}에서 단건을 조회하며 없으면 NoticeCard(error)와 목록 버튼을 표시함.
    • 제목 줄에 사용 여부 스위치를, 아래에 읽기 전용 기간 · 방식을 두고 기본 미션은 정의의 설명을 보여 줌. 기간과 방식은 수정할 수 없음.
    • 입력 순서는 이름(커스텀), 시작 기준, 수치형 미션의 단위와 목표임. 생성 모달과 상세는 시작 기준의 PeriodStartPicker와 수치형 목표의 MissionGoalFields를 공유함. 목표 칸에는 수치를 표시하고 기본 미션의 단위 칸은 비활성화함.
    • 서버가 시작 시각을 잠근 미션(startTimeLocked, 일일·주간 열량)은 비활성 시각 칸과 라벨 오른쪽의 Health에서 변경 링크를 표시함. 링크는 Health 음식 설정을 열며, 탭 복귀 후 조회한 시각을 표시함.
    • 시작 요일이 고정된 미션(startNoLocked, 주간 열량)은 요일 칸을 비활성으로 보여 주고 NoticeCard(note)로 startNoNote(고정 사실만)를 안내하며 저장 요청에 요일을 보내지 않음.
    • 커스텀 미션의 시작 기준을 바꾸면 진행 중인 입력이 폐기될 수 있다는 NoticeCard(note)를 표시함.
    • 목표가 서버가 준 허용 범위(minTarget~maxTarget)를 벗어나면 NoticeCard(error)를 표시하고 저장을 막음.
    • targetLocked인 일일·주간 열량과 주간 운동 목표는 비활성 입력칸으로 표시함. 목표 라벨 오른쪽의 Health에서 변경 링크는 Health 개인 건강 설정을 열며, 탭 복귀 후 조회한 목표를 표시함.
    • HEALTH 권한이 없는 Health 기반 미션은 스위치가 비활성이며 사유를 표시함.
  • 하단 고정 액션바는 목록 아이콘 버튼, 커스텀 미션의 삭제 아이콘 버튼(빨강), 저장 순서임. 변경이 없거나 입력이 올바르지 않으면 저장이 비활성임.
    • 저장은 공통 PUT /missions/{code}를 한 번 호출함. 커스텀 미션의 이름·단위도 같은 요청에 담으며, 성공하면 상세에 머물고 서버 값으로 폼을 동기화함.
    • 저장 실패는 토스트로 알리며 서버 상태를 다시 읽고 작성 중인 입력값을 유지함.
    • 삭제는 FormModal 확인을 거쳐 처리하고 목록으로 돌아감. 저장·삭제 중에는 LoadingModal을 표시함.

1.6 문구와 오류 처리​

  • 안내·빈 상태·오류 문구는 공통 UI 가이드 2.9의 NoticeCard로 표시함. 화면 문구는 한국어이며 문장형은 하십시오체와 마침표를 사용함. 401·403은 Hub 로그인으로 복귀하고 조회 실패는 화면의 오류 영역에 표시함. 포커스·탭 복귀 시 현황을 다시 조회함.

2. 검증​

  • 개발 UI는 Vite 15013, API는 18013임. questlog:dev-all, questlog:backend, questlog:frontend, questlog:build VS Code 작업과 just questlog-frontend, just questlog-backend, just questlog-ui-build를 사용함.
  • npm run typecheck --prefix apps/questlog-ui, npm run build --prefix apps/questlog-ui로 검사함. Tailwind 스캔 경로에 apps/questlog-ui와 apps/questlog-api의 템플릿이 libs/shared-ui/tailwind.config.cjs로 등록돼 있음.