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) hacia fuerza_ventas.cat_tipos_requerimiento_visita(empresa_id, id).
• Aislamiento Multi-Tenant (RLS): Integra empresa_id BIGINT NOT NULL con políticas RLS obligatorias.
• Integridad Referencial Compuesta: Clave única compuesta (empresa_id, id) y FK compuesta (empresa_id, visita_id) hacia fuerza_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

DBMLSQLSQLAlchemyAlembic

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
);

-- Í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)';

from datetime import date, datetime
from typing import Optional
import uuid

from sqlalchemy import (
    BigInteger,
    Boolean,
    Date,
    DateTime,
    ForeignKeyConstraint,
    Index,
    String,
    Text,
    UniqueConstraint,
    text,
)
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship


class Base(DeclarativeBase):
    pass


class TrxVisitasRequerimiento(Base):
    __tablename__ = "trx_visitas_requerimientos"
    __table_args__ = (
        UniqueConstraint(
            "empresa_id",
            "id",
            name="uq_trx_visitas_req_empresa_id",
        ),
        ForeignKeyConstraint(
            ["empresa_id", "visita_id"],
            ["fuerza_ventas.trx_visitas.empresa_id", "fuerza_ventas.trx_visitas.id"],
            ondelete="CASCADE",
            name="fk_trx_visitas_req_visita",
        ),
        ForeignKeyConstraint(
            ["empresa_id", "tipo_requerimiento_id"],
            ["fuerza_ventas.cat_tipos_requerimiento_visita.empresa_id", "fuerza_ventas.cat_tipos_requerimiento_visita.id"],
            ondelete="RESTRICT",
            name="fk_trx_visitas_req_tipo",
        ),
        Index(
            "ix_trx_visitas_req_empresa_visita",
            "empresa_id",
            "visita_id",
        ),
        Index(
            "ix_trx_visitas_req_empresa_tipo",
            "empresa_id",
            "tipo_requerimiento_id",
        ),
        Index(
            "ix_trx_visitas_req_empresa_estado",
            "empresa_id",
            "estado_atencion",
        ),
        Index(
            "ix_trx_visitas_req_empresa_responsable",
            "empresa_id",
            "usuario_responsable_id",
        ),
        Index(
            "ix_trx_visitas_req_empresa_activo",
            "empresa_id",
            "is_activo",
        ),
        {"schema": "fuerza_ventas"},
    )

    # Identificadores y Claves
    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        primary_key=True,
        server_default=text("gen_random_uuid()"),
        comment="Identificador único UUID",
    )

    empresa_id: Mapped[int] = mapped_column(
        BigInteger,
        nullable=False,
        comment="Identificador UUID de la empresa en core.identidad (RLS)",
    )

    visita_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        nullable=False,
        comment="Visita origen asociada",
    )

    tipo_requerimiento_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        nullable=False,
        comment="Identificador del tipo de requerimiento (FK cat_tipos_requerimiento_visita)",
    )

    # Campos de Negocio
    descripcion_requerimiento: Mapped[str] = mapped_column(
        Text,
        nullable=False,
        comment="Detalle de lo solicitado por el cliente",
    )

    prioridad_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        nullable=False,
        comment="Nivel de prioridad (FK cat_prioridades_requerimiento)",
    )

    estado_atencion_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        nullable=False,
        comment="Estado de resolución (FK cat_estados_requerimiento_visita)",
    )

    fecha_compromiso: Mapped[Optional[date]] = mapped_column(
        Date,
        nullable=True,
        comment="Fecha límite acordada para resolución",
    )

    fecha_atencion: Mapped[Optional[datetime]] = mapped_column(
        DateTime(timezone=True),
        nullable=True,
        comment="Fecha y hora real en que se completó",
    )

    usuario_responsable_id: Mapped[Optional[uuid.UUID]] = mapped_column(
        UUID(as_uuid=True),
        nullable=True,
        comment="Usuario asignado para resolver (correlación core.identidad)",
    )

    observaciones_resolucion: Mapped[Optional[str]] = mapped_column(
        Text,
        nullable=True,
        comment="Comentarios de cierre o dictamen de atención",
    )

    # Auditoría General
    is_activo: Mapped[bool] = mapped_column(
        Boolean,
        nullable=False,
        server_default=text("true"),
        comment="Estado lógico del registro",
    )

    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True),
        nullable=False,
        server_default=text("now()"),
        comment="Fecha de creación",
    )

    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True),
        nullable=False,
        server_default=text("now()"),
        onupdate=datetime.utcnow,
        comment="Fecha de última actualización",
    )

    deleted_at: Mapped[Optional[datetime]] = mapped_column(
        DateTime(timezone=True),
        nullable=True,
        comment="Fecha de eliminación lógica",
    )

    created_by: Mapped[Optional[uuid.UUID]] = mapped_column(
        UUID(as_uuid=True),
        nullable=True,
        comment="Usuario creador",
    )

    updated_by: Mapped[Optional[uuid.UUID]] = mapped_column(
        UUID(as_uuid=True),
        nullable=True,
        comment="Usuario modificador",
    )

