tb_bizcard_card_m은 owner_user_id, 원본 경로·크기·수정 시각·SHA-256, 명함 등록일 registered_on(DATE), 인식·수정 필드, 처리 상태, 사용 모델·오류·일시를 저장함. source_path에는 스캔 루트 기준의 절대 경로가 저장되며 이미지 조회와 재인식에서 이 경로를 그대로 사용함. BizCard API만 이 테이블을 읽고 씀.
ensure_schema()는 registered_on 컬럼이 없는 기존 SQLite에 컬럼을 추가하고 값이 NULL인 명함만 채움. 파일명 끝의 -YYYYMMDD가 유효하면 이를 등록일로 사용하고, 없거나 유효하지 않으면 원본 파일의 최초 생성 시각을 한국 시간 날짜로 변환함. 이미 저장된 등록일은 시작 시 다시 계산하거나 덮어쓰지 않음.
tb_bizcard_error_log는 owner_user_id, 오류 발생 시각, 작업 종류(refresh·selected·single·previous), 대상 card_id·source_path, 오류 메시지를 저장함. 사용자·발생 시각·로그 ID 인덱스로 최신 오류를 조회함. tb_bizcard_card_m.recognition_error는 현재 오류만 나타내며, 오류 이력은 재인식 성공이나 수동 저장 후에도 보존됨.
tb_bizcard_card_category_r은 명함과 분류의 다대다 연결(card_id, category_code, KST 기본값 created_at)을 저장하며 (card_id, category_code)가 기본 키이고 card_id는 tb_bizcard_card_m을 ON DELETE CASCADE로 참조함.
ensure_schema()가 CREATE TABLE IF NOT EXISTS로 만들며 기존 테이블은 변경하지 않음.
분류 코드의 표시명·정렬·활성 여부는 Hub 공통코드 BIZCARD_CATEGORY가 소유하고 BizCard는 코드 값만 저장함.
재귀 스캔은 JPG·JPEG·PNG·WebP 파일만 대상으로 하며, 변경 후 30초가 지나지 않은 파일은 다음 실행으로 미룸.
같은 사용자의 경로·크기·수정 시각이 같은 파일은 재해시하지 않고 건너뜀. (owner_user_id, source_sha256) 유니크 제약으로 사용자별 동일 이미지 재등록을 막음. 새 레코드는 PENDING_RECOGNITION으로 생성됨.
신규 파일의 registered_on은 수집 시 원본 파일의 최초 생성 시각을 stat -c %W로 읽어 한국 시간의 날짜로 저장함. 생성 시각을 확인할 수 없으면 임의의 수정일·스캔일로 대체하지 않고 오류를 반환함. 파일명 날짜를 우선하는 규칙은 기존 데이터의 빈 등록일을 채울 때만 사용함.
인식은 사용자가 갱신 또는 재인식을 실행할 때만 수행함. POST /refresh/prepare가 새 이미지를 등록하고 PENDING_RECOGNITION·FAILED 대상을 최대 50건 반환하며, UI가 각 대상을 POST /cards/{card_id}/recognize-pending으로 순차 처리함.
BIZCARD_RECOGNITION 라우트는 다른 기능과 독립적으로 모델을 선택함.
로컬·기본·운영 라우팅 파일은 LiteLLM openrouter/qwen/qwen3.7-flash를 기본 모델로, BIZCARD_RECOGNITION_FALLBACK의 openrouter/google/gemma-4-31b-it를 대체 모델로 설정함.
기본 라우트는 json_object와 reasoning_enabled: false, 대체 라우트는 json_schema를 사용하며 두 라우트의 출력 한도는 1024토큰임.
shared-ai는 기본 라우트의 시스템 프롬프트에 JSON Schema를 포함하고 응답을 Pydantic으로 검증함.
운영 호스트의 /sorc001/junkbox/master-data/ai-routing.yml이 BizCard 컨테이너에 읽기 전용으로 마운트되며, 배포 스크립트가 Git 관리 기본 라우팅 파일을 이 경로로 복사함.
모델 설정과 reasoning_enabled 전달을 지원하는 shared-ai 코드를 함께 배포해야 함.
인식 시스템 프롬프트와 사용자 프롬프트는 shared-core.masterdata.PromptService가 Hub tb_ai_prompt_m의 활성 현재 버전 BIZCARD_RECOGNITION_INSTRUCTION, BIZCARD_RECOGNITION_USER_TEMPLATE에서 읽음. 프롬프트가 없거나 비활성이면 503 오류를 반환함. AI 모델 공통코드는 Hub 마스터데이터 서비스를 통해 조회하고 BizCard가 Hub SQLite를 직접 열지 않음.
이미지 data URL을 shared-ai direct runner에 전달하고 이름·회사·부서·직급·이메일·전화·휴대전화·웹사이트·주소·메모를 구조화함. 인식 응답은 10개 문자열 필드를 모두 요구하고 추가 필드를 거부하며, 없는 값은 빈 문자열로 받음. 이 호출에서는 구조화 응답 복구 재시도를 사용하지 않음. PaddleOCR 등 별도 OCR 전처리 단계는 사용하지 않음.
기본 인식의 JSON 파싱·필드 검증 실패, 출력 한도 도달, 모든 필드가 빈 결과, 연결·시간 초과, HTTP 429·일부 5xx 오류는 같은 원본 이미지와 프롬프트로 대체 라우트를 한 번 호출함. 설정 오류 등 그 밖의 오류에는 대체 호출을 하지 않음. 대체 경로까지 실패하면 기본·대체 경로의 오류 범주를 함께 기록함. 한자가 섞인 이름은 한글 부분만 저장하며 빈 인식 결과는 실패로 처리함.
JSON과 필드 검증을 통과한 글자 오독이나 일부 조직 표기 누락은 자동으로 판별하지 않음. 성공 상태 REVIEW_REQUIRED의 원본 이미지와 추출값을 사용자가 검토하는 흐름임.
Recognition과 이를 상속한 수동 수정 입력 CardUpdate는 phone·mobile에서 ASCII 숫자 0–9 이외 문자를 제거함. 따라서 AI 인식과 상세 수정 저장 모두 전화번호·휴대전화 번호를 구분 기호 없는 숫자 문자열로 저장하며 앞자리 0을 유지함. 현재 SQLite의 두 컬럼 값도 같은 형식임.
CardUpdate는 필수 날짜 registered_on을 받음. 수동 저장은 이 날짜를 함께 갱신하며, 다시 인식하거나 인식 결과를 저장할 때는 등록일을 변경하지 않음.
인식 성공 상태는 REVIEW_REQUIRED, 실패 상태는 FAILED, 수동 저장 상태는 REVIEWED임. 실패 항목도 다시 인식할 수 있으며 오류는 recognition_error에 남음.
갱신 준비·대상 인식·선택 재인식 요청의 예외와 개별 인식 실패를 BizCard 오류 이력에 기록함. AI 라우트가 없는 갱신 시도도 전체 갱신 오류로 기록함. 개별 인식 실패의 카드 상태 갱신과 오류 이력 삽입은 같은 DB 트랜잭션에서 확정함.
관리 API 접두사는 /api/bizcard이며 Hub JWT의 BIZCARD module 권한을 요구함. 목록·상세·원본 이미지 조회, 정보 수정, 수동 갱신, 개별·선택 재인식, 분류 조회와 명함 분류 지정을 제공함. 모든 조회·등록·수정·삭제와 스캔·인식은 현재 사용자 owner_user_id 범위에서 처리함.
GET /cards와 GET /cards/{card_id}는 registered_on과 지정된 분류 코드 배열 categories(코드 오름차순, 없으면 빈 배열)를 반환함. 목록은 분류를 한 번의 조회로 묶어 읽음. 목록 API의 기본 순서는 등록일 내림차순, 같은 날짜의 공백 없는 이름 오름차순, card_id 내림차순임. 빈 이름은 같은 날짜의 이름 있는 명함 뒤에 둠. 화면의 이름순·회사순 선택은 UI에서 조회된 목록을 다시 정렬함.
POST /scan은 수집과 대기 인식을 한 요청에서 수행하는 수동 API임. POST /refresh/prepare와 POST /cards/{card_id}/recognize-pending은 진행 상황을 보여주는 모바일 UI 흐름에서 사용함.
POST /cards/{card_id}/retry-selected는 처리 상태와 무관하게 명함을 PENDING_RECOGNITION으로 되돌려 재인식하며 {card, skipped}로 응답함(skipped는 현재 항상 false). REVIEWED 명함은 수동 수정 값이 인식 결과로 덮어써지므로 UI가 확인을 받은 뒤 호출함. POST /cards/{card_id}/retry-review-required는 검토 필요 항목만 허용하고 다른 상태는 skipped로 응답함.
GET /categories는 BIZCARD_CATEGORY 공통코드(활성·비활성 모두)를 code·name·sort_order_no·is_active로 sort_order_no, code 순서로 반환함. 공통코드는 MasterDataService로 조회하며 BizCard가 Hub SQLite를 직접 열지 않음.
PUT /cards/{card_id}/categories는 category_codes로 해당 명함의 분류를 통째로 교체하고 갱신된 명함을 반환함.
POST /cards/categories/bulk는 card_ids(1–500개)·category_codes·action(add·remove)으로 선택한 명함에 분류를 일괄 추가·삭제하고 {card_count, changed}를 반환함.
두 API 모두 새로 추가하는 코드는 활성 공통코드여야 하며(그 밖은 400) 이미 지정된 비활성 코드의 유지·삭제는 허용함.
본인 소유가 아닌 card_id는 무시하고, 분류 변경은 status·updated_at·recognition_error를 변경하지 않음.
GET /error-logs는 현재 사용자 오류 이력을 발생 시각과 로그 ID 내림차순으로 반환함. limit 기본값은 50, 허용 범위는 1–100이며 offset으로 다음 묶음을 조회함. 다른 관리 API와 동일하게 Hub JWT BIZCARD 권한을 요구함.
/bizcards, /bizcards/logs, /bizcards/{card_id} 화면은 Hub Cookie 또는 Bearer Header로 사용자 인증을 확인하고 required_module=BIZCARD 로그인·복귀 흐름을 사용함.
이미지 응답은 설정된 스캔 루트 내부의 허용 확장자 파일만 제공하며 private·no-store cache 헤더를 사용함.