Especificación Técnica: `trx_visitas_documentos`¶

Esquema: fuerza_ventas
Base de Datos: crm
Tabla Legacy Origen: c064t_documentos_agenda (4.640 MB bytea eliminados)
Propósito: Evidencias fotográficas, firmas digitales y actas de visita capturadas en la app móvil y almacenadas en Object Storage (S3 / MinIO).

1. Justificación y Mejoras de Arquitectura¶

Desacoplamiento de Binarios (Blob Offloading): Elimina el almacenamiento de imágenes binarias dentro de PostgreSQL, conservando URLs hacia S3/MinIO, tipo MIME, tamaño y hash de integridad SHA-256.
Georreferenciación de Evidencias: Registra coordenadas GPS (latitud_captura, longitud_captura) en DOUBLE PRECISION para auditar la presencia física al momento de la toma de evidencias.
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_documentos {
    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 asociada']
    tipo_evidencia_id   uuid              [not null, note: 'Tipo de evidencia (FK cat_tipos_evidencia_visita)']
    url_almacenamiento  varchar(500)      [not null, note: 'URL en Object Storage (S3/MinIO)']
    mime_type           varchar(100)      [not null, note: 'Tipo de contenido MIME']
    tamano_bytes        bigint            [not null, note: 'Tamaño del archivo en bytes']
    hash_sha256         varchar(64)       [note: 'Hash criptográfico SHA-256 para verificación de integridad']
    latitud_captura     double precision  [note: 'Coordenada GPS Latitud al capturar la evidencia']
    longitud_captura    double precision  [note: 'Coordenada GPS Longitud al capturar la evidencia']

    // 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_docs_empresa_id']
        (empresa_id, is_activo) [name: 'ix_trx_visitas_docs_empresa_activo']
        (empresa_id, visita_id) [name: 'ix_trx_visitas_docs_empresa_visita']
        (empresa_id, tipo_evidencia_id) [name: 'ix_trx_visitas_docs_empresa_tipo']
    }
}

Ref: fuerza_ventas.trx_visitas_documentos.(empresa_id, visita_id) > fuerza_ventas.trx_visitas.(empresa_id, id) [delete: cascade]
Ref: fuerza_ventas.trx_visitas_documentos.(empresa_id, tipo_evidencia_id) > fuerza_ventas.cat_tipos_evidencia_visita.(empresa_id, id) [delete: restrict]

CREATE TABLE IF NOT EXISTS fuerza_ventas.trx_visitas_documentos (
    id UUID NOT NULL DEFAULT gen_random_uuid(),
    empresa_id BIGINT NOT NULL,
    visita_id UUID NOT NULL,
    tipo_evidencia_id UUID NOT NULL,
    url_almacenamiento VARCHAR(500) NOT NULL,
    mime_type VARCHAR(100) NOT NULL,
    tamano_bytes BIGINT NOT NULL,
    hash_sha256 VARCHAR(64),
    latitud_captura DOUBLE PRECISION,
    longitud_captura DOUBLE PRECISION,

    -- 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_documentos
        PRIMARY KEY (id),

    CONSTRAINT uq_trx_visitas_docs_empresa_id
        UNIQUE (empresa_id, id),

    CONSTRAINT fk_trx_visitas_docs_visita
        FOREIGN KEY (empresa_id, visita_id)
        REFERENCES fuerza_ventas.trx_visitas (empresa_id, id)
        ON DELETE CASCADE

    CONSTRAINT fk_trx_visitas_docs_tipo_evidencia
        FOREIGN KEY (empresa_id, tipo_evidencia_id)
        REFERENCES fuerza_ventas.cat_tipos_evidencia_visita (empresa_id, id)
        ON DELETE RESTRICT
);

CREATE INDEX IF NOT EXISTS ix_trx_visitas_docs_empresa_activo
    ON fuerza_ventas.trx_visitas_documentos (empresa_id, is_activo);

CREATE INDEX IF NOT EXISTS ix_trx_visitas_docs_empresa_visita
    ON fuerza_ventas.trx_visitas_documentos (empresa_id, visita_id);