```python """create trx_visitas_requerimientos

Revision ID: trx_0002 Revises: trx_0001 Create Date: 2026-09-09 """

from typing import Sequence, Union

from alembic import op import sqlalchemy as sa from sqlalchemy.dialects import postgresql

revision identifiers, used by Alembic.

revision: str = "trx_0002" down_revision: Union[str, Sequence[str], None] = "trx_0001" branch_labels: Union[str, Sequence[str], None] = None depends_on: Union[str, Sequence[str], None] = None

def upgrade() -> None:

op.create_table(
    "trx_visitas_requerimientos",

    sa.Column(
        "id",
        postgresql.UUID(as_uuid=True),
        nullable=False,
        server_default=sa.text("gen_random_uuid()"),
        comment="Identificador único UUID",
    ),

    sa.Column(
        "empresa_id",
        sa.BigInteger(),
        nullable=False,
        comment="Identificador UUID de la empresa en core.identidad (RLS)",
    ),

    sa.Column(
        "visita_id",
        postgresql.UUID(as_uuid=True),
        nullable=False,
        comment="Visita origen asociada",
    ),

    sa.Column(
        "tipo_requerimiento_id",
        postgresql.UUID(as_uuid=True),
        nullable=False,
        comment="Identificador del tipo de requerimiento (FK cat_tipos_requerimiento_visita)",
    ),

    sa.Column(
        "descripcion_requerimiento",
        sa.Text(),
        nullable=False,
        comment="Detalle de lo solicitado por el cliente",
    ),

    sa.Column(
        "prioridad_id",
        postgresql.UUID(as_uuid=True),
        nullable=False,
        comment="Nivel de prioridad (FK cat_prioridades_requerimiento)",
    ),

    sa.Column(
        "estado_atencion_id",
        postgresql.UUID(as_uuid=True),
        nullable=False,
        comment="Estado de resolución (FK cat_estados_requerimiento_visita)",
    ),

    sa.Column(
        "fecha_compromiso",
        sa.Date(),
        nullable=True,
        comment="Fecha límite acordada para resolución",
    ),

    sa.Column(
        "fecha_atencion",
        sa.TIMESTAMP(timezone=True),
        nullable=True,
        comment="Fecha y hora real en que se completó",
    ),

    sa.Column(
        "usuario_responsable_id",
        postgresql.UUID(as_uuid=True),
        nullable=True,
        comment="Usuario asignado para resolver (correlación core.identidad)",
    ),

    sa.Column(
        "observaciones_resolucion",
        sa.Text(),
        nullable=True,
        comment="Comentarios de cierre o dictamen de atención",
    ),

    # Auditoría General
    sa.Column(
        "is_activo",
        sa.Boolean(),
        nullable=False,
        server_default=sa.text("true"),
        comment="Estado lógico del registro",
    ),

    sa.Column(
        "created_at",
        sa.TIMESTAMP(timezone=True),
        nullable=False,
        server_default=sa.text("now()"),
        comment="Fecha de creación",
    ),

    sa.Column(
        "updated_at",
        sa.TIMESTAMP(timezone=True),
        nullable=False,
        server_default=sa.text("now()"),
        comment="Fecha de última actualización",
    ),

    sa.Column(
        "deleted_at",
        sa.TIMESTAMP(timezone=True),
        nullable=True,
        comment="Fecha de eliminación lógica",
    ),

    sa.Column(
        "created_by",
        postgresql.UUID(as_uuid=True),
        nullable=True,
        comment="Usuario creador",
    ),

    sa.Column(
        "updated_by",
        postgresql.UUID(as_uuid=True),
        nullable=True,
        comment="Usuario modificador",
    ),

    sa.PrimaryKeyConstraint(
        "id",
        name="pk_trx_visitas_requerimientos",
    ),

    sa.UniqueConstraint(
        "empresa_id",
        "id",
        name="uq_trx_visitas_req_empresa_id",
    ),

    sa.ForeignKeyConstraint(
        ["empresa_id", "visita_id"],
        ["fuerza_ventas.trx_visitas.empresa_id", "fuerza_ventas.trx_visitas.id"],
        ondelete="CASCADE",
        name="fk_trx_visitas_req_visita",
    ),

    sa.ForeignKeyConstraint(
        ["empresa_id", "tipo_requerimiento_id"],
        ["fuerza_ventas.cat_tipos_requerimiento_visita.empresa_id", "fuerza_ventas.cat_tipos_requerimiento_visita.id"],
        ondelete="RESTRICT",
        name="fk_trx_visitas_req_tipo",
    ),

    comment="Requerimientos de Visitas (Normalizado 1:N)",
    schema="fuerza_ventas",
)

op.create_index(
    "ix_trx_visitas_req_empresa_activo",
    "trx_visitas_requerimientos",
    ["empresa_id", "is_activo"],
    unique=False,
    schema="fuerza_ventas",
)

op.create_index(
    "ix_trx_visitas_req_empresa_visita",
    "trx_visitas_requerimientos",
    ["empresa_id", "visita_id"],
    unique=False,
    schema="fuerza_ventas",
)

op.create_index(
    "ix_trx_visitas_req_empresa_tipo",
    "trx_visitas_requerimientos",
    ["empresa_id", "tipo_requerimiento_id"],
    unique=False,
    schema="fuerza_ventas",
)

op.create_index(
    "ix_trx_visitas_req_empresa_estado",
    "trx_visitas_requerimientos",
    ["empresa_id", "estado_atencion"],
    unique=False,
    schema="fuerza_ventas",
)

op.create_index(
    "ix_trx_visitas_req_empresa_responsable",
    "trx_visitas_requerimientos",
    ["empresa_id", "usuario_responsable_id"],
    unique=False,
    schema="fuerza_ventas",
)

op.execute(
    """
    ALTER TABLE fuerza_ventas.trx_visitas_requerimientos
    ENABLE ROW LEVEL SECURITY;
    """
)

op.execute(
    """
    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
    );
    """
)

def downgrade() -> None:

op.execute(
    """
    DROP POLICY IF EXISTS rls_trx_visitas_req_empresa
    ON fuerza_ventas.trx_visitas_requerimientos;
    """
)

op.execute(
    """
    ALTER TABLE fuerza_ventas.trx_visitas_requerimientos
    DISABLE ROW LEVEL SECURITY;
    """
)

op.drop_index(
    "ix_trx_visitas_req_empresa_responsable",
    table_name="trx_visitas_requerimientos",
    schema="fuerza_ventas",
)

op.drop_index(
    "ix_trx_visitas_req_empresa_estado",
    table_name="trx_visitas_requerimientos",
    schema="fuerza_ventas",
)

op.drop_index(
    "ix_trx_visitas_req_empresa_tipo",
    table_name="trx_visitas_requerimientos",
    schema="fuerza_ventas",
)

op.drop_index(
    "ix_trx_visitas_req_empresa_visita",
    table_name="trx_visitas_requerimientos",
    schema="fuerza_ventas",
)

op.drop_index(
    "ix_trx_visitas_req_empresa_activo",
    table_name="trx_visitas_requerimientos",
    schema="fuerza_ventas",
)

op.drop_table(
    "trx_visitas_requerimientos",
    schema="fuerza_ventas",
)