본문으로 건너뛰기

JunkBox apps/hub-ui 가이드

1. 역할과 실행​

  • apps/hub-ui는 hub 운영 화면 전용 프런트엔드 앱임.
  • hub-api가 제공하는 서버 렌더링 HTML 골격 위에 React 화면을 마운트하는 역할을 담당함.
  • dashboard, portal, tools, tools-md, portal-menus, users, codes, metas, prompts, ai-logs 화면 엔트리를 소유함.
  • 공통 스타일과 공통 React 유틸은 libs/shared-ui를 소비함.
  • codes, metas, prompts 엔트리는 hub 네비게이션에 노출되는 공통 마스터데이터·AI 프롬프트 관리 화면임.

1.1 런타임 구성​

  • 번들러는 Vite 6 기반 React + TypeScript 구조를 사용함.
  • 운영 산출물은 apps/hub-ui/dist에 생성됨.
  • public은 운영 웹에 배포할 정적 자산을 두는 위치이며 Vite 빌드 시 내용이 dist에 복사됨. 테스트 APK와 임시 다운로드 링크는 웹 빌드와 독립된 제공 경로에서 관리함. 개발 APK 제공 계약은 네이티브 앱 가이드의 휴대폰 테스트 제공 절을 따름.
  • hub-api는 이 디렉터리를 /hub-ui 경로로 직접 마운트함.
  • 개발 서버 기본 포트는 15001임.
  • 루트 진입 /, /hub-ui, /hub-ui/는 /portal로 리다이렉트됨.

1.2 엔트리 구조​

  • src/entries/portal.tsx
  • src/entries/dashboard.tsx
  • src/entries/portal-menus.tsx
  • src/entries/users.tsx
  • src/entries/codes.tsx
  • src/entries/metas.tsx
  • src/entries/prompts.tsx
  • src/entries/ai-logs.tsx
  • src/entries/tools.tsx
  • src/entries/tools-md.tsx
  • src/entries/tools-audiobook.tsx

