> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/analytics/es/iot-query/schema-overview/bronze-layer/bdr.md).

# Esquema BDR

BDR organiza dispositivos y entidades de negocio en activos, con campos personalizados, relaciones y trazas de auditoría. Revise la definición del esquema y las descripciones clave de las tablas

{% hint style="warning" %}
**Este esquema está actualmente en desarrollo.** BDR (Repositorio de datos de negocio) organiza los datos alrededor de los activos: una combinación unificada de un dispositivo y una entidad de negocio, como un vehículo y su conductor, o un dispositivo y sus sensores. IoT Query lee de BDR para exponer estos datos para el análisis. Si está interesado en acceso anticipado o tiene preguntas sobre esta funcionalidad, comuníquese con <iotquery@navixy.com>.
{% endhint %}

BDR proporciona un marco integral para administrar estructuras organizacionales, actores, dispositivos, activos y sus relaciones en entornos multiinquilino. Construido sobre PostgreSQL 18 con las `ltree` y `pg_trgm` extensiones, el esquema admite organizaciones jerárquicas, definiciones de Campos personalizados para cualquier tipo de entidad, control de acceso basado en papeles de actores con restricciones a nivel de objeto, bloqueo optimista para ediciones simultáneas y registros de auditoría completos con seguimiento de cambios a nivel de campo. Todas las entidades pueden ampliarse sin modificaciones al esquema, localizarse para implementaciones internacionales y vincularse mediante relaciones polimórficas flexibles.

El esquema aborda escenarios complejos de administración de datos, incluidas jerarquías de activos de flota en distintos niveles organizacionales, plataformas SaaS multiinquilino que requieren aislamiento de datos, operaciones impulsadas por cumplimiento normativo con requisitos detallados de auditoría y sistemas que necesitan modelos de datos dinámicos adaptables mediante Campos personalizados en lugar de migraciones de base de datos.

{% hint style="info" %}
El diagrama interactivo del esquema de datos BDR está disponible en **dbdiagram.io**: <https://dbdiagram.io/d/Navixy-Repo-data-schema-68ad788c1e7a611967a0930e>
{% endhint %}

Encuentre los detalles del esquema BDR a continuación.

{% code title="esquema de datos BDR" expandable="true" %}

