패키지 / 선납권¶

이 페이지에서 찾을 수 있는 것

선납권 구매 / 선납권 충전 / 선납권 환불 / 패키지 구매 / 패키지 차감 / 보유 패키지 / 가족 대납 / 포인트 적립 / 포인트 사용 / Standard / Gold / VIP / 선납금 / 회차 차감 / 회차 취소 / 패키지 회차

선납권(prepaid package)은 환자가 미리 일정 금액을 충전하고, 추후 진료 시 그 잔액에서 차감하는 결제 수단입니다. 짱한의원 시스템에서는 선납권 = 패키지로 통합되어 있으며, 차트 좌측 "패키지 보유" 영역에서 잔여 회차/금액을 확인하고 사용합니다.

선납권 = 패키지 통합 정책 (중요)¶

꼭 기억하세요

선납권 구매 시 차트는 만들지 않습니다. 별도 선납권 구매 팝업에서 진행 (이중 매출 방지)
차트에는 이벤트 시술(슈링크 등)만 기록합니다
선납권 잔액/회차 관리는 차트 좌측 패키지 탭에서 확인합니다
환불 시 포인트는 전액 삭제, 사용한 시술은 정가 차감 (work-item 04-07 정책)

이 정책은 매출 이중집계를 방지하고, 선납권 흐름과 일반 진료 흐름을 분리합니다.

선납권 등급 (3단계)¶

등급	충전액	보너스 포인트	총 사용 가능
Standard	2,000,000원	200,000원 (10%)	2,200,000원
Gold	3,000,000원	360,000원 (12%)	3,360,000원
VIP	5,000,000원	750,000원 (15%)	5,750,000원

→ 등급이 높을수록 보너스 포인트 비율이 큼. 포인트는 진료비 결제 시 우선 차감됩니다 (2026-04-07 정책 변경).

화면 구성¶

선납권/패키지는 3개 화면에서 관리됩니다.

1. 차트 좌측 — 패키지 보유 영역 (표시 전용)¶

환자 차트 진입 시 좌측 패널 하단에 환자 보유 패키지/선납권 목록.

표시 항목	의미
패키지명	슈링크 5회 / 베이직탕 3개월 / 선납권 Standard 등
사용 회차	`사용횟수/총횟수회 사용` 형식 (예: `2/5회 사용` = 5회 중 2회 사용)
진행 상태	사용중(active, 초록) / 완료(completed) / 취소(cancelled)
만료일	사용 가능 마지막일 (있을 경우)

이 영역은 보유 현황 표시만

