나인반포 상가 운영·관리 플랫폼
PG 처리와 내부 업무 반영 상태를 분리하고 Outbox 기반 실패 추적·재시도를 구현했습니다. 결제·예약·알림 정책을 개발하고 React 공통 구조와 팀 개발 기준을 설계했습니다.
- 참여 기간
- 2025.11 – 2026.09
- 담당 역할
- 백엔드 개발 · React 프론트엔드 구조 설계 및 개발 리딩
- Java
- Spring
- MyBatis
- React
- Vite
- TanStack Query
- React Hook Form
- Zod
- Zustand
- Axios
- Firebase Cloud Messaging
핵심 기여
- Page–Feature–Common 구조와 공통 훅으로 화면 개발 기준 정립
- 결제 상태와 업무 반영 상태를 분리하고 후처리 실패 추적·재시도 구현
- 상품별 자원 선점 시점과 예약·만료 처리 구분
- 발송 직전 동의 확인 및 대상별 알림 결과 기록
상가의 관리단과 입점사가 사용하는 운영 플랫폼에서 React 프론트엔드의 공통 구조를 설계하고, 결제·주차권·창고·계약·알림 관련 백엔드를 개발했습니다. 반복되는 화면 기능을 공통화하는 작업과 업무별 상태·실패·이력을 다루는 작업을 함께 수행했습니다.
- 담당 역할: 백엔드 기능 개발, React 아키텍처 설계, 팀 개발 기준 정리와 작업 조율.
- 기록상 작업 기간: 2025.11–2026.09. 프론트엔드는 2025.11–2026.07, 확인한 백엔드 모듈은 2026.02–2026.09의 기록입니다.
- 공개 범위: 회사·고객·서비스명은 익명화했습니다.
프로젝트 개요
관리 화면에는 검색·정렬·페이지네이션·등록·수정과 같은 반복 기능이 많고, 결제와 공간 이용에는 상품별 정책과 상태 전환이 필요했습니다. 저는 화면 개발의 공통 기준을 마련하는 한편, 결제 이후 내부 업무 반영 실패, 결제 중단 후 남는 선점, 예약 이후의 동의 변경과 같은 예외 흐름을 구현했습니다.
모듈별 요약
- 프론트엔드 공통 기반: 레이아웃·라우팅·공통 UI, 목록·폼 훅, 서버 캐시와 URL 조회 상태 관리.
- 결제 및 후처리: 준비·승인·취소 흐름, 상품별 검증과 스냅샷, 업무 반영 상태 기록 및 재시도.
- 주차권·창고 예약: 구매·취소 반영, 창고 신청 선점, 시작일 활성화·중단 정리·이용 만료 처리.
- 계약·호실 관리: 호실별 계약 조회와 기존 계약 종료, 신규 연결 및 이력 보존.
- 알림·배치: 토픽·수신 동의 검증, 예약 발송, FCM 대상별 결과와 오류 이력.
- 인증·미디어: 기존 인증 기반의 비밀번호 변경·메뉴 처리 보완, 파일 다운로드·다건 삭제·삭제 실패 기록.
주요 작업
1. React 화면의 공통 구조와 개발 기준 정립
문제: 목록·등록·수정 화면마다 데이터 조회, 폼 검증, 검색 상태와 저장 후 갱신 처리가 반복되었습니다.
고려사항: 도메인별 입력값과 API 차이를 유지하면서, 공통 기능의 책임과 팀원이 따라갈 구현 기준을 명확하게 해야 했습니다.
담당 작업: Page–Feature–Common 구조를 설계하고 검색·정렬·페이지네이션·조회·제출 훅을 구현했습니다. API·스키마·상수 관리 기준과 등록·수정 폼 재사용 방식을 문서화했습니다.
기술적 접근: 페이지는 조합, Feature는 도메인 기능, Common은 공통 UI를 담당하도록 구분했습니다. 각 페이지가 API·스키마·데이터 변환 함수를 설정해 공통 훅을 사용하도록 구성했습니다.
결과: 반복 로직을 재사용하고, 업무별 화면을 같은 기준으로 확장할 수 있는 개발 기반을 마련했습니다. 작업 범위·일정·우선순위 조율과 코드 리뷰 기준 정리도 담당했습니다.
상태·폼·인증 처리 상세
- TanStack Query의 조회 조건별 Query Key와 변경 요청 후 캐시 무효화 기준을 정리했습니다.
- 검색·정렬·페이지 상태를 URL 파라미터로 관리해 뒤로 가기 시 조건 복원과 조회 결과 공유를 지원했습니다.
- React Hook Form과 Zod로 필수값·형식·조건부 검증을 처리하고, 조회 데이터의 폼 초기화와 제출 데이터 변환을 공통화했습니다.
- Zustand로 인증·사용자·메뉴 상태를 관리하고 Axios 인터셉터에서 토큰 갱신과 실패 요청 재시도를 처리했습니다.
- 동시 인증 만료 시 갱신 요청을 단일화하고, 새로고침 시 인증 복원과 권한 준비 상태에 맞춰 경로 접근을 제어했습니다.
2. 결제 승인과 내부 업무 반영의 실패 분리
문제: 외부 PG 승인이 끝난 뒤 내부 구매·예약 데이터 반영이 실패할 수 있었습니다.
고려사항: 결제 완료 여부와 업무 반영 완료 여부를 구분해야 했으며, 메시지 브로커 도입에 필요한 비용과 운영 복잡도도 고려했습니다.
담당 작업: 동기 내부 API 호출에 Outbox 기반 실패 추적·재시도를 결합하고, 결제 준비·승인·취소 처리와 후처리 워커를 구현했습니다.
기술적 접근: 준비 단계에서 검증한 상품·금액 정보를 스냅샷으로 저장하고 승인 전에 대조했습니다. PG 처리 결과와 내부 업무 반영 상태를 나누어 기록하고, 실패 이벤트를 워커가 다시 조회해 상품 유형에 맞는 내부 API를 호출하도록 구성했습니다.
결과: 결제 후처리 실패를 별도 상태와 오류 기록으로 확인하고, 실패한 업무 반영을 다시 시도할 수 있는 경로를 마련했습니다.
후처리 재시도와 책임 분리 상세
준비·검증·선점·승인 반영·취소 반영의 책임을 resolver와 handler로 구분했습니다. 주차권과 창고처럼 업무 규칙이 다른 상품은 각 처리기로 연결했습니다.
워커는 저장된 승인·취소 이벤트를 읽어 내부 업무 반영을 재시도합니다. 성공하면 완료 상태로 전환하고, 실패하면 횟수와 오류를 기록하며 한도 초과 상태를 구분했습니다. 이는 PG 승인을 다시 실행하는 작업과 별개의 처리입니다.
장기 미승인 결제 정리에서는 선점 해제가 필요한 상품의 내부 해제 API를 먼저 호출하도록 보완했습니다. 외부 PG와 내부 DB 전체를 하나의 원자적 트랜잭션으로 처리하거나, 모든 실패의 자동 복구를 보장하는 구조로 설명하지 않습니다.
3. 상품별 자원 점유와 예약 상태 전환 설계
문제: 주차권 구매와 달리 창고는 동일 공간에 대한 신청이 겹칠 수 있고, 결제를 중단하면 준비 단계의 선점이 남을 수 있었습니다.
고려사항: 상품별로 자원을 점유하는 시점이 달랐으며, 예약 시작일·이용 종료일·취소·연장에 따른 처리도 구분해야 했습니다.
담당 작업: 주차권은 승인 후 구매 내역을 반영하고 창고는 준비 단계에 신청을 생성해 선점하도록 구성했습니다. 예약 활성화, 결제 중단 정리, 이용 기간 만료 워커를 구현했습니다.
기술적 접근: 창고 준비 과정에서 선점 식별자를 저장하고 이후 승인·취소 처리에 전달했습니다. 준비 데이터 저장 실패 시 선점 해제 경로를 연결하고, 시작일과 종료일에 맞춰 상태를 바꾸도록 처리했습니다.
결과: 상품별 점유 정책을 결제 흐름에 반영하고, 신청 이후의 사용·취소·만료를 별도 업무 단계로 관리하도록 구성했습니다.
4. 발송 시점의 조건을 반영한 알림 처리
문제: 예약 등록 이후 실제 발송 전까지 수신 동의나 디바이스 상태가 바뀔 수 있고, 한 번의 발송에서도 대상별 결과가 달라질 수 있었습니다.
고려사항: 등록 시점 검증과 발송 직전 검증을 구분하고, 여러 워커의 작업 선정과 대상별 실패를 처리해야 했습니다.
담당 작업: 공통 알림 등록 서비스와 FCM 발송 워커, 대상별 결과 저장을 구현했습니다.
기술적 접근: 등록 시 토픽·채널·수신 동의를 확인하고, 발송 대상 조회에서 동의와 활성 디바이스를 다시 확인했습니다. 작업 선정에는 FOR UPDATE SKIP LOCKED를 적용하고, 전송 응답은 대상별 성공·실패·오류로 기록했습니다.
결과: 예약 이후 동의 변경을 대상 선정에 반영하고, 일부 대상의 실패도 개별 이력으로 확인할 수 있도록 했습니다.
발송 결과 해석과 구현 범위
토큰이 없는 대상은 별도 실패 이력으로 기록하고, 전송 응답에 따라 지정된 오류의 디바이스를 비활성화했습니다. 결과 이력 저장과 메시지 집계 갱신을 DB 트랜잭션으로 묶었습니다.
메시지 완료 상태는 모든 대상의 성공과 같지 않습니다. 당시 구현은 한 건 이상 성공하면 완료 상태가 될 수 있으므로, 실제 결과는 성공·실패 집계와 대상별 이력으로 확인하도록 구분했습니다. DB 작업 선점 역시 외부 전송의 정확히 한 번 실행을 보장한다는 의미는 아닙니다.
배치 작업은 Spring 스케줄링과 MyBatis 기반으로 구현했습니다.
5. 다중 호실 계약과 과거 이력의 구분
문제: 하나의 입점사가 여러 호실을 이용할 때 입점사의 최신 계약만 조회하면 특정 호실에 연결된 계약을 정확히 표현하기 어려웠습니다.
고려사항: 현재 계약을 찾는 기준과 계약 종료 이후 남겨야 하는 이력을 분리해야 했습니다.
담당 작업: 호실에 연결된 계약을 조회하도록 수정하고, 기존 계약 종료와 신규 계약·호실 연결 이력 생성을 구현했습니다.
기술적 접근: 호실별 관계를 기준으로 조회하고 계약 종료·신규 연결·이력 생성을 트랜잭션으로 처리했습니다.
결과: 현재 계약과 과거 임차 이력을 구분하고, 다중 호실 이용을 반영하는 조회·변경 흐름을 구성했습니다.
상세 내용 및 설계 자료
FigJam에 데이터 관계, 요청 검증, 상태 변경과 실패 처리 흐름을 정리했습니다. 계약 종료 시 이력 보존, 결제 중단 시 자원 해제, 알림 수신 동의 적용을 논의 사항으로 구체화하고 검토한 방향을 구현에 반영했습니다.
팀의 API 명세 작성 규칙을 재사용 가능한 커스텀 스킬로 정리해 문서 작성에도 활용했습니다. 요청·응답 필드와 필수 여부, 중첩 구조·JSON 예제 형식을 규칙화하고, 코드와 문서가 다르면 차이를 명시하도록 구성했습니다.
이 문서는 직접 구현·개선한 범위를 중심으로 작성했습니다. 일부 공용시설·통계·시설관리 프론트엔드는 초기 UI와 더미 데이터 기반 구현에 해당하며, 해당 화면의 후속 API 연동 전체를 제 기여로 포함하지 않았습니다. 실제 화면과 설계 자료는 공개 범위 검토 후 추가할 예정입니다.