1.3 페이지 구조​

  • 각 엔트리는 서버 템플릿이 주입한 hub-ui-root, hub-ui-page-props를 기준으로 마운트함.
  • 페이지 구현은 src/pages/*.tsx에 위치함.
  • API 응답 계약과 화면 props 계약은 src/types/models.ts 기준으로 관리함.
  • 브라우저 전역 타입과 import.meta.env 타입은 src/global.d.ts 기준으로 관리함.

1.4 TypeScript 및 Vite 설정 구조​

  • 브라우저 런타임 코드는 tsconfig.json을 기준으로 타입체크함.
  • Vite 설정과 Node 타입이 필요한 파일은 tsconfig.node.json을 기준으로 별도 타입체크함.
  • vite.config.ts는 ESM 기준으로 작성하며, 경로 계산은 import.meta.url과 fileURLToPath() 기반 구조를 사용함.
  • typecheck 스크립트는 브라우저 코드와 Node 설정 파일을 각각 검사하는 구조를 사용함.

1.5 개발 서버 프록시 구조​

  • /api, /login, /dashboard, /portal, /portal-menus, /users, /codes, /metas, /prompts, /ai-logs, /error, /shared-ui, /health는 hub-api로 프록시됨.
  • Vite는 127.0.0.1:15001에 수신하고 공통 LAN TCP 전달기가 기본 경로의 사설 IPv4 주소에서 같은 포트를 제공함. Vite 프록시는 검증된 Host 기준 localhost·LAN HTTP·Tailnet HTTPS origin을 hub-api에 전달함. Tailnet HTTPS는 tailscale serve가 루프백 Vite 서버로 전달함.
  • 개발 모드 엔트리 자산 경로는 /hub-ui/src/entries/*.tsx 기준임.
  • Vite dev client 경로는 /hub-ui/@vite/client임.
  • React refresh runtime 경로는 /hub-ui/@react-refresh임.

2. 공통 UI 계약​

2.1 공통 의존 구조​

  • 입력형 헤더 필터가 있는 Hub Tabulator 화면은 @shared-ui/utils/tabulator-header-filter의 JunkboxTabulator를 사용함. 원격 점진 로딩 화면은 withRemoteHeaderFilters로 로컬 필터를 억제하고 입력값을 API에 전달함.
  • 공통 React 유틸은 @shared-ui/* alias를 통해 libs/shared-ui/src/react를 참조함.
  • 이 alias는 TypeScript paths와 Vite resolve.alias가 함께 해석하는 구조를 사용함.
  • 공통 토스트, HTTP 요청, 페이지 props 파서, Tabulator 점진 로딩 유틸을 직접 복제하지 않음.
  • 공통 CSS는 서버 템플릿이 shared-ui stylesheet 매크로를 호출해 hub-ui-base.css와 화면 모드별 hub-ui-mobile.css, hub-ui-desktop.css 조합으로 로드함.
  • 포털과 /tools, /tools/md는 본문을 모바일 폭으로 유지하되 상단 메뉴는 FHD/모바일 반응형으로 동작해야 하므로 base + mobile + desktop 조합을 사용함.
  • /tools/audiobook은 모바일 전용 화면이라 base + mobile 조합만 사용함. 데스크톱 CSS에만 정의된 .jb-form-stack·jb-modal-head 같은 클래스를 이 화면에서 쓰지 않음.
  • 로그인 같은 모바일 화면은 base + mobile 조합을 사용함.
  • ai-logs, codes, metas, prompts, users, portal-menus 같은 운영 관리자 화면은 base + desktop 조합을 사용함.
  • hub 공통 메뉴바는 각 화면의 본문 폭 정책과 분리해서 뷰포트 기준 반응형으로 동작해야 함.
  • Hub의 PC 상단 메뉴와 모바일 드로어는 같은 순서로 Portal, Dashboard, 도구, Portal 설정, 사용자, 공통 코드, 메타, AI 프롬프트, AI 로그를 표시함.

2.2 구현 원칙​

  • hub 전용 화면만 포함하고 health 화면 엔트리와 타입은 포함하지 않음.
  • 페이지 전용 CSS 파일을 추가하지 않음.
  • 공통 시각 규칙은 shared-ui 클래스 조합으로만 표현함.
  • 공통 유틸 또는 아이콘이 필요하면 먼저 libs/shared-ui/src/react 확장을 우선함.
  • 사용자 노출 텍스트는 화면 컴포넌트에 한국어 문구로 직접 작성함.
  • 공통코드 라벨과 메타 설정값처럼 데이터 자체가 마스터데이터인 값만 DB 조회 구조를 사용함.

3. 화면 구조​

3.1 모바일 화면 구조​

  • /login과 /portal은 모바일 전용 360px 고정 폭 기준을 사용함.
  • /tools와 /tools/md도 포털과 같은 모바일 전용 본문 폭을 사용함. 도구 카드는 한 줄에 하나씩 표시하고, 아이콘과 제목을 같은 줄에 배치함.
  • /portal의 본문은 모바일 전용 360px 고정 폭 기준을 유지하지만, 공통 헤더와 메뉴바는 PC 기준에서는 데스크톱 네비게이션, 모바일 기준에서는 드로어 네비게이션을 사용함.
  • 포털 화면은 모바일에서도 카드 2열 구조를 유지함.
  • 포털 카드 메인 텍스트는 1rem, 서브 텍스트는 0.8rem 기준을 사용함.
  • 모바일 포털 카드는 축소 비율 대응이 아니라 공통 폭, 여백, 아이콘 크기, 카드 패딩 보정으로 사용성을 확보함.
  • /dashboard는 모바일(뷰포트 1440px 미만) 기준에서 360px 고정 폭으로 모든 카드를 1열 세로 목록으로 표시하며, 화면 폭을 초과하는 별도 좌우 스크롤을 만들지 않음.
  • /dashboard의 모바일 보기 전환은 현재 선택된 탭을 표시하는 단일 버튼과 shared-ui의 BottomOptionPicker 하단 선택 시트 조합을 사용함.
  • /portal-menus, /users, /codes, /metas, /ai-logs는 FHD PC-only 본문 정책을 유지하지만, 공통 메뉴바만큼은 모바일 뷰포트에서 드로어 메뉴로 전환됨.
  • 운영 화면, JSON/텍스트 뷰어, 그리드, 필드 라벨은 모두 shared-ui의 Pretendard 기준 폰트 규칙을 따름.

3.2 공통 코드 화면​

  • /codes는 좌측 코드 타입 Tabulator와 우측 메타/코드 상세 영역으로 구성됨.
  • 좌측 type_code, type_name 클릭은 현재 코드 타입을 선택하고 우측 코드 목록과 메타를 로드한 뒤 같은 셀을 편집 모드로 전환하는 동작임.
  • 좌측 count 클릭은 현재 코드 타입을 선택하고 우측 코드 목록과 메타를 로드하는 동작임.
  • 코드 타입의 논리 식별자는 code_type_code이며, 물리 식별자는 code_type_code_id이므로 type_code는 저장 시 하위 공통코드의 code_type_code와 함께 변경될 수 있음.
  • 좌측 Tabulator는 체크박스 기반 멀티 선택 삭제와 현재 코드 타입 활성화를 함께 지원함.
  • 우측 하단 Tabulator는 선택된 코드 타입의 실제 코드 목록을 편집하는 용도임.
  • 우측 하단 Tabulator는 체크박스 기반 멀티 선택 삭제를 지원하며, 삭제 대상 코드는 저장 시 batch API로 반영함.
  • 우측 타입 삭제 전용 버튼은 사용하지 않으며, 코드 타입 삭제는 좌측 Tabulator의 체크박스 선택과 선택 삭제 버튼으로 수행함.
  • 코드 타입 저장은 code_type_code 기준 중복을 저장 전에 확인하고, 서버 409 응답도 중복 저장 실패로 처리함.
  • 공통코드 저장은 같은 code_type_code 안의 common_code 기준 중복을 저장 전에 확인하고, 서버 409 응답도 중복 저장 실패로 처리함.
  • 중복 저장 시 한국어 중복 안내 토스트를 표시하고 저장 요청 또는 저장 후 반영을 중단함.
  • 버튼 영역은 삭제, 조회, 저장 성격 순서를 따르며, 삭제 계열과 조회 계열 사이에는 jb-action-divider를 사용할 수 있음.
  • 좌측 코드 타입 목록과 우측 코드 목록은 각각 선택 삭제, 조회/새로고침, 저장 계열 액션을 같은 성격 순서로 배치함.

3.3 공통 메타/사용자 화면​

  • /metas는 전체 폭 목록과 오른쪽 상세 오버레이 구조를 사용하며 목록에서 체크박스 기반 멀티 선택 삭제를 지원함.
  • /metas 저장은 meta_key 기준 중복을 저장 전에 확인하고, 서버 409 응답도 중복 저장 실패로 처리함.
  • /metas 목록의 선택 삭제 버튼과 상세 패널의 삭제 버튼은 함께 유지됨.
  • /metas 상세 편집 패널은 현재 편집 중인 meta_key, meta_val 기준의 MD 다운로드 버튼을 제공함.
  • MD 다운로드는 서버 저장 여부와 무관하게 현재 폼 상태의 meta_val을 text/markdown;charset=utf-8 Blob으로 생성하고, 파일명은 meta_key 기반 ${meta_key}.md 형식을 사용함.
  • MD 다운로드 파일명은 브라우저와 운영체제 파일명에 부적합한 제어문자와 <>:"/\|?* 문자를 _로 치환함.
  • /users는 점진 로딩형 목록과 상세 편집 구조를 사용하며, 사용자 물리 식별자는 id, 논리 식별자는 user_id를 사용함.
  • /users의 ID 헤더는 숫자 종류로 지정하여 일반 일부 포함, = 정확 일치, 숫자 부등호 비교를 지원함. USER ID, UPDATED BY 헤더는 텍스트 일부 포함과 = 정확 일치를 지원하며 서버가 전체 결과를 필터링함.
  • /users 저장은 user_id 기준 중복을 저장 전에 확인하고, 서버 409 응답도 중복 저장 실패로 처리함.
  • /users 좌측 목록은 체크박스 기반 멀티 선택 삭제를 지원하되 현재 로그인 사용자는 삭제할 수 없음.
  • /users 상세 편집에서 현재 로그인한 사용자 본인의 allowed_modules를 변경하면 저장 전 확인 다이얼로그를 표시하고, 확인 시 저장 후 즉시 로그아웃하여 로그인 화면으로 이동함. 본인 권한 변경은 서버에서 해당 사용자의 활성 세션 전체를 revoke하므로, 클라이언트는 목록 재조회 없이 바로 로그아웃 처리함.
  • /users 상세 편집의 user_id, password는 텍스트 입력 필드이며 select 성격 UI로 렌더링하지 않음.
  • 메타·AI 프롬프트 화면은 @shared-ui/components/WorkspaceDetailOverlay를 사용함. 초기에는 Tabulator를 전체 폭으로 표시하고, 행 클릭이나 신규 버튼으로 오른쪽 50%의 상세 편집 패널을 열며 접기로 닫음. 열려 있는 동안 목록의 노출된 왼쪽 부분을 계속 스크롤하고 다른 행을 선택할 수 있음.
  • AI 프롬프트 화면은 현재 버전 목록과 선택 키의 버전 이력을 별도로 조회하며, 상세에서 새 버전 저장·과거 버전 적용·활성 상태 변경을 처리함.
  • 메타, 사용자 화면의 중복 저장 피드백은 화면 컴포넌트의 한국어 문구로 직접 표시함.
  • /metas, /users 버튼 영역은 삭제, 조회, 저장 성격 순서를 따르며, 삭제 계열과 조회 계열 사이에는 jb-action-divider를 사용할 수 있음.
  • Portal 설정 화면(/portal-menus)도 같은 관리자 화면 액션 정렬 기준을 사용하며, 선택 삭제와 조회/새로고침, 저장 계열 액션을 버튼 성격 기준으로 배치함.

3.4 포털 소비 화면​

  • /portal은 APP, SERVICE 탭 구조를 유지함.
  • /portal의 APP, SERVICE 탭은 shared-ui의 SegmentedTabs를 사용하며, 모바일 고정 폭 안에서 fill 폭 정책으로 2개 탭을 균등 분할함.
  • 포털 API가 반환한 tab=apps 카드는 APP 탭에 표시함.
  • 하위 호환을 위해 tab=projects 카드도 APP 탭에 포함함.
  • iconType=app-icon 카드는 icon 값을 shared-ui 앱 아이콘 slug로 해석하여 /shared-ui/app-icons/{icon}/icon.svg를 표시함.
  • iconType=image 카드는 icon 값을 이미지 URL로 사용하고, 그 외 카드는 icon 값을 텍스트 아이콘으로 표시함.
  • 포털 카드의 앱 이름과 서비스 이름은 jb-portal-card-title의 normal weight 텍스트로 표시하며 별도 굵은 강조를 적용하지 않음.
  • 카드 드래그 정렬은 Sortable을 사용하고, 현재 활성 탭의 카드 순서만 서버에 저장함.
  • 포털 카드 드래그 핸들은 shared-ui 공통 SortableDragHandle과 공통 sortable 옵션을 사용함.
  • 포털 카드 드래그는 핸들을 1초 이상 누른 뒤 이동할 때 정렬 모드로 진입함.
  • 모바일 폭에서도 카드 2열, 드래그 핸들, 설명 표시 규칙을 유지함.

3.5 대시보드 화면​

탭과 레이아웃​

  • /dashboard는 포털과 별개로 동적 데이터를 보여주는 PC/모바일 겸용 운영 화면임.
  • 대시보드 탭은 즐겨찾기, 소식, 경제, 건강, 홈서버 순서로 표시함. HEALTH 권한이 없는 사용자에게는 건강 탭과 음식 카드를 표시하지 않음.
  • 대시보드의 기본 활성 탭은 즐겨찾기임.
  • PC 기준 대시보드는 사용 가능한 탭을 shared-ui의 SegmentedTabs 인라인 탭으로 표시함.
  • 모바일(뷰포트 1440px 미만) 기준 대시보드는 인라인 SegmentedTabs를 숨기고, 현재 탭 버튼을 누르면 BottomOptionPicker 하단 선택 시트로 같은 탭 목록을 선택함.
  • 대시보드 모바일 하단 선택 시트는 현재 선택된 탭이 열림 직후 목록 안에서 보이는 위치로 정렬되어야 함.
  • 즐겨찾기 탭은 사용자가 즐겨찾기한 큰 카드만 최대 8개까지 표시함.
  • 소식 탭은 WMania 최신뉴스, 네이버 스포츠 야구, 네이버 스포츠 해외야구, FMKorea 핫딜 카드를 표시함.
  • 경제 탭은 펀드, 국내 주식, 해외 주식 카드를 표시함.
  • 건강 탭은 현재 로그인 사용자의 음식 섭취 카드를 표시하고 Health 음식 기록 화면으로 연결함.
    • 오늘 섭취량과 주간 평균 (오늘 제외)(주간 한도를 넘겨 실패하면 (오늘 포함))을 두 개의 반원 게이지로 표시함.
    • 주간 평균은 QuestLog 주간 평균 열량 미션이 계산한 값(사용자가 고른 시작 요일부터의 주 중 오늘을 뺀 지난 날짜 기준)이며, 지난 날이 없으면 지난 날 없음, 오늘 기록이 없으면 기록 없음으로 표시함.
    • 카드 값은 QuestLog 미션 판정에서 오므로 QUESTLOG 권한이 없거나 QuestLog 조회가 실패하면 카드가 오류 상태로 표시됨.
  • 두 음식 게이지는 각자의 눈금을 사용하며 눈금 끝은 목표임.
    • 색은 QuestLog 판정 상태(진행 파랑·실패 빨강, 공통 UI 가이드 7.10 상태 색 표준)가 정하고, 값이 목표를 넘은 경우에만 호가 끝까지 차면서 목표 위치에 텍스트 없는 짧은 표시선을 그림.
    • 주간 평균이 목표를 넘었어도 주간 한도 이내이면 진행(파랑)과 표시선임.
    • 오늘 섭취량에 아직 먹지 않은 예정분이 있으면 먹은 구간 뒤에 같은 계열의 옅은 색 구간으로 이어 그리고 (N kcal 예정 포함) 문구를 표시함. 게이지 가운데 숫자는 먹은 양과 예정분의 합계이며 채움·비율·판정은 먹은 양만 사용함.
    • 계산은 shared-ui의 progressGeometry를 사용함.
    • 기록 일수의 별도 보조 문구는 표시하지 않음.
  • 홈서버 탭은 AI, CPU, RAM, Docker, 상위 프로세스, 도커 이상 상태, 수집 상태 카드를 표시함.
  • PC 기준 대시보드는 4열 x 2행 고정 슬롯 배치를 사용하며, 모든 큰 카드는 한 칸만 차지함.
  • PC 기준 카드 수가 한 행보다 적어도 카드 높이는 4x2 슬롯 기준으로 유지함.
  • 카드 내부 목록이 고정 카드 높이를 초과하면 카드 내부 스크롤을 사용하고, 카드 자체 높이를 늘리지 않음.
  • 모바일(뷰포트 1440px 미만) 기준 대시보드는 1열 세로 카드 목록을 사용하며 카드 높이는 자연 높이로 표시함.

카드 공통 동작​

  • 각 카드는 마지막 갱신 시각, 외부 전체보기 링크, 수집 실패 또는 미설정 상태를 자체적으로 표시함.
  • 각 카드는 큰 카드 단위 즐겨찾기 토글 버튼을 제공하며, 즐겨찾기 상태는 서버 preference API로 저장함.
  • 대시보드 헤더의 마지막 생성 시각과 카드별 갱신 시각은 YYYY-MM-DD HH24:MI:SS 형식으로 표시함.
  • 뉴스/핫딜 항목의 publishedAt은 서버가 전달한 원본 문자열을 우선 존중하되, YYYYMMDD, YYYY-MM-DD, YYYY.MM.DD, YYYY-MM-DD HH:MI[:SS], ISO datetime처럼 명확하게 해석 가능한 날짜/시간만 공통 표준 형식으로 정규화함.
  • WMania처럼 외부 원본이 YY-MM-DD 형태의 기사 날짜를 제공하면 임의로 4자리 연도로 보정하지 않고 원본 문자열을 그대로 표시함.
  • 뉴스/핫딜 카드에서 수집 오류가 있으면 오류 메시지만 표시하고 빈 목록 문구를 중복 표시하지 않음.
  • 핫딜 카드가 차단 상태의 stale 데이터를 표시할 때는 오류 메시지와 마지막 성공 시각을 함께 표시하고, 이전 성공 항목 목록은 계속 표시함.
  • 펀드 카드가 FunETF 일시 제한 이후 서버의 이전 성공 행을 받으면 일반 펀드 항목과 같은 형식으로 표시함.
  • 펀드 카드가 FunETF 일시 제한 상태에서 서버의 오류 항목을 받으면 해당 항목의 가격 영역 대신 오류 상태를 표시함.
  • 대시보드를 열면 /api/hub/dashboard를 요청하며 서버의 사용자 공통 30분 캐시를 재사용함. 페이지가 열려 있는 동안 자동 갱신 타이머를 실행하지 않음.
  • 새로고침 버튼은 외부 사이트에 자주 요청할 때의 제한·차단 가능성을 확인창으로 알리고, 사용자가 확인하면 /api/hub/dashboard?forceRefresh=true를 호출함. 수동 요청 중에는 공통 로딩 모달을 표시하고 중복 요청을 막음.
  • 수동 새로고침 이후 서버의 전체 응답 캐시는 완료 시점부터 다시 30분간 유효하며, source별 일시 제한 시간은 유지됨.
  • 대시보드 캐시와 수집 타임아웃 정책은 hub-api의 apps/hub-api/var/dashboard-policy.yml을 기준으로 함.

카드 정렬과 preference​

  • 대시보드 큰 카드는 shared-ui 공통 SortableDragHandle과 공통 sortable 옵션을 사용해 드래그 정렬할 수 있음.
  • 대시보드 큰 카드 드래그는 핸들을 1초 이상 누른 뒤 이동할 때 정렬 모드로 진입함.
  • 대시보드 큰 카드 순서는 탭별로 /api/hub/dashboard/preferences에 저장함.
  • 즐겨찾기 탭의 드래그 순서는 favoriteCardIds 배열 순서로 저장함.
  • 소식, 경제, 홈서버 탭의 드래그 순서는 cardOrders.news, cardOrders.economy, cardOrders.system 배열 순서로 저장함.
  • 건강 탭의 드래그 순서는 cardOrders.health 배열 순서로 저장함.
  • 대시보드 preference 저장은 브라우저 localStorage를 사용하지 않으며, 같은 사용자 계정 기준으로 기기와 브라우저를 넘어 유지됨.

투자 카드​

  • 투자 카드의 펀드/국내 주식/해외 주식 항목 순서는 서버 응답 순서를 따르며, 서버는 공통코드 sort_order_no 기준으로 정렬함.
  • 투자 카드의 펀드/국내 주식/해외 주식 항목은 드래그 핸들을 제공하며, 순서 변경 시 /api/hub/dashboard/investments/reorder로 저장함.
  • 투자 카드의 펀드/국내 주식/해외 주식 항목 드래그 핸들도 shared-ui 공통 SortableDragHandle과 공통 sortable 옵션을 사용함.
  • 투자 카드 현재가는 펀드/국내 주식/국내 지수는 ₩숫자, 해외 주식/해외 지수는 $숫자 형식으로 표시함.
  • 투자 카드 등락 금액은 부호를 통화기호 앞에 두는 +₩숫자, -₩숫자, +$숫자, -$숫자 형식으로 표시함.
  • 투자 카드 등락률은 +숫자%, -숫자% 형식으로 표시하며, 등락 방향 텍스트와 금액/등락률 부호가 같은 방향을 표현해야 함.
  • 투자 카드의 상승/하락 등락 정보는 한국 시장 관례에 맞춰 상승은 빨간색, 하락은 파란색으로 표시함.

AI 카드​

  • AI 카드는 OpenRouter Management API 기준의 금일, 금주, 금월 사용량을 USD로 표시함.
  • AI 카드는 OpenRouter API key별 주간 사용량을 USD로 표시함.
  • AI 카드는 OpenRouter 잔여 크레딧과 크레딧 조회 상태를 표시함.
  • AI 카드의 외부 전체보기 링크는 https://openrouter.ai/settings/credits로 연결함.
  • AI 카드 사용량은 원화 환산을 수행하지 않으며, AI 로그 화면의 KRW/USD 토글과 별도 표시 계약을 사용함.
  • AI 카드 내부 지표는 대시보드 다른 카드와 같은 플랫한 저대비 톤을 사용하고 강한 색상 음영이나 그라데이션을 사용하지 않음.

홈서버 카드​

  • 홈서버 CPU 카드와 RAM 카드는 사용률 게이지, 대표 수치, 세부 메트릭을 함께 표시함.
  • 홈서버 Docker 카드는 전체/실행/Healthy/Unhealthy/문제 컨테이너 개수를 표시함.
  • 홈서버 상위 프로세스 카드는 프로세스명, PID, CPU 사용률, 메모리 사용률, 상태를 표시함.
  • 홈서버 도커 이상 상태 카드는 비정상 컨테이너 이름, 이미지, CPU, RAM, 상태를 표시하고, 문제가 없으면 빈 상태 문구를 표시함.
  • 홈서버 수집 상태 카드는 Glances API 수집 상태, CPU/RAM 대표 수치, 도커 이상 개수를 요약함.

3.6 AI 로그 상세 화면​

  • /ai-logs는 KST 오늘의 최신 로그 100건으로 진입함. 100건 더 보기와 이 날짜 전체 보기는 현재 날짜 조회에 행을 이어 붙임.
  • 호출 상세의 응답 검증은 최초 호출과 보정 시도별로 호출 결과, JSON·스키마·업무 검증 상태, 오류 경로와 프롬프트 버전을 표시함. 미기록 단계는 기록 없음으로 표시함.
  • 전날·다음날 이동은 날짜만 바꾸고 헤더 필터와 정렬을 유지함. 오늘은 다음날을 비활성화함.
  • 헤더 필터와 열 정렬은 선택 날짜 전체에 서버에서 적용함. COST를 처음 누르면 비용이 큰 순으로 조회함. 텍스트 필터는 일부 포함, = 입력은 정확 일치로 처리함.
  • 상단 제목 옆에 오늘 비용, 최근 7일 비용, 오늘 성공률, 오늘 성공 호출 평균을 표시함. 그리드는 화면의 남은 높이를 채움.
  • /ai-logs 목록과 요약 영역은 사용된 AI의 토큰 수와 예상 비용을 표시함. 문자 단위로 과금한 호출(usageUnit=CHARACTER)은 토큰 칸에 usageQuantity를 273자 형식으로 표시함.
  • 미기록 토큰·실행 시간은 —로 표시함. 실행 시간은 밀리초 단위로 표시함.
  • AI 예상 비용의 원본 값은 USD 기준이며, 화면 최초 표시는 원화 기준임.
  • 원화 계산은 메타 EXCHANGE_RATE의 meta_val을 1달러당 원화 숫자값으로 해석해 수행함.
  • 비용 표시는 원화는 소수점 둘째 자리, 달러는 소수점 여섯째 자리까지 표시함.
  • 비용이 NULL이거나 숫자로 해석되지 않으면 목록·상세에서 미산정으로 표시하고 명시적인 비용 0과 구분함. 원화 표시에서 비용은 있으나 환율을 얻지 못한 경우는 -로 표시함.
  • 미산정 건이 있는 기간의 비용 옆에 안내 버튼을 표시함. 안내를 열면 해당 기간의 미산정 건수와 비용 합계 제외 기준을 표시함.
  • 그리드 버튼 영역의 통화 전환 버튼은 현재 비용 표시 단위를 KRW와 USD 사이에서 토글함.
  • 통화 전환 버튼 문구는 화면 컴포넌트의 한국어 문구로 직접 작성함.
  • USD 표시는 API 응답의 USD 예상 비용 값을 그대로 사용함.
  • KRW 전환 시 환율 메타가 없거나 숫자로 해석되지 않으면 한국어 안내 토스트를 표시하고 현재 통화 상태를 유지함.
  • /ai-logs 상세 모달은 입력 파라미터와 출력 내용을 JSON 트리 또는 텍스트 뷰어로 표시함.
  • 상세 뷰어는 공통 jb-json-tree, jb-code-view 클래스를 사용함.
  • ai-logs 화면은 요약 라벨, JSON 트리, 텍스트 뷰어, 그리드까지 shared-ui의 Pretendard 기준 폰트를 일관되게 사용함.

3.7 도구 화면​

  • /tools는 마스터데이터 캐시 갱신, 북마크 등록, MD 문서 생성, 프로 레슬링 뉴스, EPUB 오디오북 변환 카드를 이 순서로 세로 목록에 표시함.
  • 마스터데이터 캐시 갱신은 진행 중 LoadingModal을 표시하고, 완료하면 닫기 동작만 있는 공통 모달에 성공·실패 집계와 앱별 상태·오류를 표시함. 요청 전체가 실패하면 같은 모달의 NoticeCard에 원인을 표시함.
  • 북마크 등록은 하단 시트에서 URL 중복 확인, 웹페이지 분석, 제목·요약·태그 확인, 저장을 진행함.
  • /tools/md는 초안 입력, AI 생성 결과 편집·미리보기, Vault 폴더 선택, 등록 단계를 제공함. 문서 카테고리는 AI가 추천하지 않고 사용자가 선택함.
  • /tools/md의 초안 상태는 jb-mobile-page에 viewport 기준 높이와 공통 하단 액션바 여백을 적용하고, jb-panel 안의 jb-input textarea가 남는 높이를 채움. 생성 결과가 있으면 고정 높이를 해제하고 문서 편집·미리보기 내용을 자연 스크롤로 표시함.
  • /tools/md의 하단 고정바는 왼쪽 IconMenu 링크로 /tools 목록에 돌아가며, 초안 상태의 AI로 문서 생성 버튼은 나머지 폭을 사용함. 생성 결과가 있으면 다시 생성 보조 버튼과 Vault에 등록 주요 버튼을 같은 바에 표시함. 편집·미리보기 전환은 공통 모바일 segmented 선택 클래스를 사용함.
  • Vault 폴더 선택기는 현재 경로의 하위 폴더를 단계별로 보여주며, 상위 경로로 돌아갈 수 있음. 자식 폴더가 있는 항목에만 오른쪽 화살표를 표시하고 끝 폴더에는 표시하지 않음.
  • 실제 Vault 카테고리인 폴더만 선택할 수 있으며, 경로 표시를 위한 가상 상위 폴더는 탐색에만 사용함.

3.8 EPUB 오디오북 변환 화면​

  • /tools/audiobook은 SegmentedTabs의 변환·작업 내역 두 탭으로 나뉨. 변환 탭은 EPUB 선택, 음성·범위 선택, 사용량 확인을, 작업 내역 탭은 결과 재생을 jb-mobile-page 위의 jb-panel 카드 세로 배치로 보여 줌. 서버 계약은 guide-apps-hub-api.md 7.10·7.11절을 따름.
  • 진입 시 /status로 설정 상태를 읽음. 빠진 설정이 있으면 NoticeCard tone="error"로 항목별 문장을 표시하고 생성 버튼만 비활성화함. EPUB 탐색과 예상 문자 수 확인은 계속 동작함.
  • EPUB은 하단 시트(제목과 닫기 버튼을 한 줄에 둔 jb-mobile-sheet-panel)의 폴더 탐색기로 고르며 폴더와 .epub 파일만 표시함. 선택하면 제목·저자·챕터 수·본문 글자 수를 보여 줌.
  • 음성은 SelectTrigger와 BottomOptionPicker 하단 시트로 고르며 시트의 여성·남성 탭에 서버가 내려준 전체 음성을 나눠 보여 줌. 범위와 관계없이 1개만 고름.
  • 변환 범위는 SegmentedTabs(미리듣기·챕터·전체)로 고름. 챕터 선택은 BottomOptionPicker를 쓰며 전체에서는 MP3·M4B 형식을 고름.
  • 사용량은 ProgressBar와 선택 조건별 예상 문자 수(캐시 재사용분 제외)로 표시함. 예상이 남은 한도를 넘으면 오류 안내와 함께 생성을 막고, 공통 AI 사용 로그 기준 집계라는 안내를 항상 보여 줌. 미리듣기 범위 설명의 길이는 /status의 preview_seconds를 약 5분·약 4분 30초처럼 분·초로 표시함.
  • 미리듣기는 선택한 음성 1개의 합성이 끝날 때까지 LoadingModal로 진행을 표시함. 챕터·전체는 등록하는 동안만 LoadingModal을 쓰고 이후 진행은 작업 내역 탭에서 표시함. 변환 시작 뒤에는 이 탭으로 자동 전환함.
  • 작업 내역 탭은 파일 선택과 무관하게 전체 작업을 최신순으로 보여 주며 카드에 책 제목을 표시함. 카드는 StatusBadge, 변환 진행률(ProgressBar), 재생 <audio>, 다운로드, 삭제를 제공함. 진행 중 작업에는 취소, 실패·취소 작업에는 재개를 표시하며 활성 작업이 있으면 탭·파일 선택과 무관하게 5초 간격으로 갱신함.
  • 한 오디오를 재생하면 다른 오디오는 일시정지해 음성 비교를 돕고, 하단 고정바는 /tools 복귀 IconMenu 링크와 변환 탭의 범위별 주요 버튼(미리듣기 생성·챕터 변환·전체 변환), 작업 내역 탭의 새로고침을 둠.

3.9 프로 레슬링 뉴스 화면​

  • /tools/pro-wrestling-news는 공통 모바일 본문을 사용함. 최신은 최근 리포트를 보여 주고 이력은 최신순으로 수집 시작·종료 시각과 실행 구분, 소식 건수를 표시함.
  • 수집 시작과 종료를 각각 한 줄에 배치하고 날짜·요일·초까지 한국 시간으로 표시함. 이력 카드와 텔레그램의 리포트 보기 버튼은 리포트 상세를 열어 줌.
  • 수집 소유자의 최신·이력 하단에는 설정 톱니 버튼과 지금 취합이 있음. 설정 모달에서 수집 시각, 자동 수집 후 텔레그램 발송과 0건 발송을 함께 저장함. 0건 발송은 자동 발송을 켰을 때 선택할 수 있음.
  • 수동 취합 모달의 텔레그램 발송은 기본 해제 상태임. 주요 소식이 0건일 때 발송을 생략한다는 안내를 설명란에 표시함.
  • 요청이 Automation에 등록되면 브라우저를 닫아도 작업은 실행됨. 생성된 결과는 이력에서 확인함.
  • 이력 상세 하단에서 목록으로 돌아가거나 본인 리포트 삭제를 확인함. 삭제가 끝나면 이력 목록을 열어 줌. 수집·삭제의 데이터 계약은 guide-apps-hub-api.md 7.12절을 따름.

4. 관련 문서​

  • 프로젝트 전체 구조는 docs/junkbox/common/guide-jb-overview.md, 공통 원칙은 docs/junkbox/common/guide-jb-core.md를 따름.
  • hub 백엔드 구조는 docs/junkbox/apps/guide-apps-hub-api.md를 따름.
  • 공통 UI 자산 구조는 docs/junkbox/libs/guide-lib-shared-ui.md를 따름.