C# 윈도우 클라이언트·Kotlin PDA 앱과 택배사 기간계를 연결하는 Kotlin·Spring 미들웨어
주요 업무 · 택배 현장 시스템 연계개발·유지보수
Kotlin
Spring Framework 5
WebClient
MyBatis · MariaDB
EC2 · Tomcat
OVERVIEW
프로젝트 개요
C# 윈도우 클라이언트와 Kotlin PDA 모바일 앱의 바코드 스캔 데이터를 받는 Kotlin·Spring API를 개발합니다. 스캔 이력을 저장하고 택배사 기간계에 전송하며, 항목별 전송 결과와 이력 조회 기능을 제공합니다.
SCOPE
담당 업무 및 개발 내용
Kotlin·Spring 기반 연계 API 개발·유지보수를 담당합니다. C# 윈도우 클라이언트와 Kotlin PDA 모바일 앱에서 전달한 바코드 스캔 데이터의 입력 검사·DB 저장, 장비·업무 유형별 택배사 기간계 전송, 항목별 전송 결과와 이력 조회를 구현하고 관리합니다.
현장 클라이언트
C# 윈도우 · Kotlin PDA
중계 서버
Kotlin · Spring
결과 관리
항목별 전송 · 이력
01 / ARCHITECTURE
시스템 구성과 처리 흐름
두 현장 클라이언트의 바코드 스캔 데이터와 기간계 연동
현장 클라이언트C# 윈도우 · Kotlin PDA
Kotlin·Spring API입력 검사 · 업무 분기
저장 · 전송DB 이력 · WebClient
택배사 기간계전송 결과 응답
C# 윈도우 클라이언트와 Kotlin PDA 모바일 앱은 각각 바코드 스캔 데이터를 Kotlin·Spring API로 보냅니다. API는 입력을 검사하고 이력을 저장한 뒤 업무 유형에 맞게 택배사 기간계에 전달합니다. 항목별 전송 결과를 취합하고 스캔 이력과 전송 상태를 조회할 수 있으며, REST 연계 경로에는 WebClient 기반 배치 전송을 사용합니다.
02 / IMPLEMENTATION
주요 기능과 설계
기능별 처리 흐름과 문제 해결 과정, 설계 이유와 구현 결과를 소개합니다.
FEATURE 01 구현·유지보수
스캔 수집·저장
C# 윈도우 클라이언트와 Kotlin PDA 앱이 전송한 바코드 스캔 데이터의 운송장·시각·업무 정보를 검사하고 이력으로 저장합니다.
스캔 수집·저장 처리 흐름
현장 요청운송장 · 시각 · 업무
입력 검사필수 값 · 형식
중복 확인요청 내 · 기존 이력
이력 저장MyBatis · DB 적재
PROBLEM
문제
장비에서 한 번에 여러 스캔 결과가 들어오며, 누락된 필드나 동일 업무의 중복 항목을 구분해야 합니다.
SOLUTION
해결
스캔 요청 목록의 필수 값과 형식을 검사하고 요청 내부 및 기존 이력의 중복을 확인합니다. 저장할 항목을 추려 DB에 적재하고 지점의 자동·수동 전송 설정에 따라 처리 흐름을 나눕니다.
설계 이유와 트레이드오프
현장 이력과 외부 전송을 구분
스캔 이력을 먼저 저장하고 기간계 전송을 이어가는 구조입니다. 현장 기록을 조회할 수 있지만 DB 저장과 외부 전송은 하나의 트랜잭션으로 묶이지 않으므로 저장 여부와 전송 결과를 각각 다뤄야 합니다.
업무와 운송장을 기준으로 사전 중복 확인
같은 운송장이라도 업무 단계가 다르면 별도 스캔일 수 있어 업무 구분을 함께 사용합니다. 사전 중복 검사는 잘못된 반복 입력을 걸러내는 데 활용하며, 동시 재요청까지 다루려면 멱등 기준과 DB 제약을 함께 정해야 합니다.
RESULT
구현 내용
스캔 목록의 입력 검사·중복 확인·이력 저장과 자동·수동 전송 분기 기능을 구현하고 유지보수합니다.
FEATURE 02 REST 연계 구현
기간계 배치 전송
스캔 목록을 기간계 요청으로 매핑하고, REST 연계 경로에서 배치를 병렬 전송한 뒤 결과를 취합합니다.
기간계 배치 전송 처리 흐름
전송 목록업무별 요청 매핑
배치 분할요청 단위 나누기
WebClient동시 요청 수 제한
결과 취합완료 후 응답 반환
PROBLEM
문제
현장 스캔 목록을 한 요청에 모두 담거나 순차 전송하면 요청 크기와 대기 시간을 함께 관리하기 어렵습니다. 외부 서버가 처리할 수 있는 동시 요청 범위도 고려해야 합니다.
SOLUTION
해결
기간계 REST 연계 경로에서 스캔 목록을 배치로 나누고 WebClient와 Reactor로 동시 요청 수를 제한해 전송합니다. 배치별 결과를 모아 최종 성공·실패 응답을 반환합니다. 기존 연계 방식과 REST 연계 경로는 전송 방식 분기로 구분합니다.
설계 이유와 트레이드오프
병렬 전송과 최종 응답의 경계
배치 내부는 병렬로 전송하지만 API는 결과 취합이 끝난 뒤 응답합니다. 전송을 맡긴 즉시 성공으로 반환하는 방식과 달리 호출자가 결과를 받을 수 있으며, 전체 응답 시간은 외부 서버의 처리 시간에도 영향을 받습니다.
배치 크기와 동시 요청 수를 함께 관리
배치를 나누면 요청 크기를 제한할 수 있고 병렬 실행으로 여러 배치를 함께 처리할 수 있습니다. 동시 요청을 늘릴수록 외부 서버와 연결 자원의 부담도 커지므로 제한을 둔 전송 구조를 사용합니다.
RESULT
구현 내용
WebClient 기반 REST 전송에 배치 분할·제한된 병렬 실행·결과 취합이 구현되어 있습니다. 전송은 업무·장비 구분에 맞는 요청 데이터로 매핑합니다.
FEATURE 03 구현·유지보수
전송 결과·이력 조회
스캔 기록과 항목별 전송 결과를 연결하고, 기간·지점 조건의 조회와 집계를 제공합니다.
전송 결과·이력 조회 처리 흐름
기간계 응답항목별 처리 결과
응답 대조전송 목록과 매칭
결과 관리상태 갱신 · 실패 취합
이력 조회조건 조회 · 페이징
PROBLEM
문제
여러 운송장을 보낸 요청에서 일부만 실패하거나 응답에 특정 항목이 빠질 수 있습니다. HTTP 응답 하나만으로 각 스캔의 전송 결과를 판단하기 어렵습니다.
SOLUTION
해결
기간계 응답을 전송한 운송장 목록과 대조하고 응답이 없는 항목은 실패로 분류합니다. 항목별 결과를 DB 갱신과 성공·실패 취합에 사용하며, 스캔 이력은 이미지 포함·제외 조회와 페이징, 일별·월별 집계로 제공합니다.
설계 이유와 트레이드오프
요청 전체와 항목별 결과를 따로 판단
응답이 도착했더라도 항목마다 성공 여부가 다를 수 있어 목록 단위로 대조합니다. 전송 응답과 결과 저장도 별도 처리이므로 외부 성공 이후 DB 갱신 실패에 대비한 결과 대조·재처리 기준이 필요합니다.
조회 목적에 따라 이미지와 목록 분리
현장 확인에는 이미지가 필요하지만 목록·집계에서는 모든 이미지가 필요하지 않습니다. 이미지 포함 여부와 페이징을 구분해 사용 목적에 맞는 조회를 제공하고, 날짜·지점 조건으로 이력을 찾도록 구성합니다.
RESULT
구현 내용
항목별 전송 응답 대조와 결과 취합, 스캔 이력의 이미지 포함·제외 페이징 및 일별·월별 조회 기능을 제공합니다.
현장 장비와 기간계를 연결하는 업무에서는 데이터가 API에 도착한 것, 이력이 저장된 것, 기간계가 처리한 것을 구분해야 했습니다. 여러 스캔 결과를 한 번에 보내더라도 항목별 결과가 다를 수 있어, 클라이언트 입력부터 전송 응답과 이력 조회까지 이어지는 흐름을 함께 살피는 것이 중요했습니다.
NEXT / 향후 계획
향후 개선 방향
다시 설계한다면 DB 저장·외부 전송·결과 갱신의 각 단계에 재처리 기준과 멱등성을 명시하고, 부분 실패와 응답 누락을 재현하는 연계 테스트를 보강하겠습니다. 장비와 기간계 변경에 대응할 수 있도록 입력·전송 데이터 계약도 정리하려 합니다.