Skip to main content

JunkBox apps/bizcard-ui 가이드

1. 역할과 실행​

  • apps/bizcard-ui는 BizCard API가 /bizcards에서 제공하는 모바일 전용 React + Vite 관리 화면임.
  • Vite 개발 포트는 15010이며 빌드 결과와 manifest는 BizCard API가 /bizcard-ui에서 서빙함. 개발 서버의 /·/bizcard-ui/ 진입은 /bizcards로 이동함.
  • 개발 모드에는 Vite client와 React refresh preamble을 서버 템플릿에 주입함.

2. 공통 UI 계약​

  • 서버 앱 셸은 Hub 포털 메뉴의 표시 가능한 설명을 사용하고, favicon은 shared-ui의 bizcard 아이콘을 사용함.
  • 모바일 페이지·카드·입력·하단 고정 액션바·토스트·중앙 모달은 shared-ui 자산과 jb-* 클래스를 사용함. 상세 폼은 jb-form-stack·jb-field·jb-field-label로 라벨과 입력 간격을 통일함. 앱 전용 CSS와 inline style은 사용하지 않음.
  • 로컬 개발은 just bizcard-dev-all, 빌드는 just bizcard-build를 사용하며 .vscode/tasks.json에 대응 작업이 있음.
  • UI 검증 명령은 npm run typecheck와 npm run build임.

3. 화면 구조​

3.1 라우트​

  • BrowserRouter는 /bizcards 목록, /bizcards/logs 오류 이력, /bizcards/:cardId 상세 경로를 제공하며 공통 SPA 탐색·전환 계약을 사용함. 앱 셸의 명함·로그 메뉴는 현재 경로에 따라 활성 상태가 바뀜.

3.2 목록 검색과 정렬​

  • 명함 목록의 검색 조건은 하단 액션바의 검색 아이콘 버튼이 여는 FormModal 검색 시트에서 입력함.
    • 시트에는 처리 상태·분류(다중)·정렬을 고르는 ToggleButton 칩과 이름·회사·전화번호 입력 필드가 있으며 버튼은 닫기·초기화(FormModal의 middleAction)·조회 순서의 검정(ghost)임.
    • 시트 입력은 임시(draft) 값이며 조회를 눌러야 목록과 URL에 반영됨.
    • 닫기는 입력값을 버리고 초기화는 시트 안의 조건 값만 비우되 정렬 선택은 유지함.
    • 적용된 조건은 목록 제목 아래의 적용 중: 요약으로 표시하며 정렬이 최신순이 아니면 정렬도 함께 표시함.
  • 정렬은 검색 시트에서 최신순·이름순·회사순 중 하나를 고르며 기본값은 최신순임. 등록일은 목록 카드에 표시하지 않음.
  • 목록 데이터는 GET /api/bizcard/cards로 한 번 조회한 뒤 화면에서 검색 조건과 정렬을 함께 적용함. 이름·회사는 검색어 양끝의 공백을 제거하고 대소문자를 구분하지 않는 부분 일치이며, 전화번호는 입력에서 숫자만 추출해 phone·mobile 양쪽의 숫자 문자열을 부분 일치 검색함. 분류는 선택한 분류 중 하나라도 가진 명함을 표시함(OR). 조회를 누르면 조건이 즉시 목록과 건수에 반영됨.
  • 최신순은 등록일 내림차순, 같은 날짜의 이름 가나다순, card_id 내림차순임. 이름순은 공백 없는 이름·회사 가나다순, 등록일 내림차순, card_id 내림차순이며 회사순은 공백 없는 회사·이름 가나다순, 등록일 내림차순, card_id 내림차순임. 이름·회사의 가나다순 비교는 브라우저의 한국어 Intl.Collator를 사용하고 빈 값은 뒤에 둠.
  • 검색 조건은 status·name·company·phone·category(분류 코드를 쉼표로 연결), 정렬 선택은 sort URL 쿼리에 replace 방식으로 저장함. 기본 최신순은 sort 쿼리를 생략함. 상세로 이동할 때 쿼리를 전달하고 하단 목록 버튼으로 복귀할 때 유지함. 목록 데이터는 복귀 시 다시 조회한 뒤 유지된 조건으로 필터링·정렬함.

