# IT operations — billing and Stripe webhook (Phase 4 outline)

**Schema:** [`config/it-operations/entitlements-schema.sql`](../../config/it-operations/entitlements-schema.sql)  
**Spec:** [SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md](../02-architecture/SANKOFA_IT_OPERATIONS_CONTROLLER_SPEC.md) sections 3.4 and roadmap Phase 4.

## Model

- **`entitlement`** rows represent seats/SKUs bound to an `org_id`, optionally linked to **`dbis_core`** via `external_sku_id` (mirror `IruOffering` or catalog id).
- **`usage_snapshot`** rows are appended by a nightly Proxmox metering job (VMID → vCPU/RAM/disk).
- **`stripe_webhook_event`** stores raw events for idempotency (`id` = Stripe `event.id`).

## Webhook handler (future BFF)

1. Verify signature with `STRIPE_WEBHOOK_SECRET`.
2. On `customer.subscription.updated` / `deleted`, upsert **`entitlement`** (`valid_to`, `seat_count`, `stripe_subscription_id`).
3. Mark event **`processed`**; on failure store **`error`** for replay.

## Keycloak

- Map paid SKUs to optional group claims (e.g. `sankofa-it-admin` only via HR-approved assignment; billing does not auto-grant super-admin).

## Finance export

- Nightly job: aggregate **`usage_snapshot`** + open **`entitlement`** → CSV or QuickBooks/NetSuite API — out of scope for v1 code in this repo; schema supports it.