25 lines
1.3 KiB
Markdown
25 lines
1.3 KiB
Markdown
|
# 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.
|