> ## Documentation Index
> Fetch the complete documentation index at: https://internal.softcrum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Módulo — Fidelización (LOY)

> Programas, libro de puntos, motor de reglas, recompensas, cupones, referidos y niveles. Schema loyalty. Depende de core; nunca de messaging ni de crm.

> **El inglés es la versión autoritativa.** Esta traducción existe para que cualquier persona
> pueda leer y revisar el módulo completo. Ante cualquier discrepancia, manda
> [`../../../modules/loyalty/`](/modules/loyalty/overview). Ambas versiones comparten `version` y
> `status`, y el validador falla si se separan.

| Documento                                                                                                           | Propósito                                                                 |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [`prd.md`](/es/modules/loyalty/prd)                                                                                 | Qué es el módulo, para quién, qué NO hace, éxito, modelo comercial, fases |
| [`spec.md`](/es/modules/loyalty/spec)                                                                               | La forma técnica viva: entidades, invariantes, eventos, endpoints         |
| [`features/`](https://github.com/softcrumlabs/softcrum-suite/tree/master/docs/internal/es/modules/loyalty/features) | Los feature specs — las unidades de entrega                               |

## Hoja de ruta

Catorce entregas, cortadas por incrementos que se pueden lanzar solos, no por tablas.
Seis de ellas componen F1a.

| FS                                                                              | Feature                                     | Fase | Depende de | Estado  |
| ------------------------------------------------------------------------------- | ------------------------------------------- | ---- | ---------- | ------- |
| [FS-LOY-0001](/es/modules/loyalty/features/fs-loy-0001-programs-and-currencies) | Programas y monedas de puntos               | F1a  | —          | `draft` |
| [FS-LOY-0002](/es/modules/loyalty/features/fs-loy-0002-points-ledger)           | Libro de puntos y lotes FIFO                | F1a  | 0001       | `draft` |
| [FS-LOY-0003](/es/modules/loyalty/features/fs-loy-0003-balance-projection)      | Proyección de saldo y reconciliación        | F1a  | 0002       | `draft` |
| [FS-LOY-0004](/es/modules/loyalty/features/fs-loy-0004-rules-engine)            | Motor de reglas — condiciones y efectos     | F1a  | 0002       | `draft` |
| [FS-LOY-0005](/es/modules/loyalty/features/fs-loy-0005-rewards-catalog)         | Catálogo de recompensas                     | F1a  | 0001       | `draft` |
| [FS-LOY-0006](/es/modules/loyalty/features/fs-loy-0006-redemptions)             | Canjes — padre/hijo, idempotentes, rollback | F1a  | 0002, 0005 | `draft` |
| [FS-LOY-0007](/es/modules/loyalty/features/fs-loy-0007-coupons)                 | Cupones y generación masiva de códigos      | F1b  | 0004       | `draft` |
| [FS-LOY-0008](/es/modules/loyalty/features/fs-loy-0008-stacking-rules)          | Reglas de acumulación de beneficios         | F1b  | 0006, 0007 | `draft` |
| [FS-LOY-0009](/es/modules/loyalty/features/fs-loy-0009-referrals)               | Referidos — doble recompensa y antifraude   | F1b  | 0004       | `draft` |
| [FS-LOY-0010](/es/modules/loyalty/features/fs-loy-0010-tiers)                   | Niveles y ventanas de calificación          | F1b  | 0002       | `draft` |
| [FS-LOY-0011](/es/modules/loyalty/features/fs-loy-0011-expiring-points)         | Puntos por vencer y escaneos de retención   | F1b  | 0002       | `draft` |
| [FS-LOY-0012](/es/modules/loyalty/features/fs-loy-0012-gamification)            | Gamificación — insignias y desafíos         | F2   | 0010       | `draft` |
| [FS-LOY-0013](/es/modules/loyalty/features/fs-loy-0013-apply-discount)          | Efecto `apply_discount`                     | F2   | 0004, 0008 | `draft` |
| [FS-LOY-0014](/es/modules/loyalty/features/fs-loy-0014-wallet-passes)           | Wallet passes (Apple y Google)              | F2   | 0010       | `draft` |

## El corte, explicado

La descomposición sigue una sola prueba: **¿esto se puede lanzar solo y vale algo?**

* Libro de puntos y saldos van separados (`0002`, `0003`) porque el libro es la fuente de verdad
  y la proyección es una decisión de rendimiento. Fallan distinto y se verifican distinto.
* El motor de reglas (`0004`) es independiente del catálogo (`0005`): un programa puede acreditar
  puntos mucho antes de tener en qué gastarlos.
* Los canjes (`0006`) necesitan ambos, y por eso cierran F1a.
* La acumulación de beneficios (`0008`) deliberadamente **no** vive dentro de cupones: es una capa
  de política sobre canjes y cupones a la vez, y meterla en cualquiera de los dos habría producido
  un spec imposible de aprobar.

## Costuras reservadas en F1

Presentes desde la primera migración, deliberadamente sin usar, para que habilitarlas después no
requiera ninguna migración de datos:

| Costura                                           | Reservada para                                                      | Decisión |
| ------------------------------------------------- | ------------------------------------------------------------------- | -------- |
| ~~`program_id` + programa por defecto invisible~~ | **se entrega en F1** — multi-programa es capacidad de primera clase | ADR-021  |
| `money_component` nullable en canjes              | canje mixto puntos + dinero                                         | DEC-H3   |
| Catálogo paramétrico abierto `rule_effect_types`  | `apply_discount` en F2                                              | DEC-H4   |
| Schema de `badges` / `challenges`                 | gamificación en F2                                                  | spec.md  |