```sql
// ============================================
// Esquema BDR (Business Data Repository) - recorrido del cliente
// PostgreSQL 18 con las extensiones ltree, pg_trgm
// Versión: 2.2
// ============================================

// ============================================
// TABLAS DE REFERENCIA BASE (jerarquía ci_base - herencia de una sola tabla)
// ============================================

Tabla ci_base {
  id uuid [primary key, note: 'código de tipo de entidad de 4 caracteres incrustado en los bytes 5-8 del UUID, extraído mediante uuid_type_code()']
  code text [not null, note: 'Código legible por máquina, debe comenzar con una letra']
  title_en text [not null, note: 'Intercalación sin distinción de mayúsculas/minúsculas (ICU)']
  description_en text
  order int [not null, default: 0]
  is_system boolean [not null, default: false]
  discriminator text [not null, note: 'Se completa automáticamente a partir del id mediante trg_ci_set_discriminator']
  catalog_id uuid [note: 'Catálogo padre para los elementos del catálogo de usuario. NULL para los catálogos del sistema y las propias definiciones de catálogo']
  organization_id uuid
  parent_id uuid
  path ltree [note: 'Mantenido automáticamente por un trigger cuando is_hierarchical = true']
  is_hierarchical boolean [not null, default: false]
  extra jsonb [not null, default: `{}`]
  version int [not null, default: 1, note: 'Bloqueo optimista']
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz

  índices {
    (id) [name: 'idx_ci_active', note: 'parcial: WHERE deleted_at IS NULL']
    (parent_id) [name: 'idx_ci_parent']
    (path) [type: gist, name: 'idx_ci_path_gist']
    (catalog_id) [name: 'idx_ci_catalog']
    (organization_id) [name: 'idx_ci_org']
    (discriminator) [name: 'idx_ci_discriminator']
    (title_en) [name: 'idx_ci_title_en']
    (discriminator, code) [único, nombre: 'uq_ci_code_discriminator']
    (catalog_id, code) [único, nombre: 'uq_ci_code_catalog']
  }
}

Tabla ci_module {
  id uuid [clave primaria]
}

Tabla ci_catalog_category {
  id uuid [clave primaria]
}

Tabla ci_country {
  id uuid [clave primaria]
}

Tabla ci_papel {
  id uuid [clave primaria]
}

Tabla ci_entity_type {
  id uuid [clave primaria]
  uuid_discriminator char(4) [no nulo, nota: 'código de 4 caracteres incrustado en los UUIDs de las entidades']
  is_customizable boolean [no nulo, predeterminado: true, nota: 'Si las entidades de este tipo admiten Campos personalizados']
}

Tabla ci_device_status {
  id uuid [clave primaria]
}

Tabla ci_permission_scope {
  id uuid [clave primaria]
  module_id uuid [no nulo]
  entity_type_id uuid [no nulo]
  category text [no nulo]
}

Tabla ci_device_vendor {
  id uuid [clave primaria, nota: 'Fabricantes/proveedores de dispositivos']
}

Tabla ci_device_model {
  id uuid [clave primaria]
  vendor_id uuid [no nulo]
}

Tabla ci_device_type {
  id uuid [clave primaria]
}

Tabla ci_Activo_type {
  id uuid [clave primaria, nota: 'jerárquico mediante ci_base parent_id/path']
}

Tabla ci_geo_object_type {
  id uuid [clave primaria]
}

Tabla ci_schedule_type {
  id uuid [clave primaria]
}

Tabla ci_activo_grupo_type {
  id uuid [clave primaria]
}

Tabla relación_tipo_de_grupo_de_activos_a_tipo_de_activo {
  id uuid [clave primaria]
  Grupo_type_id uuid [no nulo]
  asset_type_id uuid [no nulo]
  max_items int [nota: 'Máximo de activos de este tipo en el grupo. NULL = ilimitado']

  índices {
    (group_type_id) [nombre: 'idx_agt_at_rel_group']
    (activo_type_id) [name: 'idx_agt_at_rel_activo']
    (Grupo_type_id, Activo_type_id) [único]
  }
}

Tabla ci_device_relation_type {
  id uuid [clave primaria]
}

Tabla ci_Etiqueta {
  id uuid [clave primaria]
  entity_type_id uuid [note: 'Tipo de entidad aplicable. NULL = Etiqueta universal']
}

Tabla ci_user_catalog_item {
  id uuid [clave primaria, nota: 'Elementos de catálogos definidos por el usuario']
}

Tabla ci_catalog {
  id uuid [clave primaria, nota: 'Definiciones de catálogo. Los catálogos son, a su vez, elementos del catálogo']
  organization_id uuid [no nulo]
  module_id uuid [no nulo]
  category_id uuid
  fields_schema jsonb [nota: 'Esquema JSON para la validación de item.extra y la interfaz de usuario']

  índices {
    (organization_id) [name: 'idx_ci_catalog_org']
    (module_id) [name: 'idx_ci_catalog_module']
  }
}

Tabla ci_custom_field_definition {
  id uuid [clave primaria]
  owner_catalog_item_id uuid [not null, note: 'Propietario: entity_type (system) o un tipo específico como asset_type']
  target_entity_type_id uuid [no nulo]
  field_type text [no nulo, nota: 'STRING, TEXT, NUMBER, BOOLEAN, DATE, DATETIME, GEOJSON, SCHEDULE, OPTIONS, DEVICE, REFERENCE, CATALOG, ETIQUETA']
  is_required boolean [no nulo, predeterminado: false]
  params jsonb [nota: 'Parámetros específicos del tipo (mín./máx., opciones, referencia, etc.)']

  índices {
    (propietario_catalog_item_id) [name: 'idx_ci_cfd_propietario']
    (target_entity_type_id) [name: 'idx_ci_cfd_target']
  }
}

// ============================================
// ENTIDADES PRINCIPALES
// ============================================

Organización de la tabla {
  id uuid [clave primaria]
  parent_id uuid
  ruta ltree
  texto de código [no nulo]
  title_en text [no nulo]
  external_id texto [nota: 'Identificador del sistema externo para integraciones']
  is_active boolean [no nulo, predeterminado: true]
  is_dealer boolean [no nulo, predeterminado: false, nota: 'Si la organización puede crear organizaciones secundarias']
  version int [no nulo, predeterminado: 1]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (parent_id) [name: 'idx_org_parent']
    (path) [type: gist, name: 'idx_org_path_gist']
    (code) [único, name: 'uq_org_code']
    (external_id) [name: 'idx_org_external_id']
    (title_en) [name: 'idx_org_title', nota: 'El DDL de origen apunta a una columna title inexistente, corregido aquí a title_en']
  }
}

Tabla actor {
  id uuid [clave primaria, nota: 'Entidad abstracta para usuarios e integraciones. Base para ACL']
  actor_type text [no nulo, nota: 'USER, INTEGRATION, or SYSTEM']
  version int [no nulo, predeterminado: 1]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (actor_type) [nombre: 'idx_actor_type']
  }
}

Tabla user {
  id uuid [clave primaria]
  identity_provider text [no nulo, predeterminado: 'keycloak']
  identity_provider_id uuid [no nulo]
  full_name text [no nulo]
  external_id text
  is_active boolean [no nulo, predeterminado: true]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (identity_provider, identity_provider_id) [único, nombre: 'uq_user_idp']
    (external_id) [nombre: 'idx_user_external_id']
  }
}

Tabla member {
  id uuid [clave primaria, nota: 'Pertenencia de un usuario en una organización']
  user_id uuid [no nulo]
  organization_id uuid [no nulo]
  is_active boolean [no nulo, predeterminado: true]
  custom_fields_data jsonb [no nulo, predeterminado: `{}`, nota: 'Campos personalizados del miembro (puesto, departamento, etc.)']
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  assigned_at timestamptz [no nulo, predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (user_id) [name: 'idx_member_user']
    (organization_id) [name: 'idx_member_org']
    (user_id, organization_id) [único, name: 'uq_member_user_org']
  }
}

Tabla integration {
  id uuid [clave primaria, nota: 'Actor de integración de un sistema externo']
  name text [no nulo]
  texto de credential_ref [nota: 'Referencia a credenciales en una bóveda segura']
  is_active boolean [no nulo, predeterminado: true]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid
}

// ============================================
// CONTROL DE ACCESO (ACL)
// ============================================

Tabla actor_role {
  id uuid [clave primaria]
  actor_id uuid [no nulo]
  role_id uuid [no nulo]
  assigned_at timestamptz [no nulo, predeterminado: `CURRENT_TIMESTAMP`]
  asignado_por uuid
  expire_date timestamptz [nota: 'NULL = permanente']

  índices {
    (actor_id) [name: 'idx_actor_role_actor']
    (role_id) [name: 'idx_actor_role_role']
    (actor_id, role_id) [único]
  }
}

Tabla acl_role_permission {
  id uuid [clave primaria]
  role_id uuid [no nulo]
  permission_scope_id uuid [no nulo]
  target_entity_id uuid [nota: 'Entidad específica. NULL = todas las entidades de ese tipo. Polimórfico, sin FK']
  actions int [not null, note: 'Máscara de bits: READ=1, CREATE=2, UPDATE=4, DELETE=8']
  granted_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  otorgado_por uuid

  índices {
    (role_id) [name: 'idx_acl_role_perm_role']
    (permission_scope_id) [name: 'idx_acl_role_perm_scope']
    (role_id, permission_scope_id, target_entity_id) [único]
  }
}

Tabla acl_user_scope {
  id uuid [primary key, note: 'Filtro de lista blanca. Vacío = acceso completo al Papel. Lleno = intersección con papeles']
  actor_id uuid [no nulo]
  permission_scope_id uuid [no nulo]
  target_entity_id uuid [no nulo]
  actions int [no nulo]

  índices {
    (actor_id, permission_scope_id) [nombre: 'idx_acl_user_scope_actor']
    (actor_id, permission_scope_id, target_entity_id) [único]
  }
}

// ============================================
// ENTIDADES DE NEGOCIO
// ============================================

Tabla device {
  id uuid [clave primaria]
  organization_id uuid [no nulo]
  device_type_id uuid [no nulo]
  model_id uuid [nota: 'Opcional']
  status_id uuid [no nulo]
  title text [no nulo]
  custom_fields_data jsonb [no nulo, predeterminado: `{}`]
  version int [no nulo, predeterminado: 1]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (organization_id) [nombre: 'idx_device_org']
    (device_type_id) [nombre: 'idx_device_type']
    (model_id) [nombre: 'idx_device_model']
    (status_id) [nombre: 'idx_device_status']
    (title) [tipo: gin, nombre: 'idx_device_title_trgm', nota: 'gin_trgm_ops para búsqueda difusa']
  }
}

Tabla device_identifier {
  id uuid [clave primaria]
  device_id uuid [no nulo]
  type text [no nulo, nota: 'UUID, IMEI, MEID_HEX, MEID_DEC, MAC_ADDRESS, SERIAL_NUMBER, CUSTOM']
  texto de value [no nulo]
  texto de namespace [nota: 'Ámbito de unicidad. NULL = global']
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]

  índices {
    (device_id) [nombre: 'idx_device_identifier_device']
    (value) [nombre: 'idx_device_identifier_value']
    (type, value) [único, nombre: 'uq_device_identifier_global', nota: 'parcial: WHERE namespace IS NULL']
    (type, value, namespace) [único, nombre: 'uq_device_identifier_namespaced', nota: 'parcial: WHERE namespace IS NOT NULL']
  }
}

Tabla device_relation {
  id uuid [clave primaria]
  first_id uuid [no nulo]
  second_id uuid [no nulo]
  relation_type_id uuid [no nulo, nota: 'Restricción CHECK: first_id <> second_id']

  índices {
    (first_id) [name: 'idx_device_relation_first']
    (second_id) [name: 'idx_device_relation_second']
    (first_id, second_id, relation_type_id) [único]
  }
}

Tabla inventory {
  id uuid [clave primaria]
  organization_id uuid [no nulo]
  title text [no nulo]
  texto de código [no nulo]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (organization_id) [name: 'idx_inventory_org']
    (organization_id, code) [único, name: 'uq_inventory_org_code']
  }
}

Tabla device_inventory_relation {
  id uuid [clave primaria]
  device_id uuid [no nulo]
  inventory_id uuid [no nulo]
  assigned_at timestamptz [no nulo, predeterminado: `CURRENT_TIMESTAMP`]
  asignado_por uuid
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (device_id) [único, name: 'uq_device_inventory_active', note: 'parcial: WHERE deleted_at IS NULL - un inventario activo por dispositivo']
    (inventory_id) [name: 'idx_device_inventory_rel_inventory']
  }
}

Activo de tabla {
  id uuid [clave primaria]
  organization_id uuid [no nulo]
  asset_type_id uuid [no nulo]
  title text [no nulo]
  custom_fields_data jsonb [no nulo, predeterminado: `{}`]
  version int [no nulo, predeterminado: 1]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (organization_id) [name: 'idx_activo_org']
    (asset_type_id) [name: 'idx_asset_type']
    (título) [tipo: gin, nombre: 'idx_activo_title_trgm']
  }
}

Tabla Activo_Grupo {
  id uuid [clave primaria]
  organization_id uuid [no nulo]
  Grupo_type_id uuid [no nulo]
  title_en text [no nulo]
  texto de color
  version int [no nulo, predeterminado: 1]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (organization_id) [name: 'idx_asset_group_org']
    (grupo_tipo_id) [nombre: 'idx_activo_grupo_tipo']
  }
}

Tabla activo_grupo_item {
  id uuid [clave primaria]
  group_id uuid [no nulo]
  activo_id uuid [no nulo]
  attached_at timestamptz [no nulo, predeterminado: `CURRENT_TIMESTAMP`]
  detached_at timestamptz [nota: 'NULL = actualmente adjunto']

  índices {
    (Grupo_id) [nombre: 'idx_Activo_Grupo_item_Grupo']
    (Activo_id) [nombre: 'idx_Activo_Grupo_item_Activo']
    (group_id, asset_id, detached_at) [único]
  }
}

Tabla geo_Objeto {
  id uuid [clave primaria, nota: 'geocercas, puntos de interés, rutas']
  organization_id uuid [no nulo]
  geo_object_type_id uuid [no nulo]
  title text [no nulo]
  custom_fields_data jsonb [no nulo, valor predeterminado: `{}`, nota: 'Incluye geometría geojson']
  version int [no nulo, predeterminado: 1]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (organization_id) [nombre: 'idx_geo_object_org']
    (geo_object_type_id) [name: 'idx_geo_object_type']
    (título) [type: gin, name: 'idx_geo_objeto_título_trgm']
  }
}

Programación de la tabla {
  id uuid [clave primaria]
  organization_id uuid [no nulo]
  schedule_type_id uuid [no nulo]
  title text [no nulo]
  custom_fields_data jsonb [no nulo, predeterminado: `{}`, nota: 'Los datos del horario residen aquí']
  version int [no nulo, predeterminado: 1]
  created_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  updated_at timestamptz [no nulo, valor predeterminado: `CURRENT_TIMESTAMP`]
  deleted_at timestamptz
  deleted_by uuid

  índices {
    (organization_id) [nombre: 'idx_schedule_org']
    (schedule_type_id) [nombre: 'idx_schedule_type']
    (título) [tipo: gin, nombre: 'idx_schedule_title_trgm']
  }
}

// ============================================
// LOCALIZACIÓN
// ============================================

Tabla i18n_text {
  entity_id uuid [pk]
  field_code text [pk]
  locale text [pk]
  texto de value [no nulo]

  índices {
    (entity_id) [name: 'idx_i18n_entity']
    (locale) [name: 'idx_i18n_locale']
    (value) [type: gin, name: 'idx_i18n_text_trgm']
  }
}

// ============================================
// Campos personalizados - valores (tablas de caché, una por field_type)
// ============================================

Tabla custom_field_value_text {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  texto de value [no nulo]

  índices {
    (field_definition_id, value) [name: 'idx_cfv_text_value']
  }
}

Tabla custom_field_value_number {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  value numeric [no nulo]
}

Tabla custom_field_value_boolean {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  value boolean [no nulo]
}

Tabla custom_field_value_date {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  value date [no nulo]
}

Tabla custom_field_value_datetime {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  value timestamptz [no nulo]
}

Tabla custom_field_value_geojson {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  valor jsonb [no nulo]
}

Tabla custom_field_value_schedule {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  valor jsonb [no nulo]
}

Tabla custom_field_value_option {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  ref_item_id uuid [no nulo, nota: 'Referencia a ci_user_catalog_item']
}

Tabla custom_field_value_device {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  ref_device_id uuid [no nulo]
}

Tabla custom_field_value_entity {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  ref_entity_id uuid [no nulo, nota: 'Referencia polimórfica, sin clave foránea']
}

Tabla custom_field_value_catalog {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  ref_item_id uuid [not null, note: 'Referencia a ci_base']
}

Tabla custom_field_value_etiqueta {
  entity_id uuid [pk]
  field_definition_id uuid [pk]
  value_index smallint [pk, predeterminado: 0]
  ref_etiqueta_id uuid [not null]
}

// ============================================
// AUDITORÍA
// ============================================

Enum source_type {
  WEB
  MÓVIL
  API
  INTERNO
  Integración
}

Tabla audit_event {
  id uuid [no nulo]
  organization_id uuid
  event_category text [no nulo, nota: 'auth o domain']
  actor_id uuid
  ip_address inet
  texto de user_agent
  source_type source_type [no nulo, predeterminado: 'API']
  texto del nombre de la fuente [nota: 'Nombre de la aplicación de origen']
  trace_id uuid [nota: 'ID de rastreo distribuido para la correlación de registros']
  aggregate_type texto [nota: 'Tipo de entidad: dispositivo, Activo, usuario, etc.']
  aggregate_id uuid [nota: 'Polimórfico, sin FK']
  event_type text [no nulo, nota: 'CREADO, ACTUALIZADO, ELIMINADO, RESTAURADO, Papel_ASIGNADO, etc.']
  event_data jsonb [nota: 'Carga útil con delta de changed_fields']
  occurred_at timestamptz [no nulo, predeterminado: `CURRENT_TIMESTAMP`]

  Nota: 'Particionado POR RANGO (occurred_at), particiones mensuales, creadas automáticamente mediante create_audit_partition_if_needed()'

  índices {
    (id, occurred_at) [pk]
    (actor_id, occurred_at) [nombre: 'idx_audit_event_actor']
    (aggregate_type, aggregate_id, occurred_at) [nombre: 'idx_audit_event_aggregate']
    (event_category, occurred_at) [nombre: 'idx_audit_event_category']
    (event_type, occurred_at) [nombre: 'idx_audit_event_type']
    (organization_id, occurred_at) [name: 'idx_audit_event_org']
    (trace_id) [nombre: 'idx_audit_event_trace']
  }
}

// ============================================
// RELACIONES
// ============================================

Ref: ci_base.catalog_id > ci_catalog.id
Ref.: ci_base.organization_id > organization.id
Ref: ci_base.parent_id > ci_base.id

Ref.: ci_module.id - ci_base.id
Ref: ci_catalog_category.id - ci_base.id
Ref: ci_country.id - ci_base.id
Ref.: ci_role.id - ci_base.id
Ref.: ci_entity_type.id - ci_base.id
Ref.: ci_device_status.id - ci_base.id
Ref: ci_permission_scope.id - ci_base.id
Referencia: ci_device_vendor.id - ci_base.id
Referencia: ci_device_model.id - ci_base.id
Ref.: ci_device_type.id - ci_base.id
Referencia: ci_asset_type.id - ci_base.id
Referencia: ci_geo_object_type.id - ci_base.id
Ref.: ci_schedule_type.id - ci_base.id
Ref.: ci_asset_group_type.id - ci_base.id
Ref: ci_device_relation_type.id - ci_base.id
Ref.: ci_tag.id - ci_base.id
Referencia: ci_user_catalog_item.id - ci_base.id
Ref.: ci_catalog.id - ci_base.id
Ref: ci_custom_field_definition.id - ci_base.id

Ref: ci_device_model.vendor_id > ci_device_vendor.id
Ref: ci_permission_scope.module_id > ci_module.id
Ref: ci_permission_scope.entity_type_id > ci_entity_type.id
Referencia: asset_group_type_to_asset_type_relation.group_type_id > ci_asset_group_type.id
Referencia: asset_group_type_to_asset_type_relation.asset_type_id > ci_asset_type.id
Ref.: ci_tag.entity_type_id > ci_entity_type.id
Referencia: ci_catalog.organization_id > organization.id
Ref: ci_catalog.module_id > ci_module.id
Ref.: ci_catalog.category_id > ci_catalog_category.id
Referencia: ci_custom_field_definition.owner_catalog_item_id > ci_base.id
Ref: ci_custom_field_definition.target_entity_type_id > ci_entity_type.id

Ref: organization.parent_id > organization.id
Ref: organization.deleted_by > actor.id

Ref: actor.deleted_by > actor.id

Ref.: user.id - actor.id
Ref: user.deleted_by > actor.id

Ref: member.user_id > user.id
Referencia: member.organization_id > organization.id
Ref: member.deleted_by > actor.id

Ref.: integration.id - actor.id
Ref: integration.deleted_by > actor.id

Ref.: actor_role.actor_id > actor.id
Ref.: actor_role.role_id > ci_role.id
Ref.: actor_role.assigned_by > actor.id

Referencia: acl_role_permission.role_id > ci_role.id
Ref.: acl_role_permission.permission_scope_id > ci_permission_scope.id
Referencia: acl_role_permission.granted_by > actor.id

Ref: acl_user_scope.actor_id > actor.id
Ref: acl_user_scope.permission_scope_id > ci_permission_scope.id

Ref: device.organization_id > organization.id
Ref.: device.device_type_id > ci_device_type.id
Ref: device.model_id > ci_device_model.id
Ref: device.status_id > ci_device_status.id
Ref: device.deleted_by > actor.id

Ref: device_identifier.device_id > device.id

Ref.: device_relation.first_id > device.id
Ref: device_relation.second_id > device.id
Ref.: device_relation.relation_type_id > ci_device_relation_type.id

Ref: inventory.organization_id > organization.id
Ref: inventory.deleted_by > actor.id

Ref.: device_inventory_relation.device_id > device.id
Ref.: device_inventory_relation.inventory_id > inventory.id
Ref: device_inventory_relation.assigned_by > actor.id
Referencia: device_inventory_relation.deleted_by > actor.id

Ref: Activo.organization_id > organization.id
Referencia: asset.asset_type_id > ci_asset_type.id
Ref.: Activo.deleted_by > actor.id

Ref.: activo_grupo.organization_id > organization.id
Referencia: asset_group.group_type_id > ci_asset_group_type.id
Ref.: Activo_Grupo.deleted_by > actor.id

Referencia: asset_group_item.group_id > asset_group.id
Ref.: activo_grupo_item.activo_id > activo.id

Ref.: geo_objeto.organization_id > organization.id
Referencia: geo_object.geo_object_type_id > ci_geo_object_type.id
Ref.: geo_Objeto.deleted_by > actor.id

Ref: schedule.organization_id > organization.id
Ref: schedule.schedule_type_id > ci_schedule_type.id
Ref: schedule.deleted_by > actor.id

Ref: custom_field_value_text.field_definition_id > ci_custom_field_definition.id
Ref: custom_field_value_number.field_definition_id > ci_custom_field_definition.id
Ref: custom_field_value_boolean.field_definition_id > ci_custom_field_definition.id
Ref: custom_field_value_date.field_definition_id > ci_custom_field_definition.id
Ref: custom_field_value_datetime.field_definition_id > ci_custom_field_definition.id
Ref: custom_field_value_geojson.field_definition_id > ci_custom_field_definition.id
Ref: custom_field_value_schedule.field_definition_id > ci_custom_field_definition.id
Referencia: custom_field_value_option.field_definition_id > ci_custom_field_definition.id
Ref: custom_field_value_option.ref_item_id > ci_user_catalog_item.id
Ref: custom_field_value_device.field_definition_id > ci_custom_field_definition.id
Ref.: custom_field_value_device.ref_device_id > device.id
Ref: custom_field_value_entity.field_definition_id > ci_custom_field_definition.id
Ref.: custom_field_value_catalog.field_definition_id > ci_custom_field_definition.id
Referencia: custom_field_value_catalog.ref_item_id > ci_base.id
Referencia: custom_field_value_tag.field_definition_id > ci_custom_field_definition.id
Ref.: custom_field_value_tag.ref_tag_id > ci_tag.id

Ref: audit_event.organization_id > organization.id
Ref: audit_event.actor_id > actor.id
```

