문서 검수 현황 관제 및 백오피스
검수 MVP 이후 확장 범위로, 검수 현황 관제 보드, 사용자·권한 관리, OCR 엔진 연동 설정, 감사 로그와 알림 규칙을 통합한 백오피스 프로젝트입니다.
프로젝트 개요
검수 MVP 이후 확장 범위로, 검수 현황 관제 보드, 사용자·권한 관리, OCR 엔진 연동 설정, 감사 로그와 알림 규칙을 통합한 백오피스 프로젝트입니다. 대량 요청의 비동기 큐 상태와 실패 재실행, 검수 이력 통계를 한 화면 체계로 구현합니다.
작업 범위
- 검수 현황 관제: 상단 상태바, 시간대별 검수 흐름 타임라인, 우선 대응 큐로 구성한 관제 화면에서 대기·실패·불일치 급증 건을 확인하고 재실행합니다
- 사용자·권한 관리: 직원 계정을 등록하고 일반 사용자와 관리자 역할을 부여하며 부서별 접근 범위를 설정합니다. 검수 이력은 사용자별로 조회하고 내보냅니다
- OCR 엔진 연동 설정: 상용 OCR/Vision API 공급자를 등록하고 API 키, 우선 순위, 대체 호출 순서, 웹훅 주소를 설정합니다
- 감사 로그·알림 규칙: 모든 검수·룰·설정 변경을 감사 로그로 기록하고 검수 완료·실패·이상 징후에 대한 이메일 알림 규칙을 정의합니다
주요 업무
- 검수 현황 관제 화면: 큐 상태와 검수 이력 집계를 한 화면에 모읍니다
- 사용자·권한 관리 화면: 계정 목록, 역할 편집, 이력 조회 및 CSV 내보내기를 포함합니다
- OCR 엔진 연동 설정 화면: 공급자별 상태 점검과 대체 호출 규칙을 관리하는 설정 화면입니다
- 감사 로그·알림 규칙 화면: 로그 검색과 알림 규칙 편집 화면을 포함합니다



프로젝트 핵심 과제
대량 검수 요청이 몰릴 때 큐 적체 구간을 구분해 보여주는 관제 집계 모델과 갱신 주기 설계
공급자 대체 호출 시 동일 문서의 중복 호출과 결과 충돌을 막는 멱등 키 설계
API 키와 웹훅 주소 같은 설정값을 안전하게 저장하고 화면에는 마스킹해 노출하는 구조 설계
부서별 접근 범위와 이력 내보내기 권한이 어긋나지 않
서버 측 단일 검증 지점 설계 필요
핵심 기능 상세
검수 현황 관제
상단 상태바, 시간대별 검수 흐름 타임라인, 우선 대응 큐로 구성한 관제 화면에서 대기·실패·불일치 급증 건을 확인하고 재실행합니다. 큐 상태와 검수 이력 집계를 한 화면에 모읍니다.
- Bull 큐 상태 조회 API와 SSE로 대기·처리·실패 건수를 상태바에 실시간 반영
- PostgreSQL Materialized View로 시간대별·문서 유형별 검수 집계를 구성하고 증분 갱신
- 실패 건 선택 재실행과 일괄 재실행을 멱등 키로 보호
큐 상태와 검수 결과 분포를 하나의 관제 화면으로 묶어 실패 건을 우선순위 큐에서 바로 재실행하는 흐름을 구현합니다.


사용자·권한 관리
직원 계정을 등록하고 일반 사용자와 관리자 역할을 부여하며 부서별 접근 범위를 설정합니다. 검수 이력은 사용자별로 조회하고 내보냅니다. 계정 목록, 역할 편집, 이력 조회 및 CSV 내보내기를 포함합니다.
- JWT 액세스·리프레시 토큰 구조와 역할 기반 접근 제어 미들웨어 적용
- 라우트·API·화면 요소 3중 권한 검사 구성
- 검수 이력 서버 사이드 필터링과 CSV 스트리밍 내보내기 구현
역할과 부서 범위를 서버에서 일관되게 검증하는 권한 체계를 설계하고 이력 내보내기까지 같은 권한 규칙으로 보호합니다.


OCR 엔진 연동 설정
상용 OCR/Vision API 공급자를 등록하고 API 키, 우선 순위, 대체 호출 순서, 웹훅 주소를 설정합니다. 공급자별 상태 점검과 대체 호출 규칙을 관리하는 설정 화면입니다.
- 공급자 어댑터 레지스트리와 우선순위 기반 대체 호출 체인 구현
- API 키는 서버에서 암호화 저장하고 화면에는 마스킹 값만 표시
- 공급자 상태 점검 호출과 응답 지연 기록 화면 구성
공급자를 설정 화면에서 교체하고 장애 시 다음 공급자로 넘기는 구조를 설계해 특정 서비스 종속을 줄입니다.


감사 로그·알림 규칙
모든 검수·룰·설정 변경을 감사 로그로 기록하고 검수 완료·실패·이상 징후에 대한 이메일 알림 규칙을 정의합니다. 로그 검색과 알림 규칙 편집 화면을 포함합니다.
- 변경 전후 값을 JSON diff로 저장하는 추가 전용 감사 로그 테이블 설계
- 알림 규칙(조건·수신자·채널)을 룰 엔진 평가기와 공유하는 구조로 구현
- Bull 큐 기반 이메일 발송과 실패 재시도, 발송 이력 저장
감사 로그와 알림 규칙을 룰 엔진 평가기와 같은 조건 모델로 구성해 설정 화면을 일관되게 유지합니다.


프로젝트 진행 단계
백오피스 정보 구조 및 권한 모델 설계 · 2026.10
역할·부서 범위 모델, 감사 로그 테이블, 집계용 Materialized View 구조 설계
큐 상태 API 및 집계 파이프라인 구현 · 2026.10
Bull 큐 상태 조회, Redis 기반 상태 캐시, 시간대별 검수 집계 API 구현
관제 화면 및 재실행 흐름 개발 · 2026.10
상태바·타임라인·우선 대응 큐 화면과 실패 건 선택·일괄 재실행 구현
연동 설정 및 알림 규칙 개발 · 2026.10
OCR 공급자 레지스트리, 대체 호출 체인, 알림 규칙 편집 화면 구현
개발 결과
기술적 주안점
- 큐 상태와 검수 결과 분포를 하나의 관제 화면으로 묶어 실패 건을 우선순위 큐에서 바로 재실행하는 흐름을 구현합니다
- 역할과 부서 범위를 서버에서 일관되게 검증하는 권한 체계를 설계하고 이력 내보내기까지 같은 권한 규칙으로 보호합니다
- 공급자를 설정 화면에서 교체하고 장애 시 다음 공급자로 넘기는 구조를 설계해 특정 서비스 종속을 줄입니다