Documentación completa de vistas

Book

Libros: vw_book

vw_book consolida en una única salida el catálogo de libros con:

• metadatos básicos (códigos, título, estado)

• autores (concatenados)

• materias (códigos y rutas jerárquicas via vw_materia)

• proveedor principal (via vw_party)

• precio vigente según lista definida por parámetro global parameter.key='PriceList'

• costo vigente más reciente del libro

• stock consolidado (suma en depósitos)

• auditoría (transacciones de creación/actualización)

Notas importantes

• Precio: price corresponde a la lista indicada en parameter.value para la clave PriceList. Cambiar ese parámetro cambia el resultado de la vista.

*Performance: la vista incluye varias subconsultas correlacionadas (autores, materias, isbn/barcode, stock). Para listados masivos se recomienda filtrar/paginar.

• En la vista vw_book_audit hay fechas de modificaciones

TODO: búsqueda por ISBN optimizada

Casos de uso (queries de prueba)

A) Catálogo paginado (para UI/Backoffice)

SELECT book_id, int_code, title, authors_full, price, stock_total, active
FROM public.vw_book
WHERE active = true
ORDER BY title
LIMIT 50 OFFSET 0;

B) Buscar por ISBN o código interno

SELECT *
FROM public.vw_book
WHERE isbn = '9789871234567'
   OR int_code = 'INT-000123';

C) Stock + precio por proveedor principal

SELECT main_provider_party_id, main_provider_name, COUNT(*) AS books, SUM(stock_total) AS stock
FROM public.vw_book
WHERE main_provider_party_id IS NOT NULL
GROUP BY main_provider_party_id, main_provider_name
ORDER BY books DESC;

Diccionario de Columnas

Book Audit

Auditoría de libros vw_book_audit

Vista orientada a auditoría y sincronización incremental del catálogo. Devuelve las fechas clave de actividad del libro y calcula global_last_modification_at como indicador único de “última modificación”.

Casos de uso

Query de uso típico: “libros cambiados desde X”

SELECT book_id, int_code, title, global_last_modification_at
FROM public.vw_book_audit
WHERE global_last_modification_at > '2025-06-01'::timestamp
ORDER BY global_last_modification_at;

Catálogo de Libros — Sincronización y Vistas

Este módulo expone el catálogo de libros mediante vistas SQL optimizadas para dos propósitos distintos:

• Detección eficiente de cambios (auditoría / sincronización incremental)

• Obtención del detalle completo del libro (catálogo enriquecido)

La separación de responsabilidades permite escalar el sistema sin penalizar consultas frecuentes ni procesos batch.

Vistas principales

vw_book_audit — Auditoría y detección de cambios

Vista liviana orientada a control y sincronización. Expone las fechas clave de actividad de cada libro y calcula un único timestamp de referencia:

global_last_modification_at

Este campo representa la fecha más reciente entre:

creación o edición de la ficha del libro,

último cambio de precio (según la lista definida por el parámetro global PriceList),

último movimiento real de stock.

👉 Uso principal: detectar qué libros cambiaron desde una fecha/hora.

vw_book — Vista maestra de catálogo

Vista enriquecida que consolida:

metadatos del libro,

autores (concatenados),

materias jerárquicas (vía vw_materia),

proveedor principal (vía vw_party),

stock consolidado,

precio vigente según PriceList,

auditoría.

👉 Uso principal: obtener todos los datos del libro para UI, APIs o exportaciones.

Flujo recomendado de sincronización

• Consultar vw_book_audit para identificar los libros modificados desde la última sincronización.

• Usar los book_id obtenidos para consultar vw_book.

• Procesar los resultados en orden, permitiendo paginación y reintentos seguros.

Este patrón evita escanear todo el catálogo y reduce significativamente el costo de sincronización.

Queries de ejemplo

1) Traer todos los datos de libros modificados desde una fecha/hora

-- :since = timestamp de última sincronización
WITH changed_books AS (
  SELECT book_id, global_last_modification_at
  FROM public.vw_book_audit
  WHERE global_last_modification_at > '2025-06-01 00:00:00'::timestamp
)
SELECT
  vb.*,
  cb.global_last_modification_at
FROM public.vw_book vb
JOIN changed_books cb ON cb.book_id = vb.book_id
ORDER BY cb.global_last_modification_at ASC, vb.book_id;

2) Sincronización incremental por lotes (paginable)

