Especificación Técnica: trx_visitas_requerimientos¶
Esquema: fuerza_ventas
Base de Datos: crm
Tabla Legacy Origen: c065t_requerimientos_visita
Propósito: Requerimientos comerciales, técnicos, materiales POP y reclamos solicitados durante una visita. Normaliza requerimientos 1:N con ciclo de vida, fechas de compromiso y asignación de responsables.
1. Justificación y Mejoras de Arquitectura¶
- Estructura Normalizada y Desacoplada (1:N): Sustituye flags booleanos rígidos por un modelo estructurado donde cada visita puede originar múltiples requerimientos con seguimiento independiente de estados (
PENDIENTE,EN_PROCESO,ATENDIDO,CANCELADO). - Integración con Catálogos de Requerimiento: Relaciona formalmente mediante FK compuesta
(empresa_id, tipo_requerimiento_id)haciafuerza_ventas.cat_tipos_requerimiento_visita(empresa_id, id),(empresa_id, prioridad_id)haciafuerza_ventas.cat_prioridades_requerimiento(empresa_id, id)y(empresa_id, estado_atencion_id)haciafuerza_ventas.cat_estados_requerimiento_visita(empresa_id, id). - Aislamiento Multi-Tenant (RLS): Integra
empresa_id BIGINT NOT NULLcon políticas RLS obligatorias. - Integridad Referencial Compuesta: Clave única compuesta
(empresa_id, id)y FK compuesta(empresa_id, visita_id)haciafuerza_ventas.trx_visitas(empresa_id, id)con borrado en cascada. - Trazabilidad y Auditoría: Auditoría integral (
created_at,updated_at,deleted_at,created_by,updated_by) con auditoría integral.
2. Definiciones de Implementación¶
Table fuerza_ventas.trx_visitas_requerimientos {
id uuid [pk, default: `gen_random_uuid()`, note: 'Identificador único UUID']
empresa_id bigint [not null, note: 'Identificador BIGINT de la empresa en core.identidad (RLS)']
visita_id uuid [not null, note: 'Visita origen asociada']
tipo_requerimiento_id uuid [not null, note: 'Identificador del tipo de requerimiento (FK cat_tipos_requerimiento_visita)']
descripcion_requerimiento text [not null, note: 'Detalle de lo solicitado por el cliente']
prioridad_id uuid [not null, note: 'Nivel de prioridad (FK cat_prioridades_requerimiento)']
estado_atencion_id uuid [not null, note: 'Estado de resolución (FK cat_estados_requerimiento_visita)']
fecha_compromiso date [note: 'Fecha límite acordada para resolución']
fecha_atencion timestamptz [note: 'Fecha y hora real en que se completó']
usuario_responsable_id uuid [note: 'Usuario asignado para resolver (correlación core.identidad)']
observaciones_resolucion text [note: 'Comentarios de cierre o dictamen de atención']
// Auditoría General
is_activo boolean [not null, default: `true`, note: 'Estado lógico del registro']
created_at timestamptz [not null, default: `now()`, note: 'Fecha de creación']
updated_at timestamptz [not null, default: `now()`, note: 'Fecha de última actualización']
deleted_at timestamptz [note: 'Fecha de eliminación lógica']
created_by uuid [note: 'Usuario creador']
updated_by uuid [note: 'Usuario modificador']
Indexes {
(empresa_id, id) [unique, name: 'uq_trx_visitas_req_empresa_id']
(empresa_id, visita_id) [name: 'ix_trx_visitas_req_empresa_visita']
(empresa_id, tipo_requerimiento_id) [name: 'ix_trx_visitas_req_empresa_tipo']
(empresa_id, estado_atencion_id) [name: 'ix_trx_visitas_req_empresa_estado']
(empresa_id, usuario_responsable_id) [name: 'ix_trx_visitas_req_empresa_responsable']
(empresa_id, is_activo) [name: 'ix_trx_visitas_req_empresa_activo']
}
}
Ref: fuerza_ventas.trx_visitas_requerimientos.(empresa_id, visita_id) > fuerza_ventas.trx_visitas.(empresa_id, id) [delete: cascade]
Ref: fuerza_ventas.trx_visitas_requerimientos.(empresa_id, tipo_requerimiento_id) > fuerza_ventas.cat_tipos_requerimiento_visita.(empresa_id, id) [delete: restrict]
Ref: fuerza_ventas.trx_visitas_requerimientos.(empresa_id, prioridad_id) > fuerza_ventas.cat_prioridades_requerimiento.(empresa_id, id) [delete: restrict]
Ref: fuerza_ventas.trx_visitas_requerimientos.(empresa_id, estado_atencion_id) > fuerza_ventas.cat_estados_requerimiento_visita.(empresa_id, id) [delete: restrict]
CREATE TABLE IF NOT EXISTS fuerza_ventas.trx_visitas_requerimientos (
id UUID NOT NULL DEFAULT gen_random_uuid(),
empresa_id BIGINT NOT NULL,
visita_id UUID NOT NULL,
tipo_requerimiento_id UUID NOT NULL,
descripcion_requerimiento TEXT NOT NULL,
prioridad_id UUID NOT NULL,
estado_atencion_id UUID NOT NULL,
fecha_compromiso DATE,
fecha_atencion TIMESTAMPTZ,
usuario_responsable_id UUID,
observaciones_resolucion TEXT,
-- Auditoría General
is_activo BOOLEAN NOT NULL DEFAULT true,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
deleted_at TIMESTAMPTZ,
created_by UUID,
updated_by UUID,
CONSTRAINT pk_trx_visitas_requerimientos PRIMARY KEY (id),
CONSTRAINT uq_trx_visitas_req_empresa_id UNIQUE (empresa_id, id),
CONSTRAINT fk_trx_visitas_req_visita FOREIGN KEY (empresa_id, visita_id)
REFERENCES fuerza_ventas.trx_visitas (empresa_id, id)
ON DELETE CASCADE,
CONSTRAINT fk_trx_visitas_req_tipo FOREIGN KEY (empresa_id, tipo_requerimiento_id)
REFERENCES fuerza_ventas.cat_tipos_requerimiento_visita (empresa_id, id)
ON DELETE RESTRICT,
CONSTRAINT fk_trx_visitas_req_prioridad FOREIGN KEY (empresa_id, prioridad_id)
REFERENCES fuerza_ventas.cat_prioridades_requerimiento (empresa_id, id)
ON DELETE RESTRICT,
CONSTRAINT fk_trx_visitas_req_estado FOREIGN KEY (empresa_id, estado_atencion_id)
REFERENCES fuerza_ventas.cat_estados_requerimiento_visita (empresa_id, id)
ON DELETE RESTRICT
);
-- Índices
CREATE INDEX IF NOT EXISTS ix_trx_visitas_req_empresa_visita
ON fuerza_ventas.trx_visitas_requerimientos (empresa_id, visita_id);
CREATE INDEX IF NOT EXISTS ix_trx_visitas_req_empresa_tipo
ON fuerza_ventas.trx_visitas_requerimientos (empresa_id, tipo_requerimiento_id);
CREATE INDEX IF NOT EXISTS ix_trx_visitas_req_empresa_estado
ON fuerza_ventas.trx_visitas_requerimientos (empresa_id, estado_atencion_id);
CREATE INDEX IF NOT EXISTS ix_trx_visitas_req_empresa_responsable
ON fuerza_ventas.trx_visitas_requerimientos (empresa_id, usuario_responsable_id);
CREATE INDEX IF NOT EXISTS ix_trx_visitas_req_empresa_activo
ON fuerza_ventas.trx_visitas_requerimientos (empresa_id, is_activo);
-- Row-Level Security
ALTER TABLE fuerza_ventas.trx_visitas_requerimientos ENABLE ROW LEVEL SECURITY;
CREATE POLICY rls_trx_visitas_req_empresa
ON fuerza_ventas.trx_visitas_requerimientos
FOR ALL
USING (
empresa_id = current_setting('app.current_empresa_id', true)::BIGINT
)
WITH CHECK (
empresa_id = current_setting('app.current_empresa_id', true)::BIGINT
);
-- Comentarios
COMMENT ON TABLE fuerza_ventas.trx_visitas_requerimientos IS 'Requerimientos comerciales, técnicos y reclamos levantados en visitas (Normalizado 1:N)';
COMMENT ON COLUMN fuerza_ventas.trx_visitas_requerimientos.tipo_requerimiento_id IS 'Identificador del tipo de requerimiento (FK cat_tipos_requerimiento_visita)';
COMMENT ON COLUMN fuerza_ventas.trx_visitas_requerimientos.prioridad_id IS 'ALTA, MEDIA, BAJA, URGENTE';
COMMENT ON COLUMN fuerza_ventas.trx_visitas_requerimientos.estado_atencion_id IS 'PENDIENTE, EN_PROCESO, ATENDIDO, CANCELADO';
COMMENT ON COLUMN fuerza_ventas.trx_visitas_requerimientos.usuario_responsable_id IS 'Correlación lógica con core.identidad.mae_usuarios (sin FK cross-DB)';