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_marcacioneses la única fuente ysvc-rrhhla 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óndefaultno se documentan por ahora). - PK compuesta
(id, fecha_marcacion): elidUUID 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_ides una referencia lógica asvc-rrhh(lo resuelve por evento), sin FOREIGN KEY, igual que en el fuente.payload_crudo JSONBconserva 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 quetrx_refresh_tokensencore.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ó';