Recomendado para procesos batch o APIs.

-- Cursor compuesto: (last_sync_at, last_book_id)
WITH changed_books AS (
  SELECT book_id, global_last_modification_at
  FROM public.vw_book_audit
  WHERE (global_last_modification_at, book_id)
        > ('2025-06-01 00:00:00'::timestamp, 0)
  ORDER BY global_last_modification_at, book_id
  LIMIT 500
)
SELECT
  vb.*,
  cb.global_last_modification_at
FROM public.vw_book vb
JOIN changed_books cb ON cb.book_id = vb.book_id
ORDER BY cb.global_last_modification_at, vb.book_id;

Permite:

guardar el último cursor procesado,

retomar sin duplicar registros,

procesar catálogos grandes de forma segura.

3) Delta mínimo (solo IDs y fecha)

Útil para colas de reprocesamiento o validaciones rápidas.

SELECT book_id, global_last_modification_at
FROM public.vw_book_audit
WHERE global_last_modification_at > '2025-06-01 00:00:00'::timestamp
ORDER BY global_last_modification_at, book_id;

4) Cambios desde fecha + filtro por ISBN (usa índice)

⚠️ Importante: el campo isbn en vw_book es derivado. Para que PostgreSQL use índice, el filtro debe hacerse sobre book_isbn.

WITH changed_books AS (
  SELECT book_id, global_last_modification_at
  FROM public.vw_book_audit
  WHERE global_last_modification_at > '2025-06-01 00:00:00'::timestamp
)
SELECT
  vb.*,
  cb.global_last_modification_at
FROM changed_books cb
JOIN public.book_isbn bi ON bi.book_id = cb.book_id
JOIN public.vw_book vb ON vb.book_id = cb.book_id
WHERE bi.isbn = '9789871234567'
ORDER BY cb.global_last_modification_at, vb.book_id;

Consideraciones de performance

vw_book_audit está pensada para ser liviana y usada frecuentemente.

vw_book incluye subconsultas correlacionadas (autores, materias, ISBN, stock).

Usar siempre con filtros (WHERE, LIMIT) o para un conjunto acotado de libros.

Recordar restricción de búsqueda por ISBN.

Diccionario de Columnas

Client

Clientes: vw_client

vw_client es una vista consolidada del rol Cliente, que combina:

• Identidad base (desde public.vw_party): nombre, tipo, tax_id, IVA, contactos y ubicación.

• Atributos comerciales (desde public.client y catálogos): tipo de cliente, cuenta corriente, límites, moneda, condición de venta, lista de precios, zona.

• Vendedor asignado: resuelto como otra identidad (vw_party) a partir de client.salesman_id.

Casos de uso (queries de prueba)

1) Buscar cliente por código

SELECT party_id, client_code, legalname, tax_id, has_account
FROM public.vw_client
WHERE client_code = 'CL-000123';

2) Listado operativo con vendedor y condición de venta

SELECT client_code, name, sell_condition_name, price_list_name, salesman_name
FROM public.vw_client
ORDER BY name
LIMIT 50;

3) Control de crédito: clientes con cuenta corriente y límite definido

SELECT client_code, legalname, credit_limit, limit_currency_symbol
FROM public.vw_client
WHERE has_account = true
  AND credit_limit IS NOT NULL
ORDER BY credit_limit DESC
LIMIT 100;

4) Cantidad de clientes por vendedor

SELECT
  salesman_id,
  salesman_name,
  COUNT(*) AS client_qty
FROM public.vw_client
WHERE salesman_id IS NOT NULL
GROUP BY salesman_id, salesman_name
ORDER BY client_qty DESC;

Diccionario de Columnas

Document

Documentos: vw_document

vw_document es la vista base para consulta, auditoría y reporting de documentos del sistema. Abstrae la tabla public.document y enriquece cada registro con:

• nombres legibles de tipo de documento (document_type_name),

• una familia/grupo funcional (document_group) derivada de reglas de negocio,

• información de sucursal,

• auditoría completa de la transacción que originó el documento (usuario y fecha).

El mapeo de tipos y grupos se realiza mediante un CTE embebido (doc_types), que refleja directamente los enums utilizados en el código de la aplicación.

Importante: para los reportes lo más probable es que no se use esta vista, sino las vistas particulares de cada módulo. Esta vista se utiliza para simplificar la construcción de documentos en otras vistas.

Conceptos clave

