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

# Spec de módulo — customer-core (schema core)

> Es dueño del contacto, su identidad, su comportamiento, su consentimiento y las tablas transversales de plataforma. Nadie más es dueño del contacto.

> Traducción. Autoritativo: [`../../../modules/core/spec.md`](/modules/core/spec).

## Entidades e invariantes

| Tabla                                                        | Invariantes clave                                                                                                                                                                      |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contacts                                                     | `contact_kind` person\|company; documento normalizado + único parcial por (tenant, tipo, id); campos base + atributos personalizados tipados; company ⇒ `legal_name`, sin `birth_date` |
| contact\_identities                                          | (proveedor, identificador) único por tenant; promoción anónimo→conocido; flag `verified`                                                                                               |
| contact\_merges                                              | inmutable; el superviviente conserva todas las identidades y eventos; la fusión emite `contact.merged`                                                                                 |
| consents                                                     | una fila por (contacto, canal, cambio de estado) — historia, nunca sobreescritura; prueba y `captured_at` obligatorios                                                                 |
| tracked\_events                                              | append-only, particionada mensualmente; `idempotency_key` único por tenant; `correlation_id` obligatorio                                                                               |
| segments / segment\_members                                  | DSL v1 (ADR-012); historia de membresía `entered_at`/`exited_at`; flag `nightly_only`                                                                                                  |
| attribute\_definitions                                       | tipadas (string, number, date, bool, enum); alimentan el constructor de segmentos y la validación Zod                                                                                  |
| event\_taxonomies                                            | plantillas verticales COMO DATOS; instalables por tenant; la primera: suscripciones y servicios                                                                                        |
| national\_id\_types, currencies, notification\_channels      | catálogos paramétricos transversales                                                                                                                                                   |
| audit\_log, usage\_snapshots, processed\_jobs, dead\_letters | tablas de plataforma (estándares data.md / jobs.md)                                                                                                                                    |

## Eventos emitidos

contact.created|updated|merged · consent.granted|revoked · event.tracked · segment.entered|exited

## Endpoints (cada uno con su permiso — DEC-D5)

* `POST /v1/core/track|identify|batch` → `core.events.write` (Runtime, fast-ack 202)
* `GET/POST/PATCH /v1/core/contacts[...]` → `core.contacts.read|create|update`; lectura completa del
  documento → `core.contacts.read_national_id`
* `POST /v1/core/contacts/{id}/erasure` → `core.contacts.erase` (ARCO; ≤30 días automatizado,
  anonimización del libro de puntos)
* `GET /v1/core/contacts/{id}/export` → `core.contacts.export` (portabilidad ARCO)
* CRUD `/v1/core/segments` → `core.segments.*` · `POST /v1/core/auth/token-exchange` (según ADR-010)
* Importación: `POST /v1/core/imports` (CSV) → las filas con documento duplicado caen en la cola de
  fusión sugerida (DEC-A6)

## No negociables

La resolución de identidad y las fusiones ocurren SOLO aquí. `messaging` verifica consentimientos;
solo aquí se ESCRIBEN. Supresión = borrar perfil y eventos, anonimizar las referencias del libro de
puntos (tombstone), exportando antes si se solicitó.