관리자(백오피스) 매뉴얼

목차

1. 접속과 로그인

관리자 콘솔은 아이디·비밀번호(1단계)와 OTP 일회용 번호(2단계)를 모두 통과해야 들어갈 수 있는 2단계 로그인 구조입니다. 여기에 더해 접속 장소(IP)까지 제한합니다.

1-1. 2단계 로그인 흐름

잘못 눌러 되돌아가려면 [처음으로]로 1단계(아이디·비밀번호)로 돌아갑니다. 로그인 시도는 아이디 기준(1단계)·IP 기준(OTP 확인)으로 무차별 대입이 차단됩니다(이용제한 정책). 발급된 출입증(토큰)은 브라우저에 보관되며, 우측 상단 [로그아웃]으로 지울 수 있습니다.

1-2. 사내 IP 제한

관리자 API(/api/admin/**)는 미리 등록해 둔 IP(사무실 등)에서 온 요청만 통과시키고, 그 밖의 곳에서 온 요청은 아이디·비밀번호를 보기도 전에 거부(403)합니다. 관리자 화면은 권한이 크기 때문에 아이디·비밀번호에 더해 "장소"까지 제한하는 방식입니다.

• 공통 허용 IP(1차 관문) — 모든 관리자에게 적용되는 관문입니다. 여기에 없는 IP 는 로그인 화면조차 열 수 없습니다.
• 관리자별 허용 IP(추가 제한) — 특정 관리자에게만 거는 추가 제한입니다. 로그인 후 매 요청마다 함께 검사됩니다.
• 허용 IP 는 관리자 관리 → 접근 허용 IP 화면에서 등록·삭제합니다. DB 에 IP 가 하나도 없을 때만 설치 초기용 목록(서버 설정)이 임시로 쓰이고, 첫 IP 를 등록하면 초기 목록은 자동으로 무시됩니다.

주의: 허용 IP 를 잘못 등록·삭제하면 본인도 접속이 막힐 수 있습니다. 반드시 현재 접속 중인 IP 가 목록에 남는지 확인하세요.

1-3. 관리자는 전원 동등 (등급 없음)

NestPay 관리자에는 root/일반 같은 등급 구분이 없습니다. 모든 관리자가 모든 메뉴에 접근하고, 등록·수정·삭제·초기화·정책 변경을 동일하게 할 수 있습니다(서버에서도 동일하게 처리). 대신 모든 조치는 감사 기록에 남아 "누가 언제 무엇을 했는지" 추적됩니다.

2. 화면 구성 · 전체 메뉴 지도

왼쪽 사이드바에 메뉴가 7개 그룹으로 묶여 있습니다. 그룹 제목을 누르면 접었다 펼 수 있고(접힘 상태는 브라우저에 기억됨), 지금 보고 있는 화면이 든 그룹은 자동으로 펼쳐집니다. 상단 헤더에는 현재 화면 이름과 로그인한 관리자 이름·로그아웃 버튼이 있습니다.

회원은 수만 명, 매장은 수천 개 규모라 목록 화면은 검색·조회 중심이며, 상세 보기·조치는 이름/상호를 눌러 독립 상세 페이지(주소에 번호가 붙는 #/members/123 형태)에서 처리합니다.

각 화면 상단에는 접었다 펼 수 있는 안내 패널이 붙어 있어, 그 화면에서 무엇을 할 수 있는지·주의점을 바로 확인할 수 있습니다.

3. 현황

대시보드 #/dashboard

목적 — 관리자가 지금 손대야 하는 일을 급한 순서로 한 화면에 모아 보여 줍니다. 데이터는 서버 한 곳(GET /admin/stats/ops)에서 한 번에 받아 옵니다.

자동 새로고침 — 20초마다 스스로 최신 숫자를 가져옵니다(F5 불필요). 오른쪽 위 체크를 끄면 멈추고, 그 옆에 “…기준” 으로 언제 시점의 숫자인지 표시됩니다. 갱신할 때 화면을 다시 그리지 않고 바뀐 숫자만 고쳐 쓰므로 보던 위치가 튀지 않습니다. 다른 메뉴로 이동하면 자동으로 멈춥니다.

★ 숫자 = 그 화면의 건수 — 카드를 누르면 그 숫자와 똑같은 목록이 열립니다. 숫자와 목록이 다르면 시스템을 믿을 수 없게 되므로, 각 카드의 조건은 이동할 화면의 목록 조건과 동일하게 맞춰져 있습니다.

구성

주의 — 오류 모니터링 숫자가 오르면 원인을 확인하세요. 처리 대기 건은 방치하지 말고 해당 화면으로 이동해 처리합니다.

4. 고객

회원 관리 #/members

목적 — 회원(users)을 이름·아이디로 검색하고 상태별로 거르는 "찾기 전용" 화면입니다. 조작 — 상단 검색어(이름/아이디)+상태 필터(정상/정지/탈퇴)로 조회, [+ 회원 등록]으로 신규 회원을 본인인증 대기(PENDING) 상태로 사전 생성(아이디·초기 비밀번호·임시 이름·휴대폰). 이름을 누르면 회원 상세로 이동합니다.

보유 금액 표시 — 목록에서 회원별 잔액(모든 카드 지갑 합계)과 함께 카드관리처럼 유상 포인트(충전)/무상 포인트(적립)를 나눠 보여 줍니다(만료 전 로트 잔여 기준).

주의 — 이름·휴대폰·인증계좌는 개인정보 보호를 위해 가운데를 가려(마스킹) 보여 줍니다(서버가 복호화·마스킹을 끝낸 값만 내려줌). 사전 생성한 회원은 최초 로그인 후 앱에서 휴대폰 본인인증을 마쳐야 서비스를 이용할 수 있습니다(휴대폰 본인인증은 외부연동 스텁).

회원 상세 #/members/{번호}

목적 — 한 회원의 정보·보유 카드·거래를 보고 필요한 조치를 처리합니다. 주요 조작:

이 밖에 보유 카드(잔액과 유상/무상 포인트), 연결계좌 변경 이력(사용중 1개 + 변경 시 옛 계좌는 해지로 보존), 거래 내역(충전·결제·출금·선물, 받은 선물 포함)을 함께 봅니다. 모든 조치는 감사 기록에 남습니다.

카드 관리 #/cards

목적 — 발급된 모든 카드를 검색·조회합니다(회원 이름·아이디·카드번호). 포인트 구분 — 잔액을 유상(충전)/무상(적립)으로 나눠 보여 줍니다(만료 전 잔여 기준). 대표 카드는 번호 옆 ★로 표시됩니다. 회원 이름을 누르면 그 회원 상세로 이동합니다.

민감정보 열람 — 카드번호는 목록에서 마스킹되며, 행의 [열람] 버튼으로 사유를 입력해야 전체 번호·CVC 를 단건으로 볼 수 있습니다. 이 열람은 개인정보 열람 기록(감사 장부)에 남습니다("이 열람은 기록되었습니다" 안내).

매장 관리 #/merchants

목적 — 매장(가맹점)을 상호·사업자번호·대표자로 검색하는 "찾기 전용" 화면입니다. 조작 — 상태 필터(심사중/보완 대기/정상/반려/정지/해지), [+ 매장 등록]으로 심사대기(PENDING) 매장을 매장앱 로그인 계정과 함께 생성. 상호를 누르면 매장 상세로 이동합니다.

보유 금액 표시 — 목록에 매장별 보유 총액(매장 지갑 = 정산 예정 잔액)을 함께 보여 줍니다. 매장 포인트는 유효기간 개념이 없어 유상/무상 구분 없이 총액만 표시합니다.

정상(ACTIVE) 매장만 결제·정산이 동작합니다.

매장 상세 #/merchants/{번호}

목적 — 한 페이지에서 ① 기본 정보·심사 조치, ② 필수 서류, ③ PG 연동 심사, ④ 결제 내역을 모두 처리합니다.

PG 신청 #/pg-applications

목적 — 전 매장의 PG(결제대행) 연동 신청과 진행 단계를 한눈에 보는 대시보드입니다. 진행은 신청 → 승인 → 테스트(샌드박스) → 라이브 4단계이며, 각 행에 현재 단계 배지(예: "2/4 승인")와 테스트 3종 통과 표시가 나옵니다. 조작 — 승인 + 샌드박스 3종 테스트를 모두 통과한 매장만 [라이브 전환] 버튼이 열립니다(설정 실수로 실서비스가 열리는 것을 방지). 그 외 실제 조치(승인/반려, 발급키·화이트IP)는 각 행의 [매장 상세] PG 패널에서 합니다.

PG 결제요청 #/pg-orders

목적 — 매장이 PG 오픈 API 로 만든 결제요청(주문)을 전부 조회합니다. 상태: 대기(미결제) → 결제완료, 유효시간 경과 시 만료, 매장이 취소하면 취소/환불. 유효시간은 정책의 PG_ORDER_TTL_MINUTES(기본 5분)를 따릅니다. 결제완료 건은 거래(원장) 번호로 연결됩니다.

실제 잔액 이동(결제·환불)은 거래 관리(원장)에 단일 원장으로 기록되며, 이 화면은 결제요청 단위로만 봅니다.

탈퇴 신청 #/closures

목적 — 회원이 앱에서 낸 탈퇴 신청을 확인하고 처리합니다. 기본은 대기(PENDING) 건만 보여 줍니다. 조작 — 체크박스로 여러 건을 골라 [선택 승인] / [선택 반려]로 한꺼번에 처리(헤더 체크박스로 전체 선택).

★ 승인 전 반드시 확인 — 승인하면 그 회원은 즉시 탈퇴(WITHDRAWN) 처리되고 카드가 정지되며, 남아 있던 보유 포인트가 소멸됩니다. 되돌릴 수 없습니다. 승인 확인 창에 소멸 예정 포인트 합계가 함께 표시됩니다.

회원별 실제 소멸 총액은 이 화면의 "실제 소멸P" 컬럼에서 봅니다. 카드 한 장씩 얼마가 소멸됐는지는 아래 탈퇴 소멸 메뉴에서 봅니다.

탈퇴 소멸 #/forfeits

목적 — 탈퇴 승인으로 회수(소멸)된 포인트를 카드 단위로 조회합니다(탈퇴 신청 처리와는 별개의 조회 전용 메뉴). 탈퇴가 승인되면 회원의 카드(지갑)마다 소멸 거래가 한 건씩 남는데, 그 거래를 회원·카드·금액·일시로 풀어 보여 줍니다. 한 회원이 여러 카드를 가졌으면 카드 수만큼 줄이 나옵니다.

조작 — 상단에 총 소멸 건수·소멸 합계가 표시됩니다. 회원 이름·거래번호로 검색하며, 숫자를 넣으면 회원번호·카드번호로도 찾습니다. 각 줄의 회원·카드를 누르면 회원 상세로 이동합니다.

회원별 총액은 [탈퇴 신청]에서, 카드별 상세는 여기서 — 두 화면이 짝을 이룹니다. 각 줄은 원장(transactions)의 소멸 거래(조정·FORFEIT) 한 건으로, 되돌릴 수 없는 확정 기록입니다.

5. 거래

거래 관리 #/transactions

목적 — 모든 돈 이동을 담는 하나의 원장(transactions)을 조회하고, 필요 시 결제를 취소(환불)하는 화면입니다(발주사 요청: 단일 원장 관리). 결제·PG·정산·입출금·선물이 전부 여기에 기록됩니다. 조작 — 상단 빠른 분류 칩(전체·결제·충전·출금·정산·선물·취소·조정)으로 자주 보는 묶음을 한 번에 거르고, 거래번호·회원·매장 검색과 상태 필터를 함께 씁니다. 세부 유형(QR결제·PG결제·정산지급 등)은 우리말로 풀어 보여 줍니다.

결제 취소(관리자 환불) — 확정(CONFIRMED)된 결제 행의 [취소] 버튼으로 전액 환불합니다. 사유 입력이 필수이며 감사 기록(누가·언제·왜)에 남습니다. 회원에게 전액이 즉시 환불되고 매장 정산 잔액에서 차감되며, 되돌릴 수 없습니다. 취소 권한은 매장·관리자만 있습니다(회원은 앱에서 취소할 수 없음 — 2026-07-27 정책). PG 주문에 붙은 결제는 여기서 취소할 수 없고 매장 시스템의 PG 환불 API로만 환불됩니다(웹훅 정합). 매장 정산 잔액이 부족하면 취소가 거절됩니다.

수정 불가 — 원장은 추가만 되는(append-only) 장부라 기록을 지우지 않습니다. 취소도 역분개(반대 기입)로 남아 돈의 흐름이 전부 추적됩니다.

충전신청 #/deposit-requests

목적 — 회원이 앱에서 낸 충전신청을 조회하고, 아직 입금이 확인되지 않은 대기(PENDING) 신청을 취소합니다. 충전은 회원앱 충전신청 → 페이솔루스 입금요청 API → 신청마다 배정된 회사 입금계좌 안내 → 회원이 본인 인증계좌에서 신청 금액을 그대로 입금 → 입금통지 웹훅 → 아래 네 가지가 모두 맞으면 자동 충전으로 이어집니다. 충전 확정은 입금통지 매칭으로 자동 처리되며 관리자 승인이 필요 없습니다.

무엇을 맞춰 보나요 — ① 예금주명이 회원의 인증계좌(본인인증 → 실명조회 → 1원 인증을 마친 계좌)와 같아야 합니다(공백·기호는 무시하고 비교). ② 금액이 신청 금액과 정확히 같아야 합니다. ③ 신청할 때 배정해 준 입금계좌로 들어와야 합니다. ④ 시각이 신청 1분 전 ~ 10분 뒤 사이여야 합니다. 남의 계좌에서 보낸 돈은 충전되지 않습니다(자금 출처 증명).

조작 — 입금 예금주·회원·계좌번호 검색과 상태 필터(대기/충전완료/만료/취소)로 조회하고, 대기(PENDING) 상태 신청만 [취소]할 수 있습니다(감사 기록). 이미 충전완료·만료·취소된 신청은 취소되지 않습니다. 목록에는 회원·금액·입금 예금주·배정계좌·신청일·만료가 함께 표시됩니다.

취소했는데 입금이 들어오면? — 자동취소(신청 10분 뒤)와 입금 인정 시간이 같아 보통은 겹치지 않지만, 청소 배치 주기 때문에 "9분 50초에 취소 → 10분에 입금 도착" 같은 경계가 생길 수 있습니다. 이때는 실제로 들어온 돈이므로 충전됩니다(들어온 돈을 버리지 않습니다).

무신청 충전은 불가합니다(신청 없이 들어온 입금은 아래 미매칭 입금으로 빠집니다). 회원당 진행 중인 신청은 1건이며, 입금 금액은 신청 금액과 정확히 일치해야 매칭됩니다. 레거시 "입금자 코드"(회원당 고정 자동적립) 방식은 폐기되었습니다.

미매칭 입금 #/unmatched

목적 — 주인을 못 찾은 입금(예금주명·금액·입금계좌·시각 중 하나라도 안 맞는 입금, 무신청 입금 등)을 관리자 재량으로 처리합니다(장부 밖 돈 없음 원칙). 조작(대기 건에만 표시):

• 수동 매칭 — 입금자를 확인했으면 회원 카드 번호를 넣어 그 카드로 충전해 줍니다(원장 분개 + 충전 로트 생성 + 감사 기록까지 서버가 한 번에 처리). 처리 사유 필수.
• 반환 — 보낸 사람에게 돌려줍니다(장부 이동 + 반환 대기 상태). 반환 사유 필수. 실제 이체는 펌뱅킹 연동 시 실행(현재 외부연동 스텁).

입금통장 #/deposit-accounts

목적 — 사용자가 무통장 입금으로 충전할 때 앱 충전 화면에 안내되는 회사 수납 계좌를 관리합니다. 조작 — [+ 계좌 등록](은행·계좌번호·예금주·이름표·노출 순서), 행별 노출/숨김 전환·삭제. 노출(ACTIVE) 계좌만 앱에 보이며, 여러 개면 순서대로 안내됩니다.

★ 주의 — 계좌번호를 잘못 넣으면 사용자가 엉뚱한 곳으로 입금할 수 있습니다. 등록하면 바로 노출되므로 계좌번호를 반드시 다시 확인하세요.

출금통장 #/payout-accounts

목적 — 회원 출금·매장 정산을 지급할 때 돈이 빠져나가는 우리 회사 계좌를 관리합니다(손님이 보내는 입금통장과 반대 방향입니다). 조작 — [+ 계좌 등록](은행·계좌번호·예금주·이름표·사용 순서), 행별 사용/숨김 전환·삭제.

어느 계좌에서 나가나요 — 사용(ACTIVE) 계좌 중 순서가 가장 앞선 계좌에서 나갑니다. 사용 중인 계좌는 항상 하나가 되도록 데이터베이스가 강제합니다(어느 계좌에서 나갔는지 헷갈리지 않게 함). 계좌를 바꾸려면 새 계좌를 [사용]으로 바꾸면 기존 계좌가 자동으로 숨겨집니다.

★ 주의 — 계좌번호를 잘못 넣으면 송금이 실패하거나 엉뚱한 곳으로 나갑니다. 저장 전에 반드시 확인하세요. 사용 중인 계좌가 하나도 없으면 출금·정산 송금을 시작할 수 없습니다.

출금신청 #/withdrawals

목적 — 회원이 낸 계좌 출금 신청의 진행 상태를 모니터링합니다(조회 전용). 상태는 처리대기(HOLD)·이체중(PENDING)·완료(CONFIRMED)·실패(FAILED)·미확인(UNKNOWN)이며, 실패·미확인 건은 사유가 함께 표시됩니다. 조작 — 거래번호·회원 검색과 상태 필터로 조회합니다(회원·금액·수수료·출금계좌·예정/완료 시각 표시).

이 화면은 승인 게이트가 아닙니다. 회원이 신청하면 워커가 즉시 처리하며, 실제 이체는 페이솔루스 출금요청 API + 출금통지 웹훅으로 이뤄집니다. 원장(transactions)은 추가만 되는(append-only) 장부라 이 화면에서는 값을 바꾸지 않고 진행 상태만 조회합니다.

선물 내역 #/gifts

목적 — 회원 간 선물(GIFT) 거래 전체를 조회하는 화면입니다(조회 전용). 방식(직접/링크/회수 반환/만료 반환), 보낸 회원 → 받는 회원, 금액, 상태(완료·수령 대기·회수됨·실패), 보낸/수령 시각을 봅니다. 이름을 누르면 회원 상세로 이동합니다.

받는 회원 칸이 비어 있으면 링크형 선물이 아직 수령 전이라는 뜻입니다.

정산신청 #/settlement-requests

목적 — 매장에 지급되는 건별 정산지급 신청의 진행 상태를 모니터링합니다(조회 전용). 상태값과 처리 방식은 출금신청과 동일합니다(처리대기·이체중·완료·실패·미확인 / 신청 즉시 워커가 처리, 실제 이체는 페이솔루스 출금요청 API + 출금통지 웹훅, 원장 append-only 라 조회만). 조작 — 거래번호·매장상호 검색과 상태 필터로 조회합니다(매장·금액·수수료·정산계좌·예정/완료 시각 표시).

월 정산서 마감은 정산 조회, 정산계좌 승인은 정산통장 승인에서 하며, 이 화면은 건별 정산지급 진행 상태 전용입니다.

정산 조회 #/settlements

목적 — 매장 월 정산서(마감본)를 월·검색·페이징으로 봅니다(판매·취소·공급가액·부가세·수수료·지급액·마감잔액). 조작 — 월(YYYYMM)과 매장 검색으로 조회, [마감(재계산)] 버튼으로 입력한 달의 정산서를 다시 계산해 채웁니다. 같은 달을 여러 번 눌러도 값이 통째로 다시 계산되어 안전합니다(멱등).

실제 지급 시점(대기일·실행시각)은 정책의 "출금·정산 실행 정책"을 따르고, 정산통장은 정산통장 승인에서 승인된 것만 지급됩니다.

정산통장 승인 #/settle-accounts

목적 — 매장이 계좌 실명확인 + 1원 인증을 마친 정산통장을 최종 승인/반려합니다. 승인(ACTIVE)된 통장으로만 정산(출금)이 나갑니다. 통장 예금주가 사업자/대표자와 맞는지 확인하고 승인하세요. 정보가 맞지 않으면 반려(매장은 다시 인증·신청).

계좌 실명조회·1원 인증은 외부연동 스텁입니다.

현금영수증 #/cash-receipts

목적 — 전 매장이 발행한 현금영수증 내역을 한곳에서 봅니다. 국세청에는 익일 12시 이후 반영됩니다. 조작 — 상태 필터(결과 모름·발행완료·발행실패·취소완료·취소실패)와 검색으로 조회하고, 발행완료 건은 [취소]할 수 있습니다(사유 필수 · 감사 기록).

대리 발행 — 회원 문의로 대신 발행해야 할 때는 [거래 관리]에서 해당 결제 건의 [현금영수증] 버튼을 누릅니다. 취소는 전체 금액만 됩니다(부분취소 없음). 취소하면 그 결제 건은 다시 발행할 수 있습니다.

조치 필요 — 결과 모름(발행됐는지 알 수 없음)과 취소실패는 사람이 확인해야 하는 건입니다. [조치 필요만]으로 모아 볼 수 있고, 취소실패는 [취소]를 다시 누르면 재시도됩니다.

관리자 화면에서는 인증값(휴대폰·사업자번호)을 가리지 않고 원문으로 보여 줍니다. 국세청 문의·정정 때 뒤 4자리만으로는 동일인을 구분할 수 없기 때문입니다(앱 화면은 마스킹).

미결 건 #/vendor-pending

목적 — 발주사에 요청은 걸었는데 성공·실패가 확정되지 않은 건을 사람이 확인해 종결합니다. 다시 보내면 두 번 처리될 수 있어(이중 지급·이중 발행) 자동으로 재시도하지 않습니다.

먼저 [보냄] 칸을 보세요 — "나감"은 보냈는데 답을 못 받은 건, "모름"은 보내는 도중 멈춘 건입니다. 둘 다 발주사에 확인한 뒤 결과대로 [확인 후 종결] 하세요(처리됨 / 처리 안 됨).

현금영수증 — 발행 건을 [처리됨]으로 종결할 때는 발주사에서 받은 승인번호와 거래번호를 함께 적어야 합니다. 그래야 손님에게 보여 주고 나중에 취소할 수 있습니다. 종결은 모두 감사 장부에 남으므로 판단 근거를 반드시 적으세요.

6. 위험 관리

FDS 경보 #/fds-alerts

목적 — 이상거래 탐지에 걸린 건을 처리합니다. 처음에는 미처리 건부터 보여 줍니다(업무 큐). 조작 — 미처리 건은 [검토]·[조치]·[무혐의] 중 하나로 처리하며 처리 의견 입력이 필수입니다(감사 기록). 상단 [지금 탐지]로 켜진 룰을 즉시 한 번 돌릴 수 있고, 같은 주체의 미처리 경보가 이미 있으면 중복으로 쌓지 않습니다(여러 번 눌러도 안전).

상태 흐름: 미처리 → 검토됨 → 조치됨, 또는 무혐의(오탐). 오탐이 잦으면 FDS 룰에서 수치를 조정합니다.

FDS 룰 #/fds-rules

목적 — 이상거래 탐지 룰 8종의 수치(JSON)·동작·켬끔을 조정합니다. 값을 바꾸면 배포 없이 바로 다음 탐지부터 적용됩니다. 동작 — 차단(거래 자체 막음)·보류(일단 잡아 둠)·경보(통과시키되 경보만)·관찰만(기록만). 조작 — 각 행에서 이름·수치·동작·켬끔을 고치고 [저장].

주의 — 수치(JSON)는 적힌 예시 형식은 그대로 두고 숫자만 바꾸세요. 룰마다 꼭 필요한 항목이 정해져 있어 빠뜨리면 저장할 때 알려 줍니다. 처음엔 경보/관찰로 두고 오탐이 없는지 지켜본 뒤 차단으로 올리는 것을 권장합니다.

8종이 각각 무엇을 잡나요 — 화면 상단 안내 패널에도 같은 설명이 있습니다.

기본값은 8종 모두 켬 · 경보(ALERT) 입니다. 경보는 거래를 막지 않고 [FDS 경보] 에 쌓기만 하므로 정상 손님이 피해를 보지 않습니다.

이용제한 #/rate-limits

목적 — 로그인·가입·출금 등 민감한 동작의 호출 빈도 제한(무차별 시도 차단)을 조정합니다. 조작 — 각 동작 키마다 창(초)·최대 횟수·기준(IP/회원)·켬끔을 고치고 [저장]. "정한 초(창) 동안 이 횟수를 넘으면 잠시 막음"이라는 뜻이며, 바꾸면 바로 다음 요청부터 적용됩니다.

주의 — 너무 빡빡하면 정상 사용자도 막히니 실제 사용 패턴을 보며 조절하세요.

금액 무결성 #/integrity

목적 — 돈이 "1원도 어긋나지 않는지" 계속 검사한 결과를 봅니다. 워커가 한 시간마다 자동으로 네 가지 규칙을 대조합니다: ① 지갑 잔액 = 그 지갑 원장 순액(들어온 돈−나간 돈), ② 전체 원장의 차변 합 = 대변 합, ③ 거래마다 차변 = 대변, ④ 거래마다 수수료 금액 = 실제 원장에 적힌 수수료. 하나라도 어긋나면 "발견"으로 쌓입니다.

보는 법 — 위 검사 실행 이력은 언제 검사가 돌았고 몇 건 어긋났는지(정상(0) 또는 N건 발견)를 보여 줍니다. 아래 불일치 발견은 어긋난 건을 "기대값 vs 실제값" 문장으로 보여 주며, 상태 칩(미해결·조사중·해결·오탐)으로 거릅니다.

처리 — 발견을 눌러 [조사중](원인 파악 시작) → 원인을 찾아 각 업무 화면에서 바로잡은 뒤 [해결], 실제 오류가 아니면 [오탐]으로 종결합니다(사유는 인수인계·감사 근거로 남습니다). [지금 검사] 버튼으로 자동 주기를 기다리지 않고 즉시 한 번 돌릴 수 있습니다(몇 번 눌러도 안전).

함께 채워지는 것 — 하루 한 번 전날 일별 집계(충전·결제·출금·정산·선물·수수료 합계)와 지갑 잔액 스냅샷이 기록되어, 나중에 특정 날짜의 원장을 되짚을 때 검증 재개점으로 씁니다.

검사 결과 저장 — 모든 검사 실행은 integrity_check_runs(언제·무엇을·몇 건 어긋났는지)에, 발견된 불일치는 integrity_findings(기대 vs 실제·처리 상태)에 영구 저장됩니다. 지운 적이 없으므로 과거 어느 시점의 검사 결과든 다시 볼 수 있습니다.

매장별 매출 무결성 — 매장 관리 → 매장 상세 페이지 아래 "매출 무결성(대사)" 패널에서 그 매장의 지갑 잔액이 원장(받은 결제 − 취소 − 정산)과 맞는지 확인합니다. 같은 화면을 매장 사장님도 매장앱 매출 화면에서 봅니다(정상/점검 필요 배지). 어긋나면 해당 매장의 결제·취소·정산 흐름을 거래 관리에서 추적하세요.

시스템 오류 #/system-errors

목적 — 서버에서 발생한 오류(app_error_logs)를 한 건씩 보고 원인을 추적합니다. 대시보드의 "오류 모니터링"은 최근 24시간 건수만 보여 주고, 이 화면에서 실제 내용(무엇이·어디서·언제·추적키)을 확인합니다.

조작 — 심각도(CRITICAL=서버 결함 / ERROR)·소스(API·WORKER·BATCH) 필터와 메시지·코드·추적키 검색으로 거릅니다. 추적키(traceId)로 서버 콘솔 로그의 전체 스택과 대조해 원인을 찾습니다.

CRITICAL 은 실제 서버 결함(5xx)만 셉니다. 잘못된 메서드·형식 등 클라이언트 요청 실수(405/415/404)는 정상적인 4xx 응답으로 처리되어 여기 잡히지 않습니다.

7. 콘텐츠 · 고객지원

공통 — 공지·이벤트·배너·FAQ 는 게시(PUBLISHED) 상태 + 노출 기간 안인 것만 앱에 나갑니다. 작성중(DRAFT)·숨김(HIDDEN)·기간 밖은 앱에서 절대 보이지 않습니다(서버 SQL 로 강제). 등록·수정은 팝업 창에서, 삭제는 확인 창을 거칩니다.

공지사항 #/notices

목적 — 앱에 노출되는 공지사항(글)을 관리합니다(제목·본문 중심). 조작 — [+ 공지사항 등록], 상태·노출 대상(전체/회원앱만/매장앱만)·노출 기간 지정. 중요한 공지는 [무조건 표시]로 앱 메인 팝업(확인해야 사용)으로 띄울 수 있습니다.

이벤트 #/events

목적 — 앱에 노출되는 이벤트(이미지·링크 배너형)를 관리합니다. 조작 — 이미지를 올리고 링크를 넣으면 앱에서 이미지를 눌러 이동합니다(본문은 선택). 상태·노출 대상·노출 기간은 공지와 동일.

배너 #/banners

목적 — 앱 화면에 노출되는 배너를 관리합니다. 조작 — [+ 등록](위치·이미지·연결·순서·상태). 위치는 회원앱 홈·비로그인 화면·충전 화면·매장앱 홈 중 선택, 연결은 없음/공지로/이벤트로/외부 URL. 행에서 이미지 내려받기, 게시/숨김 전환, 삭제가 가능합니다.

배너는 등록·상태 전환·삭제만 있고 "내용 수정" 경로는 없습니다(다시 등록).

FAQ #/faqs

목적 — 자주 묻는 질문을 관리합니다. 조작 — [+ 등록]/행별 수정·삭제(분류·질문·답변·순서·상태).

1:1 문의 #/inquiries

목적 — 회원·매장이 보낸 문의를 확인하고 답변합니다. 미답변만 보기는 상태 필터에서 "미답변"을 고릅니다. 조작 — 미답변 건은 표의 [답변] 버튼으로 그 자리에서 빠르게 답하거나, 제목을 눌러 상세(#/inquiries/{번호})에서 전체 내용을 보고 답합니다. 답변을 등록하면 "답변됨"으로 바뀝니다.

답변 등록 시 앱 푸시 통지는 푸시 연동 완료 후 나갑니다.

파일·이미지 #/files

목적 — 앱·관리자에 올라온 모든 업로드 파일이 모이는 중앙 대장을 조회합니다(회원 프로필·공지 이미지·배너·문의 첨부·매장 서류). 조작 — 파일 이름 검색, "이미지만"·"미사용만" 필터, 이미지 미리보기, 내려받기, 삭제(미사용 파일만).

• 참조처 칸에 이 파일이 어디에 쓰이는지 표시됩니다. "미사용"은 아무 데도 안 쓰는 파일입니다.
• 사용 중 파일은 삭제 버튼이 잠깁니다(지우면 화면 이미지가 깨지므로 서버가 막음).
• 실물은 두 WAS 가 함께 바라보는 공유 폴더에 보관하고, 정보(이름·크기·형식)만 files 대장에 둡니다. WAS #1 의 파일 폴더를 WAS #2 가 함께 마운트합니다(발주사 확정 2026-08-11 — 오브젝트 스토리지 사용 불가). 폴더가 연결돼 있지 않으면 서버가 아예 켜지지 않습니다.

약관·방침 #/policy-docs

목적 — 이용약관·개인정보처리방침·탈퇴 안내 문서의 버전을 등록하고 시행합니다. 조작 — [새 버전 등록](종류·버전·시행일·본문 → 작성중으로 저장), 행의 [보기](본문 확인)·[시행]. 같은 종류는 시행 중인 버전이 항상 1개만 유지되며, 새 버전을 시행하면 기존 시행본은 자동으로 보관됩니다. 앱에는 "시행 중"인 최신본만 보입니다(DRAFT 미노출).

푸시 발송 #/push

목적 — 회원 전체·iOS·Android·매장 전체·개별 대상에게 알림을 보냅니다. 조작 — 제목(100자)·내용(500자)·대상·구분(정보성/광고성) 입력 후 [발송 접수](확인 창). 개별 지정이면 회원/매장 번호를 쉼표로 입력. 아래에 발송 이력(대상·구분·상태·성공/실패·보낸 관리자)이 쌓입니다.

• 접수하면 작업함(outbox)에 들어가고 워커가 30초 안에 발송을 시작합니다.
• 앱 알림함에는 항상 쌓이고, 폰 잠금화면 푸시는 푸시 설정을 완료해야 실제로 나갑니다(FCM 외부연동).
• 광고성 알림은 제목에 "(광고)"가 자동으로 붙고, 수신 동의자에게만·야간(21~08시)엔 아침으로 보류되어 나갑니다(법령 준수).

8. 운영

정책 관리 #/policies

목적 — 서비스 동작의 기준값을 관리합니다. 배포 시 기본값(전체 기본=GLOBAL)이 이미 들어 있으니 상황에 맞게 조정합니다. 비슷한 정책끼리 3개 묶음으로 그룹핑되어 있습니다.

범위(scope) — 전체 기본(GLOBAL)은 모든 회원·매장에 적용됩니다. 특정 회원/매장만 다르게 하려면 범위를 특정으로 고르고 "대상번호"에 그 번호를 넣습니다(전체 기본이면 대상번호는 비움). 조작 — [+ 추가]·행의 [수정]은 팝업에서 입력하며, 같은 자리(종류+범위+대상)에 저장하면 기존 값을 덮어씁니다(upsert). [삭제]도 가능(포인트 유효기간은 고정이라 수정만).

이 화면 상단에는 은행 점검시간 설정도 있습니다. 켜면 그 시간대에는 계좌 실명조회·1원 인증·출금 신청이 서버에서 막히고 앱에도 안내됩니다(매일 반복, 자정 넘는 구간도 가능).

모든 변경은 감사 장부에 남고, 정책은 이력이 자동 보존되어 "그 시점의 정책"이 증빙으로 남습니다.

알림 설정 #/notification-settings

목적 — NestPay 가 보내는 알림을 이벤트별로 켜고 끕니다. 조작 — 각 이벤트마다 발송 여부·채널·심각도를 고치고 [저장]. 채널은 앱 알림함 / 폰 푸시 / 둘 다. 폰 푸시 실발송은 푸시 설정을 완료해야 실제로 나갑니다(그 전에는 앱 알림함에만 쌓임). 심각도는 정보·경고·심각. 바꾸면 바로 다음 알림부터 적용됩니다.

푸시 설정 #/push-settings

목적 — 폰 잠금화면 푸시(FCM)에 필요한 값을 설정합니다. 조작 — Firebase 프로젝트 ID 입력, 서비스 계정 키(JSON) 파일 업로드, 폰 푸시 발송 켬/끔 후 [저장]. 세 값이 채워지면 준비 상태가 "준비 완료"로 바뀌고, 그때 발송을 켜면 됩니다. 화면 아래에 처음 설정하는 사람을 위한 단계별 안내(프로젝트 생성 → 앱 등록 → 키 내려받기 → 켜기)가 있습니다.

앱 안 알림함은 이 설정 없이도 동작하며, 이 설정은 "폰 잠금화면 푸시"를 켜는 것입니다. FCM 서비스 계정 키 실제 등록·발송은 외부연동입니다.

앱 게이트 #/app-gate

목적 — 강제 업데이트 최소버전·스토어 URL·점검 모드를 관리합니다.

9. 관리자 관리

관리자 계정 #/admins

목적 — 관리자 계정과 접근 허용 IP 를 관리합니다(모든 관리자 동등 — 누구나 관리 가능). 조작:

접근 허용 IP(아래 패널) — [+ IP 규칙 추가]로 IP/CIDR 을 등록합니다. 대상을 공통(모든 관리자)으로 두면 1차 관문이 되고, 특정 관리자를 지정하면 그 관리자에게만 적용되는 추가 제한이 됩니다. 행별 삭제 가능.

주의 — IP 를 잘못 넣으면 본인도 접속이 막힐 수 있습니다.

감사 기록 #/audits

목적 — 관리자들의 모든 조치(승인·반려·정지·정책 변경·민감정보 열람 등)를 남기는 장부입니다. 조작 — 조치·내용·사유·관리자 검색과 페이징으로 조회(관리자·조치·대상·내용·사유·IP·일시 표시). 사고·분쟁 시 "누가 언제 무엇을 했는지" 추적하는 증빙으로 씁니다.

무결성 — 추가만 되는(append-only) 장부라 수정·삭제 기능이 일부러 없습니다.

참고: 현재 코드 기준으로 감사 기록 메뉴·열람은 모든 관리자에게 동일하게 열려 있습니다(관리자 동등 정책). 화면 안내 문구 일부에 "root 전용"이라는 옛 표현이 남아 있으나 실제 동작과 다른 표기 잔재이며, 필요 시 문구 정리가 필요합니다.

10. 핵심 업무 절차

10-1. 매장 가입 승인

1. 매장이 매장앱에서 가입(또는 관리자가 매장 관리 → [+ 매장 등록]으로 사전 생성) → 상태 심사중(PENDING).
2. 매장 관리에서 상태 필터 "심사중"으로 대상 매장을 찾아 상호 클릭 → 매장 상세.
3. ② 필수 서류 패널에서 필요한 서류(예: 사업자등록증)를 요구하고, 매장이 올린 서류를 내려받아 확인합니다(요구 서류가 전부 제출되어야 승인 가능).
4. 정보가 부족하면 [보충요청](사유), 부적격이면 [반려](사유), 문제없으면 [승인] → 상태 정상(ACTIVE). 이때부터 결제·정산이 동작합니다.
5. (PG 를 쓰는 매장) ③ PG 연동 심사에서 연동 승인 → 매장이 샌드박스 3종 테스트 통과 → 매장 화이트IP 승인 → PG 신청 화면 또는 매장 상세에서 라이브 전환.

10-2. 정산 승인(월 정산 → 지급 통장)

1. 정산통장 승인에서 매장이 실명+1원 인증한 정산통장을 예금주 확인 후 [승인](승인된 통장으로만 정산 출금이 나감).
2. 정산 조회에서 대상 월(YYYYMM)을 입력하고 [마감(재계산)] → 그 달의 매장별 정산서가 계산됩니다(같은 달 재실행 안전 — 멱등).
3. 정산서의 지급액·마감잔액을 확인합니다. 실제 지급 시점은 정책 → 출금·정산 실행 정책(매장 기본 당일 등)을 따릅니다.
4. 실제 계좌 이체(펌뱅킹)는 외부연동 스텁 상태입니다.

10-3. 정책 수정(예: 수수료·한도)

1. 정책 관리에서 해당 정책 패널(수수료/한도/…)로 이동.
2. 전체에 적용하려면 [+ 추가]에서 범위=전체 기본(GLOBAL), 특정 회원/매장만 다르게 하려면 범위=특정 + 대상번호 입력.
3. 값을 넣고 저장하면 같은 자리(종류+범위+대상)에 덮어쓰기(upsert)됩니다. 기존 값을 바꾸려면 행의 [수정].
4. 저장 즉시 반영되며, 변경 내역은 감사 장부에 남고 정책 이력이 자동 보존됩니다.

10-4. 관리자 등록

1. 관리자 관리 → 관리자 계정 → [+ 관리자 등록]에서 아이디·이름 입력 → 생성(초기 비밀번호 123456).
2. 새 관리자에게 아이디와 초기 비밀번호를 전달합니다.
3. 새 관리자는 최초 로그인 1단계 후 OTP 등록 화면에서 인증앱(구글 OTP 등)에 QR/열쇠를 등록하고 6자리를 입력해 로그인합니다.
4. 필요하면 접근 허용 IP 패널에서 그 관리자 전용 IP 규칙을 추가합니다(공통 IP 관문은 이미 걸려 있어야 합니다).
5. 분실 대응 — 비밀번호 분실은 [비밀번호 초기화](123456), 인증앱 기기 분실·잠김은 [OTP 초기화].

11. 상태값 · 용어 · 외부연동 현황

11-1. 주요 상태값

11-2. 자주 나오는 용어

• 유상/무상 포인트 — 유상은 충전(입금) 포인트, 무상은 적립(리워드) 포인트. 출금·환불은 유상 잔액에서만 나갑니다.
• 단일 원장 — 모든 돈 이동을 한 장부(transactions)에 append-only 로 기록. 취소·환불·정산은 원장에 분개로 남습니다.
• 마스킹 — 이름·휴대폰·계좌·카드번호의 가운데를 가려 표시. 전체 열람은 사유 입력 후 단건으로만 가능하며 감사 기록에 남습니다.
• 멱등 — 같은 작업(예: 정산 마감)을 여러 번 실행해도 결과가 같아 안전함.
• 화이트IP — 미리 허용한 IP 에서 온 요청만 통과시키는 방식(관리자 콘솔·매장 PG open API 에 적용).

11-3. 외부연동 현황 (계약 전 스텁)

아래 기능은 화면·처리 흐름은 구현되어 있으나, 실제 외부기관 연동은 계약 후 진행되는 스텁 상태입니다. 관리자 조작 자체는 가능하되, 실물 결과(문자 수신·이체·폰 푸시 등)는 연동 완료 후 나갑니다.

• 휴대폰 본인인증(회원 가입·인증계좌 재등록 유도)
• 계좌 실명조회 · 1원 인증(정산통장 승인)
• 펌뱅킹 이체(미매칭 입금 반환, 정산·출금 실제 지급)
• FCM 폰 잠금화면 푸시(푸시 설정 완료 전까지 앱 알림함까지만 적재)

NestPay 산출물 · (주)페이네스트 · 작성일 2026-07-27 · 실제 코드/DB 기준 · 외부연동(펌뱅킹·본인인증·은행 실명조회)은 계약 전 스텁 상태임을 명시