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