DocuFlow - 구매 거래명세서 및 영수증 관리 시스템 운영 매뉴얼

1

시스템 개요 및 워크플로우

시스템 접속 주소

http://fileserver.countec-pnf.com:8080/receipts

데이터 저장소

DB: server_db.json (receipts) / 파일: /storage/receipts/

+ Paperless-ngx 이중 보관 (문서 ID paperlessId로 연결, §8 참조)

자동 변환 파일명 표준 규칙

{YYMMDD}_{업체명}.pdf (예: 260918_국민종합볼트.pdf)

원장 조회 및 UI 최적화

기본 10개씩 페이징 + 상단 Sticky 헤더 + 콤팩트 관리 툴바

전체 처리 파이프라인 흐름도

[현장 종이 명세서 수령] ──► [복합기 평판 스캔 (300DPI 권장 PDF 생성)]
                                         │
                                         ▼
[다중 파일 드래그앤드롭] ──► [1차 검증: SHA-256 바이너리 해시 계산]
                                         │
                                         ├─ 중복 파일 일치 시 ──► 즉시 업로드 차단 ("이미 등록된 파일")
                                         ▼ 신규 파일
[텍스트 레이어 검사 & 서버 OCR]
   ├─ 전자 생성 PDF : PDF.js 텍스트 레이어 즉시 추출 (0.1초)
   └─ 종이 스캔본   : 300DPI 고해상도 렌더링 ➔ 서버 Tesseract OCR 판독 (/api/ocr)
                                         │
                                         ▼
[다중 파일 순차 검수 모달 큐 (Batch Queue)]
   ├─ 상단 네비게이터 : [이전 파일] [ 6 / 11 ] [다음 파일] 자유 이동 지원
   ├─ 좌측 : 원본 스캔 PDF 미리보기 뷰어 (줌 / 다운로드 / 새 탭 열기)
   ├─ 우측 : 추출 텍스트 원문 확인(자유 드래그 복사) & 5대 항목 수동 보정
   └─ 안전장치 : 8초 비동기 타임아웃 방어 및 [건너뛰고 다음 파일] 버튼 제공
                                         │
                                         ▼
[사내 서버 영구 보관 & 원장 반영]
   ├─ 원장 테이블 : 기본 10건 단위 페이징 (10/20/50건 선택) & 상단 헤더 고정
   ├─ 조작 바 : 가로 스크롤 없는 컴팩트 툴바 [다운로드] [수정] [삭제]
   └─ 삭제 안전장치 : 실수 방지 커스텀 2단계 확인 모달 [영구 삭제] 승인
                                         │
                                         ▼
[Paperless-ngx 백그라운드 자동 연동 (§8)]
   ├─ 등록 완료 후 서버가 Paperless로 파일·업체·날짜·합계를 자동 업로드
   ├─ Paperless 자체 OCR(한+영)로 본문 전문 검색 인덱스 생성
   └─ 반환된 문서 ID를 원장에 paperlessId로 기록해 양쪽 연결

2

현장 스캔 및 다중 파일 일괄 업로드

1 복합기 스캔 권장 설정

해상도: 300 DPI 권장 (200 DPI 이하 시 미세 글자 오인식 발생)
컬러 모드: 흑백(Grayscale) 또는 컬러 모두 지원
파일 포맷: PDF 형식 필수
파일명: 복합기 임의 파일명(예: scan_001.pdf) 그대로 올려도 무방합니다. (시스템이 YYMMDD_업체명.pdf로 표준 리네이밍)

2 다중 파일(Batch) 드래그앤드롭

스캔된 PDF 파일을 점선 박스(Drop Zone)에 여러 개 한꺼번에 끌어다 놓습니다.
10장, 20장 동시 업로드 지원: 모든 파일이 내부 검수 큐(Queue)에 담겨 순차 처리됩니다.
[PDF 파일 선택 (다중 가능)] 버튼으로 파일 탐색기에서 다중 선택(Ctrl+클릭)해도 동일합니다.

3 진행 게이지 바 확인

