Common Data Service

CommonDataService es la fachada única para acceder a los parámetros que viven en nostromo_common (el commonPool compartido por todos los tenants): indicadores económicos, tasas previsionales, AFP, AFC, topes, escalas tributarias, vacaciones, regímenes, vida útil de activos, corrección monetaria, giros, etc.

No extiende BaseService porque casi no necesita contexto de tenant — los parámetros son globales. Usa commonPool directamente vía su repository.

Por qué fachada

CommonDataRepository (870 LOC) implementa unas ~50 queries específicas. CommonDataService (429 LOC) es la API estable que el resto del código consume — agrupa por preocupación, agrega lógica de mezcla (e.g. getSocialLawsParameters combina AFP + indicadores + topes en un solo SocialLawsRates), y oculta el detalle del SQL.

Si una tabla nueva entra al commonPool, va al repository; si una composición nueva agrega valor (e.g. “dame todo lo que necesito para liquidar nómina del período X”), va al service.

Mapa de Dominios

flowchart LR
  subgraph S["CommonDataService"]
    IND["Indicadores económicos"]
    LSS["Leyes Sociales"]
    IMP["Impuestos"]
    AFP["AFP / AFC"]
    PAR["Parámetros generales"]
    VAC["Vacaciones"]
    REG["Regímenes y Normativa"]
    LAB["Causales término"]
    CM["Corrección monetaria"]
    VIDA["Vida útil activos"]
    OTR["Otros impuestos / Giros"]
  end
  POOL[("commonPool · nostromo_common")]
  S --> POOL

Lecturas — catálogo principal

Indicadores económicos

Método	Devuelve
getIndicators(periodDate)	{ uf, utm, sueldoMinimo } (paralelo).
getIndicador(periodDate, indicador)	Una fila o null.
getIndicadores(periodDate)	Array completo del período.
getUtm(periodDate)	Solo UTM (atajo común).

Leyes sociales

Método	Devuelve
getSocialLawsParameters(periodDate, afpCode?)	SocialLawsRates — composición de varias fuentes.

Cómo compone getSocialLawsParameters (lógica significativa, no es passthrough):

1. Si llega afpCode: lee tasa y recargo desde getAfpTasa(afpCode, periodDate).
2. Lee indicadoresAll(periodDate) y busca por nombre:
   • SIS → sisRate. Si valor > 1 divide por 100 (los rows históricos guardan a veces %, a veces fracción).
   • EXPECTATIVA_VIDA → socialSecurityRate (Sanna). Misma normalización + cap doble división si rate > 0.2.
   • Cualquier indicador con MUTUAL o ACCID en el nombre → mutualRate. Default 0.0348.
3. Lee getTopes(periodDate). findTope busca exacto y luego parcial (case-insensitive):
   • TOPE AFP o TOPE INP → pensionCap.
   • TOPE AFC → unemploymentCap.
4. Retorna el objeto compuesto; afcWorkerRate y afcEmployerRate quedan en 0 — se resuelven aparte vía getAfcByContract.

Normalización defensiva de tasas

El doble check (valor > 1 divide por 100, después si > 0.2 divide otra vez) cubre rows con formato inconsistente — 0.03 vs 3 vs 300 para “3%”. Es una defensa contra carga histórica sucia, no contra input nuevo.

Impuestos

Método	Devuelve
getTaxBrackets(periodDate, periodo='MENSUAL')	Tramos del impuesto (MENSUAL/ANUAL).
getImpuesto2CatRows(periodDate, periodo?)	Tramos del Impuesto Segunda Categoría.
getPpmScale(year, regimenId, incomeUF=0)	Escala PPM resuelta para el ingreso dado.
getPpmScales(year, regimenId)	Todas las escalas PPM del régimen.

AFP / AFC

Método	Devuelve
getAfpTasas(periodDate, afpCode?)	Array (todas o una AFP específica).
getAfcParameters(periodDate)	Parámetros AFC por contrato.
getAfcByContract(periodDate, contractType, contractStartDate?)	Tasas worker/employer según tipo.

getAfcByContract decisión por contrato:

contractType	Etiqueta resuelta
CASA_PARTICULAR	'Casa Particular'
PLAZO_FIJO	'Plazo Fijo'
INDEFINIDO (default)	'Plazo Indefinido'
INDEFINIDO con contractStartDate y antigüedad ≥ 11 años	'Plazo Indef 11' (tasa diferenciada)
Otro	'Otros'

El cálculo de antigüedad usa (now - start) / (1000 * 60 * 60 * 24 * 365.25).

Parámetros generales

Método	Devuelve
getTopes(periodDate)	Todos los topes del período.
getRentaMinima(periodDate)	Renta mínima por tipo de trabajador.
getAsignacionFamiliar(periodDate)	Tramos de asignación familiar.
getHolidays(from, to)	Feriados en rango.
getMonedaSeries(codigo, toDate)	Serie histórica de una moneda.
getMonedasByPeriod(periodDate, codigoMoneda?)	Conversión $/moneda por período.

Vacaciones, regímenes, normativa

Método	Devuelve
getRegions() / getCommunes(code)	Regiones y comunas (vacaciones).
getTaxRegimes()	Catálogo de regímenes tributarios.
getNormativa(tipoFuente?)	Normativa fiscal.
getNormativaForRegimen(regimenId)	Normativa aplicable a un régimen.

Causales término, corrección, vida útil, otros

Método	Devuelve
getCausal(code) / getAllCausales()	Causales de término de contrato.
getCorreccionMonetaria(year)	Factores de corrección monetaria anual.
getVidaUtilActivos(seccion?, soloActivos=true)	Tabla SII de vida útil de activos fijos.
getOtrosImpuestosCodigos(soloActivos=true)	Códigos SII de otros impuestos.
getGirosComerciales(soloActivos=true)	Catálogo de giros.

Escrituras — upsert/delete

El service también permite mantener el commonPool. Cada bloque sigue el patrón upsertX(data) + deleteX(...):

Recurso	Métodos
AFP tasas	upsertAfpTasa, updateAfpTasa(id, data), deleteAfpTasa(id)
AFC	upsertAfc, deleteAfc(periodo_mes, contrato)
Topes	upsertTope, deleteTope(periodo_mes, tope)
Renta mínima	upsertRentaMinima, deleteRentaMinima(periodo_mes, tipo_trabajador)
Indicadores	upsertIndicador, deleteIndicador(periodo_mes, indicador)
Asignación familiar	upsertAsignacionFamiliar, deleteAsignacionFamiliar(id)
Corrección monetaria	upsertCorreccionMonetaria, deleteCorreccionMonetaria(año, mes_origen, mes_destino)

Los delete lanzan Error con statusCode: 404 adjunto si la fila no existió.

Mutaciones afectan a TODOS los tenants

Estas tablas son del commonPool — lo que escribes acá lo ven todos los tenants en su próxima lectura. Confirma con el operador antes de cambiar topes, AFP, AFC, etc. Por convención solo SUPER_ADMIN puede invocar estos endpoints.

Por qué no extiende BaseService

• Casi todos los datos son globales (commonPool), no tenant-specific. ServiceContext.tenantDb sería irrelevante.
• No hay withTransaction en este service — todas las operaciones son single-statement.
• No emite eventos al DomainEventBus — cambios en parámetros se reflejan en la próxima lectura sin intermediarios.

Si en el futuro se quiere notificar (e.g. “TOPE AFP cambió, invalida cache de leyes sociales”), agregar evento common_data:updated y migrar a BaseService.

Consumidores típicos

Consumidor	Para qué
PayrollEngine (cálculo nómina)	getSocialLawsParameters, getAfcByContract, getTaxBrackets, getIndicadores.
HonorariosService	getIndicador('TASA_RETENCION_HONORARIOS', ...).
DepreciacionService	getVidaUtilActivos, getCorreccionMonetaria.
F29Service	getTaxBrackets, getImpuesto2CatRows, getPpmScale.
VacationsService	getHolidays.
CompanyService (frontend)	getTaxRegimes, getNormativa.
ContractsService	getCausal, getAfcByContract.