add selectai

lab/selectai/02_annotations.sql

@@ -0,0 +1,297 @@
+set define off
+
+-- ============================================================================
+-- Lab: Annotations para SELECT AI
+-- ============================================================================
+-- Este script documenta tablas relacionales generadas desde una JSON COLLECTION
+-- TABLE y la JSON Relational Duality View que recompone el documento.
+--
+-- SELECT AI usa nombres, relaciones y metadatos para generar SQL. Las
+-- annotations ayudan a explicar el significado de tablas y columnas con
+-- lenguaje de negocio, sinonimos y pistas de uso.
+--
+-- Nota: para ejecutar el lab mas de una vez, cambie ADD por REPLACE en las
+-- annotations que ya existan.
+-- ============================================================================
+
+-- ============================================================================
+-- T_ROOT: tabla raiz del documento JSON
+-- ============================================================================
+
+ALTER TABLE t_root ANNOTATIONS (
+  ADD display_name 'Documento de promocion',
+  ADD business_description 'Tabla raiz de cada promocion extraida desde markdown. Une promocion, medios de pago, cuotas, reintegro, exclusiones y listas hijas.',
+  ADD select_ai_hint 'Use esta tabla como punto de partida cuando la pregunta sea sobre una promocion completa o sobre condiciones generales.',
+  ADD example_questions 'Que promociones existen? Cuales son las exclusiones? Que banco emite la promocion?'
+);
+
+ALTER TABLE t_root MODIFY "_id" ANNOTATIONS (
+  ADD display_name 'Identificador del documento',
+  ADD business_description 'Clave tecnica RAW que identifica un documento JSON de promocion.',
+  ADD select_ai_hint 'No mostrar al usuario final salvo que pida identificadores tecnicos.'
+);
+
+ALTER TABLE t_root MODIFY exclusoes ANNOTATIONS (
+  ADD display_name 'Exclusiones de la promocion',
+  ADD business_description 'Lista JSON con reglas, restricciones y condiciones que excluyen compras o situaciones del beneficio.',
+  ADD synonyms 'restricciones, condiciones, limitaciones, no aplica, fuera de promocion',
+  ADD select_ai_hint 'Cuando el usuario pregunte que no aplica o que esta excluido, consulte este campo JSON.'
+);
+
+ALTER TABLE t_root MODIFY titulo_t_promocao ANNOTATIONS (
+  ADD display_name 'Titulo de la promocion',
+  ADD business_description 'Referencia al titulo principal de la promocion.',
+  ADD relationship_hint 'Clave foranea hacia T_PROMOCAO.TITULO.'
+);
+
+ALTER TABLE t_root MODIFY emissor_t_medios_pago ANNOTATIONS (
+  ADD display_name 'Emisor del medio de pago',
+  ADD business_description 'Banco o entidad emisora usada para enlazar los medios de pago aceptados.',
+  ADD relationship_hint 'Clave foranea hacia T_MEDIOS_PAGO.EMISSOR.'
+);
+
+ALTER TABLE t_root MODIFY maximo_sin_intereses_t_cuotas ANNOTATIONS (
+  ADD display_name 'Maximo de cuotas sin intereses',
+  ADD business_description 'Valor usado para enlazar las condiciones de cuotas sin intereses.',
+  ADD unit 'cuotas',
+  ADD relationship_hint 'Clave foranea hacia T_CUOTAS.MAXIMO_SIN_INTERESES.'
+);
+
+ALTER TABLE t_root MODIFY prazo_dias_habiles_t_acreditacao_reintegro ANNOTATIONS (
+  ADD display_name 'Plazo de acreditacion del reintegro',
+  ADD business_description 'Cantidad de dias habiles usada para enlazar la regla de acreditacion del reintegro.',
+  ADD unit 'dias habiles',
+  ADD relationship_hint 'Clave foranea hacia T_ACREDITACAO_REINTEGRO.PRAZO_DIAS_HABILES.'
+);
+
+-- ============================================================================
+-- T_PROMOCAO y T_VIGENCIA: datos principales de la promocion
+-- ============================================================================
+
+ALTER TABLE t_promocao ANNOTATIONS (
+  ADD display_name 'Promocion',
+  ADD business_description 'Datos principales de la oferta bancaria, incluyendo titulo y vigencia.',
+  ADD select_ai_hint 'Use esta tabla para responder preguntas sobre el nombre de la promocion y sus fechas.'
+);
+
+ALTER TABLE t_promocao MODIFY titulo ANNOTATIONS (
+  ADD display_name 'Titulo',
+  ADD business_description 'Nombre oficial de la promocion segun el documento markdown.',
+  ADD synonyms 'nombre de promocion, campana, oferta'
+);
+
+ALTER TABLE t_promocao MODIFY data_inicio_t_vigencia ANNOTATIONS (
+  ADD display_name 'Fecha de inicio',
+  ADD business_description 'Fecha inicial de vigencia enlazada con T_VIGENCIA.',
+  ADD relationship_hint 'Parte de la clave compuesta hacia T_VIGENCIA.'
+);
+
+ALTER TABLE t_promocao MODIFY data_fim_t_vigencia ANNOTATIONS (
+  ADD display_name 'Fecha de fin',
+  ADD business_description 'Fecha final de vigencia enlazada con T_VIGENCIA.',
+  ADD relationship_hint 'Parte de la clave compuesta hacia T_VIGENCIA.'
+);
+
+ALTER TABLE t_vigencia ANNOTATIONS (
+  ADD display_name 'Vigencia',
+  ADD business_description 'Rango de fechas en que la promocion esta activa.',
+  ADD example_questions 'La promocion sigue vigente? Cuando termina la promocion?'
+);
+
+ALTER TABLE t_vigencia MODIFY data_inicio ANNOTATIONS (
+  ADD display_name 'Inicio de vigencia',
+  ADD business_description 'Primer dia en que la promocion puede ser aplicada.',
+  ADD unit 'fecha'
+);
+
+ALTER TABLE t_vigencia MODIFY data_fim ANNOTATIONS (
+  ADD display_name 'Fin de vigencia',
+  ADD business_description 'Ultimo dia en que la promocion puede ser aplicada.',
+  ADD unit 'fecha'
+);
+
+-- ============================================================================
+-- T_MEDIOS_PAGO: tarjetas, QR, ecommerce y billeteras
+-- ============================================================================
+
+ALTER TABLE t_medios_pago ANNOTATIONS (
+  ADD display_name 'Medios de pago',
+  ADD business_description 'Condiciones de pago aceptadas por la promocion, como tarjetas, red, QR, ecommerce y billeteras electronicas.',
+  ADD select_ai_hint 'Use esta tabla para preguntas sobre como pagar para recibir el beneficio.'
+);
+
+ALTER TABLE t_medios_pago MODIFY emissor ANNOTATIONS (
+  ADD display_name 'Emisor',
+  ADD business_description 'Entidad emisora aceptada para participar de la promocion.',
+  ADD synonyms 'banco, entidad, issuer'
+);
+
+ALTER TABLE t_medios_pago MODIFY rede ANNOTATIONS (
+  ADD display_name 'Red de tarjeta',
+  ADD business_description 'Red o marca de tarjeta aceptada por la promocion.',
+  ADD synonyms 'marca, red, network'
+);
+
+ALTER TABLE t_medios_pago MODIFY qr_permitido ANNOTATIONS (
+  ADD display_name 'QR permitido',
+  ADD business_description 'Indica si el pago por QR participa de la promocion.',
+  ADD select_ai_hint 'Campo booleano: true significa que QR esta permitido.'
+);
+
+ALTER TABLE t_medios_pago MODIFY ecommerce_permitido ANNOTATIONS (
+  ADD display_name 'Ecommerce permitido',
+  ADD business_description 'Indica si compras online o ecommerce participan de la promocion.',
+  ADD select_ai_hint 'Campo booleano: true significa que ecommerce esta permitido.'
+);
+
+ALTER TABLE t_medios_pago MODIFY tarjetas_aceitas ANNOTATIONS (
+  ADD display_name 'Tarjetas aceptadas',
+  ADD business_description 'Array JSON con las tarjetas o productos de tarjeta que califican.',
+  ADD synonyms 'tarjetas validas, tarjetas admitidas, tarjetas participantes',
+  ADD select_ai_hint 'Use funciones JSON cuando necesite filtrar por una tarjeta especifica.'
+);
+
+ALTER TABLE t_medios_pago MODIFY billeteras_electronicas ANNOTATIONS (
+  ADD display_name 'Billeteras electronicas',
+  ADD business_description 'Array JSON con billeteras digitales aceptadas por la promocion.',
+  ADD synonyms 'wallets, billeteras, monederos digitales',
+  ADD select_ai_hint 'Use funciones JSON cuando el usuario pregunte por una billetera especifica.'
+);
+
+-- ============================================================================
+-- T_CUOTAS: informacion de financiamiento
+-- ============================================================================
+
+ALTER TABLE t_cuotas ANNOTATIONS (
+  ADD display_name 'Cuotas',
+  ADD business_description 'Reglas de financiamiento sin intereses para la promocion.',
+  ADD example_questions 'Cuantas cuotas sin intereses permite la promocion? El cliente debe pedir las cuotas?'
+);
+
+ALTER TABLE t_cuotas MODIFY maximo_sin_intereses ANNOTATIONS (
+  ADD display_name 'Maximo sin intereses',
+  ADD business_description 'Cantidad maxima de cuotas sin intereses permitidas.',
+  ADD unit 'cuotas'
+);
+
+ALTER TABLE t_cuotas MODIFY requer_solicitacao_cliente ANNOTATIONS (
+  ADD display_name 'Requiere solicitud del cliente',
+  ADD business_description 'Indica si el cliente debe solicitar expresamente el pago en cuotas.',
+  ADD select_ai_hint 'Campo booleano: true significa que el cliente debe solicitarlo.'
+);
+
+-- ============================================================================
+-- T_ACREDITACAO_REINTEGRO: como se acredita el beneficio
+-- ============================================================================
+
+ALTER TABLE t_acreditacao_reintegro ANNOTATIONS (
+  ADD display_name 'Acreditacion del reintegro',
+  ADD business_description 'Reglas de acreditacion del reintegro: plazo, porcentaje acreditado y tipo de cuenta.',
+  ADD select_ai_hint 'Use esta tabla para preguntas sobre cuando y donde se acredita el reintegro.'
+);
+
+ALTER TABLE t_acreditacao_reintegro MODIFY prazo_dias_habiles ANNOTATIONS (
+  ADD display_name 'Plazo en dias habiles',
+  ADD business_description 'Cantidad de dias habiles hasta acreditar el reintegro.',
+  ADD unit 'dias habiles',
+  ADD synonyms 'plazo, demora, tiempo de acreditacion'
+);
+
+ALTER TABLE t_acreditacao_reintegro MODIFY percentual_creditado ANNOTATIONS (
+  ADD display_name 'Porcentaje acreditado',
+  ADD business_description 'Porcentaje del reintegro que sera acreditado al cliente.',
+  ADD unit 'porcentaje'
+);
+
+ALTER TABLE t_acreditacao_reintegro MODIFY tipo_conta ANNOTATIONS (
+  ADD display_name 'Tipo de cuenta',
+  ADD business_description 'Cuenta o producto donde se acredita el reintegro.',
+  ADD synonyms 'cuenta destino, producto, cuenta de acreditacion'
+);
+
+-- ============================================================================
+-- T_COMERCIOS: comercios participantes
+-- ============================================================================
+
+ALTER TABLE t_comercios ANNOTATIONS (
+  ADD display_name 'Comercios participantes',
+  ADD business_description 'Lista de comercios que participan de la promocion, con categoria y procesador de pago.',
+  ADD select_ai_hint 'Use esta tabla para preguntas sobre donde comprar, rubros participantes o procesadores de pago.'
+);
+
+ALTER TABLE t_comercios MODIFY name ANNOTATIONS (
+  ADD display_name 'Nombre del comercio',
+  ADD business_description 'Nombre del comercio tal como aparece en el documento original.',
+  ADD synonyms 'tienda, local, merchant, comercio'
+);
+
+ALTER TABLE t_comercios MODIFY category ANNOTATIONS (
+  ADD display_name 'Categoria del comercio',
+  ADD business_description 'Rubro o seccion del markdown donde aparece el comercio.',
+  ADD synonyms 'rubro, segmento, categoria, grupo'
+);
+
+ALTER TABLE t_comercios MODIFY payment_processor ANNOTATIONS (
+  ADD display_name 'Procesador de pago',
+  ADD business_description 'Procesador asociado al comercio, por ejemplo upay o bancard.',
+  ADD synonyms 'procesadora, adquirente, payment processor'
+);
+
+ALTER TABLE t_comercios MODIFY "_id_t_root" ANNOTATIONS (
+  ADD display_name 'Documento de origen',
+  ADD business_description 'Clave tecnica que enlaza el comercio con el documento raiz de la promocion.',
+  ADD relationship_hint 'Clave foranea hacia T_ROOT."_id".'
+);
+
+-- ============================================================================
+-- T_BENEFICIOS_POR_NIVEL: reglas de reintegro por nivel
+-- ============================================================================
+
+ALTER TABLE t_beneficios_por_nivel ANNOTATIONS (
+  ADD display_name 'Beneficios por nivel',
+  ADD business_description 'Lista de niveles de cliente y sus reglas de reintegro, compra minima y tope maximo.',
+  ADD select_ai_hint 'Use esta tabla para comparar beneficios entre niveles.'
+);
+
+ALTER TABLE t_beneficios_por_nivel MODIFY nivel ANNOTATIONS (
+  ADD display_name 'Nivel del cliente',
+  ADD business_description 'Nivel o segmento del cliente dentro de la promocion.',
+  ADD synonyms 'segmento, nivel, categoria de cliente'
+);
+
+ALTER TABLE t_beneficios_por_nivel MODIFY percentual_reintegro ANNOTATIONS (
+  ADD display_name 'Porcentaje de reintegro',
+  ADD business_description 'Porcentaje de reintegro ofrecido para el nivel.',
+  ADD unit 'porcentaje'
+);
+
+ALTER TABLE t_beneficios_por_nivel MODIFY monto_compra_minimo_gs ANNOTATIONS (
+  ADD display_name 'Compra minima',
+  ADD business_description 'Monto minimo de compra requerido para aplicar el beneficio.',
+  ADD unit 'guaranies'
+);
+
+ALTER TABLE t_beneficios_por_nivel MODIFY reintegro_maximo_gs ANNOTATIONS (
+  ADD display_name 'Tope maximo de reintegro',
+  ADD business_description 'Monto maximo de reintegro que puede recibir el cliente en guaranies.',
+  ADD unit 'guaranies',
+  ADD synonyms 'tope, limite, maximo de devolucion'
+);
+
+ALTER TABLE t_beneficios_por_nivel MODIFY "_id_t_root" ANNOTATIONS (
+  ADD display_name 'Documento de origen',
+  ADD business_description 'Clave tecnica que enlaza el beneficio por nivel con el documento raiz de la promocion.',
+  ADD relationship_hint 'Clave foranea hacia T_ROOT."_id".'
+);
+
+-- ============================================================================
+-- V_PARSED_MARKDOWN_FILES: vista JSON Relational Duality
+-- ============================================================================
+
+ALTER VIEW v_parsed_markdown_files ANNOTATIONS (
+  ADD display_name 'Documento JSON de promocion',
+  ADD business_description 'JSON Relational Duality View que presenta las tablas normalizadas como un unico documento JSON consultable y actualizable.',
+  ADD select_ai_hint 'Use esta vista cuando el usuario pregunte por el documento completo o quiera ver la estructura JSON de la promocion.',
+  ADD example_questions 'Muestre el JSON completo de la promocion. Que comercios aparecen dentro del documento? Que condiciones tiene la promocion?'
+);
+