Skip to content

hbjs97/billg

BranchesTags

Repository files navigation

📊 BillG - Excel 영수증 스캐너 추가 기능

BillG Logo

영수증을 한 번의 클릭으로 Excel 데이터로 변환하세요

License: MIT Node Version React Version TypeScript

🎯 개요

BillG는 OpenAI GPT-4o의 멀티모달 처리 기능을 활용하여 영수증 이미지에서 데이터를 자동으로 추출하고 Excel 스프레드시트에 직접 삽입하는 Microsoft Excel 추가 기능입니다. 전통적인 OCR보다 뛰어난 정확도로 경비 추적, 회계 처리, 데이터 입력 자동화를 지원합니다.

💡 프로젝트 배경

왜 BillG를 만들었나요?

Excel로 영수증을 하나하나 수동으로 입력하는 반복적이고 지루한 작업을 보며, "이걸 자동화할 수 없을까?"라는 단순한 질문에서 시작된 사이드 프로젝트입니다.

기술적 여정

오픈소스 OCR의 한계

  • 여러 오픈소스 OCR 모델을 테스트했지만 한국어 인식률이 낮음
  • 영수증의 구분선, 테이블 구조 처리에 취약
  • 폰트 변형이나 기울어진 텍스트 인식 실패

상용 API의 높은 비용

  • 네이버 클로바 OCR, 업스테이지 Document AI 등 검토
  • 높은 정확도를 제공하지만 개인 프로젝트에는 비용 부담이 과도함
  • 소규모 사용에도 최소 비용이 발생

GPT-4o: 실용적인 해결책

  • 멀티모달 AI의 강력한 이미지 이해 능력 활용
  • 한국어 영수증도 높은 정확도로 처리
  • 구조화된 데이터 추출이 가능
  • Temperature 0 설정에서도 간혹 일관성 문제가 있지만, 실용적 수준의 정확도 달성

Excel 애드온으로 구현한 이유

  • 사용자가 익숙한 Excel 환경에서 직접 작동
  • 별도 프로그램 설치 없이 간편하게 사용
  • 기존 업무 플로우를 그대로 유지하면서 자동화 혜택

🎬 시연 영상

demo.mp4

주요 시연 내용:

  • Excel에서 열 머리글 선택
  • 영수증 이미지 업로드 (드래그 앤 드롭)
  • AI 기반 데이터 추출 및 자동 입력
  • 다중 영수증 일괄 처리

✨ 주요 기능

  • 🤖 GPT-4o AI - 최신 멀티모달 LLM으로 높은 정확도의 텍스트 추출
  • 📸 스마트 영수증 스캔 - 여러 영수증 이미지를 업로드하고 자동으로 데이터 추출
  • 📊 Excel 직접 연동 - 선택한 Excel 테이블로 데이터가 바로 입력
  • 🌏 한국어 지원 - 완벽한 한국어 UI 제공
  • 🎨 모던 UI - Fluent UI로 Office와 완벽하게 통합
  • 🔒 보안 처리 - HTTPS 암호화 및 파일 검증
  • ⚡ 일괄 처리 - 최대 50개의 영수증을 한 번에 처리

🔗 관련 프로젝트

BillG Server

영수증 처리를 위한 백엔드 API 서버입니다.

  • 저장소: https://github.com/hbjs97/billg-server
  • 기술 스택: FastAPI, Python 3.12, OpenAI GPT-4o API
  • 주요 기능:
    • 멀티모달 AI 기반 영수증 데이터 추출
    • 이미지 전처리 및 최적화
    • IP 기반 요청 제한 (60초당 10개 요청)
    • 비동기 처리 및 배치 처리 지원

자세한 설정 및 사용법은 BillG Server 문서를 참조하세요.

🚀 빠른 시작

사전 요구사항

  • Node.js 20.11 이상
  • npm 9.0 이상
  • Microsoft Excel 2016 이상 (데스크톱 또는 온라인)
  • SSL 인증서 (로컬 개발용)

설치

  1. 저장소 복제

    git clone https://github.com/hbjs97/billg.git
cd billg

  2. 의존성 설치

    npm install

  3. 환경 변수 설정

    # 루트 디렉토리에 .env 파일 생성
echo "API_ORIGIN=https://your-billg-server.com" > .env

  4. 개발 서버 시작

    npm run dev-server

    추가 기능은 https://localhost:3000에서 사용할 수 있습니다

📖 사용자 가이드

Excel에서 추가 기능 로드하기

방법 1: 개발용 사이드로드

  1. 개발 서버 시작

    npm run dev-server

  2. 추가 기능 사이드로드

    npm start

    Excel이 자동으로 열리고 추가 기능이 로드됩니다

방법 2: 수동 설치

  1. Excel 열기
  2. 삽입 → 추가 기능 → 내 추가 기능 이동
  3. 내 추가 기능 업로드 클릭
  4. 프로젝트 루트에서 manifest.xml 선택
  5. 업로드 클릭

추가 기능 사용하기

  1. Excel 테이블 준비

    • 추출할 데이터에 대한 열 머리글 생성
    • 예시: 날짜 | 상점명 | 금액 | 세금 | 총액
    • 클릭 및 드래그로 머리글 행 선택

  2. 영수증 이미지 업로드

    • 업로드 영역 클릭 또는 이미지 드래그 앤 드롭
    • 지원 형식: PNG, JPG, JPEG
    • 최대 파일 크기: 이미지당 20MB
    • 최대 파일 수: 한 번에 50개

  3. 스캔 및 추출

    • 스캔 버튼 클릭
    • 처리 대기 (보통 5-30초)
    • 데이터가 자동으로 머리글 아래에 표시됨

  4. 검토 및 편집

    • 추출된 데이터의 정확성 확인
    • Excel에서 직접 셀 편집 가능
    • 프로세스를 반복하여 더 많은 영수증 추가