{% endcode %}

## Frecuencia de actualización

Los datos en BDR se sincronizan en tiempo real con los sistemas de origen. Las actualizaciones ocurren inmediatamente a medida que se producen los cambios, y las auditorías capturan todas las modificaciones para el cumplimiento y el análisis histórico.

## `ci_base`

BDR utiliza una **herencia de una sola tabla** patrón para todos los datos de referencia a través de la `ci_base` tabla. Este diseño consolida los diccionarios del sistema, las clasificaciones y los elementos de referencia definidos por el usuario en una sola estructura unificada, proporcionando coherencia y flexibilidad en todo el esquema.

**Arquitectura:**

El `ci_base` tabla sirve como base para todos los datos de referencia, utilizando un `discriminador` campo para identificar el tipo específico de referencia. Cada tipo de referencia tiene una tabla correspondiente (como `ci_device_type`, `ci_asset_type`) que comparte el mismo `id` como `ci_base`, creando una relación de herencia segura en cuanto a tipos. El `discriminador` no se establece manualmente. Un disparador lo deriva automáticamente del código de tipo de 4 caracteres incrustado en el UUID de la entidad, y falla la inserción si el código de tipo del UUID no se reconoce.

Las jerarquías (p. ej., tipos de Activo anidados o Etiquetas) se gestionan directamente en `ci_base` a través de su propio `parent_id`/`path` columnas en lugar de mediante tablas de categorías separadas. Una sola `is_hierarchical` la bandera activa esto por cada elemento del catálogo.

