Spec de módulo — fidelización (schema loyalty) - Softcrum Suite

Traducción. El inglés es la versión autoritativa: ../../../modules/loyalty/spec.md.

Entidades e invariantes

Tabla	Invariantes clave
programs	`program_id` en TODAS las tablas de loyalty desde la migración 1; nombrado por el tenant, CRUD completo, cantidad gateada por entitlement; programa por defecto auto-creado y resuelto cuando el request lo omite (ADR-021)
point_currencies	≥2 por programa: canjeable + estatus; nunca mezcladas (ADR-011)
ledger_transactions	append-only; tipos paramétricos earn\|redeem\|expire\|revoke\|adjust; pending→available tras la ventana de devolución del tenant
point_lots	consumo FIFO; expiración rolling\|end_of_month\|end_of_year, sobreescribible por nivel; escaneo de expiring_soon (cron fan-out)
contact_balances	proyección, MISMA transacción que la escritura del libro; reconciliación nocturna de drift (el add-on de frescura sube solo la frecuencia de la reconciliación)
rule_campaigns / rules	versionadas; AST de condiciones (JSON) + efectos; presupuestos totales y por contacto; publicar invalida la caché de reglas compiladas
rewards	`reward_types` paramétrico (extensible por tenant); `cost_points`; catálogo por programa
coupon_campaigns / coupon_codes	generación masiva de códigos únicos (F1b) o código genérico; estados issued→redeemed\|expired\|void
redemptions	padre/hijo desde el día 1; `Idempotency-Key` obligatorio; rollback a nivel de padre revert\|keep; `money_component` nullable (costura puntos + dinero, DEC-H3 — sin usar en F1)
stacking_rules	UI en F1b; política ALL vs PARTIAL; categorías de descuento y jerarquía; conjuntos no combinables
referral_codes / referral_conversions	recompensa doble liberada por evento calificante (primera compra PAGADA, nunca el registro); flags de fraude: auto-referido, velocidad, heurísticas de dispositivo/IP
tier_definitions / tier_memberships	`qualification_metric`: points_earned\|spend\|event_count; ventana rolling\|calendar; política de descenso explícita + período de gracia; `tier_overrides` (multiplicadores de acumulación, precios de recompensas, expiración) — schema día 1, UI F1b
badges / challenges	schema reservado, F2 (gamificación estratégica: goal-gradient, endowed progress)

Contrato del motor de reglas

Evento → condiciones (atributos de perfil, pertenencia a segmento o nivel, agregados, frecuencia) → efectos (rule_effect_types paramétrico, semillas is_system: award_points, issue_coupon, send_webhook, trigger_campaign; fila F2: apply_discount según DEC-H4). Los efectos se deduplican por (evento, regla) — idempotentes.

Eventos emitidos

points.earned|redeemed|expired|adjusted|revoked · points.expiring_soon · coupon.issued|redeemed|expired · referral.link_created|converted · tier.upgraded|downgraded

Endpoints (Runtime caliente: SLO <300 ms)

POST /v1/loyalty/redemptions (loyalty.redemptions.create) · POST /v1/loyalty/coupons/validate (loyalty.coupons.validate) · POST /v1/loyalty/qualifications (loyalty.qualifications.read) · GET /v1/loyalty/members/me (token de member) · CRUD de gestión: campañas, reglas, recompensas, niveles, referidos (loyalty.{resource}.{action})

⌘I