콘텐츠로 이동

결제 운영 정책

문서 역할

  • 역할: 규범
  • 문서 종류: policy
  • 충돌 시 우선 문서: 결제 무결성·상태 전이·환불·정산은 이 문서, 관리자 역할·최대 접근 범위는 security-access-control-policy.md
  • 기준 성격: transition
    • 결제 무결성 규칙은 현행 기준이고, 관리자 역할·범위는 보안/접근통제 정책의 최종 기준을 사용한다.
    • 현행 Admin/API 인가와의 차이는 기술 부채 정리의 관리자 권한 서버 인가·표시 계약 미정렬에서 추적한다.

목적

  • 구매 회원 자격과 결제 검증/지급/환불/정산 흐름의 운영 기준을 단일화해 결제 회귀와 금전 리스크를 방지한다.

적용 범위

  • coupler-api, coupler-admin-web, coupler-mobile-app
  • 인앱 결제 처리(google, apple, onestore), 환불 상태 변경, 키 지급/회수, 결제 운영 점검

단일 SoT

구매 회원 자격과 거래 무결성 규칙은 기존·신규 세 플랫폼 인앱결제 operation에 적용하는 최종 상태다. 별도 transition 예외는 없으며, 관리자 역할·범위만 이 문서의 권한 전환 기준을 따른다.

필수 규칙

1) 구매 회원 자격

  • Mobile 회원의 구매 자격은 회원 생애주기 상태와 회원 레벨의 교집합으로 판정한다.
  • 회원 생애주기는 PENDING 또는 NORMAL이어야 한다.
  • 회원 레벨은 v_member_review_status.member_level 기준 GENERAL_MEMBER, SEMI_MEMBER, FULL_MEMBER, SPECIAL_MEMBER 중 하나여야 한다.
  • PENDING은 소개글 승인 전의 일반회원·준회원을 포함하므로 t_member.status = PENDING만으로 구매를 차단하지 않는다.
  • PRE_MEMBER, 비활성 생애주기(REJECTED, HOLD, BLOCK, LEAVE), 누락되거나 미정의인 회원 레벨은 fail-closed로 차단한다.
  • 레거시 t_member.level을 구매 자격 판정 기준으로 사용하지 않는다.

2) 거래 무결성 검증

  • order_id 기준 중복 거래 검증을 필수로 수행한다.
  • 중복 거래는 재지급하지 않고 기존 결과를 반환한다.
  • 결제 요청 파라미터 누락/불일치 시 즉시 실패시킨다.

3) 키 지급/회수 일관성

  • 결제 성공 시 t_iap, t_member.key, t_member_key_log를 동일 트랜잭션 경계에서 반영한다.
  • 환불로 NORMAL -> PENDING 전환 시 지급된 키 회수와 키 로그 기록을 함께 수행한다.
  • 회수량은 현재 보유 키를 초과할 수 없다.

4) 상태 전이 통제

  • 결제 상태 전이는 허용된 경로만 허용한다(PENDING <-> NORMAL).
  • 상태 변경 API는 권한 검증과 사유 입력을 필수로 강제한다.
  • 미정의 상태값/불일치 상태는 fail-closed로 차단한다.

5) 정산/운영 점검

  • 현재 Admin UI/API에는 별도 정산 행위가 없다. 이 절의 정산은 원천 거래와 기간별 집계를 대조하는 운영 점검을 뜻하며 신규 정산 기능 구현을 요구하지 않는다.
  • 일/주/월 집계 API 결과와 원천 거래 합계 차이를 정기 점검한다.
  • 환불/취소 반영 지연이 발생하면 원인과 복구 절차를 릴리스 노트에 기록한다.
  • 운영 장애 발생 시 롤백 기준 태그와 데이터 복구 범위를 함께 남긴다.