업로드 즉시 [1 / 11] 파일 검증 및 OCR 판독 중... 프로그레스 바가 표시됩니다.
판독이 완료되면 첫 번째 영수증부터 검수 모달이 자동으로 열리며 상단에 [ 1 / 11 ] 배지가 나타납니다.

3

서버 Tesseract OCR 분석 원리 및 상태 확인

DocuFlow는 클라이언트(브라우저)와 리눅스 서버 백엔드가 결합된 하이브리드 파싱 엔진을 채택하고 있습니다.

Case 1. 전자 생성 PDF (Digital PDF)

홈택스 전자세금계산서나 거래처가 이메일로 송부한 전자 PDF는 브라우저의 PDF.js 텍스트 레이어를 0.1초 만에 즉시 추출합니다.

Case 2. 복합기 스캔본 (Image PDF)

글자 레이어가 없는 스캔본은 브라우저가 첫 페이지를 300DPI 캔버스로 고해상도 변환하여 서버의 /api/ocr로 전송하며, 우분투 서버의 Tesseract OCR (kor+eng) 엔진이 글자 모양을 읽어냅니다.

검수창 표시 상태	의미 및 엔진 동작	사용자 권장 조치
서버 Tesseract OCR 판독 성공	사내 우분투 서버의 Tesseract 엔진이 스캔본 이미지 글자를 정상 판독함	자동 채워진 값 눈으로 확인 후 저장
전자 PDF 텍스트 레이어 추출	디지털 원본 PDF의 텍스트를 100% 무손실로 직접 추출함	확인 후 [검수 완료] 클릭
우분투 서버에 Tesseract 설치 필요	서버에 Tesseract 패키지가 미설치된 상태 (안내 명령어 자동 출력)	서버에 패키지 1회 설치 필요
스캔 이미지 본 (수동 확인 모드)	스캔 화질이 너무 흐리거나 기울어져 글자 인식이 불가한 상태	좌측 원본을 보고 우측에 직접 입력

4

검수 모달 조작 가이드 & 무한 로딩 방어 체계 (v2.4 신규)

1 다중 파일 일괄 큐 네비게이션 ([◀ 이전 파일] [다음 파일 ▶])

여러 장의 PDF를 올렸을 때 특정 영수증에 얽매이지 않고 상단 네비게이션 버튼을 통해 원하는 영수증으로 앞뒤 자유롭게 이동하며 검수할 수 있습니다. 현재 페이지 번호와 전체 개수가 6 / 11 형태로 명확히 표시됩니다.

8초 자동 타임아웃 무한 로딩 방어

스캔 PDF의 용량이 크거나 서버 네트워크가 일시적으로 지연되어 "서버 저장 중..." 상태에서 멈추는 문제를 원천 차단했습니다. 요청 후 8초 동안 응답이 없으면 자동으로 요청을 취소하고 오류 토스트를 띄우며 저장 버튼을 즉시 정상화합니다.

[건너뛰고 다음 파일] 비상 탈출 버튼

특정 영수증의 입력 정보를 나중에 확인하고 싶거나 일시적 오류가 발생한 경우, [건너뛰고 다음 파일] 버튼을 누르면 해당 파일을 큐에 남겨둔 채 다음 영수증 검수를 막힘없이 진행할 수 있습니다.

2 추출 텍스트 원문 자유 드래그 복사 기능

우측 상단 [추출 텍스트 원문] 버튼을 클릭하면 서버 OCR이 판독한 전체 텍스트 박스가 열립니다. 마우스로 특정 단어나 숫자를 자유롭게 블록 지정(드래그)하여 복사(Ctrl+C)할 수 있으며, [전체 복사] 버튼으로 전문을 한 번에 가져올 수도 있습니다.

3 거래처 자동완성 & 다중 품목 실시간 자동 계산

사내 거래처 드롭다운에서 상호명을 선택하면 즉시 표준 파일명에 반영됩니다. 또한 [+ 품목 추가]를 통해 여러 품목의 수량과 단가를 입력하면 품목 금액 및 하단 최종 합계 금액이 실시간으로 계산됩니다.

