고객별 문서를 분리해 처리하는 AI 플랫폼 만들기

핵심 요약

1. 고객사 업무 프로그램에서 문서를 보내고 진행 상황과 분석 결과를 받는 API를 만듭니다. 2. FastAPI로 파일을 받고, BullMQ의 중복방지 기능과 PostgreSQL RLS를 연결합니다. 3. 고객별 API 개발에서는 접수번호, 결과 항목, 재요청 처리와 접근 권한을 직접 구현합니다.

문서 분석 AI 플랫폼을 고객사에 제공하려면 기존 업무 화면에서 결과를 받아 활용할 수 있어야 합니다. API는 프로그램끼리 요청과 결과를 주고받는 연결 통로입니다. 여기서는 거래명세서를 고객사 입고 업무에 연결하는 상품을 만들 때 필요한 기능과 검수 기준을 설명합니다.

FastAPI로 파일을 받고 접수번호 발급하기

고객사 프로그램은 거래명세서 파일과 문서 종류, 고객사가 부여한 요청번호를 보냅니다. FastAPI (https://fastapi.tiangolo.com/tutorial/request-files/)의 UploadFile은 업로드 파일을 받는 기능을 제공합니다. 업무에 필요한 파일 검사와 권한 확인, 보관 규칙은 별도로 개발합니다.

먼저 고객사별 허용 파일 형식과 크기를 확인하고, 필수 입력값이 빠진 요청에는 수정할 항목을 알려줍니다. 접수가 가능한 파일은 고객사와 요청번호를 연결해 저장한 뒤 고유한 접수번호를 돌려줍니다. 검수할 때는 접수번호로 원본 파일을 찾을 수 있는지, 거절한 파일에는 접수 완료 안내가 나가지 않는지 확인합니다.

접수번호로 처리 현황을 확인하는 화면 연결하기

고객사 업무 화면의 ‘처리 현황’ 버튼은 발급받은 접수번호로 진행 상황을 조회합니다. 접수 응답에 최종 분석 결과까지 담으려 하지 않고, 결과가 준비됐는지 확인하는 기능을 따로 만듭니다. 화면에는 처리 중이라는 안내나 결과 확인 방법처럼 담당자가 행동하는 데 필요한 정보를 표시합니다.

조회 응답의 항목 이름과 조회 간격은 고객사와 정할 API 규격에 포함합니다. 결과를 받을 준비가 된 뒤에만 완료 안내와 내려받기 기능을 연결합니다. 접수 직후, 분석 도중, 결과 준비 이후에 각각 조회해 안내가 맞는지 확인하고, 처리가 중단된 경우에는 다시 제출할 필요가 있는지 설명하도록 만듭니다.

고객사 업무 항목에 맞춰 결과 내려받기

문서 분석 결과를 그대로 전달하기보다 고객사 프로그램이 받을 항목에 맞춰 변환하는 기능이 필요합니다. 예를 들어 거래처명, 발행일, 품목, 수량을 입고 등록 화면의 항목과 연결합니다. 결과 전달에는 항목 이름과 값을 짝지어 표현하는 JSON 형식을 사용할 수 있으며, 실제로 전달할 항목은 고객사와 합의합니다.

날짜 표기, 수량의 단위, 값이 없는 항목의 처리 방법은 변환 로직으로 직접 구현합니다. 필수 항목이 비어 있으면 임의로 채우지 않고, 고객사 화면에서 확인이 필요한 항목을 구분할 수 있게 응답합니다. ‘결과 내려받기’로 받은 내용이 합의한 형식과 맞는지 검사하고, 문서에 적힌 값과 입고 화면에 표시된 값을 대조해 검수합니다.

BullMQ와 접수 기록으로 재요청 처리하기

파일을 보낸 뒤 응답을 받지 못하면 고객사 프로그램이 같은 요청을 다시 보낼 수 있습니다. BullMQ (https://docs.bullmq.io/guide/jobs/deduplication)의 Simple Mode는 같은 중복방지 ID의 미완료 작업이 있으면 추가 작업을 무시하지만, 외부 업무의 중복 처리까지 보장하지는 않습니다. 따라서 작업 중복방지와 별개로 고객사 요청을 기억하는 접수 기록을 만듭니다.

고객사 구분값과 요청번호를 묶어 기록하고, 같은 파일을 같은 번호로 다시 보내면 기존 접수번호를 반환하도록 개발합니다. 같은 요청번호에 다른 파일이 들어오면 새 접수로 처리하지 않고 번호를 확인하라는 오류를 돌려줍니다. 완료된 요청의 기록 보관 기간과 재요청 응답도 API 계약에 포함하며, 고객사 입고 프로그램에서 같은 결과를 두 번 등록하지 않도록 접수번호 확인 규칙을 함께 정합니다.

PostgreSQL RLS로 고객별 조회와 다운로드 제한하기

PostgreSQL RLS (https://www.postgresql.org/docs/current/ddl-rowsecurity.html)는 행 단위 보안 정책으로 사용자별 조회·추가·수정·삭제 대상 행을 제한할 수 있습니다. 접수 기록과 분석 결과에 고객사 구분값을 붙이고, 인증된 고객사에 해당하는 자료만 접근하도록 정책을 적용합니다. 요청에 적힌 고객사 이름만 믿지 않도록 인증 정보와 고객사 계정을 연결하는 로직도 필요합니다.

고객사별 허용 문서 종류와 조회·다운로드 권한은 별도 규칙으로 관리하고, 결과 파일을 전달하는 경로에서도 권한을 확인합니다. 대표적인 실패 사례 검수는 B 고객사 인증 정보로 A 고객사의 접수번호를 조회하고 내려받기를 시도하는 것입니다. 두 요청 모두 파일명과 분석 내용이 노출되지 않아야 하며, 실제 운영에 사용할 데이터베이스 계정과 정책으로 이를 확인합니다.

민감정보를 가린 거래명세서 PDF 샘플과 고객사 프로그램의 입고 등록 항목표를 준비해, 필요한 접수·조회·결과 다운로드 기능과 고객별 허용 범위를 트램스에 개발 문의해 주세요. 트램스 AI 제작 문의 (https://trams.co.kr/ai-si/contact/#inquiry)