• Todos los documentos tienen fecha pero no todos tienen fecha contable. Dentro del sistema, si un documento no tiene fecha contable, se toma la fecha real como fecha contable.

• Tipo de documento

Representado por document_type_id (valor numérico).

Traducido a document_type_name (ej: SALE_BILL, BUY_ORDER).

• Grupo de documento (document_group)

Agrupa documentos por función de negocio, facilitando filtros y reportes masivos.

Ejemplos de grupos:

BUY_ORDER

BUY_BILL

SALE_BILL

SALE_ORDER

SALE_PAYMENT

STOCK

BOOKKEEPING

RRMM_LIQUIDATION

PERSONAL

PERSONAL_PAYMENT

Casos de uso típicos

1) Listar documentos por grupo (ej: Stock)

SELECT
  document_id,
  real_date,
  document_type_name,
  sucursal_name
FROM public.vw_document
WHERE document_group = 'STOCK'
ORDER BY real_date DESC;

2) Documentos de venta (facturas y notas) en un período

SELECT
  document_id,
  document_type_name,
  real_date,
  account_date,
  sucursal_name
FROM public.vw_document
WHERE document_group IN ('SALE_BILL', 'SALE_CREDIT_NOTE')
  AND real_date BETWEEN '2025-01-01' AND '2025-01-31'
ORDER BY account_date;

3) Auditoría: documentos generados por un usuario

SELECT
  document_id,
  document_type_name,
  document_group,
  transaction_date
FROM public.vw_document
WHERE user_id = 42
ORDER BY transaction_date DESC;

4) Control operativo por sucursal

SELECT
  sucursal_name,
  document_group,
  COUNT(*) AS qty
FROM public.vw_document
WHERE real_date >= NOW() - INTERVAL '7 days'
GROUP BY sucursal_name, document_group
ORDER BY sucursal_name, qty DESC;

5) Diferencia entre fecha real y fecha contable

Útil para control contable/impositivo.

SELECT
  document_id,
  document_type_name,
  real_date,
  account_date
FROM public.vw_document
WHERE real_date <> account_date
ORDER BY real_date DESC;

6) Actividad reciente del sistema (quién hizo qué)

SELECT
  transaction_date,
  operator_name,
  document_type_name,
  sucursal_name
FROM public.vw_document
ORDER BY transaction_date DESC
LIMIT 100;

Consideraciones de diseño

vw_document no reemplaza a public.document: la enriquece para lectura.

El mapeo de tipos está hardcodeado en la vista y debe mantenerse sincronizado con el enum del código.

Si un document_type_id no está contemplado en el mapeo:

document_type_name y document_group pueden quedar NULL

esto sirve como señal de desalineación entre base y aplicación.

Relación con otras vistas

vw_transaction: aporta auditoría (usuario y fecha).

vw_book_audit: utiliza real_date y transaction_date para calcular cambios globales.

vw_book: depende indirectamente de documentos para stock y precios.

Diccionario de Columnas

Materia

Materias: vw_materia

vw_materia expone el catálogo de materias como una jerarquía (árbol). Cada fila representa una materia y su relación padre/hijo, además de un campo full_path que describe la ruta completa desde una materia raíz hasta el nodo.

Contrato importante: la jerarquía debe ser acíclica (sin bucles en materia_padre_id).

Casos de uso (queries)

1) Listar materias con su ruta completa

SELECT materia_id, code, full_path
FROM public.vw_materia
ORDER BY full_path;

2) Buscar por texto dentro de la ruta

SELECT materia_id, full_path
FROM public.vw_materia
WHERE full_path ILIKE '%Historia%'
ORDER BY full_path;

3) Obtener el subárbol de una materia (por ID)

SELECT *
FROM public.vw_materia
WHERE full_path LIKE (
  SELECT full_path || '%'
  FROM public.vw_materia
  WHERE materia_id = 123
)
ORDER BY full_path;

Diccionario de Columnas

Party

Identidades (party): vw_party

vw_party es la vista base para trabajar con identidades (“party”) en el sistema. Unifica en una única salida tanto Personas como Organizaciones.

Las vistas de clientes, proveedores, vendedores y otros roles se construyen sobre esta vista.

Temas que resuelve:

• Tipo de party (persona/organización)

• Nombres “legal” y “comercial”

• Identificación fiscal

• Condición de IVA

• Contactos principales (email y teléfono)

