택시 QR 포인트 관리자 콘솔
방별 현황과 엑셀 내려받기, 기사·대리점 가입 승인과 코드 발급, 관리자 포인트 입력과 역할별 비율 자동 배분, 지급 금액 계산 화면을 담은 확장 관리자 콘솔 프로젝트입니다.
프로젝트 개요
방별 현황과 엑셀 내려받기, 기사·대리점 가입 승인과 코드 발급, 관리자 포인트 입력과 역할별 비율 자동 배분, 지급 금액 계산 화면을 담은 확장 관리자 콘솔 프로젝트입니다. MVP와 같은 Node.js + Express + PostgreSQL 스택에 Redis와 Bull Queue를 더해 감사 로그, 백업·장애 알림, 2단계 확장용 포인트 원장 구조까지 설계합니다.
작업 범위
- 방별 현황: 기사방·대리점방·손님방별 내 고객 수와 보유 포인트를 한 화면에서 보고, 본사 전체 합계와 사람별 목록을 엑셀로 내려받습니다
- 가입 승인: 대리점·기사 신청 내역을 확인하고 승인하면 코드가 발급되며, 관리자 메일 알림으로 이어지는 구조를 보여 줍니다
- 포인트 입력과 배분: 관리자가 제휴사 구매 내역을 보고 손님별 포인트를 입력하면 기사·대리점·손님에게 정해진 비율로 자동 배분되고, 배분 결과를 미리 확인한 뒤 확정합니다
- 정산 금액 계산: 기사·대리점·가맹점별로 지급할 금액을 기간별로 계산해 보여 줍니다. 이체는 관리자가 직접 처리하는 전제입니다
주요 업무
- 방별 현황 화면: 방 유형별 집계, 본사 합계, 사람별 목록, 엑셀 파일 생성
- 가입 승인 화면: 신청 목록, 승인·반려 처리, 코드 발급, 메일 알림 큐
- 포인트 입력과 배분 화면: 손님별 포인트 입력, 배분 비율 설정, 배분 결과 미리보기, 원장 기록
- 정산 금액 계산 화면: 기간별 지급 금액 계산, 대상별 소계, 역할별 보기 권한
프로젝트 핵심 과제
포인트 배분 시 비율 계산의 소수점 차이로 합계가 어긋날 수 있어
정수 단위 보정 규칙과 합계 검증을 함께 설계합니다
제휴사 구매 내역은 관리자가 확인해 입력하는 구조라 입력 실수가 생길 수 있어
미리보기와 감사 로그로 수정 이력을 남길 계획입니다
2단계의 구매 자동 반영과 취소 회수를 붙일 때 기존 원장을 바꾸지 않도록
주문 연계 필드를 지금 단계에서 확장 가능한 형태로 설계해야 합니다
방과 사람이 늘어나는 엑셀 내려받기는 요청이 몰리면 서버 부담이 커질 수 있어
큐 기반 비동기 생성으로 대응합니다
핵심 기능 상세
방별 현황
기사방·대리점방·손님방별 내 고객 수와 보유 포인트를 한 화면에서 보고, 본사 전체 합계와 사람별 목록을 엑셀로 내려받습니다. 방 유형별 집계, 본사 합계, 사람별 목록, 엑셀 파일 생성.
- PostgreSQL 집계 쿼리와 Materialized View로 방 유형별 고객 수·보유 포인트 합계를 조회하는 구조 설계
- ExcelJS 스트리밍 쓰기로 사람별 목록을 대량 행이어도 메모리를 아끼며 내려받는 API 구현
- Bull Queue에서 엑셀 생성 작업을 비동기로 처리하고 완료 알림으로 내려받기 링크를 제공
방 유형별 집계와 비동기 엑셀 생성 큐로 본사 합계와 사람별 목록을 한 화면에서 내려받는 구조를 구현합니다.
가입 승인
대리점·기사 신청 내역을 확인하고 승인하면 코드가 발급되며, 관리자 메일 알림으로 이어지는 구조를 보여 줍니다. 신청 목록, 승인·반려 처리, 코드 발급, 메일 알림 큐.
- 신청 상태(대기·승인·반려) 전이를 서버에서 검증하는 상태 머신 구현
- 승인 시 중복 없는 코드를 발급하는 유일 제약과 재시도 로직 설계
- Bull Queue 기반 관리자 메일 발송 작업과 실패 재시도 정책 구현
신청 상태 전이와 코드 발급을 한 트랜잭션으로 묶고, 알림은 큐로 분리해 승인 처리가 메일 상태에 막히지 않는 구조를 구현합니다.
포인트 입력과 배분
관리자가 제휴사 구매 내역을 보고 손님별 포인트를 입력하면 기사·대리점·손님에게 정해진 비율로 자동 배분되고, 배분 결과를 미리 확인한 뒤 확정합니다.
- 역할별 배분 비율을 설정 테이블로 분리하고 합계가 100이 되는지 입력 단계에서 검증
- 정수 단위 반올림 차이를 마지막 수령자에게 보정하는 배분 계산 함수 구현
- 배분 확정 시 원장 행을 일괄 기록하고 변경 내용을 감사 로그 테이블에 남기는 트랜잭션 설계
비율 설정, 미리보기, 확정을 분리하고 확정 시 원장과 감사 로그를 한 트랜잭션으로 기록하는 배분 엔진을 구현합니다.
정산 금액 계산
기사·대리점·가맹점별로 지급할 금액을 기간별로 계산해 보여 줍니다. 이체는 관리자가 직접 처리하는 전제입니다. 기간별 지급 금액 계산, 대상별 소계, 역할별 보기 권한.
- 원장 행을 기간·수령자 기준으로 집계해 지급 금액을 계산하는 SQL 뷰 설계
- 역할(운영 관리자·정산 담당)별로 조회·수정 가능한 항목을 나누는 권한 미들웨어 구현
- 2단계 구매 자동 반영과 취소 회수를 붙일 수 있도록 주문 연계 컬럼을 원장에 확장 가능한 형태로 설계
원장 집계 기반 지급 금액 계산과 역할별 권한 분리로, 이후 단계의 자동 반영을 같은 원장에 붙일 수 있는 구조를 구현합니다.
프로젝트 진행 단계
포인트 원장·주문 연계 모델 설계 · 2026.10
원장 행 구조와 2단계 확장용 주문 연계 컬럼, 배분 비율 설정 테이블 ERD 설계
배분 엔진과 감사 로그 구현 · 2026.10
비율 검증, 정수 보정 배분 계산, 확정 트랜잭션과 변경 이력 기록 구현
가입 승인·현황·정산 화면 개발 · 2026.10
신청 상태 전이·코드 발급, 방별 집계 뷰, 지급 금액 계산, 비동기 엑셀 생성 작업 구현
권한 분리·백업·장애 알림 점검 · 2026.10
역할별 접근 권한 테스트, 일일 백업 스크립트, 장애 알림 훅 구성
개발 결과
기술적 주안점
- 방 유형별 집계와 비동기 엑셀 생성 큐로 본사 합계와 사람별 목록을 한 화면에서 내려받는 구조를 구현합니다
- 신청 상태 전이와 코드 발급을 한 트랜잭션으로 묶고, 알림은 큐로 분리해 승인 처리가 메일 상태에 막히지 않는 구조를 구현합니다
- 비율 설정, 미리보기, 확정을 분리하고 확정 시 원장과 감사 로그를 한 트랜잭션으로 기록하는 배분 엔진을 구현합니다