6) 관리자 조회·변경 범위

  • Super Admin은 결제 로그, 매출 집계와 무료키 지급 이력을 GLOBAL로 조회한다.
  • 일반 클럽매니저는 현재 로그인 관리자에게 전담(CHARGE) 배정된 회원의 결제 로그, 매출 집계와 무료키 지급 이력만 ASSIGNED로 조회한다. 공유(SHARE) 배정은 결제 조회 범위에 포함하지 않는다.
  • 결제 상태 변경과 환불은 Super Admin은 GLOBAL, 일반 클럽매니저는 현재 CHARGE 배정 회원 결제의 ASSIGNED 범위에서 수행한다.
  • 목록 조회는 위 범위로 필터링하고 상세·상태 변경 operation은 대상 결제의 회원 배정을 다시 확인한다.

권한 전환 기준

  • 이 문서의 결제 규칙은 현행으로 유지하고, 관리자 역할·범위만 보안/접근통제 정책의 전환 생명주기를 따른다.
  • 현행 Admin/API가 위 범위와 다르면 기존 기능의 완료 범위를 소급 변경하지 않고 기술 부채 정리의 관리자 권한 서버 인가·표시 계약 미정렬에서 추적한다.
  • 전환 완료 조건은 일반 클럽매니저의 CHARGE 결제 조회·상태 변경만 허용되고 SHARE·타 전담 직접 요청과 상태 변경이 거부되며, Super Admin·일반 클럽매니저·타 담당자 회귀 테스트가 같은 결론을 검증한 상태다.

현재 정책 범위 밖 항목

  • 플랫폼별 추가 영수증/서명 검증 방식과 서버 연동 여부는 현재 정책 범위에 포함하지 않는다.
  • 해당 항목은 필요성과 운영 기준이 합의된 뒤 별도 정책 또는 본 문서 개정으로 반영한다.

운영 절차

  1. 배포 전: 일반회원 이상 허용, 회원전·비활성 회원 차단, 중복 거래 차단과 환불 회수 시나리오를 확인한다.
  2. 권한 검증: Super Admin 전체 조회·상태 변경, 일반 클럽매니저 CHARGE 조회·상태 변경, SHARE·타 전담 조회·상태 변경 거부를 확인한다.
  3. 배포 직후: 핵심 시나리오(신규 결제/중복 결제/환불)를 실행 검증한다.
  4. 일상 운영: 결제 통계와 원천 데이터의 차이를 모니터링한다.
  5. 이상 징후: 지급 중복/정산 불일치 발견 시 즉시 지급 차단 또는 롤백을 실행한다.
  6. 사후 조치: 장애 원인/영향/복구 결과를 릴리스 노트와 정책 근거에 반영한다.

증빙/추적

  • PR/작업 보고에 아래를 필수로 남긴다.
    • 결제 검증 시나리오 결과(성공/실패 케이스)
    • 상태 전이 및 키 지급/회수 로그 경로
    • 릴리스 태그/롤백 기준
  • 운영 변경 시 관리자 액션 사유와 수행자 식별자를 감사 가능하게 보관한다.

체크리스트

  • [ ] PENDING/NORMAL + GENERAL_MEMBER 이상만 구매할 수 있고 PRE_MEMBER와 비활성 회원은 차단되는가?
  • [ ] t_member.status = PENDING인 일반회원·준회원의 구매가 허용되는가?
  • [ ] 중복 거래 차단 후 재요청 시 재지급이 발생하지 않는가?
  • [ ] 환불 시 상태 전이, 키 회수, 로그 기록이 동시에 반영되는가?
  • [ ] 일반 클럽매니저는 CHARGE 회원의 조회·상태 변경만 허용되고 SHARE·타 전담 조회·상태 변경은 거부되는가?
  • [ ] 정산 집계와 원천 거래 합계 차이에 대한 점검 결과가 있는가?
  • [ ] PR/릴리스 노트에 결제 검증 증빙과 롤백 기준이 기록되었는가?

관련 문서