인시던트 대응

실제 엔드포인트·증적과 수동 대응 절차를 안내합니다. PG 응답이 불확실한 환불은 즉시 다시 요청하지 말고 외부 처리 여부와 내부 기록을 먼저 확인하세요.

Recon 런북 (무결성 드리프트)

POST /api/v1/admin/reconciliation/run      # admin
GET  /api/v1/admin/reconciliation/reports  # 실행 목록
GET  /api/v1/admin/reconciliation/report/:id

각 finding에 대해:

1. Finding 타입 읽기 — 7개 검사는 대사에 열거되어 있습니다.
2. auto_fixed 항목 — 오래된 inbox/outbox 리스만; 후속 효과를 확인하고(재전달됐나? 여전히 실패하나?) 넘어가세요.
3. needs_review 항목 — 돈/entitlement 드리프트:
   • paid_no_entitlement → 누락된 라이선스를 발급하거나 첨부하거나, 환불.
   • unpaid_but_entitled → 결제를 수금하거나 라이선스를 폐기.
   • refunded_but_valid_entitlement → 라이선스 폐기(PATCH /licenses/:id {"status":"revoked"}).
   • subscription_expired_but_renewed → 갱신 주문 검사; 복원 또는 해소.
   • duplicate_issuance_per_payment → 라이선스 하나 유지, 나머지 폐기.
   • dead_letter/오래된 outbox → OUTBOX_SINK_URL 도달 가능성 확인, 리스 복구 경로 또는 수동 재구동으로 처리.
4. 결정 기록 — 자동 해결 워크플로는 없습니다; 운영자가 조치할 때까지 findings는 needs_review로 남습니다(SLA/담당자 없음 — 제한 사항 §4.14–4.15).

환불 인시던트 경로

POST /api/v1/orders/:id/refund            # 셀러 소유자
{ "amount_krw": 5000, "reason": "…" }     # 금액 선택적 → 남은 전액
GET  /api/v1/orders/:id/refund-attempts   # 감사 추적

• status:'succeeded' — 완료; ledger + license 보정 적용됨.
• status:'failed' — error_json 읽기(예: NO_PAYMENT_KEY, PAYMENT_KEY_INVALID, PG 오류); 원인을 조사하고 PG 취소 발생 여부를 확인한 뒤 새 요청 가능 여부를 판단하세요. 시도를 미리 기록했다는 사실만으로 재시도가 안전한 것은 아닙니다.
• status:'needs_review' — PG 호출 결과가 불확실; 시도는 의도적으로 환불됨으로 표시되지 않았습니다. PG 콘솔에서 확인한 후 수동으로 보정하세요. 스위퍼가 없습니다 — 이것은 여러분을 기다립니다.

라이선스 침해 경로

1. PATCH /api/v1/licenses/:id {"status":"revoked"} — 다음 가드된 호출에서 효과(라이브 행 재조회).
2. GET /api/v1/security-events?lic_id= — 리플레이(jti 재사용), jkt 이상, license_blocked 버스트 찾기.
3. GET /api/v1/licenses/:id/bindings + /usage — 바인딩된 디바이스와 실행을 리포트용으로 열거.
4. 대응의 일부로 키가 로테이션된 경우: 하드 컷오버입니다 — 진행 중인 entitlement는 120초 내 401로 죽습니다; 영향받는 셀러에게 재활성화를 알리세요.

결제 레일 인시던트

• 웹훅 스톰 / 무효 서명 — body는 절대 신뢰되지 않습니다; 공격을 가정하기 전에 TOSS webhook secret 설정을 확인하세요.
• 402 NOT_LIVE_PAYMENT 표면화 — 설정 드리프트: PAYMENT_LIVE_ENABLED 또는 프로바이더 불일치.
• 503 PAYMENT_PROVIDER_UNAVAILABLE — Portone은 미구현; 요청이 어쨌든 도달했습니다.

에스컬레이션 경계

• 실제 PG 분쟁/법적 항목은 플랫폼 범위 밖 — 외부 의존성은 제한 사항 §2에서 추적됩니다.
• 명시적 승인 없이 파괴적 작업(D1 리셋, 시드, 롤백)을 절대 실행하지 마세요 — charter 게이트됨.

금전 정합성 장애

증거 순서: GET /api/v1/admin/financial-integrity/summary → 예외 상세(이벤트 로그) → 복구 op 수명주기 → audit_evidence 행 → GET /api/v1/admin/audit/v2/verify(체인 건강).

증상	첫 조치
AUDIT_KEY_MISSING 500(prod checkout/refund/settle/ops)	NOUGAT_AUDIT_HMAC_KEY secret 미바인딩 — 설계된 fail closed예요. secret을 복구하세요. 오류를 하향하지 마세요. 비prod는 약해진 행 없이 방출을 skip해요.
/admin/audit/v2/verify가 ok:false	first_mismatch=첫 변조/재작성 행, link_breaks=끊긴 명시적 링크 수, sequence_gaps=태워진 순번(죽은 writer — 반드시 변조는 아님). DB는 증거이므로 보존하세요 — 제자리 복구 금지.
run이 running/degraded로 정체	heartbeat_at 확인 — stale run은 다음 recon이 failed로 회수해요. degraded=check ERROR/INCOMPLETE 존재 — 부분 커버리지예요.
연속 3회+ failed/미완주 run	audit_evidence의 alert:recon_failures 증적(외부 알림은 PLANNED) — recon 정전 장애로 취급하세요.
RESOLVED 후 REOPENED	지문 재발견 — 근본 원인 미해결이므로 TRIAGED부터 재개하세요. 재종결 금지.
verify 중 op FAILED	verification_json.verification.note가 미충족 기대를 명시해요 — 대상 상태를 바로잡고 새 op를 만드세요(FAILED는 종단).

전체 서피스: financial-integrity · reconciliation · refund · settlement · audit-evidence