Files

hskwon aca1767eb9 초기 커밋: 5130 레거시 시스템

- URL 하드코딩 → .env APP_URL 기반 동적 URL로 변경
- DB 연결 하드코딩 → .env 기반으로 변경
- MySQL strict mode DATE 오류 수정

2025-12-10 20:14:31 +09:00

22 KiB

Raw Blame History

사업자등록증 OCR 시스템

브라우저 기반 OCR을 사용하여 사업자등록증 이미지/PDF를 자동으로 인식하고 데이터를 추출하는 시스템입니다.

📋 기능

✅ 사업자등록증 이미지/PDF 업로드
✅ 듀얼 OCR 모드: JavaScript OCR + AI API (Claude) 선택 가능 ⭐NEW
✅ 브라우저 기반 OCR (Tesseract.js)
✅ AI 기반 OCR (Claude 3 Haiku with Vision) ⭐NEW
✅ 자동 정보 추출 및 폼 자동입력
✅ 사업자번호 유효성 검증 (체크섬)
✅ 데이터 저장 및 목록 관리
✅ 검색 및 페이징
✅ 상세보기 모달

📁 파일 구조

ocr/
├── index.php           # OCR 메인 페이지 (업로드 및 인식)
├── claude_api.php      # Claude AI API 호출 백엔드 ⭐NEW
├── save_biz.php        # 데이터 저장 API
├── list.php            # 목록 페이지
├── view_detail.php     # 상세정보 조회 API
├── test_api.php        # API 키 테스트 스크립트 (개발용)
├── test_models.php     # Claude 모델 테스트 스크립트 (개발용)
├── dev.md              # 개발 참고자료
└── README.md           # 사용 설명서

🗄️ 데이터베이스

테이블: biz_cert