좌측 패키지 보유 영역은 사용 회차/상태 확인용 표시 영역입니다. 실제 회차 차감은 차트 우측 RightPanel의 "보유 패키지 사용" 버튼에서 진행합니다 (아래 #3 참조).

2. 선납권 구매 팝업 (`/popup/prepaid-purchase/:patientId`)¶

환자가 선납권 신규 구매 시 별도 팝업으로 진행.

Standard / Gold / VIP 카드 선택 (색상 구분)
구매 확정 → 자동으로 수납 팝업 오픈
결제 완료 시 자동으로 선납금 + 포인트 충전

3. 차트 우측 — "보유 패키지 사용" 버튼 (실제 차감 진입점)¶

차트 진입 후 우측 RightPanel(시술 입력 영역) 의 "보유 패키지 사용" 버튼이 회차 차감의 진입점입니다.

[차트 우측 패널]
  ┌─ 시술 입력 (오더 추가)
  ├─ ...
  └─ [보유 패키지 사용] ← 이 버튼 클릭
       ↓
       PackageUseModal 열림

PackageUseModal 동작: - 환자 보유 패키지 목록 표시 - 사용할 항목 선택 + 수량 입력 - 저장 → 자동 차감 (patient_packages.used_sessions +1, remaining_sessions 자동 -1) - 차트에 시술 항목으로 자동 추가 (선택)

자주 쓰는 동작¶

시나리오 1 — 선납권 신규 구매¶

환자가 선납권 Standard 200만원 구매

환자 차트 진입 → 우클릭 메뉴 → "선납권 구매"
별도 팝업 (/popup/prepaid-purchase/:patientId) 자동 열림
등급 선택 (Standard / Gold / VIP) — 색상 카드로 구분
구매 확정 버튼
자동으로 수납 팝업 오픈
결제 수단 선택 (카드 200만원) → 결제 처리
결제 완료 감지 → activate API 자동 호출
- payments INSERT (매출 인식)
- patient_prepaid_balance.prepaid_balance += 2,000,000원
- 자동 보너스 포인트 적립: point_balance += 200,000원
- 당일 미수가 있으면 자동 차감
차트 좌측 "패키지 보유"에 "선납권 Standard" 추가됨

구매 시 차트 만들지 않음

선납권 구매는 차트와 무관한 별도 흐름입니다. 일반 진료 차트와 섞이지 않게 설계되어 매출 이중집계를 방지합니다.

시나리오 2 — 선납권으로 진료비 결제¶

보유 선납금 50만원에서 진료비 39,000원 차감

차트 입력 + 저장 (오더: 슈링크 1000샷 39,000원)
수납 팝업 → 미수처리 탭
결제 수단 중 "선납권" 행에 39,000원 입력
자동으로 선납금/포인트 잔액에서 차감 (포인트 우선)
- 포인트 잔액 충분: 포인트에서 39,000원 차감
- 포인트 부족: 부족분만 선납금에서 차감
payments 테이블에 INSERT 안 됨 (이중매출 방지)
patient_prepaid usage 이력만 기록
차트 paid_amount 자동 갱신, reservation 수납완료 자동 전환

시나리오 3 — 패키지 회차 차감 (슈링크 5회 등) ⭐ 자주 쓰는 흐름¶

보유 슈링크 5회 패키지에서 1회 차감

환자 차트 진입
차트 우측 패널의 "보유 패키지 사용" 버튼 클릭 (좌측 패키지 영역 클릭 X — 표시 전용)
PackageUseModal 열림
사용할 항목 선택 (슈링크 1회) + 수량 1
사용 확정
자동 처리:
- patient_package_usages INSERT (회차 사용 이력)
- patient_packages.used_sessions += 1
- remaining_sessions (Generated Column) 자동 -1
- 차트에 시술 항목으로 자동 추가 (선택)
좌측 패키지 보유 표시: 1/5회 사용으로 갱신

시나리오 4 — 잘못 차감한 회차 취소¶

실수로 회차를 차감했을 때

환자 차트 → 우측 "보유 패키지 사용" 버튼 → PackageUseModal에서 사용 이력 확인 (또는 환자 검색 → 해당 환자 → 패키지 사용 이력)
잘못 차감한 이력 우측 "취소" 버튼
자동 처리:
- patient_package_usages.is_cancelled = 1 (soft delete)
- patient_packages.used_sessions -= 1
- remaining_sessions 자동 +1 (회차 복원)
- 재고 복원 (자동 출고된 항목이 있으면)
정합성 봇 9번 "패키지 음수 회차" 알림 자동 정리

시나리오 5 — 선납권 환불 (일부 사용한 환자)¶

Standard 200만 충전, 슈링크 5회 사용 후 환불 요청

선납권 환불 원칙 (work-item 04-07 정책):

차트 → 패키지 탭 → 선납권 Standard → "환불" 버튼
시스템 자동 계산:
- 포인트 전액 삭제 (예: 보너스 포인트 200,000원 → 0)
- 사용한 시술은 정가 차감 (예: 슈링크 1000샷 95,000 × 5회 = 475,000)
- 환불액 = 선납금 잔액 - 시술 정가
- 예: 충전 200만 - 사용 5회 정가 47.5만 = 환불 152.5만원
환불 결제 수단 선택 (현금/카드 환불)
처리 완료
- patient_prepaid refund 이력 INSERT (is_refund=1)
- payments INSERT (is_refund=1, refund_amount)
- 잔액 0으로 초기화
- patient_packages.status = 'cancelled'

시나리오 6 — 가족 대납 (어머니 선납권으로 자녀 진료비)¶

어머니 선납권으로 자녀 진료비 결제

자녀 차트 + 수납 팝업 진입
미수처리 탭 → "가족선납권조회" 버튼
어머니 환자 검색 → 어머니 보유 선납금/포인트 표시
어머니 선납금에서 자녀 진료비 차감
어머니의 patient_prepaid usage 이력에 "자녀 진료비" 메모 기록

권한별 차이¶

기능	권한
선납권 구매 등록	🟢 모든 직원
패키지 회차 사용 / 취소	🟢 모든 직원 (level 4 OK)
선납권 환불 (정책에 따라)	🟢 모든 직원
선납금 직접 충전 / 차감	🟢 모든 직원
선납권 패키지 마스터 추가/수정	🔴 Level 1~2 (병원 설정)
가족 대납	🟢 모든 직원

자동 검증 (정합성)¶

선납권/패키지는 매일 06:00 정합성 봇이 다음 항목을 검사합니다.

검사 번호	내용	처리 방향
4	선납금/포인트 잔액 마이너스	차트 → 패키지/선납권 탭에서 잘못된 사용/환불 이력 취소
8	선납권 잔액 불일치 (캐시 vs 이력)	🔴 #dev 문의 (이력 정정 동반 케이스)
9	패키지 음수 회차	차트 → 패키지 탭에서 잘못된 사용 이력 '취소' 클릭
13	차트에 선납권 패키지 혼입 (매출 이중집계 위험)	차트 진입 → 오더에서 "선납권" 항목 삭제
15 (신규)	선납권 차감했는데 시술 기록 없음	차트에 누락된 시술 항목 추가 또는 선납권 사용 취소

자주 발생하는 문제 / FAQ¶

Q1. 선납권 구매하려고 차트에 "선납권 Standard" 오더를 추가했어요. A. 잘못된 흐름입니다. 정합성 봇 13번 "차트에 선납권 패키지 혼입" 알림이 옵니다. 매출이 이중집계됩니다 (구매 결제 + 차트 청구액). → 차트에서 선납권 오더를 삭제하시고, 선납권 구매는 환자 우클릭 → "선납권 구매" 팝업으로 진행하세요.

Q2. 선납권 잔액이 마이너스가 됐어요. A. 정합성 봇 4번에 잡힙니다. 차트 → 패키지/선납권 탭에서 잘못된 사용 이력을 "취소"해서 잔액 0 이상으로 정상화하세요. 정상 환불 이력은 취소하지 마세요.

Q3. 패키지 잔여 회차가 -1로 표시돼요. A. 정합성 봇 9번에 잡힙니다. 차트 → 패키지 탭 → 잘못 사용된 이력 "취소"하시면 자동 복원됩니다 (patient_packages.used_sessions 감소 + 재고 복원).

Q4. 환불 처리했는데 환불액이 너무 적어요. A. 환불 정책상 사용한 시술은 정가로 차감됩니다. 예: 200만 충전했는데 정가 50만 시술을 받았으면 환불은 150만이 됩니다 (할인 받은 가격 기준이 아닌 정가). 환자에게 미리 안내 부탁드립니다.

Q5. 어머니 선납권으로 자녀 결제하면 어머니 잔액이 줄어드나요? A. 네. 어머니의 patient_prepaid_balance에서 차감되고, 어머니의 사용 이력에 "자녀 진료비" 메모와 함께 기록됩니다.

Q6. 선납권 충전 시 포인트가 자동 적립 안 됐어요. A. prescription_packages 마스터의 bonus_points 값을 확인하세요. 0이면 적립 안 됩니다 (병원 설정 > 패키지 관리에서 변경, Level 1~2).

Q7. 패키지 사용을 차트와 연동하고 싶어요. A. PackageUseModal에서 인하우스 환자라면 "차트 자동 반영" 체크박스가 있습니다. 체크하면 사용한 시술 항목이 당일 차트의 오더로 자동 추가됩니다.

Q8. 선납권 만료일이 지났어요. A. 시스템상 만료된 패키지는 자동으로 사용 불가 처리되며, 잔액도 expire 이력으로 정리됩니다. 환자 동의 하에 만료 전 환불을 권장합니다.

Q9. 진료비 결제 시 포인트와 선납금이 둘 다 있는데 어느 쪽이 먼저 차감되나요? A. 포인트 우선 차감입니다 (2026-04-07 정책 변경). 포인트 부족 시 부족분만 선납금에서 차감됩니다.

Q10. 선납권 구매 후 결제 안 했는데 잔액이 충전됐어요. A. 시스템 결함입니다. pending_payment 상태에서 activate API가 잘못 호출됐을 가능성이 있으니 #dev에 문의하세요.