Vite는 127.0.0.1:15001에 수신하고 공통 LAN TCP 전달기가 기본 경로의 사설 IPv4 주소에서 같은 포트를 제공함. Vite 프록시는 검증된 Host 기준 localhost·LAN HTTP·Tailnet HTTPS origin을 hub-api에 전달함. Tailnet HTTPS는 tailscale serve가 루프백 Vite 서버로 전달함.
/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)도 같은 관리자 화면 액션 정렬 기준을 사용하며, 선택 삭제와 조회/새로고침, 저장 계열 액션을 버튼 성격 기준으로 배치함.
각 카드는 마지막 갱신 시각, 외부 전체보기 링크, 수집 실패 또는 미설정 상태를 자체적으로 표시함.
각 카드는 큰 카드 단위 즐겨찾기 토글 버튼을 제공하며, 즐겨찾기 상태는 서버 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을 기준으로 함.
/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 카테고리인 폴더만 선택할 수 있으며, 경로 표시를 위한 가상 상위 폴더는 탐색에만 사용함.
/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 링크와 변환 탭의 범위별 주요 버튼(미리듣기 생성·챕터 변환·전체 변환), 작업 내역 탭의 새로고침을 둠.