3.3 명함 카드와 선택 작업​

  • 각 명함 카드는 공백 없는 이름과 직급, 다음 줄의 회사와 부서, 휴대전화 또는 전화, 이메일, 우측 상단의 작은 상태 배지를 표시하며, 지정된 분류가 있으면 이메일 아래에 #분류명 jb-chip을 표시함. 배지는 공통 모바일 카드 규격을 사용하며 인식 대기는 회색, 검토 필요는 주황색, 검토 완료는 녹색, 인식 실패는 빨간색임.
  • 모든 명함 카드에 체크박스가 표시되며 처리 상태와 무관하게 선택할 수 있음.
    • 하단 전체 선택/선택 해제 아이콘 버튼(IconListChecks·IconListX)은 현재 검색 조건으로 보이는 목록 전체를 선택·해제함.
    • 선택한 명함 ID는 탭 세션의 sessionStorage(bizcard:selected-card-ids)에 저장되어 상세에 다녀오거나 목록을 다시 열어도 유지되며 선택 해제·재인식 완료·목록에서 사라진 명함은 제거됨.
    • 검색 조건을 바꿔도 선택은 유지되므로 보이지 않는 선택도 선택 건수와 작업 대상에 포함됨.

3.4 상세와 인식​

  • 상세는 원본 이미지와 인식 오류를 보여주고 등록일(type=date)·이름·회사·부서·직급·이메일·전화·휴대전화·웹사이트·주소·메모를 수정함. 등록일을 비우면 저장 요청을 보내지 않고 입력을 요구함.
  • 저장은 PUT /api/bizcard/cards/{card_id}, 상세 다시 인식은 POST /api/bizcard/cards/{card_id}/retry를 호출함.
    • 목록 하단 액션바는 [검색][전체 선택/해제][갱신] 아이콘 버튼 3개와 분류 (n)·재인식 (n) 텍스트 버튼으로 구성함.
    • 검색·전체 선택/해제·분류(시트 열기)는 검정(ghost), 갱신과 재인식은 노랑(warning)임.
    • 갱신(RefreshCw, 접근성 이름 명함 갱신)은 새 이미지 등록과 외부 AI 호출을 하는 광범위 작업이라 노랑이며 확인창 없이 POST /api/bizcard/refresh/prepare로 새 이미지를 찾고 대상을 받은 뒤 각 POST /api/bizcard/cards/{card_id}/recognize-pending을 순차 호출함.
    • 재인식은 선택한 명함을 처리 상태와 무관하게 각 POST /api/bizcard/cards/{card_id}/retry-selected로 처리함.
    • 선택에 REVIEWED 명함이 있으면 "검토 완료 명함 n건이 포함되어 있으며 재인식하면 저장된 정보가 덮어써짐"을 알리는 중앙 확인 모달(취소 검정·재인식 노랑)을 먼저 표시하고 확인 후 진행함.

3.5 분류​

  • 분류 (n)은 분류 추가/분류 삭제를 고르는 선택 시트를 열고, 이어서 BottomOptionPicker 다중 선택(추가는 활성 분류, 삭제는 선택한 명함에 실제로 지정된 분류의 합집합)으로 분류를 고름.
    • 시트의 확인은 임시 선택만 확정하는 검정이며, 이어지는 FormModal 확인 모달(추가 흰색·삭제 빨강, 취소 검정)이 대상 건수와 분류 칩을 보여주고 확인 시 POST /api/bizcard/cards/categories/bulk를 호출함.
    • 호출 중 LoadingModal을 표시하며 명함의 처리 상태와 갱신 시각은 바뀌지 않음.
    • 분류 목록은 GET /api/bizcard/categories로 조회하고 비활성 분류는 이미 지정된 칩과 검색 후보에만 표시하며 새로 지정하는 후보에서는 제외함.
  • 상세의 분류 패널은 지정된 분류 칩과 분류 선택 버튼을 표시함. 선택 시트에서 고른 뒤 분류 저장 확인 모달(취소 검정·저장 흰색, 기존 분류가 빠지면 삭제 안내 문구)을 거쳐 PUT /api/bizcard/cards/{card_id}/categories로 즉시 저장하며 하단 저장과 별개로 처리 상태를 바꾸지 않음. 선택이 현재 분류와 같으면 모달 없이 닫음.

3.6 진행 표시와 오류 이력​

  • 갱신·선택 재인식 중 화면 중앙 모달은 대상 파일명, 현재 처리 항목, 완료 건수, 개별 결과를 표시함. 진행 막대는 사용하지 않음.
  • 갱신·선택 재인식 API 요청이 실패하면 순차 처리를 중단하고 목록을 다시 조회함. 오류 문구는 목록 상단의 jb-mobile-error와 공통 오류 토스트에 표시함.
  • 로그 화면은 GET /api/bizcard/error-logs로 최근 오류 50건을 불러오고 더 보기에서 offset을 늘려 다음 50건을 조회함. 작업 종류·시각·대상 파일명·오류 내용을 표시하고 card_id가 있는 항목은 명함 상세로 이동할 수 있음.
  • 상태 라벨은 인식 대기, 검토 필요, 검토 완료, 인식 실패로 표시함.