CREATE INDEX IF NOT EXISTS ix_trx_visitas_docs_empresa_tipo
    ON fuerza_ventas.trx_visitas_documentos (empresa_id, tipo_evidencia_id);

COMMENT ON TABLE fuerza_ventas.trx_visitas_documentos IS
    'Documentos y Evidencias de Visita: Evidencias fotográficas, firmas digitales y actas almacenadas en Object Storage.';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.id IS
    'Identificador único UUID';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.empresa_id IS
    'Identificador UUID de la empresa en core.identidad (RLS)';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.visita_id IS
    'Visita asociada';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.tipo_evidencia_id IS
    'FOTO_FACHADA, FOTO_EXHIBIDOR, FOTO_INVENTARIO, FIRMA_DIGITAL_CLIENTE, ACTA_ACUERDO, COMPROBANTE_PAGO';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.url_almacenamiento IS
    'URL en Object Storage (S3/MinIO)';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.mime_type IS
    'Tipo de contenido MIME';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.tamano_bytes IS
    'Tamaño del archivo en bytes';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.hash_sha256 IS
    'Hash criptográfico SHA-256 para verificación de integridad';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.latitud_captura IS
    'Coordenada GPS Latitud al capturar la evidencia';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.longitud_captura IS
    'Coordenada GPS Longitud al capturar la evidencia';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.is_activo IS
    'Estado lógico del registro';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.created_at IS
    'Fecha de creación';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.updated_at IS
    'Fecha de última actualización';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.deleted_at IS
    'Fecha de eliminación lógica';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.created_by IS
    'Usuario creador';

COMMENT ON COLUMN fuerza_ventas.trx_visitas_documentos.updated_by IS
    'Usuario modificador';

ALTER TABLE fuerza_ventas.trx_visitas_documentos
    ENABLE ROW LEVEL SECURITY;

CREATE POLICY rls_trx_visitas_docs_empresa
    ON fuerza_ventas.trx_visitas_documentos
    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
    );

import uuid
from datetime import datetime
from typing import Optional

from sqlalchemy import (
    BigInteger,
    Boolean,
    Double,
    ForeignKeyConstraint,
    Index,
    String,
    UniqueConstraint,
    text,
)
from sqlalchemy.dialects.postgresql import TIMESTAMPTZ, UUID
from sqlalchemy.orm import Mapped, mapped_column

from app.db.base import Base


class TrxVisitasDocumentos(Base):
    """
    Documentos y Evidencias de Visita.

    Evidencias fotográficas, firmas digitales y actas de visita capturadas
    en la app móvil y almacenadas en MinIO/S3.

    Legacy:
        c064t_documentos_agenda
    """

    __tablename__ = "trx_visitas_documentos"

    __table_args__ = (
        UniqueConstraint(
            "empresa_id",
            "id",
            name="uq_trx_visitas_docs_empresa_id",
        ),
        ForeignKeyConstraint(
            ["empresa_id", "visita_id"],
            ["fuerza_ventas.trx_visitas.empresa_id", "fuerza_ventas.trx_visitas.id"],
            ondelete="CASCADE",
            name="fk_trx_visitas_docs_visita",
        ),
        Index(
            "ix_trx_visitas_docs_empresa_activo",
            "empresa_id",
            "is_activo",
        ),
        Index(
            "ix_trx_visitas_docs_empresa_visita",
            "empresa_id",
            "visita_id",
        ),
        Index(
            "ix_trx_visitas_docs_empresa_tipo",
            "empresa_id",
            "tipo_evidencia_id",
        ),
        {
            "schema": "fuerza_ventas",
            "comment": "Documentos y Evidencias de Visita",
        },
    )

    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 asociada",
    )

    tipo_evidencia_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        nullable=False,
        comment="Tipo de evidencia (FK cat_tipos_evidencia_visita)",
    )

    url_almacenamiento: Mapped[str] = mapped_column(
        String(500),
        nullable=False,
        comment="URL en Object Storage (S3/MinIO)",
    )

    mime_type: Mapped[str] = mapped_column(
        String(100),
        nullable=False,
        comment="Tipo de contenido MIME",
    )

    tamano_bytes: Mapped[int] = mapped_column(
        BigInteger,
        nullable=False,
        comment="Tamaño del archivo en bytes",
    )

    hash_sha256: Mapped[Optional[str]] = mapped_column(
        String(64),
        nullable=True,
        comment="Hash criptográfico SHA-256 para verificación de integridad",
    )

    latitud_captura: Mapped[Optional[float]] = mapped_column(
        Double,
        nullable=True,
        comment="Coordenada GPS Latitud al capturar la evidencia",
    )

    longitud_captura: Mapped[Optional[float]] = mapped_column(
        Double,
        nullable=True,
        comment="Coordenada GPS Longitud al capturar la evidencia",
    )

    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(
        TIMESTAMPTZ,
        nullable=False,
        server_default=text("now()"),
        comment="Fecha de creación",
    )

    updated_at: Mapped[datetime] = mapped_column(
        TIMESTAMPTZ,
        nullable=False,
        server_default=text("now()"),
        comment="Fecha de última actualización",
    )

    deleted_at: Mapped[Optional[datetime]] = mapped_column(
        TIMESTAMPTZ,
        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",
    )

