Qué es un ítem

Un ítem (modelo Bono) es una línea de la liquidación: un haber, un descuento o un aporte. En el sector privado la empresa los define a gusto. En el sector público muchos vienen fijados por ley, con fórmula y tope legal.

Ítem Sistema vs Ítem Formulado

Tipo	`rebaja`	Cómo se calcula	Ejemplo
Sistema	`Sistema`	Código Ruby dentro de la calculadora	Cotización previsional, impuesto único
Formulado	`Formulado`	Fórmula Dentaku (string) guardada en `Bono#formula`, evaluada en runtime	Sueldo base público, bono de vacaciones, asignación de antigüedad

Casi todos los ítems del sector público son Formulados: la fórmula es texto, versionable y auditable, que es justo lo que exige la trazabilidad legal. Existe un skill del repo (migrar-item-sistema-a-formulado) para convertir uno de Sistema a Formulado.

system_item? significa rebaja == Sistema — no significa "predefinido por Buk". El marcador confiable de "predefinido por Buk" es el prefijo buk_ en el code (ver Transparencia Activa CPLT).

Anatomía de un ítem de sistema en YAML

De config/data/chile/system_items/estatuto_administrativo.yml:

buk_sueldo_base_administrativo:
  name: Sueldo Base
  code: buk_sueldo_base_administrativo
  remuneration_system: estatuto_administrativo
  rebaja: Formulado
  tipo_item: haber
  imponible: true
  tributable: true
  decimal_scale: 0
  codigo_pago_nomina: '131'          # codigo para el Informe de Transparencia
  editable: editable_none            # el tenant no puede editar este item
  formula: (TABLA_POR_COLUMNA('buk_sueldo_base_administrativo', 'Grado', trabajo.grado, 'Monto', 0)/44)*trabajo.horas_semanales

El enum editable (editable_none / editable_partial / editable_full) controla qué puede tocar el tenant. Varía por estatuto para el mismo concepto: el sueldo base administrativo es editable_none, pero el docente sembrado es editable_full. No usar editable como proxy de "de sistema".

Las variables de fórmula

Dentro de una fórmula hay tres familias de identificadores:

trabajo.<x> — atributos del job: trabajo.grado, trabajo.horas_semanales, trabajo.bienios, trabajo.sistema_remuneracion, trabajo.estamento. Resueltos por CalculosBono::ItemVariables::Chile::Job. Si un trabajo.<x> no está en #element_names, es un atributo personalizado del cliente (Job::CustomAttrsEntry), no una variable del sistema.
liquidacion.<x> — valores del comprobante en curso: liquidacion.sueldo_base, liquidacion.total_haberes, liquidacion.porcentaje_afp, liquidacion.salud_obligatoria.
informativos.<code> / variable.<x> / plan.<x> — informativos auxiliares, variables de cálculo y datos del plan previsional.

Las funciones de tabla

TABLA_POR_COLUMNA(tabla, col_busqueda, valor, col_resultado, default) — lookup exacto.
TABLA_POR_RANGO(tabla, col_desde, col_hasta, valor, col_resultado, default) — lookup por rango.

Recordar del capítulo anterior: si la tabla no existe, devuelven el default sin fallar.

Las columnas de texto pasan por CaseInsensitiveStringConverter: TABLA_POR_COLUMNA(..., 'titulo', ...) matchea una fila guardada como Titulo. No es una diferencia que valga la pena unificar.

Ejemplos completos

Asignación de Antigüedad (bienios)

liquidacion.sueldo_base * 0.02 * MIN(15, trabajo.bienios)

2% del sueldo base por cada bienio, tope de 15. Traduce directamente el tope legal.

Bono de Vacaciones (Art. 23 Ley 18.566)

Solo liquida en diciembre. Doble validación: tramo por líquido de noviembre, y verificación de que el bruto de noviembre no supere el tope del tramo.

IF(
  variable.mes_de_calculo = 12,
  LET(
    liquido_nov, PERIODO_ANTERIOR('liquidacion.sueldo_liquido', 1, 0),
    LET(
      tope_bruto_tabla,
      TABLA_POR_RANGO('buk_bono_vacaciones_sector_publico',
        'Sueldo liquido desde', 'Sueldo liquido hasta', liquido_nov, 'Sueldo bruto hasta', 0),
      IF(
        OR(tope_bruto_tabla = -1,
           PERIODO_ANTERIOR('liquidacion.total_haberes', 1, 0) <= tope_bruto_tabla),
        TABLA_POR_RANGO('buk_bono_vacaciones_sector_publico',
          'Sueldo liquido desde', 'Sueldo liquido hasta', liquido_nov, 'Monto', 0),
        0
      )
    )
  ),
  0
)