• Ubicación principal (dirección, ciudad, provincia, país, CP)

• Trazabilidad por transacción (creación y última actualización)

Convenciones de datos

party_type_id: 1 = Persona, 2 = Organización.

Para Persona:

legalname: "Apellido, Nombre"

name: "Nombre Apellido"

Para Organización:

legalname: razón social (organization.legalname)

name: nombre de fantasía (organization.name)

Las direcciones que se muestran son las que corresponden al tipo de dirección principal.

Casos de uso (queries de prueba)

1) Buscar por CUIT / tax_id

SELECT party_id, party_type_name, legalname, tax_id
FROM public.vw_party
WHERE tax_id = '20304050607';

2) Listado para selector (nombre + contacto + ubicación)

SELECT party_id, name, primary_email, primary_phone, city, province, country
FROM public.vw_party
ORDER BY name
LIMIT 50;

3) Personas vs Organizaciones (conteo rápido)

SELECT party_type_name, COUNT(*) AS qty
FROM public.vw_party
GROUP BY party_type_name
ORDER BY qty DESC;

Diccionario de Columnas

Payment

Pagos: vw_payment

Vista consolidada para reportes de pagos por medio, banco, sucursal y operador.

Recomendada para:

• obtener el detalle de la forma de pago de un documento específico

• arqueos de caja/banco

• conciliaciones

• reportes por medio de pago y fechas

Formas de pago

💵 Pagos contado

🧾 Cuenta corriente

Casos de uso

1) Totales por medio de pago (últimos 7 días)

SELECT payment_type_name, SUM(amount_converted) AS total_base
FROM public.vw_payment
WHERE document_date >= NOW() - INTERVAL '90 days'
GROUP BY payment_type_name
ORDER BY total_base DESC;

2) Totales por banco (depósitos/transferencias/cheques)

SELECT bank_name, SUM(amount_converted) AS total_base
FROM public.vw_payment
WHERE bank_name IS NOT NULL
  AND document_date >= NOW() - INTERVAL '90 days'
GROUP BY bank_name
ORDER BY total_base DESC;

3) Pagos por sucursal y operador (auditoría)

SELECT sucursal_name, operator_name, COUNT(*) AS qty, SUM(amount_converted) AS total_base
FROM public.vw_payment
WHERE document_date >= NOW() - INTERVAL '90 days'
GROUP BY sucursal_name, operator_name
ORDER BY total_base DESC;

Diccionario de Columnas

Provider

Proveedores: vw_provider

vw_provider es la vista consolidada del rol Proveedor, que combina:

• Identidad base desde public.vw_party (nombre, tax_id, IVA, contactos y ubicación).
• Parámetros comerciales y operativos desde public.provider (condición de compra, plazos, descuentos, costos y estrategia de pedidos).
• Catálogos de soporte (tipo de proveedor, condición de compra y estrategia de generación de pedidos).

Casos de uso (queries de prueba)

1) Buscar proveedor por código

SELECT party_id, provider_code, legalname, tax_id
FROM public.vw_provider
WHERE provider_code = 'PR-000123';

2) Listado operativo para compras (condición + plazo + estrategia)

SELECT provider_code, name, buy_condition_name, pay_term, order_gen_strategy_name
FROM public.vw_provider
ORDER BY name
LIMIT 50;

3) Revisión de costos por proveedor

SELECT provider_code, legalname, use_cost, shipping_cost_pct, return_cost_pct
FROM public.vw_provider
WHERE use_cost = true
ORDER BY legalname;

Diccionario de Columnas

Sale Concept

Adicionales de venta: vw_sale_concept

vw_sale_concept expone los cargos y descuentos aplicados a documentos de venta que no corresponden a productos, como:

• fletes

• recargos financieros

• descuentos comerciales

• cargos administrativos

La vista unifica conceptos de Facturas Y conceptos de Notas de Crédito y devuelve los montos contablemente firmados, listos para sumarizar.

Casos de uso

¿Cuánto cobramos en concepto de Fletes este mes?

Útil para comparar lo facturado contra lo que realmente nos cobra el transporte.

SELECT 
    SUM(amount) AS recaudacion_fletes
FROM public.vw_sale_concept
WHERE concept_name ILIKE '%FLETE%'
  AND real_date BETWEEN '2025-05-01' AND '2025-05-31';

Resumen de adicionales por tipo de concepto

Para saber qué conceptos están impactando más en la facturación total.

