iatoolkit 0.3.6__py3-none-any.whl → 0.3.8__py3-none-any.whl

iatoolkit/system_prompts/sql_rules.prompt

@@ -0,0 +1,1337 @@
+## 🧠 Contexto general
+
+- La base de datos es **PostgreSQL**.
+- Muchas columnas contienen información en formato **jsonb**.
+- Todas las consultas deben ser **sintácticamente correctas** y compatibles con PostgreSQL.
+
+## 🔍 Uso correcto de campos JSONB
+
+### Regla central: ¡NO ASUMAS QUE LAS CLAVES JSONB SON COLUMNAS!
+
+- **Error frecuente:** El error `column "X" does not exist` ocurre cuando se intenta
+usar una clave de un JSONB como si fuera una columna directa.
+**¡Esto es incorrecto y la causa principal de errores!**
+- **Solución obligatoria:** Usa SIEMPRE el nombre del campo JSONB contenedor seguido
+del operador `->>` para acceder al valor.
+
+#### Ejemplo incorrecto:
+```sql
+-- INCORRECTO: "line_type" no es una columna de bcu_customer.
+SELECT line_type FROM bcu_customer GROUP BY line_type;
+```
+
+#### Ejemplo correcto:
+```sql
+-- CORRECTO: Se accede a "line_type" desde jsonb_credit.
+SELECT jsonb_credit->>'line_type' AS line_type
+FROM bcu_customer
+GROUP BY jsonb_credit->>'line_type';
+```
+Nunca asumas que un campo como 'product_type', 'created', 'current_debt', 'amount', etc.
+existe directamente como columna en la tabla base.
+Si el campo está dentro de un objeto JSONB, debes acceder a él explícitamente usando
+ la sintaxis: <jsonb_field>->>'<subfield>' o <jsonb_field>->'<subfield>' según el
+ tipo requerido (texto o json).
+
+No hagas SELECT de columnas inexistentes en tablas físicas.
+Antes de usar columnas como `amount`, `certificate_ids`, `adjudication_date`, etc.,
+verifica si están en la tabla física (como `bcu_tender`) o si provienen
+de un campo JSONB (como `jsonb_collection` en `bcu_customer`).
+Si están en un JSONB, accede a ellas mediante el operador `->>` sobre el JSON,
+no como columna del alias SQL.
+
+
+### Aplicación general:
+Esta regla aplica a todas las cláusulas SQL: `SELECT`, `WHERE`, `GROUP BY`, `ORDER BY`.
+
+- si un campo JSONB puede venir como null, primero debe verificarse antes de castear.
+
+## 🔢 Casting y tipos de datos
+
+### Regla general de casting
+
+- 🎯 El tipo de casting debe coincidir con el tipo declarado en el schema:
+  - `integer` → usa `::INTEGER`
+  - `number` o `numeric` → usa `::NUMERIC`
+
+
+🎯 Regla para castear montos numéricos desde JSONB
+	•	🔒 No asumas que los montos en JSONB son siempre enteros.
+        Algunos campos pueden venir como strings con decimales implícitos,
+        por ejemplo: "3503722.0".
+	•	Si el valor puede incluir punto decimal, incluso .0, nunca lo cases
+	    directamente como ::INTEGER, ya que eso genera error de casting.
+	•	Nunca intentes castear un campo jsonb a jsonb[].
+	•	En estos casos, usa ::NUMERIC para asegurar compatibilidad y precisión:
+        ´´´sql
+        (jsonb_field->>'field_name')::NUMERIC
+        ´´´
+
+	•	Si necesitas un entero redondeado, usa ROUND(...) sobre el valor casteado:
+	    ´´´sql
+	    ROUND((jsonb_field->>'field_name')::NUMERIC) AS field_name
+	    ´´´
+	- Siempre usa NULLIF(..., '')::NUMERIC y COALESCE(..., 0) al castear valores numéricos
+	    provenientes de JSONB para evitar errores de conversión si el campo está vacío.
+        ejemplo en ´´´sql
+            COALESCE(
+                (NULLIF(jsonb_field->>'public_line_available', ''))::NUMERIC, 0
+) AS public_line_available
+
+   - Siempre que un campo numérico provenga de una clave de tipo JSONB que podría contener string vacío, utiliza la estructura:
+    COALESCE(NULLIF(jsonb_objeto->>'campo', '')::NUMERIC, 0)
+  para evitar errores de conversión cuando el campo esté vacío.
+
+- Esta regla aplica para conversiones a NUMERIC, INTEGER, FLOAT, DOUBLE PRECISION, etc. y debe aplicarse de forma consistente en todos los campos relevantes.
+- Ejemplo correcto:
+    COALESCE(NULLIF(jsonb_column->>'field_name', '')::NUMERIC, 0) AS field_name
+- Nunca uses NULLIF(..., '') para valores numéricos ya calculados.
+  Aplica NULLIF(..., '') sólo cuando trabajes directamente con strings extraídos
+  del JSONB. Para resultados de SUM/ROUND usa solo COALESCE(..., 0).
+
+- Nunca castees directamente a NUMERIC si el valor puede ser vacío, ya que provocará un error de sintaxis en Postgres.
+	•	Como principio general:
+	      •	Usa ::NUMERIC si hay posibilidad de decimales.
+	      •	Usa ::INTEGER solo si estás seguro de que los valores siempre serán enteros sin .0.
+
+- Cuando utilices funciones agregadas como SUM, AVG, MIN, MAX
+sobre valores extraídos de un JSONB (usando ->>),
+asegúrate de convertir cada elemento al tipo numérico dentro de la función agregada.
+
+Ejemplo correcto: SUM((value->>'monto')::NUMERIC)
+Ejemplo incorrecto: SUM(value->>'monto')::NUMERIC
+
+🎯 Regla para castear fechas desde JSONB
+
+- Si el campo de fecha proviene de un JSONB y está en formato `DD-MM-YYYY`,
+**no puedes castear directamente a DATE**.
+- Usa `TO_DATE(...)` para convertir el string a fecha:
+```sql
+TO_DATE(jsonb_credit->>'created', 'DD-MM-YYYY')
+´´´
+
+- antes de comparar con `CURRENT_DATE` un campo de tipo jsonb,
+**siempre** castea explícitamente
+
+- No utilices TO_DATE si la columna ya es de tipo DATE o TIMESTAMP.
+Úsala solo si el campo es tipo TEXT o VARCHAR, y asegúrate de castearlo explícitamente si es necesario.
+TO_DATE espera un string, no una fecha ya en formato DATE, y causará un error de tipo de datos.
+
+- Si comparas fechas, asegúrate que ambos lados sean del mismo tipo.
+ejemplo:
+```sql
+-- Si 'init_date' es DATE:
+TO_CHAR(init_date, 'DD-MM-YYYY') = ...
+-- Si 'created' es texto en formato 'DD-MM-YYYY':
+TO_DATE(jsonb_guarantee->>'created', 'DD-MM-YYYY')
+- Evitar comparar campos de tipo DATE o TIMESTAMP con strings generados por TO_CHAR.
+Usar funciones como date_trunc() o INTERVAL directamente.
+
+- Cuando necesites construir fechas a partir de valores numéricos
+(por ejemplo, año y mes), utiliza TO_DATE() con un string en formato 'YYYY-MM-DD',
+no uses concatenación sobre literales de tipo DATE.
+
+- Si el campo de fecha puede venir vacío (''), usa:
+    TO_DATE(NULLIF(campo, ''), 'DD-MM-YYYY')
+    Esto evita errores de conversión cuando la fecha está ausente o mal registrada.
+
+### operaciones sobre campos de tipo JSONB
+- Cuando uses SUM o alguna otra función agregada sobre un valor extraído
+de un JSONB con ->> (texto),  aplica el cast a NUMERIC dentro del SUM y no después.
+- ✅ Siempre castea **antes** de aplicar `SUM`:
+```sql
+SUM((json_field->>'monto')::NUMERIC)
+```
+
+- ❌ Nunca castees después del `SUM`:
+```sql
+-- INCORRECTO
+SUM(json_field->>'monto')::NUMERIC
+```
+
+### Ejemplo correcto:
+```sql
+SELECT SUM((gv->>'amount')::NUMERIC) AS total
+FROM ...
+```
+
+Cuando uses SUM(...) con FILTER, aplica COALESCE sobre los valores internos dentro
+del SUM, no sobre el resultado del SUM completo.
+
+Siempre que se conviertan campos numéricos extraídos de objetos JSONB
+usando `->>` (por ejemplo, `collection_amount`, `fogape_amount`),
+debes envolver la conversión con `NULLIF(..., '')::NUMERIC` y `COALESCE(..., 0)`
+para evitar errores cuando el valor sea una cadena vacía o `null`.
+
+Cuando debas agregar valores numéricos extraídos de campos JSONB que pueden contener texto,
+valores vacíos o null, siempre utiliza la siguiente estructura dentro de la
+función SUM, AVG, COUNT u otra función agregada:
+SUM(COALESCE(NULLIF(<campo_jsonb>, '')::NUMERIC, 0))
+
+- Cuando utilices subconsultas agregadas (con SUM, COUNT, etc.) en SQL,
+asegúrate de que todos los campos que aparecen en el SELECT del subquery
+estén también en el GROUP BY de ese subquery, o que se usen únicamente
+dentro de funciones de agregación como SUM(), COUNT(), MAX(), MIN(), etc.
+
+- Cuando debas comparar un valor de un campo jsonb contra un string,
+asegúrate de convertir el valor jsonb a texto con ::text antes de la comparación.
+ Por ejemplo, para saber si un objeto jsonb está vacío,
+ usa (jsonb_field)::text != '{}' en vez de jsonb_field != '{}'.
+
+- Siempre que debas acceder a elementos contenidos en un campo JSONB definido como array,
+  como `judicial_collection`, utiliza estrictamente la función `jsonb_array_elements(campo_jsonb->'array')`.
+  Nunca uses `jsonb_each`, ya que esta función solo aplica a objetos JSONB, no arrays.
+
+- Para recorrer arrays dentro de columnas JSONB,
+utiliza la función jsonb_array_elements en la cláusula FROM o en LEFT JOIN LATERAL.
+Ejemplo:
+```sql
+LEFT JOIN LATERAL jsonb_array_elements(tabla.columna_jsonb->'nombre_array') AS alias(elemento) ON TRUE
+
+Si necesitas recorrer un array dentro de cada elemento del array anterior,
+anida los jsonb_array_elements usando otro LEFT JOIN LATERAL sobre el alias anterior.
+
+- Cuando uses `jsonb_array_elements(...) AS alias(columna)` en una
+cláusula `FROM` o `JOIN`, recuerda que el alias (`alias`) no representa un objeto
+con múltiples columnas, sino una tupla con una sola columna llamada como
+se indica en `AS alias(columna)`. Por lo tanto:
+    - Para acceder a los valores internos del JSON debes usar `alias.columna->>'campo'`.
+    - Nunca uses `alias.campo` directamente, ya que causará un error de columna no definida.
+    - Ejemplo correcto: `alias.value->>'offer_status'`.
+    - Ejemplo incorrecto: `alias.offer_status`.
+
+- No uses funciones que devuelven múltiples filas (set-returning functions) como
+jsonb_array_elements(), unnest(), generate_series(), etc.
+directamente dentro de funciones de agregación como SUM(), COUNT(), AVG(), etc.
+En su lugar, mueve la función a una subconsulta o usa un LATERAL JOIN para expandir
+primero los elementos y luego aplicar la agregación.
+    Ejemplo correcto:
+      SELECT SUM((elem->>'amount')::NUMERIC)
+      FROM tabla
+      LEFT JOIN LATERAL jsonb_array_elements(tabla.json_col) AS elem ON TRUE;
+    Ejemplo incorrecto:
+      SELECT SUM((jsonb_array_elements(tabla.json_col)->>'amount')::NUMERIC)
+      FROM tabla;
+
+### Evaluación de booleanos desde JSONB
+
+- Las claves booleanas dentro de JSONB devuelven texto.
+- Para evaluarlas correctamente, usa cast explícito:
+```sql
+(jsonb_field->>'pre_judicial')::BOOLEAN IS TRUE
+
+- aplica esta regla a todos los campos que definan true/false
+
+📌 Evita casteos múltiples de un mismo campo
+	•	Si vas a usar (jsonb->>'campo')::TIPO varias veces en la query,
+	guarda el resultado con WITH o como subquery para evitar repetir el casteo.
+	ejemplo:
+	´´´sql
+	WITH datos AS (
+  SELECT
+    rut,
+    (jsonb_column->>'field_name')::NUMERIC AS field_name
+  FROM bcu_customer
+)
+
+📌 No uses jsonb -> 'obj'::text != '{}'
+	•	Esa comparación es lenta y poco confiable. prefiere:
+	´´´sql
+	jsonb_typeof(jsonb->'obj') = 'object'
+AND jsonb_object_keys(jsonb->'obj') IS NOT NULL
+
+🟢 Regla para uso de operadores JSONB sobre arrays y objetos
+
+- Cuando uses la función jsonb_each sobre un objeto jsonb,
+    **usa el alias AS e(key, value)** solo dentro de FROM o LATERAL,
+    nunca en un subquery escalar sin alias de tabla. Ejemplo correcto:
+    FROM jsonb_each(jsonb_object) AS e(key, value)
+- Si necesitas solo value, puedes usar: FROM jsonb_each(jsonb_object) AS e
+- Cuando hagas subconsultas escalares que usan jsonb_each, **recuerda que el alias debe ser simple (AS e), y accede a los valores usando e.value->>'campo'**.
+Ejemplo correcto para sumar montos dentro de un objeto:
+    (SELECT SUM((e.value->>'amount')::NUMERIC) FROM jsonb_each(objeto_jsonb) AS e WHERE e.value->>'amount' IS NOT NULL)
+
+- Antes de utilizar operadores JSONB como jsonb_each o jsonb_array_elements en un campo,
+asegúrate de que el tipo de dato corresponde:
+•	Utiliza jsonb_each solo sobre campos JSONB de tipo objeto (dict/JSON {}).
+.   Nunca uses jsonb_each sobre arrays, nulls o strings.
+•	Utiliza jsonb_array_elements solo sobre campos JSONB de tipo array ([]).
+
+- Nunca apliques jsonb_each sobre un campo que pueda contener un array o valor nulo.
+- Nunca utilices jsonb_each sobre un campo JSONB si puede ser un array.
+Siempre verifica el tipo con jsonb_typeof.
+Si puede ser un array, utiliza jsonb_array_elements y filtra por tipo si es necesario.
+
+- Cuando uses funciones como jsonb_each(jsonb_column) asegúrate de que el
+campo sea un objeto JSONB. usa la condición:
+```sql
+LEFT JOIN LATERAL jsonb_each(c.jsonb_object->'operation') AS e ON
+  c.jsonb_object->'operation' IS NOT NULL
+  AND jsonb_typeof(c.jsonb_object->'operation') = 'object'
+
+- Cuando debas recorrer elementos dentro de un campo JSONB:
+	•	Usa jsonb_each si el campo es un objeto (dict/{}).
+	•	Usa jsonb_array_elements si el campo es un array ([]).
+
+Si necesitas recorrer un campo JSONB que es un array,
+utiliza siempre jsonb_array_elements.
+Usa jsonb_each solo si el campo es un objeto (tipo diccionario).
+Ejemplo para arrays:
+```sql
+SELECT ... FROM jsonb_array_elements(campo_jsonb->'mi_array')
+
+Ejemplo para objetos:
+```sql
+SELECT ... FROM jsonb_each(campo_jsonb->'mi_objeto')
+
+## 📐 Cálculos y expresiones
+
+### Porcentajes y divisiones
+
+- Usa `* 100.0` para forzar el uso de decimales en porcentajes.
+- Usa `NULLIF` para proteger divisiones por cero.
+
+### Coherencia en expresiones
+
+- Asegura que todos los componentes de una expresión numérica compartan el mismo tipo.
+- Protege `COALESCE` y literales con el mismo tipo que el campo:
+```sql
+COALESCE(SUM(...), 0::INTEGER)
+COALESCE(SUM(...), 0::NUMERIC)
+```
+
+### ➕ SUM sobre valores booleanos
+- `SUM()` y otras funciones de agregación no aceptan directamente expresiones booleanas.
+- Para contar condiciones booleanas, transforma el resultado a número:
+
+```sql
+SUM(CASE WHEN condición_booleana THEN 1 ELSE 0 END)
+
+Ejemplo correcto:
+```sql
+SUM(CASE WHEN (jsonb_field->'field_name')::jsonb @> '[{"status": "vigente"}]'::jsonb THEN 1 ELSE 0 END)
+
+❌ Incorrecto:
+´´´sql
+SUM((jsonb_guarantee->'field_name')::jsonb @> '[{"status": "vigente"}]'::jsonb)
+
+### Evita mezcla implícita de tipos
+
+- 🚫 No mezcles `INTEGER` y `NUMERIC` sin casting explícito.
+- Castea siempre al tipo de mayor precisión si los mezclas.
+
+### ⚠️ Validación segura al usar jsonb_array_length()
+
+Siempre que uses jsonb_array_length(jsonb_column->'key'),
+asegúrate de anteponer una condición en WHERE como:
+    jsonb_typeof(jsonb_column->'key') = 'array'
+
+Añade explícitamente la verificación jsonb_typeof(jsonb_column->'key') = 'array'
+**antes** de llamar a jsonb_array_length.
+    Por ejemplo:
+    ```
+    WHERE jsonb_column IS NOT NULL
+      AND jsonb_typeof(jsonb_column->'key') = 'array'
+      AND jsonb_array_length(jsonb_column->'key') > 0
+    ```
+    Esto evita que jsonb_array_length falle si el campo no es un array.
+
+Esta regla se aplica especialmente a cualquier campo que pueda
+contener una lista variable
+
+
+### ⚠️ Uso  de CTEs
+
+- PostgreSQL **no permite usar alias definidos en el SELECT en la cláusula ORDER BY dentro del mismo nivel** si se hace `GROUP BY`.
+- Solución: Repite la expresión original en `ORDER BY`.
+
+❌ Esto puede fallar:
+```sql
+SELECT to_char(init_date, 'MM-YYYY') AS mes
+GROUP BY mes
+ORDER BY to_date('01-' || mes, 'DD-MM-YYYY')
+
+Haz esto en su lugar:
+´´´sql
+ORDER BY to_date('01-' || to_char(init_date, 'MM-YYYY'), 'DD-MM-YYYY')
+´´
+
+Esta regla aplica en CTEs y subqueries donde defines alias y haces GROUP BY y ORDER BY juntos.
+- Si una consulta usa GROUP BY, todas las columnas del SELECT que no estén dentro
+de funciones agregadas deben estar explícitamente en la cláusula GROUP BY.
+- Además, si en el ORDER BY se hace referencia a una columna (ej: c.public_line),
+esa columna también debe agregarse al SELECT y al GROUP BY,
+a menos que esté en una función de agregación.
+- Esto incluye columnas provenientes de CTEs (WITH) como clientes_top u otras subconsultas.
+- esto mismo aplica si vas a referenciar campos de una tabla en subconsultas,
+LEFT JOIN LATERAL o expresiones posteriores,
+asegúrate de seleccionar esos campos explícitamente en el CTE o subconsulta de origen.
+
+-- Incorrecto:
+-- GROUP BY c.rut, c.client_name
+-- ORDER BY c.public_line  ← Error porque no está ni en SELECT ni en GROUP BY
+
+-- Correcto:
+-- SELECT c.rut, c.client_name, c.public_line
+-- GROUP BY c.rut, c.client_name, c.public_line
+-- ORDER BY c.public_line
+
+ - detecta automáticamente si hay columnas en el SELECT u ORDER BY que no
+ están en GROUP BY y agregarlas.
+ - las columnas de CTEs también deben respetar esta regla, ya que PostgreSQL aplica
+ las restricciones de agrupamiento a nivel global.
+
+ Siempre que haya columnas con el mismo nombre en más de una CTE,
+ usa el nombre de la tabla o CTE como prefijo en el SELECT final para
+ evitar ambigüedad. Ejemplo: cartera.garantias_vigentes o cobranza_judicial.garantias_vigentes.
+
+- Cuando definas múltiples CTEs con WITH, cada CTE debe estar separado por una coma (,)
+Nunca olvides la coma entre cada definición de CTE, excepto después del último CTE antes del SELECT final.
+Ejemplo:
+```sql
+WITH a AS (SELECT 1),
+     b AS (SELECT 2)
+SELECT * FROM a, b;
+
+Incorrecto (genera error):
+```sql
+WITH a AS (SELECT 1)
+     b AS (SELECT 2)  -- ❌ falta la coma
+SELECT * FROM a, b;
+
+- Nunca uses directamente los alias definidos dentro de un CTE en el SELECT principal.
+ Si necesitas usar una columna de un CTE, accede a ella mediante una subconsulta
+ completa que incluya el CTE o usa una tabla derivada con alias.
+
+Reutiliza exactamente los nombres de columnas definidos en las CTE previas o SELECT
+anteriores. Evita variaciones similares como 'executive' vs 'executable'."
+Si necesitas retornar una fila de una CTE o subquery con varias columnas como
+un solo campo, usa row_to_json(...).
+Si solo necesitas columnas específicas, trae cada columna por separado en el SELECT.
+ejemplo:
+´´´sql
+SELECT
+  (SELECT row_to_json(prejudicial) FROM prejudicial) AS prejudicial
+
+o bien:
+´´´sql
+SELECT
+  (SELECT clientes_prejudicial FROM prejudicial) AS clientes_prejudicial,
+  (SELECT monto_prejudicial FROM prejudicial) AS monto_prejudicial
+
+Si usas el mismo nombre de columna proveniente de varias tablas en un JOIN
+o en una CTE, asegúrate de que en el SELECT final no quede ambigüedad,
+usando siempre el prefijo de la tabla o seleccionando explícitamente solo
+una de las columnas.
+
+Cuando uses un alias de columna en el SELECT de una consulta, recuerda que en PostgreSQL no puedes referenciar ese alias directamente en el ORDER BY a menos que la consulta esté envuelta en una subquery.
+Si necesitas ordenar por ese alias, repite la expresión o usa una subconsulta.
+
+- Cuando uses JOIN entre tablas que tienen columnas con el mismo nombre (por ejemplo 'rut'),
+nunca hagas SELECT t1.columna, t2.*.
+En su lugar, selecciona los campos de forma explícita o usa alias para desambiguar.
+ejemplo:
+```sql
+SELECT cert.rut AS rut_cert, cert.status, cert.guarantee_amount_pesos FROM clientes_kaponte c JOIN bcu_certificate cert ON cert.rut = c.rut
+
+- Siempre que escribas una consulta SQL con más de una tabla o subconsulta,
+debes anteponer el alias de la tabla o subconsulta a cada columna que aparece en
+la cláusula SELECT, JOIN, ON, WHERE, GROUP BY, HAVING u ORDER BY.
+Ejemplo correcto:
+```sql
+SELECT b.rut, c.client_name FROM base b JOIN clientes c ON c.rut = b.rut
+
+- Nunca uses nombres de columnas sin el alias de su tabla correspondiente cuando
+puedan existir en varias tablas o subconsultas (por ejemplo: rut, folio, status, etc.).
+
+- Si usas LATERAL o subconsultas, también antepone el alias de tabla/subconsulta.
+Ejemplo:
+```sql
+LEFT JOIN LATERAL (SELECT ... FROM jsonb_array_elements(b.jsonb_collection->'judicial_collection')) ...
+
+Nunca uses alias de tabla (c.) fuera del alcance donde fueron definidos.
+Sólo usa alias cuando la tabla está explícitamente definida con alias en
+el FROM de esa subconsulta o CTE.
+
+
+- Cuando crees un CTE (subconsulta con WITH), los campos disponibles en los
+siguientes CTE o en el SELECT principal son solo los que seleccionaste en
+el SELECT del CTE anterior.
+- No intentes acceder a columnas originales de la tabla base que no están
+proyectadas explícitamente en el CTE.
+
+- Si necesitas un campo más adelante, asegúrate de incluirlo en el SELECT del CTE.
+- Por ejemplo, si extraes jsonb_column->>'guarantee_executive' AS ejecutiva,
+luego usa ejecutiva, no intentes usar de nuevo jsonb_column->>'guarantee_executive' en ese CTE.
+
+- Nunca pongas un WHERE entre la definición de un alias lateral y el GROUP BY.
+Si necesitas filtrar resultados de un LATERAL, pon el filtro dentro de la subconsulta LATERAL.
+
+- Si tu campo es un array, usa siempre jsonb_array_elements (no jsonb_each).
+- Si necesitas filtrar resultados de una función LATERAL (como jsonb_each o jsonb_array_elements),
+pon el filtro en una subconsulta lateral y nunca en el ON.
+- No repitas nombres de columnas o alias en diferentes scopes;
+usa nombres claros, especialmente en LATERAL.
+
+
+## Evitar referencias a alias fuera de su contexto
+
+Cuando generes subconsultas, CTEs (WITH) o expresiones LATERAL que utilicen una
+tabla virtual creada con VALUES, asegúrate de **no referenciar alias que no
+estén definidos en ese scope**.
+
+Por ejemplo, en una subconsulta tipo:
+      SELECT ... FROM (VALUES ...) AS m(col1, col2)
+    Solo puedes referenciar m.col1, m.col2, etc. en ese contexto.
+    Si la subconsulta recibe un alias (por ejemplo, j), solo puedes referenciar j.columna en el SELECT externo. **Nunca uses alias como g.columna si g no está definido en ese nivel.**
+
+    Ejemplo incorrecto:
+      SELECT g.col1 FROM (SELECT m.col1 FROM (VALUES ...) AS m) j
+
+    Ejemplo correcto:
+      SELECT j.col1 FROM (SELECT m.col1 FROM (VALUES ...) AS m) j
+
+    **Siempre asegúrate de que los campos referenciados en el SELECT provengan de los alias definidos en ese mismo FROM/JOIN.**
+
+📘 Reglas para Optimización de Consultas jsonb Numéricas
+
+🔁 1. Evitar casteos repetidos
+	•	Descripción: No repitas el casteo de un mismo campo jsonb->>'campo' a NUMERIC, INTEGER, etc.
+	•	Instrucción:
+Usa un alias intermedio o un CTE para calcular el valor una sola vez.
+Ejemplo (malo):
+´´´sql
+ORDER BY (jsonb_column->>'public_line')::NUMERIC DESC
+LIMIT 50
+
+Ejemplo (bueno):
+´´´sql
+WITH base AS (
+  SELECT
+    rut,
+    client_name,
+    (jsonb_column->>'public_line')::NUMERIC AS public_line
+  FROM bcu_customer
+)
+SELECT * FROM base ORDER BY public_line DESC LIMIT 50
+
+📦 2. Usar CTEs para mejorar legibilidad
+	•	Descripción: Si estás usando varios campos jsonb->>'...'::NUMERIC, sepáralos con un WITH al inicio.
+	•	Instrucción:
+Calcula todos los campos requeridos en un CTE y luego trabaja solo con sus alias.
+
+🏗️ USO DE CTE Y REFERENCIAS DE COLUMNAS
+
+- Cuando uses un CTE, debes referenciar únicamente los nombres de columnas que defines en el SELECT del CTE.
+  - Ejemplo: Si el CTE `base` define `rut`, usa `base.rut` (no `base.client_rut`).
+- Si necesitas un alias distinto para la columna, utiliza `AS` en el SELECT del CTE:
+  ```sql
+  b.rut AS client_rut
+
+📊 4. Ordenar por campos casteados
+	•	Descripción: Si necesitas ORDER BY sobre un campo jsonb casteado:
+	    transpórtalo primero.
+	•	Instrucción:
+Usa un alias para ordenar. Evita reescribir el cast dentro del ORDER BY.
+
+📌 Cuidado con el ORDER BY de expresiones sin índice
+	•	Si ordenas por un campo jsonb, considera:
+	•	Promoverlo a una columna normal (materializada).
+	•	Crear un índice funcional (si es factible).
+
+Cuando crees un alias con una función (por ejemplo, TO_CHAR(init_date, 'MM-YYYY') AS mes),
+usa siempre la expresión completa en el GROUP BY y en el ORDER BY,
+a menos que estés en una subconsulta o CTE donde el alias ya está definido.
+No uses el alias directamente en el mismo nivel del SELECT.
+ejemplo : ´´´sql
+SELECT TO_CHAR(init_date, 'MM-YYYY') AS mes, ...
+GROUP BY TO_CHAR(init_date, 'MM-YYYY')
+ORDER BY TO_DATE('01-' || TO_CHAR(init_date, 'MM-YYYY'), 'DD-MM-YYYY') DESC
+
+### 🧠 No reutilices campos JSONB que ya descompusiste
+
+- Si en un CTE extraes subcampos desde un JSONB, por ejemplo:
+```sql
+jsonb_column->>'guarantee_executive' AS ejecutiva,
+(jsonb_column->>'active')::INTEGER AS garantias_vigentes,
+no podrás referenciar jsonb_column directamente después en el mismo CTE.
+
+❌ Incorrecto:
+´´´sql
+SELECT ... FROM cartera WHERE TO_DATE(jsonb_column->>'created', ...) >= ...
+´´
+
+✅ Correcto:
+	•	Si necesitas seguir accediendo al objeto completo (jsonb_column),
+	inclúyelo también explícitamente en el SELECT del CTE.
+	•	O extrae directamente el campo requerido:
+	´´´sql TO_DATE(jsonb_column->>'created','DD-MM-YYYY') AS fecha_creacion ´´sql
+	y usa ese alias (fecha_creacion) más adelante.
+
+### ✅ Evita `jsonb_object_keys` en `WHERE`
+
+- **No uses `jsonb_object_keys(...)` dentro de `WHERE` o funciones escalares como `jsonb_array_length(...)`**.
+PostgreSQL no permite aplicar funciones escalares sobre funciones set-returning dentro de filtros.
+
+- Si quieres validar si un objeto JSONB tiene claves (no está vacío), haz:
+```sql
+jsonb_column IS NOT NULL
+AND jsonb_typeof(jsonb_column) = 'object'
+AND jsonb_column::text != '{}'
+
+Correcto:
+´´´sql
+WHERE jsonb_column IS NOT NULL
+  AND jsonb_typeof(jsonb_column) = 'object'
+  AND jsonb_column::text != '{}'
+
+❌ Incorrecto:
+´´´sql
+WHERE jsonb_array_length(jsonb_object_keys(jsonb_column)) > 0
+
+## validación de array de jsonb no vacio
+Para verificar si un array JSONB no está vacío, usa siempre:
+```sql
+jsonb_typeof(jsonb_column) = 'array'
+AND jsonb_array_length(jsonb_column) > 0
+
+### ✅ Agregaciones condicionales con JSONB
+
+- Nunca uses `SUM(<expresión booleana>)` directamente. PostgreSQL no admite sumar valores booleanos sin convertirlos de forma explícita.
+- En lugar de eso, usa `CASE WHEN ... THEN 1 ELSE 0 END` para transformar condiciones booleanas en enteros antes de agregarlas.
+
+✅ Correcto:
+
+```sql
+SUM(CASE WHEN jsonb_column->'subkey'::text != '{}' THEN 1 ELSE 0 END)
+
+❌ Incorrecto:
+´´´sql
+SUM((jsonb_column->'subkey')::text != '{}'::text)
+
+### ✅ consultas anidadas
+Cuando utilices funciones anidadas como `SUM`, `COALESCE`, `ROUND` y `NULLIF`,
+asegúrate de que los paréntesis estén correctamente balanceados.
+La estructura recomendada para calcular porcentajes sobre agregados es:
+
+  COALESCE(
+    ROUND(
+      100.0 * SUM(...) / NULLIF(SUM(...), 0),
+      0
+    ),
+    0
+  )
+
+Cuando utilices COALESCE en una expresión compleja,
+no anides múltiples COALESCE en la misma expresión.
+Solo usa un COALESCE externo para manejar valores nulos.
+Por ejemplo: COALESCE(ROUND(...), 0) es correcto.
+Evita COALESCE(..., 0), 0 o anidaciones similares.
+
+- Evita envolver `ROUND` dentro de otro `COALESCE` si ya estás manejando los nulos con `NULLIF`.
+- No uses `SUM((...)::BOOLEAN)` porque `SUM` espera un valor numérico. Para contar condiciones,
+usa `SUM(CASE WHEN ... THEN 1 ELSE 0 END)`.
+- Si estás usando subconsultas `SELECT ... FROM jsonb_array_elements(...)`,
+asegúrate de que estén dentro de la agregación correctamente y no mezcles `SUM(SELECT SUM(...))` — eso debe evitarse.
+Usa `SUM(...)` directamente sobre los elementos o con una subconsulta que retorne un valor escalar.
+
+- Cuando uses jsonb_array_elements sobre un campo JSONB (por ejemplo, jsonb_column->'contract'),
+el resultado es una sola columna llamada value (o el alias que definas, por ejemplo, contract).
+Para acceder a subcampos dentro del JSON, debes usar la notación alias->>'campo' y no alias.campo.
+Nunca intentes seleccionar directamente alias.campo si no existe como columna nativa.
+Ejemplo correcto:
+```sql
+LEFT JOIN LATERAL jsonb_array_elements(c.jsonb_column->'contract') AS o(contract) ON TRUE
+SELECT o.contract->>'contract_date' AS contract_date
+
+Ejemplo incorrecto (genera error):
+```sql
+SELECT o.contract_date  -- Esto fallará porque 'contract_date' no es una columna, sino un subcampo del JSON.
+
+
+## funciones de agregación en subconsultas
+- Nunca incluyas funciones de agregación como COUNT(*), SUM(...), etc.,
+directamente dentro de subconsultas del tipo LEFT JOIN LATERAL (...) ...
+si el agregado depende del contexto de la fila padre.
+
+- Si necesitas sumar o contar datos relacionados, primero usa el LATERAL para expandir los elementos,
+y solo después, en la consulta exterior, agrupa y aplica la agregación.
+
+Ejemplo correcto:
+```sql
+LEFT JOIN LATERAL (
+  SELECT
+    (contr.value->>'contract_amount')::NUMERIC AS monto_contrato
+  FROM jsonb_array_elements(c.jsonb_column->'contract') AS contr(value)
+  WHERE contr.value->>'status' = 'vigente'
+) v ON TRUE
+
+Luego, en el SELECT principal puedes usar SUM(v.monto) o COUNT(*).
+
+- No uses CASE WHEN ... THEN ... ELSE ... END como
+subconsulta dentro de un LEFT JOIN LATERAL (...).
+- Las subconsultas de JOIN LATERAL deben ser expresiones que empiecen por SELECT ...,
+o una función set-returning válida como jsonb_array_elements(...).
+- Si necesitas filtrar o condicionar un lateral,
+usa WHERE dentro de la subconsulta o pon la condición en el ON.
+- Para expandir arrays JSONB, usa directamente:
+```sql
+LEFT JOIN LATERAL jsonb_array_elements(b.jsonb_field) AS alias ON ...
+
+- Si quieres filtrar que solo se ejecute cuando sea un array y no esté vacío:
+```sql
+LEFT JOIN LATERAL jsonb_array_elements(b.jsonb_field) AS alias
+  ON b.jsonb_field IS NOT NULL AND jsonb_typeof(b.jsonb_field) = 'array' AND jsonb_array_length(b.jsonb_field) > 0
+
+- Cuando necesites devolver un array de objetos JSON
+(por ejemplo, al mostrar un perfil, una lista de clientes o resultados agrupados)
+utiliza únicamente json_agg() sobre una subconsulta, SIN envolverlo en row_to_json().
+Ejemplo correcto:
+   (SELECT json_agg(t) FROM (SELECT * FROM cartera_grupo ORDER BY ejecutiva) t) AS perfil_cartera
+Ejemplo incorrecto (NO USAR):
+   row_to_json((SELECT json_agg(t) FROM (SELECT * FROM cartera_grupo ORDER BY ejecutiva) t)) AS perfil_cartera
+
+- Si la consulta debe retornar un arreglo JSON, **usa solamente `json_agg`** en la subconsulta.
+- **No utilices `row_to_json` sobre un resultado que ya viene en formato JSON**.
+- Si quieres un objeto JSON de UNA SOLA fila, usa `row_to_json`. Si es un ARREGLO de filas, usa solo `json_agg`.
+
+- No incluyas ORDER BY directo dentro de json_agg a menos que lo hagas en un subselect,
+ porque causará errores de grouping.
+Ejemplo correcto:
+SELECT json_agg(row_to_json(x)) FROM (SELECT * FROM tabla ORDER BY campo) x;
+
+## ✅ Buenas prácticas generales
+
+- Usa nombres estándar de campos según el schema.
+- Respeta los alias comunes:
+  - `folio` ≡ `certificate_id`
+  - `client_rut` en certificados corresponde a `rut` en clientes
+
+- Usa `snake_case` y aliases consistentes en las consultas.
+- cuando filtres por ejecutiva o grupos de garantias o credito,
+siempre usa su ´**username**´ nunca su nombre completo.
+- siempre que compares strings utiliza  ilike para que sea case insensitive
+
+- - Cuando combines condiciones con AND y OR, **usa paréntesis** para agrupar correctamente y evitar resultados inesperados.
+  - Ejemplo correcto:
+    ```sql
+    WHERE ...
+      AND (
+        status ILIKE 'vigente'
+        OR status ILIKE 'terminada'
+      )
+    ```
+
+  - 📝 Regla para búsqueda de RUT en SQL (formato limpio, sin puntos)
+    - siempre elimina los puntos del valor buscado
+    - Haz la comparación directamente con el campo, ya que ya está en formato limpio.
+    - El campo rut en la base está guardado con guion y sin puntos.
+    ejemplo:
+    ´´´sql
+    -- Incorrecto:
+WHERE rut = '76.768.219-0'
+
+-- Correcto:
+WHERE rut = REPLACE('76.768.219-0', '.', '')
+
+	•	No elimines el guion al comparar, ya que en la base el
+	RUT debe tener formato: 76768219-0.
+
+- Nunca utilices columnas o campos JSONB de una tabla si esa columna no existe en la tabla.
+- Nunca hagas dos SELECTs seguidos usando los mismos CTEs.
+Si necesitas múltiples datasets, combínalos en un solo SELECT
+(usando subqueries, agregados o json_agg), o ejecuta varias queries separadas.
+- Si una subconsulta puede retornar varias filas,
+encapsúlala con json_agg(row_to_json(...)) en vez de solo row_to_json(...).
+- Nunca uses CASE unnest(array[...]) directamente, ni dentro de la función.
+Siempre primero aplica unnest(...) en el FROM y luego el CASE sobre el campo resultante.
+
+- cuando el modelo necesite realizar una función agregada condicional
+(por ejemplo, contar o sumar solo bajo ciertas condiciones),
+debe usar la sintaxis con CASE WHEN ... THEN ... ELSE ... END dentro de la
+función agregada.
+
+- No debe utilizar la sintaxis AGGREGATE(...) FILTER (WHERE ...).
+ejemplo correcto:
+```sql
+SUM(CASE WHEN <condición> THEN <valor> ELSE 0 END)
+COUNT(CASE WHEN <condición> THEN 1 ELSE NULL END)
+
+Ejemplo incorrecto:
+```sql
+SUM(<valor>) FILTER (WHERE <condición>)
+COUNT(*) FILTER (WHERE <condición>)
+
+- Evita utilizar '.value' para acceder a columnas cuando hagas JOIN lateral a tablas reales (por ejemplo, bcu_certificate).
+  Usa '.value' únicamente cuando la referencia provenga directamente de funciones JSON como jsonb_each() o jsonb_array_elements().
+  Si el JOIN lateral apunta directamente a tablas SQL estándar, accede a las columnas directamente por su nombre original sin '.value'.
+
+- Cuando hagas JOIN o subconsultas a la misma tabla original (`bcu_customer`),
+  **evita usar los mismos nombres de columnas sin alias**,
+  y califica siempre con el alias correspondiente (`c.`, `cc.`, etc.)."
+
+ - Al combinar resultados con UNION, INTERSECT o EXCEPT,
+ nunca uses funciones o expresiones en la cláusula ORDER BY como TO_DATE(...) o concatenaciones.
+Solo puedes ordenar por columnas explícitamente seleccionadas en el SELECT externo.
+
+- Si deseas agregar un campo calculado al resultado de una subconsulta o CTE,
+no utilices `SELECT *` y luego calcules sobre los campos resultantes.
+En su lugar, expón todos los campos explícitamente y realiza el cálculo directamente
+ dentro del `SELECT`, evitando aplicar funciones como `ROUND()` sobre registros
+ completos.
+
+- Cuando expandas un array JSONB usando `jsonb_array_elements(...)`,
+todos los campos internos (como `tender_id`) deben extraerse desde `value->>'campo'`,
+ no como columnas normales.
+ Ejemplo:
+ ```sql
+SELECT value->>'tender_id' AS tender_id FROM jsonb_array_elements(...) AS value
+
+- Al crear un alias para una columna o expresión en SQL,
+utiliza siempre la sintaxis `AS alias` y nunca `alias = expresión`.
+Esto aplica especialmente a expresiones `CASE`, agregaciones y conversiones de tipo.
+    Ejemplo:
+      ✅ CASE WHEN condicion THEN valor ELSE otro_valor END AS nombre_columna
+      ❌ nombre_columna = CASE WHEN condicion THEN valor ELSE otro_valor END
+
+- No utilices comentarios con // en SQL, ya que no son válidos en PostgreSQL.
+
+— Reglas para expandir JSONB sin errores en agregaciones
+
+# SRF-LATERAL-001 (PROHIBIDO):
+# No llames funciones que retornan sets (SRF) como jsonb_array_elements/jsonb_each/jsonb_each_text
+# dentro de agregados (json_agg/jsonb_agg/array_agg). Causa: "aggregate function calls cannot contain set-returning function calls".
+# ❌ Malo:
+#   json_agg(jsonb_array_elements(t.obj->'items'))
+
+# SRF-LATERAL-002 (OBLIGATORIO):
+# Para expandir arrays/objetos JSONB usa siempre un JOIN LATERAL y luego agrega.
+# ✅ Bueno (patrón base):
+#   SELECT
+#     k,
+#     COALESCE(jsonb_agg(e.elem), '[]'::jsonb) AS items
+#   FROM base b
+#   LEFT JOIN LATERAL jsonb_array_elements(b.obj->'items') AS e(elem)
+#     ON b.obj IS NOT NULL
+#    AND b.obj ? 'items'
+#    AND jsonb_typeof(b.obj->'items') = 'array'
+#   GROUP BY k;
+
+# SRF-LATERAL-003 (GUARDAS DE TIPO):
+# Antes de expandir, valida existencia y tipo para evitar errores en tiempo de ejecución.
+#   b.obj IS NOT NULL
+#   AND b.obj ? 'ruta'
+#   AND jsonb_typeof(b.obj->'ruta') = 'array'   -- o 'object' según corresponda
+
+# SRF-LATERAL-004 (AGREGADO RECOMENDADO):
+# Prefiere jsonb_agg para producir JSONB y normaliza a '[]' cuando no hay elementos.
+#   COALESCE(jsonb_agg(e.elem), '[]'::jsonb)
+
+# SRF-LATERAL-005 (ORDEN DENTRO DEL AGREGADO):
+# Si necesitas determinismo, ordena dentro del agregado.
+#   jsonb_agg(e.elem ORDER BY e.elem->>'campo')
+
+# SRF-LATERAL-006 (TEMPLATE REUTILIZABLE):
+# Usa este molde cuando necesites coleccionar elementos desde un JSONB.
+#   -- INPUT: tabla base b(pk, obj jsonb)
+#   SELECT
+#     b.pk,
+#     COALESCE(jsonb_agg(x.elem), '[]'::jsonb) AS elementos
+#   FROM base b
+#   LEFT JOIN LATERAL jsonb_array_elements(b.obj->'ruta') AS x(elem)
+#     ON b.obj IS NOT NULL
+#    AND b.obj ? 'ruta'
+#    AND jsonb_typeof(b.obj->'ruta') = 'array'
+#   GROUP BY b.pk;
+
+# SRF-LATERAL-007 (CASO CONCRETO: CONTRATOS):
+# Cuando necesites agrupar contratos contenidos en jsonb_operation->'contract':
+#   WITH datos_base AS (
+#     SELECT ... , c.jsonb_operation
+#     FROM bcu_customer c
+#     WHERE c.rut = :rut
+#   ),
+#   contratos AS (
+#     SELECT
+#       b.rut,
+#       COALESCE(jsonb_agg(o.value), '[]'::jsonb) AS contratos
+#     FROM datos_base b
+#     LEFT JOIN LATERAL jsonb_array_elements(b.jsonb_operation->'contract') AS o(value)
+#       ON b.jsonb_operation IS NOT NULL
+#      AND b.jsonb_operation ? 'contract'
+#      AND jsonb_typeof(b.jsonb_operation->'contract') = 'array'
+#     GROUP BY b.rut
+#   )
+#   SELECT ...
+#   FROM datos_base b
+#   LEFT JOIN contratos c ON c.rut = b.rut;
+
+# SRF-LATERAL-008 (TEXTOS DERIVADOS):
+# Si necesitas concatenar campos (p. ej., lista de emails en texto):
+#   SELECT
+#     b.rut,
+#     array_to_string(ARRAY_AGG(o.value->>'email' ORDER BY o.value->>'email'), ', ') AS emails
+#   FROM datos_base b
+#   LEFT JOIN LATERAL jsonb_array_elements(b.jsonb_operation->'contract') AS o(value)
+#     ON b.jsonb_operation IS NOT NULL
+#    AND b.jsonb_operation ? 'contract'
+#    AND jsonb_typeof(b.jsonb_operation->'contract') = 'array'
+#   GROUP BY b.rut;
+
+# SRF-LATERAL-009 (EVITA WHERE QUE EXCLUYA TODO ANTES DEL LATERAL):
+# Coloca las guardas de tipo en la condición del JOIN LATERAL (ON), no en WHERE, para no eliminar filas base.
+
+# SRF-LATERAL-010 (NOMBRADO CONSISTENTE):
+# Nombra la columna expandida como (alias).value o (alias).elem para claridad y reutilización en agregados.
+
+### SRF-ALIAS & CLAVES — Reglas para no inventar columnas al expandir JSONB
+
+# SRF-ALIAS-001 (COLUMNAS DISPONIBLES POR SRF):
+# - jsonb_array_elements(x)      → alias(elem|value)        # 1 sola columna
+# - jsonb_each(x) / jsonb_each_text(x) → alias(key, value)  # 2 columnas
+# - jsonb_object_keys(x)         → alias(key)               # 1 columna
+# Al usar estas SRF, el alias NO trae columnas de la tabla base (ej.: ct.rut NO existe).
+# Las claves/PK (ej.: rut) deben seleccionarse desde la tabla padre (ej.: b.rut).
+
+# SRF-ALIAS-002 (CLAVE PADRE SIEMPRE DESDE LA TABLA BASE):
+# En joins LATERAL encadenados, proyecta siempre la clave de la fila base:
+#   SELECT b.rut, ct.value->>'email' ...
+#   FROM base b
+#   LEFT JOIN LATERAL jsonb_array_elements(b.obj->'arr') AS c(value) ON ...
+#   -- NUNCA: SELECT c.rut ...
+
+# SRF-ALIAS-003 (GUARDAS DE TIPO EN EL ON DEL LATERAL):
+# Coloca las validaciones de existencia/tipo en el ON del JOIN LATERAL:
+#   LEFT JOIN LATERAL jsonb_array_elements(b.obj->'arr') AS c(value)
+#     ON b.obj ? 'arr' AND jsonb_typeof(b.obj->'arr') = 'array'
+
+# SRF-ALIAS-004 (DEDUPLICACIÓN):
+# Si solo necesitas eliminar duplicados sin agregar, usa DISTINCT en vez de GROUP BY sin agregados.
+
+# SRF-ALIAS-005 (PLANTILLA SEGURA):
+#   SELECT DISTINCT
+#     b.rut,
+#     ct.value->>'name'  AS name,
+#     ct.value->>'email' AS email
+#   FROM base b
+#   LEFT JOIN LATERAL jsonb_array_elements(b.jsonb_operation->'contract') AS contrato(value)
+#     ON b.jsonb_operation ? 'contract'
+#    AND jsonb_typeof(b.jsonb_operation->'contract') = 'array'
+#   LEFT JOIN LATERAL jsonb_array_elements(contrato.value->'signatories') AS ct(value)
+#     ON contrato.value ? 'signatories'
+#    AND jsonb_typeof(contrato.value->'signatories') = 'array'
+#   WHERE ct.value->>'email' IS NOT NULL;
+
+# SRF-ALIAS-006 (AGREGAR COMO JSON):
+# Para devolver arreglos JSON por rut:
+#   SELECT
+#     b.rut,
+#     COALESCE(jsonb_agg(ct.value), '[]'::jsonb) AS signatories
+#   FROM base b
+#   LEFT JOIN LATERAL jsonb_array_elements(b.jsonb_operation->'contract') AS contrato(value)
+#     ON b.jsonb_operation ? 'contract'
+#    AND jsonb_typeof(b.jsonb_operation->'contract') = 'array'
+#   LEFT JOIN LATERAL jsonb_array_elements(contrato.value->'signatories') AS ct(value)
+#     ON contrato.value ? 'signatories'
+#    AND jsonb_typeof(contrato.value->'signatories') = 'array'
+#   GROUP BY b.rut;
+
+### JSONB-AGG vs row_to_json — Reglas para agregar JSON/JSONB
+
+# JSONB-001 (NO usar row_to_json sobre json/jsonb):
+# Si el dato ya viene de jsonb_array_elements/jsonb_each como JSONB, NO lo envuelvas en row_to_json().
+# Usa jsonb_agg(...) para JSONB o json_agg((...)::json) si necesitas JSON.
+# ❌ Malo:
+#   json_agg(row_to_json(con.value))           -- con.value es JSONB
+# ✅ Bueno:
+#   jsonb_agg(con.value)                       -- mantiene JSONB
+#   json_agg((con.value)::json)                -- si necesitas JSON (no JSONB)
+
+# JSONB-002 (COALESCE tipado):
+# Asegura que COALESCE tenga el mismo tipo:
+#   COALESCE(jsonb_agg(...), '[]'::jsonb)
+#   COALESCE(json_agg(...),  '[]'::json)
+
+# JSONB-003 (DISTINCT en agregados JSONB):
+# Puedes usar DISTINCT dentro de jsonb_agg/json_agg:
+#   jsonb_agg(DISTINCT ct.value)
+
+# JSONB-004 (Guardas de tipo antes de expandir):
+# Antes de expandir, valida existencia y tipo en el ON del JOIN LATERAL:
+#   b.obj ? 'ruta' AND jsonb_typeof(b.obj->'ruta') = 'array'
+# Evita WHERE que elimine la fila base accidentalmente.
+
+# JSONB-005 (Convertir al final si hace falta):
+# Si la API de salida exige JSON (no JSONB), castea sólo al final:
+#   (jsonb_agg(...))::json
+
+# Al convertir arrays JSONB a texto separado por comas, NO uses aliases no definidos.
+    Usa `array_to_string(ARRAY(SELECT jsonb_array_elements_text(col_jsonb)), ', ')`
+    o bien alias explícito: `FROM jsonb_array_elements_text(col_jsonb) AS elem` y `SELECT elem`.
+  examples:
+    - bad:  "array_to_string(ARRAY(SELECT c FROM jsonb_array_elements_text(x)), ', ')"
+    - good: "array_to_string(ARRAY(SELECT jsonb_array_elements_text(x)), ', ')"
+    - good: "array_to_string(ARRAY(SELECT elem FROM jsonb_array_elements_text(x) AS elem), ', ')"
+  also:
+    - "Si el array puede ser nulo o vacío, usa COALESCE(..., '') para retornar cadena vacía."
+
+# En una subconsulta ESCALAR (usada como expresión en el SELECT),
+    NO usar `SELECT *` si la fuente tiene múltiples columnas.
+    Debe devolver **exactamente una columna**. Para filas compuestas,
+    envolver en `row_to_json(alias)` o seleccionar columnas individuales.
+  patterns:
+    - bad:  "(SELECT * FROM some_cte WHERE ... ) AS col"
+    - good: "(SELECT row_to_json(s) FROM some_cte s WHERE ... ) AS col"
+    - good: "(SELECT s.una_col FROM some_cte s WHERE ... ) AS col"
+
+
+# Nunca agrupes por columnas tipo JSON. Si necesitas agregar o devolver arrays/objetos,
+    usa tipos JSONB y funciones jsonb_*.
+  rules:
+    - "Usar jsonb_agg/to_jsonb/jsonb_build_object en lugar de json_agg/to_json."
+    - "Defaults con '[]'::jsonb o '{}'::jsonb, NO ::json."
+    - "Si una columna será parte del SELECT con GROUP BY, asegúrate de que sea jsonb (o cámbiala en el CTE)."
+    - "Para filas compuestas en una escalar, usar row_to_json(...) o to_jsonb(...)."
+  examples:
+    - bad:  "COALESCE(json_agg(x), '[]'::json) AS datos; ... GROUP BY datos"
+    - good: "COALESCE(jsonb_agg(x), '[]'::jsonb) AS datos; ... GROUP BY datos"
+    - good: "(SELECT row_to_json(r) FROM resumen r WHERE r.id = t.id) AS resumen"
+
+# Al seleccionar desde una CTE que ya AGRUPÓ datos, no mezclar funciones
+    agregadas nuevas (COUNT/MIN/...) con columnas no agregadas de esa misma CTE.
+    Usa directamente las columnas preagregadas o agrega TODO con GROUP BY.
+  bad_example: |
+    SELECT COUNT(*), min(col), otros_campos FROM cte_agrupada;
+  good_example: |
+    SELECT otros_campos FROM cte_agrupada;
+    -- o, si necesitas re-agrupar:
+    SELECT MAX(otros_campos) FROM cte_agrupada GROUP BY clave;
+
+# Toda columna referenciada en SELECT/WHERE debe estar presente en el scope
+    (CTE o tabla) con el alias usado. Si usas alias `b`, asegúrate que la CTE
+    `base` seleccione esos campos.
+  patterns:
+    - bad:  "WITH base AS (SELECT rut FROM t) ... SELECT b.rut, b.flag FROM base b"
+    - good: "WITH base AS (SELECT rut, flag FROM t) ... SELECT b.rut, b.flag FROM base b"
+  also:
+    - "Si un flag no existe, derivarlo desde JSONB (no asumir columnas)."
+
+En PostgreSQL no usar comentarios con '#'. Usa '--' para línea
+       o '/* ... */' para bloque.
+    2) Al usar jsonb_array_elements sobre posibles NULL, siempre proteger
+       con LEFT JOIN LATERAL + guardas en ON.
+  examples:
+    - bad:  "# comentario"
+    - good: "-- comentario"
+    - bad:  "LEFT JOIN LATERAL jsonb_array_elements(c.x->'arr') AS e(value) ON TRUE"
+    - good: "LEFT JOIN LATERAL jsonb_array_elements(c.x->'arr') AS e(value)
+             ON c.x IS NOT NULL AND c.x ? 'arr' AND jsonb_typeof(c.x->'arr')='array'"
+
+ - id: scalar_subquery_json_row
+  description: >
+    Las subconsultas escalares deben devolver UNA sola columna. Si necesitas
+    varias columnas, envuelve la fila en JSON con row_to_json(alias).
+  patterns:
+    - bad:  "(SELECT * FROM cte) AS x"
+    - good: "(SELECT row_to_json(c) FROM cte c) AS x"
+    - good: "(SELECT c.una_col FROM cte c) AS x"
+  also:
+    - "Al usar jsonb_array_elements sobre posibles NULL, envuelve con COALESCE(...,'[]'::jsonb)."
+
+- id: no_truncated_sql
+  description: "Nunca dejes '...' u otros placeholders en SQL: el parser fallará."
+  examples:
+    - bad:  "ROUND(100.0*total_con_maxxa/lici..."
+    - good: "ROUND(100.0*total_con_maxxa/NULLIF(licitaciones_ganadas,0),1)"
+
+- id: avoid_srf_in_select_list
+  description: >
+    No uses funciones que devuelven sets (json[b]_array_elements*, unnest, etc.)
+    en la lista SELECT para contarlas. Usa jsonb_array_length(col) o un
+    LEFT JOIN LATERAL + COUNT(*).
+  examples:
+    - bad:  "COUNT(jsonb_array_elements_text(ct.certificate_ids))"
+    - good: "SUM(COALESCE(jsonb_array_length(ct.certificate_ids),0))"
+    - good: |
+        LEFT JOIN LATERAL jsonb_array_elements(ct.certificate_ids) AS e(x) ON TRUE
+        COUNT(e.x)
+
+- id: percent_with_nullif
+  description: "Al calcular porcentajes, usa NULLIF(den,0) para evitar división por cero."
+  examples:
+    - good: "ROUND(100.0 * ganadas / NULLIF(total,0), 1)"
+
+- id: date_casts_vs_to_date
+  description: >
+    No uses TO_DATE sobre columnas DATE/TIMESTAMP. TO_DATE solo acepta texto.
+    Para DATE usa MIN(col); para TIMESTAMP usa ::date o date_trunc.
+    Si la columna es texto, entonces sí usar TO_DATE(text, 'YYYY-MM-DD').
+  examples:
+    - bad:  "TO_DATE(ts_col, 'YYYY-MM-DD')"           # ts_col es TIMESTAMP
+    - good: "ts_col::date"
+    - bad:  "TO_DATE(date_col, 'YYYY-MM-DD')"         # date_col es DATE
+    - good: "date_col"
+    - good: "TO_DATE(text_col, 'YYYY-MM-DD')"         # text_col es TEXT
+
+- id: aggregate_from_correct_table
+  description: >
+    No agregues columnas (status, montos) desde una CTE/tabla que no las tiene.
+    Si los datos están en otra tabla (p.ej. bcu_certificate), usa subselect
+    correlacionado o un JOIN/CTE agregado por rut.
+  bad:  "FROM bcu_customer ... SUM(CASE WHEN status ...)"
+  good: "FROM bcu_customer c ... (SELECT SUM(...) FROM bcu_certificate bc WHERE bc.rut=c.rut ...)"
+
+ - id: cte_scope_single_statement
+  description: >
+    Las CTE (WITH ...) solo viven durante UNA sentencia SQL. Si haces
+    múltiples SELECTs separados por ';', debes repetir el WITH o consolidar
+    todo en una sola sentencia (p.ej. usando subselects o agregando a JSON).
+  bad: |
+    WITH a AS (...) SELECT ...;
+    SELECT * FROM a;   # falla: 'a' ya no existe
+  good: |
+    WITH a AS (...), b AS (...) SELECT ... FROM a ...;
+    -- o repetir el WITH antes del segundo SELECT
+
+- Si una columna (jsonb_*) se usará después, debe proyectarse en el CTE inicial con el mismo alias.
+No referenciar columnas que no estén proyectadas.
+Si necesitas el objeto completo y un campo derivado, incluye ambos.
+
+- Usa EXACTAMENTE el mismo nombre para cada CTE/tabla en su definición y en los JOIN/SELECT posteriores (respeta mayúsculas/minúsculas y ortografía).
+Antes del SELECT final, verifica que todos los identificadores referenciados (p. ej., guarantee_summary) existen y coinciden con los CTE definidos (p. ej., guarante_summary).
+Prohíbe crear o unir CTE con nombres “parecidos”; si cambias un nombre, actualízalo en todas las referencias.
+
+En el SELECT final, cualquier subconsulta debe ser escalar.
+	•	Para objetos: SELECT row_to_json(sub) FROM (SELECT col1, col2, ...) sub.
+	•	Para listas: SELECT json_agg(row_to_json(sub)) FROM (SELECT ...) sub.
+	•	Nunca SELECT * dentro del SELECT final.
+
+- No usar row_to_json() sobre valores json/jsonb.
+Si el LLM necesita serializar un json/jsonb, usar to_json()/to_jsonb() o devolver el campo tal cual.
+Reservar row_to_json() solo para records (filas) provenientes de subconsultas/CTEs o SELECT ... con columnas.
+
+### RULE-XXX — No usar `ctid` fuera de su tabla de origen
+⚠️ **Prohibido referenciar la columna `ctid` fuera de la consulta directa a su tabla de origen.**
+
+- `ctid` es una columna interna de PostgreSQL que solo puede ser usada directamente en la tabla donde existe.
+- No puede referenciarse desde subconsultas o alias si ya no está presente en el conjunto de columnas seleccionadas.
+- Si necesitas contar o verificar filas, usa una columna real (por ejemplo, `tender_id`) o `COUNT(*)` sin `ctid`.
+
+#### Ejemplo incorrecto:
+```sql
+COUNT(*) FILTER (WHERE ctid IS NOT NULL) AS garantias_maxxa
+
+### RULE-AGG-001 — No mezclar agregados con columnas sin agrupar
+Cuando uses agregaciones (`COUNT`, `SUM`, `AVG`, `STRING_AGG`, etc.) **sin `GROUP BY`**, todo lo que aparezca en el `SELECT` debe estar dentro de una función agregada.
+
+✅ Correcto:
+```sql
+SELECT STRING_AGG(
+         ej.ejecutiva_garantia || ' (GC: ' || ej.grupo_garantia || ')'
+         || ' | '
+         || ej.ejecutiva_credito || ' (CC: ' || ej.grupo_credito || ')',
+         ', '
+       ) AS ejecutivos
+FROM ejecutivos ej;
+
+RULE-AGG-003:
+  description: No usar MAX(boolean); convertir booleanos a enteros con CASE WHEN ... THEN 1 ELSE 0 END antes de usar funciones agregadas como MAX o SUM.
+  match: MAX\(CASE\s+WHEN\s+.*\s+THEN\s+(TRUE|FALSE)\s+ELSE\s+(TRUE|FALSE)\s+END\)
+  fix: Reemplazar el CASE para devolver 1/0 en lugar de TRUE/FALSE. Ejemplo: CASE WHEN condición THEN 1 ELSE 0 END
+
+RULE-GROUPBY-001:
+  description: Toda columna que aparece en SELECT dentro de una subconsulta con GROUP BY debe también estar en el GROUP BY o estar dentro de una función agregada.
+  match: SELECT\s+(.*?)\s+FROM\s+(.*?)\s+GROUP\s+BY\s+(?!.*\1)
+  fix: Asegúrate de incluir en el GROUP BY todas las columnas del SELECT que no estén envueltas en funciones agregadas.
+
+
+RULE-JSON-005:
+  description: Al concatenar valores extraídos de JSON (`->>`), asegúrate de envolver cada fragmento con `COALESCE(..., '')` y tratarlo explícitamente como texto (`::text`) para evitar errores de representación inválida.
+  match: \|\|\s*contract\.value->>'\w+'
+  fix: Usar `COALESCE(contract.value->>'campo', '')` y aplicar cast `::text` al resultado de la concatenación si es necesario.
+
+RULE-CTE-001:
+  description: Si usas una tabla o CTE como `base` dentro de un subselect, asegúrate de incluir `FROM base` dentro de ese subselect.
+  match: SELECT\s+.*base\.
+  fix: Agrega `FROM base` dentro del subselect que usa columnas prefijadas con `base.`.
+
+
+RULE-SUBSELECT-MULTICOLUMN-ERROR-001:
+  description:
+    No puedes usar `SELECT *` desde una subconsulta (CTE o tabla derivada) dentro del SELECT final
+    si esa subconsulta devuelve más de una columna. PostgreSQL lanza error: "subquery must return only one column".
+
+  context_where_this_happens:
+    Cuando escribes en el SELECT final algo como `(SELECT * FROM algo)` y `algo` tiene más de una columna.
+
+  why_this_fails:
+    PostgreSQL espera que la subconsulta devuelva una sola columna. Pero `*` devuelve todas, causando el error.
+
+  how_to_fix_it:
+    - Si quieres agrupar varias columnas en una sola columna tipo objeto, usa:
+      `(SELECT row_to_json(alias) FROM algo alias)`
+    - Si solo necesitas una columna, escríbela explícitamente:
+      `(SELECT columna FROM algo)`
+
+  bad_example: |
+    SELECT
+      nombre,
+      (SELECT * FROM resumen_licitaciones) AS licitaciones
+    FROM base
+
+  good_example_option_1: |
+    SELECT
+      nombre,
+      (SELECT row_to_json(r) FROM resumen_licitaciones r) AS licitaciones
+    FROM base
+
+  good_example_option_2: |
+    SELECT
+      nombre,
+      (SELECT total_participa FROM resumen_licitaciones) AS licitaciones
+    FROM base
+
+RULE-JSONB-OPERATOR-001:
+  description: >
+    El operador `->>` solo puede usarse sobre columnas de tipo `jsonb`, no sobre strings literales ni columnas de tipo `text`.
+  bad_examples:
+    - "'guarantee_executive'->>'group'"
+    - "'algo'->>'otra_cosa'"
+    - "'text_literal'->>'key'"
+  good_examples:
+    - "c.jsonb_guarantee->>'guarantee_group'"
+    - "cb.jsonb_credit->>'credit_executive'"
+
+RULE-CONCATENATION-001:
+  description: >
+    No uses `%%` en concatenaciones de texto. PostgreSQL no lo interpreta como un símbolo de `%`, y lanzará un error de sintaxis.
+    Usa solo `%` si estás concatenando strings.
+  bad_examples:
+    - "'('||ROUND(ganadas*100.0/NULLIF(total,0),1)||'%%') de ellas.'"
+    - "CONCAT('Avance: ', ROUND(x*100,2), '%% completado')"
+  good_examples:
+    - "'('||ROUND(ganadas*100.0/NULLIF(total,0),1)||'%'||') de ellas.'"
+    - "CONCAT('Avance: ', ROUND(x*100,2), '% completado')"
+
+  RULE-JSONB-ACCESS-VALUE-001:
+  description: >
+    No se puede acceder a un campo de un objeto JSONB con notación de punto (por ejemplo: `cc.comment`) cuando se itera con `jsonb_array_elements`.
+    En su lugar, debes usar `cc.value->>'campo'` o `cc.value->'campo'`.
+
+  when_to_apply: >
+    Si estás usando `jsonb_array_elements(...) AS alias` en una subconsulta, debes acceder a los campos con `alias.value->>'campo'`.
+
+  how_to_fix:
+    - Reemplaza `cc.campo` por `cc.value->>'campo'` si necesitas el valor como texto.
+    - Usa `cc.value->'campo'` si necesitas el valor como JSONB.
+
+  bad_example: |
+    SELECT cc.comment FROM jsonb_array_elements(jsonb_col) cc
+
+  good_example: |
+    SELECT cc.value->>'comment' FROM jsonb_array_elements(jsonb_col) cc
+
+  RULE-SUBQUERY-SINGLE-ROW-001:
+  description: >
+    Si usas una subconsulta escalar en el `SELECT`, como `(SELECT row_to_json(...) FROM ...)`, debes garantizar que la subconsulta devuelve **solo una fila**.
+    Si no hay `WHERE`, podrías obtener múltiples filas, lo que causará un error en tiempo de ejecución.
+
+  when_to_apply: >
+    Siempre que estés usando una subconsulta en el `SELECT` que espera una sola fila (por ejemplo: `(SELECT row_to_json(...) FROM nombre_cte)`), debes filtrar por una clave única como `rut`.
+
+  how_to_fix:
+    - Agrega un `WHERE` en la subconsulta que filtre por una columna que asegure una sola fila (como `rut = b.rut`).
+    - Alternativamente, limita a una fila con `LIMIT 1`, pero no es recomendable si puede haber inconsistencias.
+
+  bad_example: |
+    (SELECT row_to_json(s) FROM resumen_garantias s)
+
+  good_example: |
+    (SELECT row_to_json(s) FROM resumen_garantias s WHERE s.rut = b.rut)
+
+  RULE-SCALAR-SUBQUERY-LIMIT-001:
+  description: >
+    Cuando uses una subconsulta escalar dentro de un `SELECT`, debes asegurarte de que la subconsulta devuelve solo una fila.
+    Si existe la posibilidad de múltiples filas, se producirá un error.
+
+  when_to_apply: >
+    Si estás usando `(SELECT ... FROM ...)` como un campo en el SELECT principal.
+
+  how_to_fix:
+    - Asegúrate de que la subconsulta solo puede devolver una fila.
+    - Usa `LIMIT 1` si estás seguro de que cualquier fila es válida, o filtra con `WHERE` para obtener una única.
+
+  bad_example: |
+    (SELECT texto FROM tabla)
+
+  good_example: |
+    (SELECT texto FROM tabla LIMIT 1)
+    -- o
+    (SELECT texto FROM tabla WHERE id = b.id)
+
+  RULE-JSONB-FUNCTION-NULL-PROTECTION-001:
+  description: >
+    Antes de aplicar funciones como `jsonb_each`, `jsonb_array_elements`, `jsonb_object_keys`, asegúrate que el campo JSONB no sea NULL.
+    Estas funciones no aceptan NULL como entrada, y generarán errores incluso si luego filtras con condiciones como `WHERE 1=0`.
+
+  when_to_apply: >
+    En subconsultas, joins laterales o expresiones donde accedes a funciones jsonb_*.
+
+  how_to_fix:
+    - Agrega `WHERE campo IS NOT NULL` o `ON campo IS NOT NULL` cuando uses funciones jsonb.
+    - Evita aplicar funciones jsonb directamente sobre campos potencialmente nulos.
+
+  bad_example: |
+    SELECT jsonb_each(b.jsonb_data)
+
+  good_example: |
+    SELECT jsonb_each(b.jsonb_data)
+    WHERE b.jsonb_data IS NOT NULL
+
+  RULE-JSONB-ARRAY-PROTECT-001:
+  description: "Antes de aplicar jsonb_array_elements() sobre una clave de tipo JSONB, verificar que dicha clave exista y sea de tipo 'array'."
+  example_good: >
+    b.jsonb_data ? 'items'
+    AND jsonb_typeof(b.jsonb_data->'items') = 'array'
+    AND jsonb_array_elements(b.jsonb_data->'items')
+  example_bad: >
+    jsonb_array_elements(b.jsonb_data->'items')
+
+  - rule_id: RULE-AGG-JSON-ORDER
+  description: >
+    Al usar jsonb_agg sobre un campo JSON construido en un LATERAL (ej. j.comi),
+    no se puede ordenar por columnas internas del subquery (ej. j.anio), ya que no existen en el scope externo.
+    Siempre ordenar usando expresiones sobre el JSON (ej. (j.comi->>'anio')::INT).
+  bad_example: |
+    jsonb_agg(j.comi ORDER BY j.anio DESC)
+  good_example: |
+    jsonb_agg(j.comi ORDER BY (j.comi->>'anio')::INT DESC)
+
+ RULE-GRAIN-001 (no mezclar granos en JOIN):
+	•	Define el grano de cada CTE (ej.: rut, tender_id, product_type).
+	•	Nunca hagas JOIN entre CTEs de granos distintos usando subconsultas con LIMIT 1 para obtener una “llave”.
+	•	Si necesitas métricas de rut en un agregado por product_type, primero une por rut (o agrega ambas fuentes al mismo grano) y recién después agrupa por product_type.
+
+Anti-patrón a prohibir: JOIN ... ON key = (SELECT ... LIMIT 1)
+Patrón correcto: incluye la clave real (p.ej., rut) en el CTE de detalle (creditos) y JOIN ... ON j.rut = c.rut antes de GROUP BY product_type.
+
+{
+  "rule_id": "RULE-UNION-001",
+  "description": "Evita errores de UNION/UNION ALL por desalineación de columnas entre subconsultas.",
+  "applies_to": "sql_bcu",
+  "rule": "Todas las subconsultas que participan en un UNION o UNION ALL deben tener exactamente el mismo número de columnas, con los mismos nombres (o alias) y en el mismo orden. Si una de las subconsultas agrega columnas adicionales como ROW_NUMBER, esas columnas deben ser excluidas explícitamente en el SELECT final para que ambas subconsultas coincidan.",
+  "examples": {
+    "incorrect": [
+      "SELECT a, b FROM tabla1 UNION ALL SELECT a, b, c FROM tabla2",
+      "SELECT * FROM (SELECT a, b, ROW_NUMBER() OVER (...) AS rn FROM x) x WHERE rn <= 10 UNION SELECT a, b FROM y"
+    ],
+    "correct": [
+      "SELECT a, b FROM tabla1 UNION ALL SELECT a, b FROM tabla2",
+      "SELECT a, b FROM (SELECT a, b, ROW_NUMBER() OVER (...) AS rn FROM x) x WHERE rn <= 10"
+    ]
+  },
+  "fix_suggestion": "Asegúrate de que todas las subconsultas dentro del UNION seleccionen explícitamente las mismas columnas. Si se usa ROW_NUMBER u otras funciones analíticas, excluye esas columnas en el SELECT exterior antes del UNION."
+}
+
+- No usar guiones (-) en los alias de columnas SQL.
+Usar guion bajo (_) en su lugar para evitar errores de sintaxis.