5

중복 업로드 차단 3중 방어 체계

1차. SHA-256 바이너리 해시

업로드 파일의 고유 디지털 지문을 계산하여 이미 DB에 존재하는 파일이면 OCR을 거치지 않고 즉시 차단합니다. (상단 '0건 방어' 통계 실시간 누적)

2차. 비즈니스 복합 키 검사

종이를 재스캔하여 파일 해시가 달라졌더라도, [거래일자 + 거래처 상호 + 합계금액]이 완전 일치하면 중복 의심 건으로 분류합니다.

3차. 사용자 대조 검수 (Human)

검수 모달에서 원본 PDF를 보며 실제 같은 날 2회 구매한 정상 별건인지, 실수 재등록인지 최종 승인/취소 결정을 내립니다.

6

원장 뷰어 고도화 (페이징·헤더고정·삭제확인 모달)

1) 10개 / 20개 / 50개 페이지네이션 (기본: 10개)

수백 건의 영수증이 한 화면에 길게 나열되어 스크롤이 무한정 늘어나는 불편을 해소했습니다. 기본 10개 단위로 깔끔하게 분할 표시되며, 하단 네비게이터(« ‹ 1 2 3 › »)를 통해 빠르게 이동할 수 있습니다.

2) 상단 Sticky Header 고정

테이블 스크롤 박스 내부에서 마우스 휠을 아래로 내려도 표의 최상단 헤더(No, 일자, 업체명, 품목명, 단가, 영수증 합계, 관리)가 상단에 항시 고정되어 데이터 열을 혼동 없이 식별할 수 있습니다.

3) 콤팩트 조작 툴바 및 불필요 열(변환 파일명) 제거

공간만 차지하고 글자가 세로로 깨지던 '변환 파일명' 열을 제거하고, 업체명과 품목명 칸을 시원하게 넓혔습니다. 우측의 [PDF 다운로드], [수정], [삭제] 버튼은 콤팩트 일체형 툴바로 정리되어 모니터 화면 밖으로 벗어나지 않으며 가로 스크롤 없이 즉시 클릭할 수 있습니다.

4) 영수증 문서 삭제 2단계 확인 팝업 (실수 방지)

삭제 버튼을 실수로 눌렀을 때 데이터가 즉시 지워지지 않도록 커스텀 삭제 확인 모달이 팝업됩니다. 삭제 대상 파일명(YYMMDD_업체명.pdf)을 확인한 뒤 [영구 삭제] 버튼을 최종 승인해야만 서버 디스크와 원장 DB에서 안전하게 영구 제거됩니다.

엑셀(.xlsx) 원장 일괄 다운로드 회계팀 및 자재팀 제출용으로 품목별 수량, 단가, 합계가 완벽히 정리된 엑셀 파일을 즉시 다운로드합니다.

우측 상단 초록 버튼

7

서버 환경설정 및 유지보수 (FAQ)

1) 우분투 서버 Tesseract 한국어 OCR 엔진 설치 (최초 1회)

서버 터미널(SSH)에서 아래 명령어를 실행하면 한국어·영어 OCR 패키지가 설치되어 스캔 이미지 인식이 활성화됩니다:

# 1. Tesseract OCR 및 한국어 언어팩 설치
sudo apt update && sudo apt install -y tesseract-ocr tesseract-ocr-kor

# 2. 설치 및 지원 언어 확인 (kor, eng 표시 확인)
tesseract --list-langs

# 3. DocuFlow 백엔드 프로세스 재기동
pm2 restart docuflow

2) PDF 저장소 경로 및 정기 백업

업로드된 원본 PDF 파일은 아래 물리 디렉터리에 타임스탬프와 함께 안전하게 저장됩니다:

# 영수증 PDF 파일 물리 저장소
/var/www/docuflow/storage/receipts/

# 영수증 메타데이터 DB 파일
/var/www/docuflow/server_db.json (내부 receipts 배열)