SELECT 
    concept_name,
    COUNT(*) as cantidad_usos,
    SUM(amount) as total_neto
FROM public.vw_sale_concept
WHERE real_date BETWEEN '2025-01-01' AND '2025-01-02'
GROUP BY concept_name
ORDER BY total_neto DESC;

Control de Descuentos Globales

Si tienes un concepto de "Descuento Especial" o "Bonificación", puedes auditar quiénes lo están recibiendo y bajo qué observación.

SELECT 
    real_date,
    observation,
    amount
FROM public.vw_sale_concept
WHERE amount < 0  -- Los descuentos resultan en montos negativos
ORDER BY real_date DESC;

Ver todos los componentes de un documento específico

Si quieres ver qué se le cobró a un cliente además de los libros en la factura ID 1500:

SELECT concept_name, observation, amount 
FROM public.vw_sale_concept 
WHERE document_id = 1500;

Diccionario de Columnas

Sale Document

Cabecera unificada de ventas: vw_sale_document

vw_sale_document unifica facturas (SALE_BILL) y notas de crédito (SALE_CREDIT_NOTE) en un esquema común para reporting y exportación. Incluye:

• identificación legal (legal_number)

• cliente y vendedor (desde vw_client / vw_salesman)

• provincia y país del cliente (desde vw_client)

• moneda y tipo de cambio histórico (exchange_rate)

• totales firmados (ventas positivas, NC negativas)

• desgloses agregados: IVA (vw_sale_tax) y conceptos (vw_sale_concept)

• Regla de signo

Factura: sign = 1

Nota de crédito: sign = -1

Todos los totales permiten sumarizar sin CASE.

Importante:

• La columna is_cancelled indica si el comprobante fue anulado. Los comprobantes anulados no deben incluirse en los reportes de ventas netas.

• Todos los documentos tienen fecha pero no todos tienen fecha contable. Dentro del sistema, si un documento no tiene fecha contable, se toma la fecha real como fecha contable.

Casos de uso y queries

1) Libro de IVA ventas (por fecha contable)

SELECT
  account_date,
  legal_number,
  client_tax_id,
  client_name,
  total_net_taxable,
  total_vat,
  total_amount
FROM public.vw_sale_document
WHERE real_date BETWEEN '2025-01-01' AND '2025-01-31'
ORDER BY account_date, legal_number;

2) Ventas netas del período (facturas - NC)

SELECT
  SUM(total_amount) AS sales_net_total
FROM public.vw_sale_document
WHERE real_date BETWEEN '2025-01-01' AND '2025-01-31'
  AND is_cancelled IS NOT TRUE;

3) Totales por cliente

SELECT
  client_party_id,
  client_name,
  SUM(total_amount) AS total
FROM public.vw_sale_document
WHERE real_date >= '2025-01-01'
  AND is_cancelled IS NOT TRUE
GROUP BY client_party_id, client_name
ORDER BY total DESC;

4) Totales por vendedor

SELECT
  salesman_party_id,
  salesman_name,
  SUM(total_amount) AS total
FROM public.vw_sale_document
WHERE real_date >= '2025-01-01'
  AND is_cancelled IS NOT TRUE
GROUP BY salesman_party_id, salesman_name
ORDER BY total DESC;

5) Auditoría operativa (últimos 100 comprobantes)

SELECT
  real_date,
  legal_number,
  document_type_name,
  sucursal_name,
  operator_name,
  total_amount
FROM public.vw_sale_document
ORDER BY real_date DESC
LIMIT 100;

6) Conversión a moneda base (control)

SELECT
  legal_number,
  currency_symbol,
  exchange_rate,
  total_amount,
  total_amount_base
FROM public.vw_sale_document
WHERE real_date >= NOW() - INTERVAL '7 days'
ORDER BY real_date DESC;

7) Control de Anulaciones por Sucursal

Para auditar qué sucursales tienen más errores o cancelaciones.

SELECT 
    sucursal_name,
    COUNT(*) FILTER (WHERE is_cancelled = true) AS cantidad_anuladas,
    COUNT(*) FILTER (WHERE is_cancelled = false) AS cantidad_validas,
    ROUND((COUNT(*) FILTER (WHERE is_cancelled = true) * 100.0 / COUNT(*)), 2) AS pct_error
FROM public.vw_sale_document
GROUP BY sucursal_name;

8) Ventas por país (join a vw_client)