CREATE TABLE biz_cert (
  id           BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  biz_no       VARCHAR(20)   NOT NULL,      -- 000-00-00000
  company_name VARCHAR(255)  NOT NULL,
  representative VARCHAR(100) NOT NULL,
  open_date    DATE          NULL,
  address      TEXT          NULL,
  type         VARCHAR(255)  NULL,
  item         VARCHAR(255)  NULL,
  issue_date   DATE          NULL,
  raw_text     LONGTEXT      NULL,          -- 원문 텍스트(디버그용)
  created_at   TIMESTAMP     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (id),
  KEY idx_biz_no (biz_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

🤖 듀얼 OCR 모드 (NEW!)

시스템은 두 가지 OCR 방식을 제공하며, 사용자가 토글 버튼으로 선택할 수 있습니다.

OCR 모드 선택

파일 업로드 전, OCR 모드 토글 버튼을 통해 원하는 방식을 선택하세요:

모드	설명	처리 위치	속도	정확도	비용
JS 사용	Tesseract.js 브라우저 OCR	클라이언트	보통 (15-30초)	80-90%	무료
AI API	Claude 3 Haiku Vision API	서버	빠름 (5-10초)	90-95%	유료

JavaScript OCR 모드 (기본)

특징:

✅ 완전 무료
✅ 서버 부하 없음
✅ 오프라인 동작 가능 (언어팩 캐시 후)
✅ 데이터 프라이버시 (서버 전송 없음)
⚠️ 처리 속도가 느림
⚠️ 복잡한 레이아웃에서 정확도 하락

처리 과정:

1. 이미지 전처리 (그레이스케일, 대비, 이진화)
2. Tesseract.js OCR (한글+영어)
3. 정규식 기반 파싱 및 오타 보정
4. 폼 자동입력

AI API 모드 (NEW!) ⭐

특징:

✅ 매우 높은 정확도 (Vision AI)
✅ 빠른 처리 속도
✅ 문맥 이해 및 자동 보정
✅ 복잡한 레이아웃도 정확히 인식
⚠️ API 비용 발생
⚠️ 인터넷 연결 필요

처리 과정:

1. 이미지 전처리 (동일)
2. Tesseract.js OCR (텍스트 추출용)
3. Claude AI API 호출
   - 이미지 분석 (Vision)
   - OCR 텍스트 분석
   - 구조화된 JSON 반환
4. 폼 자동입력

사용 모델:

Claude 3 Haiku (claude-3-haiku-20240307)
가장 빠르고 비용 효율적인 Claude 모델
Vision 기능 지원 (이미지 직접 분석)
OCR 데이터 추출에 최적화

선택 가이드

JavaScript OCR 추천:

💰 비용이 중요한 경우
🔒 데이터 보안이 최우선인 경우
📶 인터넷 연결이 불안정한 경우
📄 간단하고 깨끗한 이미지

AI API 추천:

🎯 정확도가 최우선인 경우
⚡ 빠른 처리 속도가 필요한 경우
📸 저품질 이미지나 복잡한 레이아웃
🏢 대량 처리가 필요한 경우

🚀 사용 방법

1. 새 사업자등록증 등록

ocr/index.php 페이지 접속
OCR 모드 선택 (토글 버튼) ⭐NEW
- 왼쪽 (JS 사용): 브라우저 OCR
- 오른쪽 (AI API): Claude AI 분석
"파일 선택" 버튼 클릭하여 사업자등록증 이미지 또는 PDF 선택
자동으로 OCR 처리가 시작됨
- JS 모드: 15-30초 소요
- AI 모드: 5-10초 소요
인식된 정보가 폼에 자동으로 입력됨 (노란색 배경으로 표시)
- 사업자등록번호
- 상호명
- 대표자명
- 개업일자
- 본점 소재지
- 업태/종목
- 발급일자
자동 입력된 내용 확인 및 필요시 수동 수정
"저장" 버튼 클릭

2. 목록 조회

ocr/list.php 페이지 접속
등록된 사업자등록증 목록 확인
검색창에서 사업자번호, 상호명, 대표자명으로 검색 가능
"보기" 버튼 클릭하여 상세정보 확인

3. 상세정보 보기

목록 페이지에서 "보기" 클릭
모달 팝업으로 전체 정보 표시
OCR 원문 텍스트도 확인 가능

🔧 기술 스택

프론트엔드

PDF.js 4.6.82: PDF를 이미지로 변환
Tesseract.js 5.x: 브라우저 기반 OCR (한글+영어)
Vanilla JavaScript: DOM 조작 및 API 통신
Fetch API: Claude API 비동기 호출 ⭐NEW

백엔드

PHP 7.3+: 서버 로직
PDO: 데이터베이스 연결
MySQL/MariaDB: 데이터 저장
cURL: Claude API HTTP 통신 ⭐NEW

AI/ML

Claude 3 Haiku API: Vision 기반 OCR 및 데이터 추출 ⭐NEW
Anthropic API v1: Claude API 엔드포인트
Vision API: 이미지 직접 분석

📝 주요 기능 설명

OCR 자동 인식 및 자동 입력

🎯 핵심 기능

사업자등록번호, 상호명, 대표자명 등 8개 필드 자동 추출
인식률: 70-90% (이미지 품질에 따라 변동)

🔧 오인식 보정 (ENHANCED!)

OCR 오류를 자동으로 보정하여 인식률 향상:

특수문자 제거 (최우선 처리) ✨NEW:

한글 사이의 방해 특수문자 자동 제거: _, ., -, ~, `, ', "
예시: 대 _ 표 . 자 → 대 표 자 → 대표자

한글 오인식 보정:

수식회사, 수 식 회 사 → 주식회사 (공백 포함) ✨ENHANCED
수식호사, 주식호사 → 주식회사 (호사 오타)
법인면 → 법인명 (면 → 명)
대=자 → 대표자 (= → 표)
대 표 차 → 대표자 (차 → 자)
얼태 → 업태
총 록 → 종목 (총록 → 종목)
총 목 → 종목 (총목 → 종목)
개 업 면 월 일 → 개업명월일 (공백 무시 + 오타 보정)
엘 리 베 이 터 → 엘리베이터
하 장 품 → 부장품
의 장 품 → 의장품 (보이는 물건)

날짜 관련 오인식 보정:

뭘 → 월 (06 뭘 → 06 월) ✨NEW
뭠 → 월
울 → 월
융 → 일
임 → 일
연 → 년
념 → 년

숫자 오인식 보정:

O, o → 0
I, l → 1
Z, z → 2
S → 5
b → 6

🎪 유연한 키워드 매칭 (ENHANCED!)

오타나 공백이 있어도 키워드 근처에서 정보 추출:

예시 1: "법 인 면 ( 단 체 면 ) : 수 식 회 사 미 래 기 업" ✨ENHANCED
→ 특수문자 제거: "법인면 (단체면) : 수 식 회 사 미래기업"
→ 오타 보정: "법인명 (단체명) : 주식회사 미래기업"
→ 상호명 추출 성공: "주식회사미래기업"

예시 2: "대 _ 표 . 자 : 소 현 철" ✨NEW
→ 특수문자 제거: "대 표 자 : 소 현 철"
→ 오타 보정: "대표자 : 소 현 철"
→ "대표자" 키워드 감지 → 한글 이름 패턴 (2-4자) → 공백 제거
→ 추출 성공: "소현철"

예시 3: "업태 제조업 [ 총 록 | 엘 리 베 이 터 의 장 품"
→ 오타 보정: "업태 제조업 [ 종목 | 엘리베이터 의장품"
→ "업태" 키워드 감지 → 업태 추출: "제조업"
→ "종목" 키워드 감지 → 종목 추출: "엘리베이터의장품"

예시 4: "개 업 면 월 일 : 2015 년 06 뭘 02 일"
→ 오타 보정: "개업명월일 : 2015 년 06 월 02 일"
→ "개업" 키워드 감지 → 날짜 추출 성공 → 2015-06-02

📊 다중 패턴 매칭

1단계: 오인식 보정된 텍스트에서 매칭 시도
2단계: 원본 텍스트에서 매칭 시도
3단계: 키워드 근처에서 유연하게 검색
4단계: 한국 이름 패턴 (2-4자) 길이 검증 ✨NEW

🧹 공백 및 텍스트 정리

공백 제거: "미 래 기 업" → "미래기업"
한글 연결: 글자 사이 공백 자동 제거
특수문자 제거: 불필요한 기호 정리
날짜 정규화: "2015 년 06 월 02 일" → "2015-06-02"
한국 이름 패턴 검증 ✨NEW:
- 2-4자 한글 이름 패턴 인식
- 공백이 포함된 이름도 자동 정리 ("소 현 철" → "소현철")
- 4자 초과 시 앞 3자만 추출 (일반적인 한국 이름)

🎨 자동 폼 입력

OCR 완료 후 자동으로 입력 필드에 값 채움
시각적 표시: 자동 입력된 필드는 노란색 배경으로 표시
성공률 표시: 상태 메시지에 추출 성공 개수 표시

🔍 상세 로깅

브라우저 콘솔(F12)에서 확인 가능:

OCR 원문: 실제 인식된 텍스트
오인식 보정 후: 자동 보정된 텍스트
패턴 매칭 과정: 각 필드별 추출 시도 로그
최종 추출 결과: 각 필드 성공/실패 상태
추출 성공률: X/8 필드 (XX%)

사업자번호 검증

10자리 숫자 검증
체크섬 알고리즘으로 유효성 확인
검증 실패시 경고 표시

지원 파일 형식

이미지: JPG, PNG, GIF, BMP 등
PDF: 첫 페이지 자동 추출

⚙️ 설정

권한 설정

레벨 5 이하 사용자만 접근 가능
session.php에서 권한 체크

AI API 설정 (NEW!) ⭐

1. API 키 발급

Claude Console 접속
회원가입 및 로그인
Settings → API Keys 메뉴
Create Key 버튼 클릭
API 키 복사 (예: sk-ant-api03-...)

2. API 키 저장

# API 키 파일 생성
/chandj/www/apikey/claude_api.txt

# 파일 내용 (API 키만 입력, 개행 없이)
sk-ant-api03-jevRUT9wPnqGQs5egKfSf0DTYdnlTL...

중요:

파일 경로: {DOCUMENT_ROOT}/apikey/claude_api.txt
파일 권한: chmod 600 claude_api.txt (읽기 전용)
보안: .gitignore에 추가하여 버전 관리에서 제외

3. API 키 테스트

# 브라우저에서 접속
http://your-domain/ocr/test_api.php

정상 응답 예시:

{
    "file_exists": true,
    "file_path": "/chandj/www/apikey/claude_api.txt",
    "key_length": 108,
    "key_prefix": "sk-ant-api03-jev...",
    "key_valid_format": true
}

4. 사용 가능한 모델 확인

# 브라우저에서 접속
http://your-domain/ocr/test_models.php

정상 응답 예시:

{
    "claude-3-haiku-20240307": {
        "status": 200,
        "success": true,
        "response": "OK"
    }
}

5. API 비용

Claude API는 사용량 기반 과금입니다:

모델	Input	Output	이미지
Claude 3 Haiku	$0.25 / 1M tokens	$1.25 / 1M tokens	$0.40 / 1000 images

예상 비용 (사업자등록증 1건):

이미지: ~$0.0004 (1장)
텍스트: ~$0.0002 (입력+출력)
총 비용: ~$0.0006 (약 0.8원)

무료 크레딧:

신규 가입 시 $5 무료 크레딧 제공
약 8,000건 처리 가능

6. 보안 설정

// claude_api.php 파일에서 자동 처리
// - API 키는 서버에서만 읽음
// - 클라이언트에 노출되지 않음
// - 세션 권한 체크 (레벨 5 이하)

OCR 언어 설정

한글(kor) + 영어(eng) 동시 인식
학습 데이터: https://tessdata.projectnaptha.com/4.0.0

PDF 렌더링 설정

Scale: 3.0 (고해상도 인식)
첫 페이지만 처리 (속도 최적화)

🔍 한글 인식률 향상 방법

자동 적용되는 기능 (이미 구현됨)

본 시스템은 다음 기능들이 자동으로 적용됩니다:

1. 이미지 전처리 파이프라인

원본 이미지
   ↓
그레이스케일 변환 (컬러 제거)
   ↓
대비 증가 (Contrast Enhancement, factor: 1.5)
   ↓
이진화 (Binarization, threshold: 128)
   ↓
OCR 실행

2. 고해상도 렌더링

PDF: 3.0x 스케일로 렌더링 (기본 2.0에서 증가)
이미지: 2.0x 리샘플링으로 확대

3. Tesseract 최적화 설정

tessedit_pageseg_mode: 1 - 자동 페이지 분할
preserve_interword_spaces: 1 - 단어 간 공백 유지
한글(kor) + 영어(eng) 동시 인식

추가 향상 팁 (사용자 제공)

고품질 이미지 사용: 300 DPI 이상 권장
조명 개선: 사업자등록증을 깨끗하고 밝은 곳에서 촬영
수평 정렬: 카메라를 정면에서 수평으로 촬영
그림자 제거: 그림자나 반사가 없도록 촬영
배경 단순화: 깨끗한 흰색/단색 배경 사용

인식률 비교

구분	일반 OCR	전처리 OCR	전처리 + 보정
선명도	보통	높음	높음
대비	원본	1.5배	1.5배
해상도	1x	2-3x	2-3x
오타 보정	❌	❌	✅
유연 매칭	❌	❌	✅
한글 인식률	50-70%	70-85%	80-90%
처리 시간	10초	15초	20초

전처리 효과 예시

원본: 흐릿한 배경, 낮은 대비

미 래 기 업    → 인식 실패 또는 "미  래  기   업"

전처리 후: 명확한 흑백, 높은 대비

미래기업      → 정확히 인식 "미래기업"

오인식 보정 효과 예시 (ENHANCED!)

예시 1: 특수문자 + 오타 보정 (상호명) ✨ENHANCED

OCR 인식: "법 인 면 ( 단 체 면 ) : 수 식 회 사 미 래 기 업"
→ 1단계 (특수문자 제거): "법인면 (단체면) : 수 식 회 사 미래기업"
→ 2단계 (오타 보정 - 공백 포함): "법인명 (단체명) : 주식회사 미래기업"
→ 3단계 (공백 제거): "법인명(단체명):주식회사미래기업"
→ 최종 추출: "주식회사미래기업" ✅

주요 개선점:
- '수 식 회 사' (공백 포함) → '주식회사'로 자동 보정
- '수식호사', '주식호사' 같은 오타도 자동 보정

예시 2: 특수문자 + 오타 보정 (대표자명) ✨NEW

OCR 인식: "대 _ 표 . 자 : 소 현 철"
→ 1단계 (특수문자 제거): "대 표 자 : 소 현 철"
→ 2단계 (오타 보정): "대표자 : 소 현 철"
→ 3단계 (키워드 감지): "대표자" 근처에서 한글 이름 패턴 검색
→ 4단계 (이름 추출): "소 현 철" (공백 포함)
→ 5단계 (공백 제거): "소현철"
→ 6단계 (길이 검증): 3자 (2-4자 범위) ✓
→ 최종 추출: "소현철" ✅

예시 3: 업태/종목 오타 + 공백 처리

OCR 인식: "업태 제조업 [ 총 록 | 엘 리 베 이 터 의 장 품"
→ 보정: "업태 제조업 [ 종목 | 엘리베이터 의장품"
→ 업태 키워드 감지: "업태" 근처에서 값 검색
→ 업태 추출: "제조업" (기호 제거)
→ 종목 키워드 감지: "종목" 근처에서 값 검색
→ 종목 추출: "엘리베이터의장품" (공백 제거 + 기호 제거)
→ 최종 결과: 업태="제조업", 종목="엘리베이터의장품" ✅

예시 4: 날짜 오타 보정

OCR 인식: "개 업 면 월 일 : 2015 년 06 뭘 02 일"
→ 보정: "개업명월일 : 2015 년 06 월 02 일"
→ 키워드 감지: "개업" 근처에서 날짜 패턴 검색
→ 유효성 검증: year=2015, month=6, day=2 ✓
→ 추출: "2015-06-02" ✅

예시 5: 복합 오류 처리

OCR 인식: "사업자드로즈빼세시 등록번호: 722-88-00035"
→ 숫자 패턴 우선 검색
→ 추출: "722-88-00035" ✅

🚀 더 높은 인식률이 필요한 경우

현재 시스템(브라우저 OCR)으로도 85-95%의 인식률을 달성하지만, 더 높은 정확도가 필요한 경우:

1. 서버 OCR 사용 (권장)

브라우저 OCR 대신 서버 기반 OCR 솔루션 사용:

장점:

더 빠른 처리 속도 (GPU 활용)
높은 정확도 (95-99%)
고급 전처리 기능

추천 솔루션:

Tesseract 5.x (서버 설치): 무료, 오픈소스
Google Cloud Vision API: 유료, 매우 정확
Naver Clova OCR: 한글 특화, 유료
Kakao Vision API: 한글 지원, 유료

2. 하이브리드 방식

1차: 브라우저 OCR (빠른 프리뷰)
2차: 서버 OCR (정확한 최종 결과)

3. 전처리 파라미터 조정

index.php에서 전처리 설정 조정:

// 대비 계수 조정 (현재 1.5)
const factor = 2.0; // 더 강한 대비 (단, 너무 높으면 노이즈 증가)

// 이진화 임계값 조정 (현재 128)
const threshold = 140; // 밝은 이미지: 높게, 어두운 이미지: 낮게

// PDF 스케일 조정 (현재 3.0)
const viewport = page.getViewport({ scale: 4.0 }); // 더 고해상도

4. 언어팩 최적화

// 한글만 인식 (영어 제거하면 한글 정확도 소폭 상승)
'kor'  // 대신 'kor+eng'

// 또는 특화된 학습 데이터 사용
langPath: 'https://github.com/tesseract-ocr/tessdata_best/raw/main'

📊 인식률 향상 체크리스트

이미지 전처리 (그레이스케일, 대비, 이진화)
고해상도 렌더링 (PDF 3x, 이미지 2x)
Tesseract 최적화 설정
공백 제거 및 텍스트 정규화
다중 패턴 매칭
고품질 원본 이미지 (사용자 제공)
서버 OCR 도입 (선택사항)

🐛 자동 입력이 안 되는 경우 디버깅

1. 브라우저 콘솔 확인 (F12)

OCR 처리 중 콘솔에 다음 정보가 표시됩니다:

=== OCR 원문 ===
등 록 번 호 : 722-88-00035
법 인 명 ( 단 체 명) : 주식회사 미 래 기 업
대 = 자 : 소 현 철
개 업 연 월 일 : 2015 년 06 월 02 일
...
===============

=== 추출 결과 ===
{
  biz_no: "722-88-00035",
  company_name: "주식회사미래기업",
  representative: "소현철",
  open_date: "2015-06-02",
  ...
}
================

=== 필드 자동입력 시작 ===
biz_no: "722-88-00035" → 입력
company_name: "주식회사미래기업" → 입력
representative: "소현철" → 입력
open_date: "2015-06-02" → 입력
...
총 5/8 필드 입력 완료
=========================

위 예시처럼 공백이 많이 섞인 OCR 원문도 자동으로 처리됩니다.

2. 인식률 확인

OCR 원문에서 실제로 텍스트가 제대로 인식되었는지 확인
인식이 잘못된 경우: 이미지 품질 개선 필요
인식은 되었으나 추출 실패: 정규식 패턴 개선 필요

3. 수동 입력 후 저장

자동 추출이 실패해도 수동으로 입력 가능
OCR 원문을 참고하여 정확한 정보 입력

4. 패턴 개선 (개발자용)

parseBizCert 함수의 정규식 패턴을 실제 사업자등록증 양식에 맞게 조정:

// 예: 상호명 추출 패턴 추가
let companyName = pickMultiple([
    /상\s*호\s*명?[:\s]*([^\n\r]+?)(?=\s*(?:대표자|전화|업태|종목|주소|소재지|$))/ui,
    /상\s*호[:\s]+([^\n\r]+?)(?=\s*(?:대표자|전화|$))/ui,
    // 새로운 패턴 추가
    /회사명[:\s]+([^\n\r]+?)/ui
]);

🛠️ 문제 해결

OCR이 실패하는 경우

이미지 품질 확인 (흐릿하거나 어두운 경우)
브라우저 콘솔에서 에러 메시지 확인
파일 크기 확인 (너무 큰 파일은 로딩 지연)

한글이 인식되지 않는 경우

언어팩 다운로드 대기 (최초 실행시 시간 소요)
네트워크 연결 확인
CDN 접근 가능 여부 확인

저장이 안 되는 경우

필수 항목 입력 확인 (사업자번호, 상호명, 대표자명)
데이터베이스 연결 확인
브라우저 콘솔에서 API 응답 확인

콘솔 경고 메시지 (정상 동작)

다음과 같은 경고 메시지들이 나타날 수 있으나, 이는 정상적인 동작입니다:

Warning: Parameter not found: segsearch_max_char_wh_ratio
Warning: Parameter not found: allow_blob_division
Warning: Parameter not found: assume_fixed_pitch_char_segment

Tesseract.js 라이브러리 내부에서 발생하는 경고
OCR 기능 동작에는 영향 없음
무시해도 안전함

📊 성능 최적화

브라우저 OCR의 특징

장점: 서버 부하 없음, 별도 설치 불필요
단점: 처리 속도가 서버 OCR보다 느림

최적화 전략

첫 페이지만 처리 (다중 페이지는 순차 처리)
언어팩 CDN 캐싱 활용
이미지 크기 적절히 조정

🔐 보안 고려사항

권한 체크: 모든 페이지에서 사용자 레벨 확인
SQL Injection 방지: PDO prepared statements 사용
XSS 방지: htmlspecialchars() 사용
민감정보 처리: 필요시 주민번호 마스킹 추가

🚀 향후 개선 사항

AI API 통합 (Claude Vision) ⭐COMPLETED
듀얼 OCR 모드 토글 ⭐COMPLETED
다중 페이지 PDF 지원
이미지 회전 및 보정 기능
수정/삭제 기능 추가
엑셀 내보내기 기능
파일 첨부 기능 (원본 이미지 보관)
중복 사업자번호 체크
통계 및 대시보드
AI 모델 자동 fallback (Haiku → Sonnet → Opus)
OCR 결과 신뢰도 점수 표시

📞 문의

버그 리포트 및 기능 제안은 개발팀에 문의
상세 개발 문서: dev.md 참조

개발 완료일: 2025-10-29 최신 업데이트: AI API 통합 (Claude 3 Haiku) 호환성: PHP 7.3+, MySQL 5.7+ 라이선스: 내부 사용

22 KiB Raw Blame History