Asignación de Dirección Superior (Ley 19.863, Alta Dirección Pública)

Solo para estamento autoridad_de_gobierno, estatutos administrativo y municipal. Consulta buk_asignacion_superior_sector_publico (columnas cargo, factor_cargo) con TABLA_POR_COLUMNA.

Administrativo: (sueldo base + asignaciones + modernizacion + previsional) * factor_cargo.
Municipal: (sueldo_base + asignacion_municipal) * factor_cargo.

Gastos de Representación

Derivado de la anterior, solo autoridad_de_gobierno:

IF(trabajo.estamento = 'autoridad_de_gobierno', liquidacion.sueldo_base * 0.3, 0)

Limitaciones de Dentaku que hay que conocer

Las fórmulas anidadas no admiten paréntesis ni comillas. Las funciones que reciben otra fórmula como string (PERIODO_ANTERIOR, OTROS_COMPROBANTES_PERIODO_MULTIFICHA, etc.) solo toleran expresiones simples: trabajo.horas_semanales, informativos.<code>, 1. El extractor ItemEvaluator#nested_dependencies corta en el primer ) y se rompe con la primera comilla. Consecuencia: no se puede condicionar por estatuto dentro de una fórmula anidada.
CASE con condición no existe en Dentaku 3.5. Solo CASE <valor> WHEN <literal> THEN.
Las variables bandera devuelven 0/1, y Dentaku trata 0 como verdadero. Siempre comparar = 1: IF(informacion_academica.acreditacion_carrera_docente = 1, ...). Un IF(flag, ...) a secas siempre entra por la rama verdadera.
La validación de la fórmula (al guardar el Bono) corre por un path distinto (flatted_dependencies) que el cálculo (ast). Una fórmula puede calcular bien y fallar al guardarse, o viceversa. Verificar con flatted_dependencies, no con ast.

Cuando la lógica no cabe en Dentaku, la salida es una función Ruby nueva registrada en el evaluador. Ojo: una función nueva se registra en tres lugares (ItemEvaluator, Bono::FormulasCell::MULTIFICHA_FUNCTIONS, y la doc i18n de la cell); si falta alguno, la función existe pero no aparece en la ayuda de fórmulas del usuario.

Multificha: el tope es de la persona, no del comprobante

Un docente puede tener varias fichas (varios establecimientos). Algunos ítems (BRP — Bonificación de Reconocimiento Profesional) tienen un tope que aplica a la persona, no a cada ficha. La fórmula evalúa cada ficha en aislamiento, así que la suma entre fichas puede pasarse del tope.

Esto no se modela con un guard booleano por ficha. La solución es una función Ruby que devuelve la fracción del tope que le toca a la ficha actual, construida para que las fracciones de todas las fichas sumen a lo más 1 (FRACCION_BRP_SOSTENEDOR()). El detalle completo, con todos los casos que rompieron en producción, está en Items de Remuneracion SP (sección "BRP y multificha docente") — es lectura obligada antes de tocar cualquier ítem multificha.

Antes de diagnosticar un ítem: confirmar cuál corre en ESE tenant

El error más caro del área: razonar sobre el YAML de system_items asumiendo que el tenant lo usa. Los SLEP y municipios suelen arrastrar ítems formulados propios, con atributos personalizados en vez de variables de Buk.

Checklist mínimo en el tenant antes de teorizar:

Bono.find_by(code: '<codigo_de_sistema_esperado>')                          # existe aqui?
LineaLiquidacion.where(liquidacion_id: ID).pluck(:item_code, :nombre, :monto)  # que se pago de verdad
Bono.find_by(code: '<code_real>').formula                                    # la formula que corre

Un cambio de YAML no toca tenants existentes

Buk::SystemItems.create_items! hace next if item.present?: crea, nunca actualiza. Un PR que solo cambia el YAML tiene efecto cero en tenants vivos. El fix real de una fórmula mala es siempre una migración backfill_fix aparte. Al revisar un PR de corrección de fórmula, exigir que el PR de migración exista en draft y esté linkeado.

Relacionado

20 - Modernizacion del Estado y PMG / 21 - Asignaciones y Bonos del Sector Publico / 22 - Nomina y Carrera Docente — cada beneficio explicado desde el negocio.
Items de Remuneracion SP — referencia exhaustiva (multificha, PMG, zona extrema, casos reales).
03 - Parametros Legales y Tablas YAML — de dónde salen las tablas.
06 - Nomina Publica vs Privada — cómo se ensamblan las líneas.
migrar-item-sistema-a-formulado / migrar-concepto-a-item-forzable-chile — skills relacionados.