SELECT
  c.country,
  SUM(d.total_amount_base) AS total_sales_base
FROM public.vw_sale_document d
JOIN public.vw_client c
  ON d.client_party_id = c.party_id
WHERE d.real_date BETWEEN DATE '2026-01-01' AND DATE '2026-01-31'
  AND d.is_cancelled IS NOT TRUE
GROUP BY c.country
ORDER BY total_sales_base DESC;
```sql 


### Diccionario de Columnas

| Columna | Descripción |
| :--- | :--- |
| **document_id** | ID único del documento de venta (PK de public.document). |
| **document_type_id** | ID numérico del tipo de documento (enum del código de aplicación). |
| **document_type_name** | Nombre descriptivo del tipo de documento (ej: SALE_BILL, SALE_CREDIT_NOTE). |
| **legal_number** | Número legal completo del comprobante, formateado como: Letra Prefijo-Número (ej: A 0001-00001234). |
| **real_date** | Fecha real u operativa del documento (emisión / suceso). |
| **account_date** | Fecha contable/impositiva del documento (utilizada para Libro IVA y reportes fiscales). |
| **client_party_id** | ID de identidad (party_id) del cliente asociado al documento. |
| **client_code** | Código comercial interno del cliente. |
| **client_name** | Nombre legal o razón social del cliente. |
| **client_tax_id** | Identificación fiscal del cliente (CUIT/CUIL/RFC, según país). |
| **client_iva_condition** | Condición de IVA del cliente al momento del reporte (ej: Responsable Inscripto, Exento). |
| **salesman_party_id** | ID de identidad (party_id) del vendedor asignado a la operación. |
| **salesman_name** | Nombre del vendedor responsable de la venta. |
| **currency_id** | ID de la moneda en la que está emitido el documento. |
| **currency_symbol** | Símbolo de la moneda del documento |
| **exchange_rate** | Cotización histórica de la moneda del documento a la fecha real (real_date). Se obtiene desde quotation_history usando la última cotización con date_from < real_date. Para moneda base, el valor es 1. |
| **sign** | Signo contable del documento: 1 para Facturas de Venta, -1 para Notas de Crédito. |
| **total_amount** | Importe total del documento en moneda original, con signo aplicado según el tipo de documento (Facturas positivas, Notas de Crédito negativas). Corresponde al monto de cabecera. |
| **total_net_taxable** | Suma de bases imponibles (neto gravado), firmada contablemente. Agregada desde vw_sale_tax. |
| **total_vat** | Importe total de IVA del documento, firmado contablemente. Agregado desde vw_sale_tax. |
| **total_concepts** | Importe total de conceptos adicionales (fletes, recargos, descuentos), firmado contablemente y agregado desde vw_sale_concept. |
| **total_amount_base** | Importe total del documento convertido a moneda base del sistema, utilizando exchange_rate histórico. |
| **total_vat_base** | Importe total de IVA convertido a moneda base del sistema, utilizando exchange_rate histórico. |
| **total_net_taxable_base** | Suma de bases imponibles (neto gravado) convertida a moneda base del sistema usando la cotización histórica. |
| **total_concepts_base** | Importe total de conceptos adicionales (fletes, cargos, descuentos) convertido a moneda base del sistema usando la cotización histórica. |
| **is_cancelled** | Indica si el documento fue anulado/cancelado. |
| **sucursal_name** | Nombre de la sucursal donde se generó el documento. |
| **operator_name** | Nombre del usuario operador que generó la transacción asociada al documento. |
| **transaction_id** | ID de la transacción asociada al documento, utilizada para trazabilidad técnica. |
| **client_province_id** | ID de la provincia asociada a la dirección principal del cliente. |
| **client_province** | Nombre de la provincia asociada a la dirección principal del cliente. |
| **client_country_id** | ID del país asociado a la dirección principal del cliente. |
| **client_country** | Nombre del país asociado a la dirección principal del cliente. |


## Sale Item


# Detalle de líneas de venta: vw_sale_item

vw_sale_item entrega una fila por cada ítem vendido/devolución, unificando facturas y notas de crédito.
Los importes y cantidades están con su correspondiente signo, por lo que pueden agregarse directamente.
Además expone dimensiones frecuentes de análisis para evitar joins adicionales: colección, costo, provincia y país del cliente.


## Casos de uso y queries

### 1) Top libros vendidos por cantidad (período)
```sql
SELECT
  b.title,
  SUM(si.quantity) AS qty
