금전 정합성 운영

recon finding, 예외, 복구 연산을 위한 admin 전용 운영 서피스예요. 모든 엔드포인트는 admin 역할 JWT가 필요해요(production 설정에서 x-dev-user dev 신원은 절대 인정되지 않아요). Cloudflare 워커(be-cloudflare)에 구현돼 있어요 — Axum 백엔드에는 대응 서피스가 없어요.

API 서피스

요약 + 예외

http

GET  /api/v1/admin/financial-integrity/summary
GET  /api/v1/admin/financial-integrity/exceptions[?status=]
GET  /api/v1/admin/financial-integrity/exceptions/:id          # append-only 이벤트 로그 포함
POST /api/v1/admin/financial-integrity/exceptions/:id/transition
     {to_status, reason, note?, operation_id?, correlation_id?}

예외 상태기계(transition_allowed 강제, 마이그레이션 022):

OPEN → TRIAGED → INVESTIGATING → AWAITING_APPROVAL → REMEDIATING
     → REVERIFYING → RESOLVED | REOPENED
BLOCKED — 비종단 상태 어디서든 진입/해제
CLOSED_AS_FALSE_POSITIVE — 종단(운영자 오탐 확정)
REOPENED — 엔진 지문 재발견 또는 검증 실패

모든 전이는 reason 필수 — reconciliation_exception_events에 append-only로 기록돼요.
RESOLVED는 REVERIFYING + 산출 check가 지문 미관측으로 완주할 때만 도달해요.
지문 dedup: sha256(check_name|entity_type|entity_id|finding_code) — 재발견은 새 행이 아니라 occurrence_count 증가예요.

복구 연산

http

GET  /api/v1/admin/financial-integrity/operations[?status=]
POST /api/v1/admin/financial-integrity/operations
GET  /api/v1/admin/financial-integrity/operations/:id
POST /api/v1/admin/financial-integrity/operations/:id/approve
POST /api/v1/admin/financial-integrity/operations/:id/execute
POST /api/v1/admin/financial-integrity/operations/:id/verify

status: DRAFT → PENDING_APPROVAL → APPROVED → EXECUTING → VERIFIED | FAILED | CANCELLED
금전 영향 op은 actor ≠ approver 승인 필수(403 SELF_APPROVAL_DENIED). 읽기 전용 재확인(RECHECK_PROVIDER_REFUND, RUN_RECON_VERIFY)은 자동 승인이에요.
idempotency_key UNIQUE — 재제출은 기존 연산 재생. execute/verify는 CAS로 이중 집행 방지.
내부 복구는 새 외부 PG capture/cancel을 절대 호출하지 않아요 — GET 조회만.
execute/verify마다 recovery.execute/recovery.verify 증적이 체인 봉인돼요 (audit-evidence 참조).

정산 admin

http

POST /api/v1/admin/settlements/sweep
POST /api/v1/admin/settlements/:id/mark-paid   {payout_ref}

금전 정합성 운영 ​

API 서피스 ​

요약 + 예외 ​

복구 연산 ​

정산 admin ​

금전 정합성 운영

API 서피스

요약 + 예외

복구 연산

정산 admin