**Cómo se conectan las entidades de negocio con ci\_base:**

Todas las entidades de negocio en BDR hacen referencia a `ci_base` subtipos para definir su clasificación y comportamiento:

* `organización` y `usuario`/`miembro` son *no* escritos mediante `ci_base`, ya que las organizaciones y los usuarios son entidades centrales por derecho propio, no clasificadas por un elemento del catálogo
* `dispositivo` → referencias `ci_device_type`, opcionalmente `ci_device_model` (que a su vez referencia `ci_device_vendor`), y `ci_device_status`
* `activo` → referencias `ci_asset_type`
* `activo_grupo` → referencias `ci_Activo_Grupo_type`, con los tipos de miembros permitidos restringidos mediante `relación_de_tipo_de_grupo_de_activos_a_tipo_de_activo`
* `geo_objeto` → referencias `ci_geo_tipo_de_objeto`
* `programación` → referencias `ci_schedule_type`
* `inventario` no tiene un tipo de elemento de catálogo propio

**Categorías de tipos de referencia:**

| Categoría                            | Tablas                                                                                                                   | Propósito                                                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Configuración del sistema**        | `ci_module`, `ci_country`, `ci_papel`                                                                                    | Definir módulos del sistema, referencias geográficas y roles de usuario                                                 |
| **Definiciones de tipos de entidad** | `ci_entity_type`, `ci_device_type`, `ci_asset_type`, `ci_geo_tipo_de_objeto`, `ci_schedule_type`, `ci_Activo_Grupo_type` | Clasificar todas las entidades de negocio por tipo                                                                      |
| **Catálogo de dispositivos**         | `ci_device_vendor`, `ci_device_model`, `ci_device_status`                                                                | Modelar dispositivos por fabricante, modelo y estado actual                                                             |
| **Control de acceso**                | `ci_permission_scope`                                                                                                    | Definir qué permisos pueden otorgarse (conectado a `ci_module` y `ci_entity_type`)                                      |
| **Relaciones**                       | `ci_device_relation_type`                                                                                                | Defina los tipos de relaciones entre dispositivos (maestro-esclavo, respaldo, etc.)                                     |
| **Categorización**                   | `ci_etiqueta`, `ci_catalog_category`, `ci_user_catalog_item`                                                             | Activar el etiquetado flexible y los catálogos definidos por el usuario                                                 |
| **Catálogo / Campos personalizados** | `ci_catalog`, `definición_de_campo_personalizado_ci`                                                                     | Metadatos del catálogo de catálogos y de campos personalizados, ambos modelados como elementos de catálogo en sí mismos |

