CHALLENGE
클라이언트는 여러 주소의 부동산 문서를 한꺼번에 접수하고 결과 파일을 관리해야 했습니다. 하지만 요청 한 건 안에서도 문서 종류마다 처리 결과가 달랐습니다. 등기사항증명서는 성공하고 건축물대장만 일시 실패했을 때 요청 전체를 실패로 표시하면 재처리 범위가 커지고, 운영자는 어느 단계에서 멈췄는지 알기 어려웠습니다.
클라이언트가 필요로 한 이유
클라이언트가 가장 먼저 풀어야 했던 문제는 “요청했다”와 “완료됐다” 사이의 과정이 보이지 않는다는 점이었습니다. 주소 확인, 문서별 작업 생성, 공급자 호출, 실패 유형 판별, 파일 보관, 파싱 검수의 상태가 각각 달랐지만 기존 방식에서는 요청 한 줄의 성공·실패로만 보였습니다. 그 결과 부분 성공이 사라지고, 다시 처리할 필요가 없는 문서까지 반복 요청하는 일이 생겼습니다.
그래서 요청, 문서 작업, 공급자 시도, 결과 파일을 분리해 설계했습니다. 클라이언트가 전체 건수보다 지금 먼저 처리할 요청과 재시도로 복구 가능한 작업을 구분할 수 있도록 SLA와 실패 성격으로 우선순위를 계산하고, 성공한 문서는 유지한 채 일시 실패한 작업만 다시 실행하도록 구성했습니다.
요청, 문서 작업, 공급자 시도, 발급 파일을 분리해 부분 성공과 재시도 가능 실패를 정확히 표현하는 운영 구조가 필요했습니다.
| 운영 과제 | 시스템에서 다룬 방식 |
|---|---|
| 일괄 요청의 부분 실패 | 요청 아래 문서별 작업과 상태를 별도로 저장 |
| 재시도 범위 과다 | 일시 실패한 작업만 다시 대기열에 배치 |
| 공급자 오류 원인 불명 | 시도 시각·지연·실패 코드·응답 결과 기록 |
| 결과 파일 추적 어려움 | 발급 메타데이터와 다운로드 감사 이력 연결 |
클라이언트 요청사항과 기획 방향
일괄 발급을 단순 반복 호출로 만들지 않고, 요청 안에서 성공한 문서는 지키면서 실패한 작업만 안전하게 복구하는 운영 구조를 먼저 세웠습니다.
| 클라이언트 요청 | 이렇게 기획한 이유 | 해결 방식 |
|---|---|---|
| 여러 주소와 문서를 한 번에 접수하고 싶다 | 요청 한 줄로만 관리하면 문서별 진행 상태와 부분 성공이 사라짐 | 주소별 요청 아래에 문서 종류별 작업을 각각 생성 |
| 실패한 문서만 다시 처리하고 싶다 | 전체 재실행은 성공 문서까지 중복 요청해 시간과 비용을 늘림 | 오류를 일시 실패와 종단 실패로 나누고 재시도 가능 작업만 대기열 복귀 |
| 처리 과정과 결과 파일을 함께 추적하고 싶다 | 공급자 시도·오류·PDF·다운로드가 분리되면 책임 범위를 확인하기 어려움 | 요청번호를 기준으로 시도 이력·문서·파싱 검수·감사 기록 연결 |
SOLUTION
클라이언트의 일괄 접수와 예외 처리 흐름에 맞춰 주소 검색, 최대 50건 접수, 문서별 작업 대기열, 실패 검토와 재시도, 발급 PDF 확인을 하나의 운영 콘솔에 구성했습니다. 목록에서는 SLA(처리 약속 시간)와 우선순위를 먼저 보고, 상세에서는 발급 시도와 상태 변화를 시간순으로 확인합니다.
일괄 요청 한 건이 끝나는 과정
운영자가 주소 50개를 선택하고 등기사항증명서와 건축물대장을 요청하면 주소마다 요청 1건, 문서마다 작업 2건을 만듭니다. 한 요청에 두 문서를 묶어 보여주되 실제 처리는 문서별로 나누기 때문에 등기사항증명서는 성공하고 건축물대장만 실패한 상황을 정확히 표현할 수 있습니다.
건축물대장이 일시 오류로 멈췄다면 요청 전체를 다시 보내지 않습니다. 성공한 등기 문서는 그대로 두고 실패한 작업만 대기열에 되돌립니다. 반대로 인증 불가처럼 반복해도 해결되지 않는 오류는 자동 재시도에서 제외하고 담당자 검토로 보냅니다. 목록의 우선순위 점수는 약속 시간을 넘긴 정도와 복구 가능성을 함께 반영합니다.
작업이 끝나면 문서별 완료 상태, 발급 시도 횟수, 오류 코드, PDF, 내려받기 기록이 같은 요청번호에 연결됩니다. 담당자는 ‘부분 성공’ 요청만 모아 보고 필요한 문서만 다시 처리할 수 있으며, 누가 언제 파일을 확인했는지도 감사 이력에서 확인합니다.
시스템 흐름
문서 발급 연결부는 요청·응답 형식을 분리해 공급자가 달라져도 대기열과 운영 화면의 상태 기준이 바뀌지 않게 구성했습니다.
요청 우선순위 점수
대기열은 접수 순서만 따르지 않습니다. SLA 경과, 실패 복구 가능성, 문서 완성도, 업무 우선순위를 합산해 100점의 처리 우선순위 점수를 계산합니다.
| 판단 항목 | 반영 비중 | 계산 기준 |
|---|---|---|
| SLA 경과 | 35% | 약속 시간 대비 경과 비율 |
| 재시도 가능성 | 25% | 일시 오류 코드와 이전 성공 이력 |
| 문서 완성도 | 20% | 요청 문서 중 완료된 비율 |
| 업무 우선순위 | 20% | 긴급·일반·일괄 배치 등급 |
예시 요청은 84점으로 상단에 배치됩니다. 다만 종단 실패 코드는 점수와 무관하게 자동 재시도 대상에서 제외하고, 운영자 검토 대기로 보냅니다. 높은 점수와 실행 가능 여부를 별도로 관리해 실패 요청이 무한 반복되지 않게 했습니다.
작업 실행 조건
새 작업은 멱등성 키 중복 없음, 주소 필수값 완성, 대상 문서 선택, 공급자 상태 정상이라는 네 조건을 통과해야 대기열에 들어갑니다. 재시도는 일시 실패 코드이며 재시도 상한을 넘지 않은 문서 작업에만 허용합니다. 성공한 형제 작업은 다시 호출하지 않습니다.
운영 화면
- 요청번호·주소·건물명 검색과 상태·문서 종류·담당팀 필터
- 25·50건 페이지 이동과 2페이지 이후 상세 조회
- 성공·부분 성공·일시 실패·종단 실패를 문서 단위로 표시
- 공급자 시도, 오류 코드, 지연 시간, 상태 사건 타임라인
- 일시 실패 작업만 재시도하고 결과를 감사 이력에 기록
- PDF 생성과 내려받기
BUILD
부동산, 발급 요청, 문서 작업, 공급자 시도, 문서, 파싱 필드, 요청 사건, 감사 로그를 관계형 운영 데이터로 분리했습니다. 멱등성 키로 같은 접수의 중복 생성을 막고, 요청 상태는 하위 작업 결과에서 계산해 부분 성공을 잃지 않도록 구성했습니다.
데이터를 대기열로 푸는 방식
접수 단계에서 주소와 문서 종류를 정규화하고 요청 ID 아래 문서별 작업을 생성합니다. 공급자 응답은 성공 여부뿐 아니라 오류 코드, 지연 시간, 재시도 가능 여부로 변환해 시도 이력에 저장합니다. 목록은 계산된 우선순위를 읽고, 상세는 같은 요청 ID에 연결된 작업·시도·문서·감사 사건을 시간순으로 조합합니다.
검증한 데이터 규모
| 데이터 | 규모 |
|---|---|
| 부동산 / 발급 요청 | 1,200 / 2,800 |
| 문서 작업 | 5,600 |
| 공급자 시도 | 5,993 |
| 발급 문서 | 3,332 |
| 파싱 필드 | 19,992 |
| 요청 사건 / 감사 로그 | 7,719 / 7,544 |
VALIDATION
- 자동 테스트 9건 통과
- 프로덕션 빌드 완료
- 2페이지 이후 요청 상세와 전체 검색 확인
- 정상 처리·장애·재시도·복구와 새로고침 지속성 확인
- 종단 실패가 자동 재시도에서 제외되고 부분 성공이 보존되는지 확인
- PDF 응답 형식과 다운로드 감사 이력 확인
- 데스크톱·768px 태블릿·모바일에서 예상 밖 오류 응답 없음
RESULT
| 처리 장면 | 기존에 생기던 문제 | 구축 후 처리 방식 |
|---|---|---|
| 일괄 접수 | 요청 전체를 성공 또는 실패 한 줄로만 표시 | 요청 아래 문서별 작업을 만들어 부분 성공을 그대로 표현 |
| 실패 복구 | 성공한 문서까지 다시 요청해 처리량과 비용이 늘어남 | 일시 실패한 문서 작업만 재시도하고 종단 실패는 검토로 분리 |
| 결과 추적 | 공급자 응답, PDF, 다운로드 기록이 서로 다른 위치에 남음 | 요청번호 하나로 시도·오류·문서·감사 이력을 연결 |
2,800개 요청과 5,600개 문서 작업은 정상·부분 성공·일시 실패·종단 실패가 한 배치에 섞여도 재처리 범위가 정확히 유지되는지 확인하는 데 사용했습니다.
비슷한 업무에 적용할 수 있는 부분
같은 원리는 OCR 변환, 외부 API 일괄 조회, 파일 생성처럼 한 요청에서 여러 하위 작업이 실행되는 업무에도 이어집니다. 특히 전체 재실행보다 실패한 단위만 안전하게 복구해야 하는 운영에 맞습니다.
본 프로젝트는 고객사 실제 업무 요건을 바탕으로 설계한 결과물이며, 보안 정책에 따라 일부 화면만 공개했습니다.