# 수동 백업 명령어 예시
cp -r /var/www/docuflow/storage/receipts /var/backup/docuflow/receipts_$(date +%Y%m%d)

8

Paperless-ngx 문서관리 연동 (v2.5 신규)

개요 — 화면은 그대로, 보관·검색은 Paperless가 담당

2026년 10월 23일부터 영수증 관리는 오픈소스 문서관리 시스템 Paperless-ngx와 연동됩니다. 사용자가 보는 DocuFlow 화면과 등록·검수·다운로드 절차는 기존과 동일하며, Paperless는 화면 뒤에서 문서 이중 보관, 자체 OCR, 전문(全文) 검색, 거래처별 분류를 담당합니다. Paperless는 DocuFlow와 같은 사내 서버에 설치되어 있고 외부 인터넷에는 공개되지 않습니다(사무실 내부망·Tailscale 전용).

1) 등록 시 자동 연동 흐름

[DocuFlow 영수증 등록 완료]
   ├─ 1차 저장 : 기존과 동일하게 로컬 파일(/storage/receipts) + 원장 DB에 저장
   ▼ 백그라운드 자동 업로드 (사용자 대기 없음)
[Paperless-ngx로 전송] 파일 + 제목({날짜}_{업체명}) + 문서 날짜 + 거래처 + 태그(영수증) + 합계금액
   ▼
[Paperless 처리] 자체 OCR(한국어+영어) 수행 → 본문 텍스트 추출 → 문서 보관·분류
   ▼
[연결 완료] Paperless 문서 ID가 원장 레코드의 paperlessId에 기록되어 양쪽이 연결됨

업로드가 일시적으로 실패해도 DocuFlow 등록 자체는 정상 유지됩니다. Paperless에 없는 거래처명은 업로드 시 자동 생성되어 연결됩니다.

2) Paperless로 전달되는 정보

업체명 → Paperless 거래처(Correspondent)

영수증 날짜 → Paperless 문서 생성일(created)

합계 금액 → 커스텀 필드 ‘합계금액’ (숫자)

태그 → ‘영수증’ 태그 자동 부여

품목 상세내역(품명·수량·단가)는 줄 단위 데이터이므로 Paperless로 보내지 않고 DocuFlow 원장에만 유지됩니다. Paperless는 문서 단위 보관·검색에 특화되어 있습니다.

3) 다운로드 동작

원장에서 다운로드를 누르면 Paperless 문서를 우선 가져와 내려줍니다. Paperless가 응답하지 않을 경우 자동으로 로컬 보관 파일로 대체(폴백)하므로, Paperless 점검 중에도 다운로드는 중단되지 않습니다.

4) 수정·삭제 동기화

영수증을 수정해도 기존 Paperless 연결(paperlessId)이 유지되어 중복 문서가 생기지 않습니다. 삭제하면 확인 모달 승인 후 DocuFlow 원장·로컬 파일과 Paperless 문서가 함께 삭제됩니다.

5) 운영 정보 및 현재 상태

구축: 2026-10-23, Paperless-ngx v3.3.4 (DocuFlow와 동일 서버, ~/paperless-office, 내부 포트 8000)
기존 자료 이전: 연동 이전에 등록된 영수증 397건 전량 이전 완료 (실패 0건, 원장 paperlessId 397/397 · Paperless 문서 397건 일치)
OCR: Paperless 자체 OCR이 한국어+영어로 동작하며, Paperless 화면에서 영수증 본문 단어로 전문 검색이 가능합니다.
인증: DocuFlow ↔ Paperless 통신은 서버 간 토큰 방식으로, 사용자 로그인과 무관하게 동작합니다. DocuFlow 로그인 보안 적용 이후에도 연동은 그대로 유지됩니다.
장애 시: Paperless가 중단되어도 영수증 등록·조회·다운로드(로컬 폴백)는 정상 동작합니다. 단, 그 사이 등록된 건은 Paperless 복구 후 연결 상태를 관리자가 확인해야 합니다.

구매 거래명세서 및 영수증 전산 관리 시스템 운영 매뉴얼