"""create trx_visitas_documentos

Revision ID: trx_0003
Revises: trx_0002
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_0003"
down_revision: Union[str, Sequence[str], None] = "trx_0002"
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:

    op.create_table(
        "trx_visitas_documentos",

        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 asociada",
        ),

        sa.Column(
            "tipo_evidencia_id",
            postgresql.UUID(as_uuid=True),
            nullable=False,
            comment="Tipo de evidencia (FK cat_tipos_evidencia_visita)",
        ),

        sa.Column(
            "url_almacenamiento",
            sa.String(length=500),
            nullable=False,
            comment="URL en Object Storage (S3/MinIO)",
        ),

        sa.Column(
            "mime_type",
            sa.String(length=100),
            nullable=False,
            comment="Tipo de contenido MIME",
        ),

        sa.Column(
            "tamano_bytes",
            sa.BigInteger(),
            nullable=False,
            comment="Tamaño del archivo en bytes",
        ),

        sa.Column(
            "hash_sha256",
            sa.String(length=64),
            nullable=True,
            comment="Hash criptográfico SHA-256 para verificación de integridad",
        ),

        sa.Column(
            "latitud_captura",
            sa.Float(precision=53),
            nullable=True,
            comment="Coordenada GPS Latitud al capturar la evidencia",
        ),

        sa.Column(
            "longitud_captura",
            sa.Float(precision=53),
            nullable=True,
            comment="Coordenada GPS Longitud al capturar la evidencia",
        ),

        # 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_documentos",
        ),

        sa.UniqueConstraint(
            "empresa_id",
            "id",
            name="uq_trx_visitas_docs_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_docs_visita",
        ),

        comment="Documentos y Evidencias de Visita",
        schema="fuerza_ventas",
    )

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

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

    op.create_index(
        "ix_trx_visitas_docs_empresa_tipo",
        "trx_visitas_documentos",
        ["empresa_id", "tipo_evidencia_id"],
        unique=False,
        schema="fuerza_ventas",
    )

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

    op.execute(
        """
        CREATE POLICY rls_trx_visitas_docs_empresa
        ON fuerza_ventas.trx_visitas_documentos
        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_docs_empresa
        ON fuerza_ventas.trx_visitas_documentos;
        """
    )

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

    op.drop_index(
        "ix_trx_visitas_docs_empresa_tipo",
        table_name="trx_visitas_documentos",
        schema="fuerza_ventas",
    )

    op.drop_index(
        "ix_trx_visitas_docs_empresa_visita",
        table_name="trx_visitas_documentos",
        schema="fuerza_ventas",
    )

    op.drop_index(
        "ix_trx_visitas_docs_empresa_activo",
        table_name="trx_visitas_documentos",
        schema="fuerza_ventas",
    )

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

Especificación Técnica: trx_visitas_documentos¶

1. Justificación y Mejoras de Arquitectura¶

2. Definiciones de Implementación¶

Especificación Técnica: `trx_visitas_documentos`¶