학교 매점은 하루 평균 100명 이상의 학생이 이용하는 필수 시설이지만, 수기 재고 관리와 현금 결제 중심의 운영으로 비효율이 발생했습니다. 매점 협동조합과 학생들 모두 불편을 겪고 있었고, 이를 해결하기 위해 키오스크 기반 디지털 결제 시스템이 필요했습니다.

기존 선배들이 개발한 시스템이 있었으나, 700줄이 넘는 단일 파일에 9개 도메인이 결합된 레거시 코드로 인해 새로운 기능 추가가 불가능한 상태였습니다. 또한 동아리 키오스크와 토스 플레이스 키오스크 두 가지 시스템이 혼재하면서 도메인 설계가 복잡해졌고, VAN사 연동 과정에서 실시간 결제 장애가 빈번히 발생했습니다.

본 프로젝트는 레거시 시스템을 점진적으로 개선하면서도 무중단 서비스를 유지하고, 확장 가능한 아키텍처로 재설계하여 안정적인 매점 운영 시스템을 구축하는 것을 목표로 했습니다.

기술적 도전과제

1. 높은 결합도의 레거시 코드 개선

문제 상황

700줄이 넘는 단일 서비스 파일에 9개 도메인이 결합
새로운 기능(협동조합 출자금 관리) 추가 시 기존 코드 수정 불가능
높은 결합도로 인한 유지보수 비용 증가

해결 과정

Publisher-Subscriber 패턴 도입으로 모듈 간 결합도 해소
각 도메인의 상태 변화 로직을 이벤트 기반으로 분리
캡슐화를 통해 도메인 독립성 확보

기술적 의사결정 근거

직접적인 의존성 주입 대신 이벤트 발행/구독 구조 채택
700줄 전체 리팩토링 대신 점진적 개선 가능
SOLID 원칙 중 OCP(Open-Closed Principle) 준수

결과

기존 코드 수정 없이 새로운 기능 추가 가능
이후 프로젝트에서 인터페이스 기반 설계 원칙 확립


2. 도메인 모델 재정의를 통한 복잡도 개선
문제 상황

재고(Inventory), 상품(Item), 토스재고(TossReceipt) 3개 도메인이 중복
동아리 키오스크: 실시간 재고 갱신
토스 플레이스 키오스크: 특정 시점 일괄 재고 수신
4개 도메인이 유사한 컬럼과 책임 공유로 코드 중복 심화

해결 과정

문제 정의 재수립: "재고 갱신 시점의 차이"를 핵심 문제로 인식
재고 도메인에 토스 키오스크 제품 갱신 기능 통합
상품 동기화 기능을 단일 도메인으로 책임 집중
4개 도메인 → 2개 도메인으로 재설계

기술적 의사결정 근거

도메인 주도 설계(DDD) 원칙: 유비쿼터스 언어 기반 도메인 통합
갱신 시점 차이는 도메인 분리 사유가 아닌 전략 패턴으로 해결
응집도 향상과 결합도 감소 동시 달성

결과

1,000줄 이상의 코드 감소
도메인 책임 명확화로 유지보수성 향상
서비스 설계 시 문제 정의의 중요성 체득

3. 실시간 결제 시스템 장애 대응

문제 상황

2025년 12월 8일 오후 2시 40분, 키오스크 결제 시 "잘못된 결제 요청" 오류 발생
카드 삽입 즉시 에러 발생, 서비스 중단
고객(학생) 대기 상황에서 즉각 대응 필요

해결 과정

VAN사 프로토콜 분석: STX(트랜잭션 시작) 응답 구조 재검토
로그 분석: 승인 번호 없는 STX가 last_stx_response에 저장되는 현상 발견
DLE(트랜잭션 종료) 처리 로직 오류 발견: 결제 취소 전용 DLE만 처리
승인 번호 존재 여부 검증 로직 추가
공통 응답 DLE로 트랜잭션 종료 로직 수정

기술적 의사결정 근거

VAN사 통신 프로토콜의 모든 케이스 정의 및 로깅 강화
Null-safety 검증으로 예외 상황 사전 차단
트랜잭션 상태 머신 명확화

결과

2시간 이내 장애 해결 및 서비스 복구
대안 결제 방법 안내로 고객 불편 최소화
외부 API 연동 시 로깅 전략 수립 경험 확보


4. 외부 API 의존성 관리 - Hexagonal Architecture 도입
문제 상황

다수의 외부 API(토스페이먼츠, VAN사, 학교 인증 시스템) 의존
외부 시스템 변경 시 핵심 비즈니스 로직 영향
테스트 환경 구축 어려움

해결 과정

Hexagonal Architecture 부분 적용
Port-Adapter 패턴으로 외부 시스템 인터페이스 추상화
핵심 도메인 로직과 인프라 계층 분리

기술적 의사결정 근거

외부 의존성 변경 시 어댑터만 교체하여 대응
Mock 객체 주입으로 독립적 테스트 가능
비즈니스 로직의 안정성 확보

결과

외부 API 변경 대응 시간 단축
도메인 로직 테스트 커버리지 향상
아키텍처 설계 역량 강화

프로젝트 개요

Occount는 학교 매점의 효율적인 운영을 위한 통합 관리 시스템입니다. 매점 협동조합과 학생들이 편리하게 매점을 이용할 수 있도록 키오스크 서비스, AriPay 학생증 결제 서비스를 제공하며, 2023년부터 실제 서비스되어 현재까지 안정적으로 운영되고 있습니다.