> ## 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.

# Taxonomías verticales de eventos

> Cuando esto se entregue, un negocio de suscripción partirá con invoice_paid, payment_late y service_anniversary ya definidos, en vez de una página en blanco y una discusión de nombres.

> Traducción. Autoritativo: [`fs-core-0012-event-taxonomies.md`](/modules/core/features/fs-core-0012-event-taxonomies).

## Contexto

Lo más difícil de adoptar una plataforma de engagement no es la integración: es decidir qué enviar.
Un schema de eventos en blanco significa que cada tenant inventa su propio vocabulario, de forma
inconsistente, y luego sus segmentos y reglas heredan esa inconsistencia para siempre.

DEC-H7 hace de las taxonomías **datos instalables, nunca código**. Eso es lo que permite que el
producto aplique a cualquier industria y a la vez dé a cada una un punto de partida, y lo que
convierte un vertical nuevo en un ejercicio de contenido y no en un release. La primera es
suscripciones y servicios, porque ahí está el design partner (DEC-I6).

Las plantillas RFM que acompañan a una taxonomía importan tanto como los nombres de eventos:
convierten "ahora recolectamos eventos" en "estos son tus clientes en riesgo" desde el primer día.

## Alcance *(normativo)*

* `core.event_taxonomies`: conjuntos nombrados, versionados e instalables.
* `core.event_definitions`: nombre de evento, descripción, propiedades esperadas con sus tipos.
* Instalación por tenant, aditiva y no destructiva.
* Validación de las propiedades de eventos entrantes contra la definición instalada.
* Plantillas de segmentos RFM preconstruidas por taxonomía.
* La taxonomía de suscripciones y servicios como primer conjunto entregado.

## Fuera de alcance *(normativo)*

* **Rechazar eventos que no estén en la taxonomía.** La validación advierte; nunca bloquea la
  ingesta. Una integración que se rompe porque alguien envió un evento no declarado es peor que un
  schema laxo.
* La UI del asistente de onboarding — `frontend/console`.
* Taxonomías creadas por un tenant y publicadas a otros. No es un marketplace.

## Comportamiento *(normativo)*

1. Una taxonomía es **versionada e inmutable una vez publicada**. Instalar la versión 2 es un acto
   explícito, nunca automático, porque puede cambiar lo que la validación espera.
2. La instalación es **aditiva**: agrega las definiciones que el tenant no tiene y nunca sobreescribe
   una que él haya personalizado.
3. Un tenant puede extender una taxonomía instalada con sus propias definiciones, y puede partir en
   blanco sin ninguna taxonomía.
4. La validación de propiedades contra una definición **advierte, nunca bloquea**. Una discrepancia
   se muestra en la consola y se registra, y el evento igual se ingiere y sigue siendo utilizable.
5. Quitar una definición nunca quita los eventos ya recolectados bajo ella.
6. Las plantillas RFM se instalan junto a su taxonomía como definiciones de segmento normales que el
   tenant puede leer y editar — son un punto de partida, no una caja negra.
7. Una taxonomía es dato: agregar un vertical significa agregar filas, y **no requiere deploy**.
8. Los nombres de eventos siguen la convención de la plataforma sin importar el origen: minúsculas,
   snake\_case, tiempo pasado cuando describen algo que ocurrió.

## Datos *(normativo)*

| Tabla                    | Invariantes clave                                                                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core.event_taxonomies`  | `code` único; `label`; `version`; `is_system`; inmutable una vez publicada                                                                                                                |
| `core.event_definitions` | FK taxonomía nullable (null = creada por el tenant); `tenant_id` nullable (null = de sistema); `event_name`; `description`; `properties` esquema JSONB; único (`tenant_id`, `event_name`) |

## API *(normativo)*

| Endpoint                                    | Clase      | Permiso                                         | Presupuesto |
| ------------------------------------------- | ---------- | ----------------------------------------------- | ----------- |
| `GET /v1/core/taxonomies`                   | Management | `core.taxonomies.read`                          | p95 \<1 s   |
| `POST /v1/core/taxonomies/{code}/install`   | Management | `core.taxonomies.install`                       | p95 \<5 s   |
| `GET/POST/PATCH /v1/core/event-definitions` | Management | `core.event_definitions.{read\|create\|update}` | p95 \<1 s   |

## Eventos *(normativo)*

Ninguno. La instalación es administrativa y queda cubierta por la auditoría.

## Criterios de aceptación *(normativo)*

1. Instalar la taxonomía de suscripciones y servicios crea sus definiciones y sus plantillas de
   segmento RFM en una sola operación.
2. Reinstalar es idempotente y no sobreescribe una definición personalizada por el tenant.
3. Un evento cuyas propiedades no calzan con su definición **igual se ingiere**, y la discrepancia
   queda registrada y visible.
4. Un tenant puede operar sin ninguna taxonomía instalada y definir eventos por su cuenta.
5. Quitar una definición deja consultables los eventos históricos.
6. Agregar una taxonomía vertical nueva requiere solo filas — probado agregando una en un test sin
   cambio de código.
7. **Negativo:** la instalación nunca borra ni sobreescribe una definición existente del tenant.

## Ejecución

Un solo slice, comando síncrono. F1b. El contenido de las taxonomías vive en semillas; la instalación
es una copia transaccional hacia las definiciones del tenant.

## Preguntas abiertas

| # | Pregunta                                                                                          | Decide | Para             |
| - | ------------------------------------------------------------------------------------------------- | ------ | ---------------- |
| 1 | ¿Qué vertical se entrega segundo — retail, o salud y servicios? (pregunta 1 del PRD)              | Daniel | antes de aprobar |
| 2 | ¿Un tenant puede instalar dos taxonomías a la vez, y cómo se resuelven las colisiones de nombres? | Daniel | antes de aprobar |

## Changelog

| Versión | Fecha      | Cambio           | Por qué | Autor                  |
| ------- | ---------- | ---------------- | ------- | ---------------------- |
| 0.1.0   | 2026-08-17 | Borrador inicial | —       | daniel + claude-opus-5 |

## Registro de entrega

*Aún no implementado.*