Saltar a contenido

Especificación Técnica: trx_marcaciones

Esquema: core.notificaciones
Base de Datos: core
Servicio: svc-notificaciones
Propósito: Única fuente de verdad de la marcación biométrica cruda: cada fila es una marcación de un dispositivo, recibida por evento y publicada a svc-rrhh.


1. Justificación y Mejoras de Arquitectura

  • Cierra un hallazgo de la auditoría: hoy la asistencia biométrica y la asistencia de nómina son dos fuentes de verdad sin puente. Aquí trx_marcaciones es la única fuente y svc-rrhh la recibe por evento (fecha_publicado_rrhh).
  • Tabla particionada PARTITION BY RANGE (fecha_marcacion) por alto volumen; la consulta siempre es por fecha. La partición mensual se gestiona fuera de esta especificación (procedimientos y partición default no se documentan por ahora).
  • PK compuesta (id, fecha_marcacion): el id UUID es local por partición y la fecha participa de la unicidad global.
  • Unique (dispositivo_id, identificacion_empleado, fecha_marcacion): el reloj reenvía al reconectar; la clave descarta el duplicado sola.
  • empleado_id es una referencia lógica a svc-rrhh (lo resuelve por evento), sin FOREIGN KEY, igual que en el fuente.
  • payload_crudo JSONB conserva la respuesta original del dispositivo para trazabilidad y reproceso.
  • Auditoría ligera solo-inserción (created_at, created_by): tabla de registro transaccional de alto volumen, sin borrado lógico ni actualización (mismo criterio que trx_refresh_tokens en core.identidad).

2. Definiciones de Implementación

Table core.notificaciones.trx_marcaciones {
    id                      uuid        [default: `gen_random_uuid()`]
    empresa_id              bigint      [not null]
    dispositivo_id          uuid        [not null]
    tipo_marcacion_id       uuid
    identificacion_empleado text        [not null]
    empleado_id             uuid        [note: 'Referencia lógica a svc-rrhh (sin FK), lo resuelve por evento']
    fecha_marcacion         timestamptz [not null]
    origen                  text        [not null, default: `'dispositivo'`]
    payload_crudo           jsonb
    fecha_publicado_rrhh    timestamptz

    // Auditoría ligera (solo inserción)
    created_at              timestamptz [not null, default: `now()`, note: 'Fecha de creación']
    created_by              uuid        [note: 'Usuario creador']

    Indexes {
        (id, fecha_marcacion) [pk, name: 'pk_trx_marcaciones']
        (dispositivo_id, identificacion_empleado, fecha_marcacion) [unique, name: 'uq_trx_marcaciones_dispositivo_empleado_fecha']
        (identificacion_empleado, fecha_marcacion) [name: 'ix_trx_marcaciones_empleado']
        (empresa_id) [name: 'ix_trx_marcaciones_empresa_id']
        (fecha_marcacion) [name: 'ix_trx_marcaciones_sin_publicar', note: 'WHERE fecha_publicado_rrhh IS NULL']
        (tipo_marcacion_id) [name: 'ix_trx_marcaciones_tipo_marcacion_id']
    }

    Note: 'PARTITION BY RANGE (fecha_marcacion). La partición mensual se gestiona fuera de esta especificación.'
}

Ref: mae_dispositivos_biometricos.(empresa_id, id) < trx_marcaciones.(empresa_id, dispositivo_id)
CREATE TABLE IF NOT EXISTS core.notificaciones.trx_marcaciones (
    id UUID NOT NULL DEFAULT gen_random_uuid(),
    empresa_id BIGINT NOT NULL,
    dispositivo_id UUID NOT NULL,
    tipo_marcacion_id UUID,
    identificacion_empleado TEXT NOT NULL,
    empleado_id UUID,
    fecha_marcacion TIMESTAMPTZ NOT NULL,
    origen TEXT NOT NULL DEFAULT 'dispositivo',
    payload_crudo JSONB,
    fecha_publicado_rrhh TIMESTAMPTZ,

    -- Auditoría ligera (solo inserción)
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    created_by UUID,

    CONSTRAINT pk_trx_marcaciones PRIMARY KEY (id, fecha_marcacion),
    CONSTRAINT fk_trx_marcaciones_dispositivo
        FOREIGN KEY (empresa_id, dispositivo_id)
        REFERENCES core.notificaciones.mae_dispositivos_biometricos (empresa_id, id),
    CONSTRAINT fk_trx_marcaciones_tipo
        FOREIGN KEY (tipo_marcacion_id)
        REFERENCES core.notificaciones.cat_tipos_marcacion (id),
    -- El reloj reenvía al reconectar: la clave descarta el duplicado sola.
    CONSTRAINT uq_trx_marcaciones_dispositivo_empleado_fecha UNIQUE (dispositivo_id, identificacion_empleado, fecha_marcacion)
) PARTITION BY RANGE (fecha_marcacion);

CREATE INDEX IF NOT EXISTS ix_trx_marcaciones_empleado ON core.notificaciones.trx_marcaciones (identificacion_empleado, fecha_marcacion);
CREATE INDEX IF NOT EXISTS ix_trx_marcaciones_empresa_id ON core.notificaciones.trx_marcaciones (empresa_id);
CREATE INDEX IF NOT EXISTS ix_trx_marcaciones_sin_publicar ON core.notificaciones.trx_marcaciones (fecha_marcacion) WHERE fecha_publicado_rrhh IS NULL;
CREATE INDEX IF NOT EXISTS ix_trx_marcaciones_tipo_marcacion_id ON core.notificaciones.trx_marcaciones (tipo_marcacion_id);

-- Comentarios
COMMENT ON TABLE core.notificaciones.trx_marcaciones IS 'Única fuente de verdad de la marcación cruda. svc-rrhh la recibe por evento: cierra el gap de las dos asistencias sin puente ETL.';
COMMENT ON COLUMN core.notificaciones.trx_marcaciones.empresa_id IS 'Empresa propietaria de la marcación';
COMMENT ON COLUMN core.notificaciones.trx_marcaciones.dispositivo_id IS 'Dispositivo biométrico que registró la marcación (FK compuesta con empresa_id)';
COMMENT ON COLUMN core.notificaciones.trx_marcaciones.tipo_marcacion_id IS 'Tipo de marcación (catálogo global)';
COMMENT ON COLUMN core.notificaciones.trx_marcaciones.identificacion_empleado IS 'Identificación del empleado tal como la reportó el dispositivo';
COMMENT ON COLUMN core.notificaciones.trx_marcaciones.empleado_id IS 'Empleado resuelto por svc-rrhh (referencia lógica, sin FK)';
COMMENT ON COLUMN core.notificaciones.trx_marcaciones.fecha_marcacion IS 'Fecha y hora de la marcación (clave de partición)';
COMMENT ON COLUMN core.notificaciones.trx_marcaciones.origen IS 'Origen de la marcación: dispositivo u otro';
COMMENT ON COLUMN core.notificaciones.trx_marcaciones.payload_crudo IS 'Respuesta cruda del dispositivo (trazabilidad y reproceso)';
COMMENT ON COLUMN core.notificaciones.trx_marcaciones.fecha_publicado_rrhh IS 'Fecha en que svc-rrhh consumió el evento; NULL si aún no se publicó';