FROM public.vw_sale_item si
JOIN public.vw_book b ON si.book_id = b.book_id
WHERE si.report_date BETWEEN DATE '2025-01-01' AND DATE '2025-08-31'
GROUP BY b.title
ORDER BY qty DESC
LIMIT 20;

2) Ventas netas (subtotal sin impuestos) por vendedor

SELECT
  salesman_name,
  SUM(line_total_neto_base) AS subtotal_base
FROM public.vw_sale_item
WHERE report_date BETWEEN DATE '2025-01-01' AND DATE '2025-08-31'
GROUP BY salesman_name
ORDER BY subtotal_base DESC;

3) Ventas por país (usando el cliente de la cabecera)

SELECT
  c.country,
  SUM(si.line_total_neto_base) AS subtotal_base
FROM public.vw_sale_item si
JOIN public.vw_sale_document sd ON si.document_id = sd.document_id
JOIN public.vw_client c ON sd.client_party_id = c.party_id
WHERE si.report_date >= DATE '2025-01-01'
GROUP BY c.country
ORDER BY subtotal_base DESC;

4) Devoluciones (solo NC)

SELECT
  legal_number,
  client_name,
  SUM(line_total_neto_base) AS refund_base
FROM public.vw_sale_item
WHERE sign = -1
  AND report_date >= DATE '2025-01-01'
GROUP BY legal_number, client_name
ORDER BY refund_base ASC;

5) Auditoría de líneas (últimas 50)

SELECT
  report_date,
  legal_number,
  client_name,
  title,
  quantity,
  unit_price,
  discount_pct,
  line_total_neto,
  currency_symbol
FROM public.vw_sale_item
ORDER BY report_date DESC
LIMIT 50;

Diccionario de Columnas

Sale Tax

Impuestos de ventas

Al tener esta documentación y estructura, puedes generar el Reporte Impositivo Mensual de forma directa.

Ejemplo:

SELECT 
    aliquot_name,
    percentage, 
    SUM(net_amount) AS total_neto_gravado,
    SUM(tax_amount) AS total_iva_debito
FROM public.vw_sale_tax
WHERE real_date BETWEEN '2025-05-01' AND '2025-05-31'
GROUP BY 
    aliquot_name, 
    percentage 
ORDER BY 
    percentage DESC;

Diccionario de Columnas

Salesman

Vendedores: vw_salesman

vw_salesman expone el catálogo de vendedores consolidando:

• identidad base desde vw_party (nombres, tax_id y contacto),

• datos comerciales del rol vendedor (salesman_code, comisiones),

• zona geográfica asignada (tabla zone).

Casos de uso - Queries de ejemplo (para probar)

1) Listado general de vendedores

SELECT party_id, salesman_code, legalname, zone_name, primary_phone
FROM public.vw_salesman
ORDER BY legalname;

Vendedores por zona

SELECT zone_name, COUNT(*) AS qty
FROM public.vw_salesman
GROUP BY zone_name
ORDER BY qty DESC;

Clientes por vendedor (usando vw_client)

SELECT
  c.salesman_id,
  c.salesman_name,
  COUNT(*) AS client_qty
FROM public.vw_client c
WHERE c.salesman_id IS NOT NULL
GROUP BY c.salesman_id, c.salesman_name
ORDER BY client_qty DESC;

Diccionario de Columnas

Transaction

Transacciones: vw_transaction

public.vw_transaction es una vista de trazabilidad/auditoría que consolida registros de la tabla public.transaction y los enriquece con información de contexto (usuario y sucursal).

Además, convierte el campo numérico transaction_type en un nombre legible (transaction_type_name) mediante un mapeo embebido en la propia vista.

Cuando un tipo no está contemplado en el mapeo, se expone como UNKNOWN, lo cual permite detectar rápidamente tipos nuevos o inconsistencias entre base y aplicación.

Todas las entidades y documentos del sistema tienen su transacción. Se deberá acceder a esta vista para obtener su detalle.

Índices futuros sugeridos (no implementados)

Estado actual: además del PK transaction_id, la tabla public.transaction no tiene índices sobre transaction_date, user_id, sucursal_id ni transaction_type.

Si se quiere acceder por fecha, usuario, sucursal o tipo de transacción, se recomienda crear índices para mejorar el rendimiento de las consultas.

Diccionario de Columnas