<details>

<summary><strong>Patrones de consulta de ejemplo</strong></summary>

```sql
-- Obtenga todos los tipos de dispositivo para una organización (del sistema + personalizados)
SELECT cb.id, cb.code, cb.title_en, cb.is_system
FROM bdr.ci_base cb
JOIN bdr.ci_device_type dt ON dt.id = cb.id
WHERE cb.discriminator = 'device_type'
  AND (cb.is_system = true OR cb.organization_id = $org_id)
  AND cb.deleted_at IS NULL;

-- Obtenga modelos de dispositivo con su fabricante
SELECT
  cb.code as model_code,
  cb.title_en as model_name,
  vendor_cb.title_en as vendor_name
FROM bdr.ci_base cb
JOIN bdr.ci_device_model dm ON dm.id = cb.id
JOIN bdr.ci_device_vendor v ON v.id = dm.vendor_id
JOIN bdr.ci_base vendor_cb ON vendor_cb.id = v.id
WHERE cb.discriminator = 'device_model'
  AND cb.deleted_at IS NULL;

-- Obtener la estructura jerárquica de etiquetas
SELECT cb.id, cb.code, cb.title_en, cb.path, cb.parent_id
FROM bdr.ci_base cb
JOIN bdr.ci_tag t ON t.id = cb.id
WHERE cb.discriminator = 'Etiqueta'
  AND cb.deleted_at IS NULL
ORDER BY cb.path;
```

</details>

## Tablas clave por categoría

Las tablas en BDR se organizan en categorías funcionales. Las descripciones a continuación resumen las tablas más importantes por su propósito de negocio.

<details>

<summary><code>organización</code></summary>

**Propósito:** Gestión jerárquica de la organización

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code>, <code>parent_id</code>, <code>path</code>, <code>código</code>, <code>título_en</code>, <code>está_activo</code>, <code>es_distribuidor</code>, <code>versión</code>, <code>deleted_at</code></td></tr><tr><td><strong>Indexación</strong></td><td>Índice GiST en <code>path</code> para consultas jerárquicas, índice único en <code>código</code>, índice en <code>parent_id</code></td></tr><tr><td><strong>Notas especiales</strong></td><td>Usa ltree para jerarquías multinivel. <code>es_distribuidor</code> otorga el derecho a crear organizaciones secundarias. <code>versión</code> admite bloqueo optimista</td></tr></tbody></table>

</details>

<details>

<summary><code>actor</code></summary>

**Propósito:** Abstracción compartida por cada principal de ACL: usuarios, integraciones y futuros actores del sistema

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code>, <code>tipo_de_actor</code> (<code>USUARIO</code>, <code>Integración</code>, <code>SISTEMA</code>), <code>versión</code></td></tr><tr><td><strong>Notas especiales</strong></td><td>Todas las tablas ACL (<code>papel_del_actor</code>, <code>permiso_de_papel_acl</code>, <code>alcance_de_usuario_acl</code>) y cada <code>eliminado_por</code> clave de columna desactivada <code>actor_id</code>, no <code>user_id</code>, por lo que las integraciones también pueden tener funciones y eliminar registros</td></tr></tbody></table>

</details>

<details>

<summary><code>usuario</code> / <code>miembro</code></summary>

**Propósito:** Las cuentas de usuario y sus membresías en organizaciones

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>usuario</code>: <code>id</code> (compartido con <code>actor</code>), <code>identity_provider</code>, <code>identity_provider_id</code>, <code>full_name</code>. <code>miembro</code>: <code>user_id</code>, <code>organization_id</code>, <code>custom_fields_data</code></td></tr><tr><td><strong>Indexación</strong></td><td>Índice único sobre (<code>identity_provider</code>, <code>identity_provider_id</code>). Índice único sobre (<code>user_id</code>, <code>organization_id</code>) en <code>miembro</code></td></tr><tr><td><strong>Notas especiales</strong></td><td>La pertenencia de un usuario a una organización es una fila separada en <code>miembro</code>, por lo que un usuario puede pertenecer a varias organizaciones. Los usuarios se autentican a través de un proveedor de identidad externo (Keycloak de forma predeterminada)</td></tr></tbody></table>

</details>

<details>

<summary><code>integración</code></summary>

**Propósito:** Sistemas externos que actúan sobre la plataforma (p. ej., mediante Llaves API)

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code> (compartido con <code>actor</code>), <code>nombre</code>, <code>credential_ref</code>, <code>está_activo</code></td></tr><tr><td><strong>Notas especiales</strong></td><td><code>credential_ref</code> apunta a una bóveda externa segura, por lo que no se almacenan credenciales en esta tabla</td></tr></tbody></table>

</details>

<details>

<summary><code>dispositivo</code> / <code>device_identifier</code></summary>

**Propósito:** Dispositivos físicos de seguimiento y sus identificadores de hardware

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>dispositivo</code>: <code>id</code>, <code>organization_id</code>, <code>device_type_id</code>, <code>model_id</code>, <code>status_id</code>, <code>title</code>, <code>custom_fields_data</code>, <code>versión</code>. <code>device_identifier</code>: <code>device_id</code>, <code>tipo</code>, <code>valor</code>, <code>namespace</code></td></tr><tr><td><strong>Indexación</strong></td><td>Índice de trigramas GIN en <code>title</code> para búsqueda difusa. Índice único en (<code>tipo</code>, <code>valor</code>) para identificadores globales, o (<code>tipo</code>, <code>valor</code>, <code>namespace</code>) cuando tiene namespace</td></tr><tr><td><strong>Notas especiales</strong></td><td>Un dispositivo puede tener varios identificadores (IMEI, MAC, número de serie, etc.) en lugar de una sola columna de ID de hardware. Los Campos personalizados residen directamente en <code>custom_fields_data</code> en la fila del dispositivo</td></tr></tbody></table>

</details>

<details>

<summary><code>activo</code></summary>

**Propósito:** Activos físicos o virtuales

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code>, <code>organization_id</code>, <code>activo_type_id</code>, <code>title</code>, <code>custom_fields_data</code>, <code>versión</code></td></tr><tr><td><strong>Indexación</strong></td><td>Índices en <code>organization_id</code> y <code>activo_type_id</code>. Índice de trigramas GIN en <code>title</code></td></tr><tr><td><strong>Notas especiales</strong></td><td>Campos personalizados se almacenan directamente en la fila, no a través de una tabla separada de entidad personalizable</td></tr></tbody></table>

</details>

<details>

<summary><code>inventario</code> / <code>relación_de_inventario_del_dispositivo</code></summary>

**Propósito:** Registros de inventario y almacén, y asignación de dispositivos al inventario

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>inventario</code>: <code>id</code>, <code>organization_id</code>, <code>title</code>, <code>código</code>. <code>relación_de_inventario_del_dispositivo</code>: <code>device_id</code>, <code>inventory_id</code>, <code>assigned_at</code>, <code>deleted_at</code></td></tr><tr><td><strong>Indexación</strong></td><td>Índice único sobre (<code>organization_id</code>, <code>código</code>). Un índice único parcial garantiza que un dispositivo tenga como máximo una asignación activa de inventario</td></tr><tr><td><strong>Notas especiales</strong></td><td>La asignación admite borrado lógico, por lo que se conserva el historial del inventario de dispositivos.</td></tr></tbody></table>

</details>

<details>

<summary><code>geo_objeto</code></summary>

**Propósito:** Geocercas, puntos de interés y rutas

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code>, <code>organization_id</code>, <code>geo_object_type_id</code>, <code>title</code>, <code>custom_fields_data</code></td></tr><tr><td><strong>Notas especiales</strong></td><td>Geometría (anteriormente una dedicada <code>geojson</code> columna) ahora se almacena como un campo personalizado dentro de <code>custom_fields_data</code></td></tr></tbody></table>

</details>

<details>

<summary><code>programación</code></summary>

**Propósito:** Programaciones reutilizables referenciadas por otras entidades

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code>, <code>organization_id</code>, <code>schedule_type_id</code>, <code>title</code>, <code>custom_fields_data</code></td></tr><tr><td><strong>Notas especiales</strong></td><td>Los datos de la programación en sí (reglas de recurrencia, ventanas horarias) se almacenan en <code>custom_fields_data</code></td></tr></tbody></table>

</details>

<details>

<summary><code>activo_grupo</code></summary>

**Propósito:** Agrupación de Activo con seguimiento histórico

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code>, <code>organization_id</code>, <code>group_type_id</code>, <code>título_en</code>, <code>color</code></td></tr><tr><td><strong>Relaciones</strong></td><td><code>FROM bdr.asset_group AS ag JOIN bdr.asset_group_item AS agi ON agi.group_id = ag.id JOIN bdr.asset AS a ON a.id = agi.asset_id WHERE agi.detached_at IS NULL</code></td></tr><tr><td><strong>Notas especiales</strong></td><td>Membresía basada en el tiempo mediante <code>activo_grupo_elemento</code>, consultar los miembros actuales con <code>WHERE detached_at IS NULL</code>. Los tipos de miembros permitidos por tipo de Grupo se restringen mediante <code>relación_de_tipo_de_grupo_de_activos_a_tipo_de_activo</code></td></tr></tbody></table>

</details>

<details>

<summary><code>definición_de_campo_personalizado_ci</code></summary>

**Propósito:** Definiciones y metadatos de campos personalizados, modelados como un elemento de catálogo

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code> (compartido con <code>ci_base</code>), <code>id_del_elemento_del_catálogo_del_propietario</code>, <code>target_entity_type_id</code>, <code>field_type</code>, <code>is_required</code>, <code>params</code></td></tr><tr><td><strong>Contenido</strong></td><td>12 tipos de campo: <code>STRING</code>, <code>TEXT</code>, <code>NUMBER</code>, <code>BOOLEAN</code>, <code>DATE</code>, <code>DATETIME</code>, <code>GEOJSON</code>, <code>Programación</code>, <code>Opciones</code>, <code>Dispositivo</code>, <code>Referencia</code>, <code>Catálogo</code>, <code>Etiqueta</code></td></tr><tr><td><strong>Notas especiales</strong></td><td>Los valores se almacenan tanto como la fuente de verdad (<code>custom_fields_data</code> JSONB en la entidad propietaria) y, por tipo, en un campo dedicado <code>custom_field_value_*</code> tabla de caché para filtrar/ordenar. <code>Opciones</code> es un envoltorio alrededor de <code>Catálogo</code>, y cada <code>Opciones</code> el campo obtiene su propio catálogo oculto de usuarios internamente</td></tr></tbody></table>

</details>

<details>

<summary><code>permiso_de_papel_acl</code></summary>

**Propósito:** Administración de permisos basada en Papel

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code>, <code>role_id</code>, <code>permission_scope_id</code>, <code>id_de_entidad_destino</code>, <code>acciones</code></td></tr><tr><td><strong>Contenido</strong></td><td>Máscara de bits de acciones (READ=1, CREATE=2, UPDATE=4, DELETE=8), permisos específicos del objetivo o de todo el tipo de entidad</td></tr><tr><td><strong>Relaciones</strong></td><td><code>FROM bdr.actor_role AS ar JOIN bdr.acl_role_permission AS rp ON rp.role_id = ar.role_id WHERE ar.actor_id = $actor_id</code></td></tr><tr><td><strong>Notas especiales</strong></td><td>Permisos efectivos = permisos del Papel ∩ <code>alcance_de_usuario_acl</code>. De un actor <code>alcance_de_usuario_acl</code> es un filtro de lista blanca: vacío significa acceso sin restricciones por Papel, lleno significa que el acceso se limita a los objetos listados</td></tr></tbody></table>

</details>

<details>

<summary><code>audit_event</code></summary>

**Propósito:** Registro de auditoría unificado de todos los cambios del sistema

<table><thead><tr><th width="139">Atributo</th><th>Detalles</th></tr></thead><tbody><tr><td><strong>Campos clave</strong></td><td><code>id</code>, <code>organization_id</code>, <code>categoría del evento</code>, <code>actor_id</code>, <code>tipo de origen</code>, <code>trace_id</code>, <code>aggregate_type</code>, <code>aggregate_id</code>, <code>event_type</code>, <code>event_data</code>, <code>occurred_at</code></td></tr><tr><td><strong>Indexación</strong></td><td>Índices en (<code>actor_id</code>, <code>occurred_at</code>), (<code>aggregate_type</code>, <code>aggregate_id</code>, <code>occurred_at</code>), (<code>categoría del evento</code>, <code>occurred_at</code>), (<code>organization_id</code>, <code>occurred_at</code>)</td></tr><tr><td><strong>Notas especiales</strong></td><td>Particionado físicamente por <code>occurred_at</code> (particiones de rango mensuales, creadas automáticamente). <code>categoría del evento</code> es <code>auth</code> (LOGIN, LOGOUT, FAILED_LOGIN, PASSWORD_RESET, SESSION_EXPIRED) o <code>domain</code> (CREATED, UPDATED, DELETED, RESTORED, ROLE_ASSIGNED, ROLE_REVOKED, PERMISSION_GRANTED, PERMISSION_REVOKED, LINKED, UNLINKED, ATTACHED, DETACHED). <code>tipo de origen</code> y <code>trace_id</code> admite el rastreo distribuido, y la tabla almacena deltas de cambios a nivel de campo en <code>event_data</code> JSONB</td></tr></tbody></table>

</details>

## Relaciones de datos

BDR implementa sofisticados patrones de relaciones para un modelado de datos flexible:

**Estructuras jerárquicas**

* Las organizaciones usan rutas ltree para consultas de árbol eficientes
* Elementos de referencia (`ci_base`) admiten jerarquías opcionales a través de las propias `parent_id`/`path`, condicionado por `is_hierarchical`
* Mantenimiento automático de rutas mediante disparadores de base de datos

**Patrones de herencia**

* Herencia de ID: `ci_base` → tablas de tipo de referencia (`ci_device_type`, `ci_asset_type`, etc.), y `actor` → `usuario` y `integración`
* Los campos personalizados se adjuntan por entidad mediante una `custom_fields_data` columna JSONB directamente en cada tabla de negocio (`dispositivo`, `activo`, `geo_objeto`, `programación`), en lugar de hacerlo a través de una tabla base compartida de entidad
* Discriminación de tipos mediante el `discriminador` campo en `ci_base`, derivado automáticamente del UUID de la entidad

**Bloqueo optimista**

Entidades de negocio y `ci_base` las filas llevan un `versión` entero. Las actualizaciones usan `SET version = version + 1 WHERE id = $id AND version = $expected_version`. Cero filas afectadas indica un conflicto de versión, lo que permite a los clientes detectar y resolver ediciones simultáneas sin bloqueos a nivel de base de datos. `audit_event` y otras tablas de solo anexado o con operaciones masivas no usan este patrón.

**Relaciones polimórficas**

Algunas tablas usan referencias polimórficas sin restricciones de clave foránea para lograr la máxima flexibilidad:

* `acl_role_permission.target_entity_id` y `acl_user_scope.target_entity_id` → cualquier entidad empresarial
* `audit_event.aggregate_id` → cualquier entidad comercial, emparejada con `aggregate_type`
* `custom_field_value_entity.ref_entity_id` → cualquier entidad empresarial

Estas relaciones se validan a nivel de la aplicación.

## Información adicional

### Validación de datos

BDR garantiza la integridad de los datos mediante varios mecanismos:

**Restricciones de base de datos**

* Restricciones UNIQUE con soporte para eliminación lógica (índices parciales WHERE `deleted_at` IS NULL)
* Restricciones CHECK (p. ej., `device_relation` garantiza `first_id` ≠ `second_id`, y `ci_base.code` debe comenzar con una letra)
* restricciones NOT NULL en campos obligatorios
* valores predeterminados para columnas de marcas de tiempo, booleanas y JSONB

**Validación a nivel de aplicación**

* Validación del tipo de entidad para referencias polimórficas
* Validación de catálogo para referencias de campos personalizados
* Validación del tipo de campo personalizado
* Comprobaciones de versión con bloqueo optimista al actualizar

### Optimización de consultas

Las tablas están organizadas con estrategias de indexación específicas:

**Índices estándar:**

* Todos los índices de claves foráneas tienen índices dedicados
* Índices basados en el tiempo en `created_at`, `updated_at`, `deleted_at`
* Índices compuestos para columnas que se unen con frecuencia

**Índices especializados:**

* Índices GiST sobre rutas ltree para consultas jerárquicas
* Índices únicos parciales que admiten el borrado lógico
* GIN de trigramas (`pg_trgm`) índices para búsqueda difusa en `title`/`título_en` y texto traducido
* Índices de valores de campos personalizados para filtrar y ordenar
* Índices de eventos de auditoría por tiempo + entidad para búsquedas eficientes

**Consideraciones de rendimiento:**

* Se recomienda la agrupación de conexiones (PgBouncer)
* Mantenimiento regular de VACUUM para tablas grandes
* `audit_event` está particionada físicamente por mes, por lo que las particiones más antiguas se pueden separar o archivar de forma independiente
* Vistas materializadas para cálculos complejos de control de acceso


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://navixy.com/docs/analytics/es/iot-query/schema-overview/bronze-layer/bdr.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