🛠️ 개발

사용 가능한 스크립트

명령어 설명
npm run dev-server 핫 리로드가 있는 개발 서버 시작
npm run build 프로덕션 빌드 생성
npm run build:dev 개발 빌드 생성
npm run lint ESLint 검사 실행
npm run lint:fix 린팅 문제 자동 수정
npm run prettier Prettier로 코드 포맷팅
npm run validate manifest.xml 검증
npm start Office 디버깅 세션 시작
npm stop Office 디버깅 세션 중지

프로젝트 구조

billg/
├── src/
│   ├── commands/          # Office 추가 기능 명령 핸들러
│   └── taskpane/
│       ├── components/    # React 컴포넌트
│       │   ├── App.tsx           # 메인 애플리케이션
│       │   ├── BillScanner.tsx   # 핵심 스캔 로직
│       │   ├── FileUpload.tsx    # 파일 처리
│       │   ├── Header.tsx        # 앱 헤더
│       │   └── InstructionList.tsx # 사용자 안내
│       └── index.tsx      # React 진입점
├── assets/               # 아이콘 및 이미지
├── manifest.xml         # 추가 기능 구성
├── webpack.config.js    # 빌드 구성
├── Dockerfile          # 컨테이너 설정
└── nginx.conf         # 웹 서버 구성

ngrok으로 테스트하기

다른 기기에서 테스트하거나 다른 사람과 공유하려면:

  1. ngrok 설치

    npm install -g ngrok
# 또는 https://ngrok.com에서 다운로드

  2. 로컬 서버 시작

    npm run dev-server

  3. 공개 터널 생성

    ngrok http https://localhost:3000

  4. manifest.xml 업데이트

    • 모든 https://localhost:3000을 ngrok URL로 교체
    • 예시: https://abc123.ngrok.io

  5. Excel에서 추가 기능 다시 로드

🔧 구성

환경 변수

변수 설명 기본값 필수
API_ORIGIN BillG Server API 엔드포인트 URL - 예
NODE_ENV 환경 모드 development 아니오

Manifest 구성

manifest.xml의 주요 설정:

<!-- 프로덕션용으로 이 URL들을 업데이트 -->
<SourceLocation DefaultValue="https://your-domain.com/index.html"/>
<IconUrl DefaultValue="https://your-domain.com/assets/icon-32.png"/>
<HighResolutionIconUrl DefaultValue="https://your-domain.com/assets/icon-64.png"/>

API 요구사항 (BillG Server)

GPT-4o 기반 영수증 처리 API:

엔드포인트: POST /scan

  • Content-Type: multipart/form-data
  • 요청 제한: IP당 60초당 10개 요청
  • 이미지 처리: 자동 크기 조정 및 전처리

매개변수:

매개변수 타입 필수 설명
files File[] 예 영수증 이미지 (JPEG, PNG, 최대 20MB)
columns String 예 쉼표로 구분된 추출 필드

지원되는 컬럼 타입:

  • 날짜/시간: date, time, datetime, purchase_date
  • 금액: total_amount, subtotal, tax, discount, 금액, 세금, 총액
  • 텍스트: vendor_name, store_address, receipt_number, 상점명, 주소
  • 항목 목록: items, products, 상품목록

응답 형식:

{
  "results": [
    {
      "날짜": "2024-01-15",
      "상점명": "커피숍",
      "금액": "4500",
      "세금": "450",
      "총액": "4950",
      "상품목록": ["아메리카노", "크로와상"]
    }
  ]
}

오류 응답:

상태 코드 설명
400 잘못된 요청 - 유효하지 않은 입력
429 너무 많은 요청 - 요청 제한 초과
500 내부 서버 오류 

---

## 🐛 문제 해결

### 일반적인 문제

#### 추가 기능이 로드되지 않음

- **HTTPS 인증서 확인**: 유효한 SSL 인증서 확인
- **manifest URL 확인**: 모든 URL이 HTTPS여야 함
- **Office 캐시 지우기**:

  ```bash
  # Windows
  %LOCALAPPDATA%\Microsoft\Office\16.0\Wef\

  # Mac
  ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef

스캔 실패

  • API 연결 확인: API_ORIGIN이 올바른지 확인
  • 이미지 형식 검증: PNG, JPG, JPEG만 지원
  • 파일 크기 확인: 파일당 최대 20MB
  • 콘솔 로그 검토: Excel에서 F12를 눌러 개발자 도구 확인

데이터가 삽입되지 않음

  • 단일 행 선택: 하나의 머리글 행만 선택해야 함
  • 권한 확인: Excel에 편집 권한이 있어야 함
  • 열 머리글 확인: 머리글이 비어있으면 안 됨

디버그 모드

상세 로깅 활성화:

// src/taskpane/index.tsx에서
if (process.env.NODE_ENV === "development") {
  console.log("디버그 모드 활성화");
  // 추가 로깅
}

📝 라이선스

이 프로젝트는 MIT 라이선스 하에 있습니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

📞 지원

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages