# Mapeo contable sin decisiones internas — diseño (parte A)

Fecha: 2026-10-13. Origen: DOBA S.A. (contador pidió cambiar el asiento del cierre de despacho;
en producción `Importaciones en curso` quedó con saldo acreedor de −507.271.894).

## Objetivo

Ningún asiento automático decide una cuenta por su cuenta. Cada destino contable es un
concepto que el contador mapea; el sistema **recomienda**, **avisa** a quien corresponde
cuando falta o no está confirmado, y **deja constancia** de quién decidió qué y cuándo.
Así la responsabilidad de la elección queda del lado de la empresa.

Todo lo de este documento aplica **solo a empresas con el módulo Contabilidad activo**
(`tieneModuloContabilidad`). Sin el módulo no hay asientos, avisos ni pendientes.

Criterios de éxito:

1. No queda en `integracion.service.ts` ninguna cuenta elegida por respaldo silencioso.
2. El catálogo de asientos (pantalla de Mapeo) muestra exactamente lo que el integrador
   generaría con el mapeo en pantalla, incluida la forma del asiento.
3. Si falta un mapeo, la operación del usuario no se bloquea: se guarda, queda pendiente
   con causa `FALTA_MAPEO`, el usuario ve el aviso y el contador recibe la alerta.
4. Todo mapeo tiene constancia: origen, recomendación vigente, quién confirmó y cuándo.
5. El día del despliegue ningún asiento cambia de cuenta (precarga con lo que hace hoy el código).

Fuera de alcance:

- **Parte B** (spec aparte): cuenta por ítem / categoría de producto en compras. Mientras
  tanto la línea de compra sigue saliendo de `INVENTARIO`, que es un concepto visible.
- Regularizar IMP-2026-000001 de DOBA en producción: lo hace el contador con un asiento de
  reclasificación (podemos preparar el detalle de cuentas aparte).

## Decisiones tomadas con el usuario

| Pregunta | Decisión |
|---|---|
| ¿Qué pasa si un concepto no está mapeado? | El asiento **no** se genera; el documento queda pendiente con la recomendación visible. Nunca se cae a otra cuenta. |
| ¿Cómo no frenar a quien ya opera? | Precarga al desplegar con la cuenta que el código usa hoy, marcada "sin confirmar". |
| ¿Se bloquea al usuario que carga el documento? | **No.** Se guarda y se le avisa que no se contabilizó y que ya se avisó al contador. |
| ¿Cuenta por ítem en compras? | Parte B, proyecto aparte. |
| Representación | Un concepto de `cont_mapeo_cuentas` por destino (no motor de reglas, no alias). |

## 1. Conceptos

### Nuevos

| Concepto | Reemplaza | Recomendación | Precarga |
|---|---|---|---|
| `IMPORTACION_COMPRA` | Compra imputada a una importación → `INVENTARIO` fijo | `IMPORTACIONES_EN_CURSO` | cuenta de `INVENTARIO` |
| `IMPORTACION_GASTO` | Gasto imputado a una importación → cuenta del tipo de gasto | `IMPORTACIONES_EN_CURSO` | modo `SUMAR_A_PRINCIPAL` (= cuenta del tipo de gasto) |
| `IMPORTACION_PAGO_PROVEEDOR` | Egreso de tesorería tipo PROVEEDOR imputado a importación → puente fija | `IMPORTACIONES_EN_CURSO` | cuenta de `IMPORTACIONES_EN_CURSO` (si está mapeada) |
| `IMPORTACION_TRIBUTOS` | Tributos/gastos del despacho → puente fija (o `INVENTARIO` sin puente) | `IMPORTACIONES_EN_CURSO` | la que usa hoy: puente si está mapeada, si no `INVENTARIO` |
| `IVA_NO_DEDUCIBLE` | Gasto no deducible: IVA sumado a la cuenta del gasto | modo `SUMAR_A_PRINCIPAL` | modo `SUMAR_A_PRINCIPAL` |
| `IMPORTACION_ANTICIPO_IRE` | IRE del despacho → `RETENCION_RENTA_FAVOR` o, sin mapear, a la cuenta de costo | la cuenta de `RETENCION_RENTA_FAVOR` | la de `RETENCION_RENTA_FAVOR` si está mapeada; si no, la de `IMPORTACION_TRIBUTOS` |

`IMPORTACION_ANTICIPO_IRE` es propio del despacho para no tocar `RETENCION_RENTA_FAVOR`, que
también usan los recibos (retenciones de renta que nos hacen los clientes).

`IMPORTACIONES_EN_CURSO` sigue siendo el interruptor del modelo de cuenta puente (habilita el
asiento de cierre de importación). Los cuatro `IMPORTACION_*` deciden **a dónde** va cada costo.

### Respaldos que desaparecen

Pasan a ser obligatorios cuando el documento los necesita. Si no están mapeados, la precarga
les pone la cuenta a la que hoy caen:

| Concepto | Hoy, sin mapear, cae a | Precarga |
|---|---|---|
| `CHEQUES_EN_CARTERA` | Caja (cuenta por defecto del medio) | cuenta de `CAJA_GENERAL` |
| `CHEQUES_EN_TRANSITO` | `CHEQUES_EN_CARTERA` → Caja | la de `CHEQUES_EN_CARTERA`, si no `CAJA_GENERAL` |
| `CHEQUES_A_PAGAR` | Cuenta de tesorería del pago → Caja | no se precarga: la cuenta variaba por documento; el dry-run informa las OP con cheque ya asentadas |
| `PAGO_COMISIONES_FONDOS` | `CAJA_GENERAL` | cuenta de `CAJA_GENERAL` |
| `PROVEEDORES_EXTERIOR` | `PROVEEDORES` | cuenta de `PROVEEDORES` |
| `ACREEDORES_VARIOS` | `PROVEEDORES` | cuenta de `PROVEEDORES` |
| `ANTICIPO_DESPACHO` (despacho con anticipo y puente) | Cuenta del proveedor del embarque | no se precarga: hoy solo se usa si está mapeado |

`CHEQUES_A_PAGAR`: el orden de hoy no cambia (manda el concepto). Lo único que se elimina es la
caída a la cuenta de tesorería del detalle o a Caja cuando el concepto no está mapeado. Como esa
caída no se reproduce con una sola cuenta, no se precarga: lo mapea el contador (el dry-run de la
precarga cuenta, por empresa, las órdenes de pago con cheque ya asentadas que quedarían pendientes
si se rehacen).

### Líneas opcionales que hoy abortan el asiento en silencio

En el recibo con varios medios (`RETENCION_IVA_FAVOR`, `RETENCION_RENTA_FAVOR`,
`ANTICIPOS_CLIENTES`, `PROVEEDORES`, `CONSUMO_FUNCIONARIO_PUENTE`, `SUELDOS_JORNALES`,
`INTERESES_MORATORIOS_COBRADOS`) y en la liquidación de sueldos (`APORTE_PATRONAL_IPS`,
`APORTE_ADMIN_IPS`, `IPS_A_DEPOSITAR`, `DESCUENTOS_VARIOS_RRHH`), si la línea hace falta y el
concepto no está mapeado, hoy se omite y el asiento queda descuadrado y se descarta con un log.
Pasan a `FALTA_MAPEO` con el concepto concreto, igual que el resto. No se precargan: hoy
tampoco generan asiento, así que no hay comportamiento que conservar.

### Respaldos fuera del integrador

Mismo criterio en los servicios que eligen cuenta por su cuenta antes de llegar al integrador:

| Dónde | Hoy | Precarga |
|---|---|---|
| Rendición de viáticos (`rendicion-viaticos-contabilidad.service.ts`) | `ANTICIPO_VIATICO` → `ANTICIPO_PERSONAL` | `ANTICIPO_VIATICO` ← cuenta de `ANTICIPO_PERSONAL` |
| Viáticos, salida de fondos del adelanto | `BANCO` (si falta, el asiento se omite: el `??` hacia `CAJA_GENERAL` nunca corre) | `BANCO` no se precarga (sin `BANCO` los viáticos no se asentaban); lo mapea el contador |
| Anticipo a empleado (`anticipos.service.ts`) | `DESCUENTOS_VARIOS_RRHH` → `ANTICIPO_PERSONAL` → cuenta de la categoría | `DESCUENTOS_VARIOS_RRHH` ← `ANTICIPO_PERSONAL`, si no la cuenta de la categoría "Anticipo" |
| Acreditación de sueldos (`acreditaciones-bancarias.service.ts`) | `SUELDOS_A_PAGAR` → cuenta de la categoría | `SUELDOS_A_PAGAR` ← cuenta de la categoría "Pago de Sueldos" |
| Pago de IPS (`reportes-ips.service.ts`) | `IPS_A_DEPOSITAR` → cuenta de la categoría | `IPS_A_DEPOSITAR` ← cuenta de la categoría del pago de IPS |
| Finiquito (`desvinculaciones.service.ts`) | componente sin concepto mapeado → cuenta de la categoría "Pago de Finiquito" (no se omitía) | cada componente sin concepto se precarga con la cuenta de la categoría "Pago de Finiquito"; `SUELDOS_JORNALES` no se precarga |

Estos servicios crean un movimiento de tesorería y le ponen la cuenta ya resuelta. Pasan a guardar
el **concepto** en el detalle (`tes_movimiento_det.concepto_contable`, nuevo) y el integrador de
tesorería lo resuelve al asentar: así un movimiento pendiente por falta de mapeo se regenera
bien después de mapear. Orden en `integrarMovimientoTesoreria`: cuenta de importación →
`det.cuenta_contable_id` → `det.concepto_contable` (obligatorio, sin respaldo) → categoría.

### Casos que no son decisión interna (sin cambios)

- Cuenta del proveedor: la propia del proveedor o la de su tipo. Ya es configuración del contador.
- Despacho **sin** anticipo pagado: la contrapartida es la cuenta del proveedor del embarque.
- Medios de pago y tesorería: cuenta de tesorería / regla / medio ya son configuración de la empresa.

## 2. Modelo de datos

`cont_mapeo_cuentas` suma:

| Columna | Tipo | Uso |
|---|---|---|
| `modo` | `VARCHAR(20)` default `'CUENTA'` | `CUENTA` o `SUMAR_A_PRINCIPAL` (solo `IMPORTACION_GASTO`, `IVA_NO_DEDUCIBLE`) |
| `cuenta_id` | pasa a **nullable** | null solo con `modo = SUMAR_A_PRINCIPAL` (CHECK) |
| `origen` | `VARCHAR(20)` | `PRECARGA` (sistema) o `CONTADOR` (elegido por un usuario) |
| `cuenta_recomendada_codigo` | `VARCHAR` nullable | lo que recomendábamos al momento de la elección |
| `confirmado_por` | uuid nullable → `usuario` | quién confirmó / eligió |
| `confirmado_at` | timestamp nullable | cuándo |

Las recomendaciones viven en código, junto al catálogo (`recomendaciones-mapeo.ts`): por concepto,
un **concepto de referencia** (p. ej. `IMPORTACION_COMPRA` → "la cuenta de
`IMPORTACIONES_EN_CURSO`") o un modo. Se resuelve contra el mapeo de cada empresa para mostrar la
cuenta concreta.

Constancia: cada alta/cambio/confirmación escribe `audit_logs`
(`entity_type = 'cont_mapeo_cuentas'`, `old_value`/`new_value` con cuenta, modo y recomendación).

`getCuentaPorConcepto` no cambia de contrato para los conceptos `CUENTA`; se agrega
`resolverConcepto(empresa, concepto)` → `{ modo, cuentaId }` para los dos conceptos con modo.

## 3. Integrador (`integracion.service.ts`)

- Nueva excepción interna `FaltaMapeoError(conceptos[])`. Toda obtención de cuenta pasa por el
  mapeo; se eliminan los `.catch(() => null)` que elegían otra cuenta y el respaldo duro de
  `resolverCuentaPasivo` (paso 3).
- Al capturar `FaltaMapeoError` en cada `integrar*`: el documento queda pendiente
  (`cont_documentos` BORRADOR o sin documento, según el flujo actual) con la causa
  `FALTA_MAPEO` + conceptos, se registra el intento (mismo registro que hoy lee
  `causa-pendiente.ts`) y se llama a `avisarFaltaMapeo` (sección 5). Nunca se relanza al
  flujo operativo: la operación del usuario no falla.
- **Compra/gasto imputado a importación**: se detecta por `imp_componentes_costo.compra_id` /
  `gasto_id` activo. La línea de costo (neto) va a `IMPORTACION_COMPRA` / `IMPORTACION_GASTO`
  (con `SUMAR_A_PRINCIPAL` el gasto conserva la cuenta de su tipo). El IVA no cambia.
- **Egreso imputado a importación tipo PROVEEDOR** → `IMPORTACION_PAGO_PROVEEDOR`.
  Tipo DESPACHO → `ANTICIPO_DESPACHO` (sin cambios).
- **Despacho**: el debe de costo va a `IMPORTACION_TRIBUTOS` (con o sin puente). El IRE va a
  `IMPORTACION_ANTICIPO_IRE` (obligatorio si hay IRE). La aplicación del anticipo sigue igual.
- **Recibo multi y liquidación de sueldos**: una línea necesaria sin concepto mapeado lanza
  `FaltaMapeoError` en vez de omitirse.
- **Gasto no deducible**: el IVA va a `IVA_NO_DEDUCIBLE` o se suma al gasto según el modo.

## 4. Cierre de importación

- Monto: **lo que efectivamente entró a la cuenta puente por esa importación**, sumando los
  débitos a la cuenta mapeada en `IMPORTACIONES_EN_CURSO` en los asientos confirmados de sus
  documentos: despacho (`imp_despacho`), compras y gastos de sus componentes, egresos de tesorería
  con `embarque_id`; menos los créditos a la puente de esos mismos documentos (reversiones).
- Debe `INVENTARIO` / Haber `IMPORTACIONES_EN_CURSO` por ese monto. Si da 0 no hay asiento.
- Si difiere del costo sin IVA del embarque (`costo_total_gs`) en más de Gs. 1, el cierre sale
  igual y Salud contable lo informa (sección 6).
- Se registra `imp_cierre` en `registry.seed.ts` para que aparezca en "Sin asiento" y en
  "Rehacer asientos".

**Advertencia de doble ingreso (no se decide, se avisa):** si `IMPORTACION_COMPRA` y
`IMPORTACION_PAGO_PROVEEDOR` apuntan a la misma cuenta, la pantalla de Mapeo explica los dos
esquemas válidos (DOBA: pago a la puente y factura fuera de ella; clásico: factura a la puente
contra el proveedor del exterior y el pago cancela al proveedor). La elección queda en la constancia.

## 5. Avisos

Todos vía `AlertasEmpresaService.registrar` (bandeja única, deduplicada por clave, módulo
`CONTABILIDAD`, privilegio de Mapeo de cuentas), solo con Contabilidad activa:

| Clave | Criticidad | Cuándo | Se resuelve sola |
|---|---|---|---|
| `contabilidad.falta_mapeo` | alta | algún documento quedó pendiente por `FALTA_MAPEO` | cuando no quedan conceptos faltantes |
| `contabilidad.mapeo_sin_confirmar` | media | hay mapeos con `confirmado_at` null | cuando todos están confirmados |
| `contabilidad.falta_mapeo.usuario.<id>` | media | al usuario que cargó un documento que quedó pendiente | junto con la del contador |

`datos` lleva conceptos, recomendación y cantidad de documentos frenados; `ruta` a Mapeo.

**Usuario que carga el documento**: casi todas las operaciones contabilizan en segundo plano,
después de responder (`integrar*(...).catch(...)`), así que el aviso no puede ir en la respuesta.
Va como **alerta personal** en la misma bandeja: `ai_alertas` suma `usuario_destino_id`
(nullable); con valor, solo la ve ese usuario y no se le exige el privilegio de Mapeo. Texto:
"Tu {documento} se guardó, pero no se contabilizó: falta que el contador mapee «…». Ya se le
avisó." Sale con popup como el resto de la bandeja. El usuario es el `usuario_id` del documento;
si el documento no lo guarda, solo se avisa al contador.

## 6. Conciliación

- `causa-pendiente.ts`: nueva causa `FALTA_MAPEO` (prioridad sobre `INTENTO_FALLIDO`), con
  conceptos y recomendación; en "Sin asiento" el botón lleva a Mapeo y, mapeado, se regenera ahí.
- Salud contable:
  - El control de saldo acreedor en activo suma las cuentas mapeadas en
    `IMPORTACIONES_EN_CURSO` y `ANTICIPO_DESPACHO` (hoy solo prefijos 1.01.01 / 1.01.03).
  - Nuevo: importación cerrada con diferencia entre lo trasladado y su costo.
  - Nuevo: conceptos sin mapear con documentos frenados / mapeos sin confirmar.

## 7. Pantalla de Mapeo y catálogo

- Cada concepto muestra estado: **sin mapear** / **sin confirmar (precarga)** / **confirmado** /
  **distinto de lo recomendado**, con la recomendación resuelta a cuenta concreta y
  "Usar recomendación". Botón **Confirmar todo** (registra quién y cuándo).
- Selector de modo para `IMPORTACION_GASTO` e `IVA_NO_DEDUCIBLE`.
- Advertencia de doble ingreso de la sección 4.
- Catálogo: lo ya hecho hoy (formas por mapeo, `soloSiMapeado`, cuenta por tipo de proveedor) se
  mantiene. Los `respaldo`/`respaldoDinamico` agregados hoy **se reemplazan** por la recomendación:
  una línea sin mapear se muestra como "Falta mapear — recomendado: X", porque ya no hay respaldo.
  Se agregan los conceptos nuevos a las situaciones (compra/gasto de importación, IVA no deducible).

## 8. Migración y precarga

1. Migración de esquema: columnas de la sección 2 (`cuenta_id` nullable + CHECK),
   `ai_alertas.usuario_destino_id` y `tes_movimiento_det.concepto_contable`.
2. Todos los mapeos existentes: `origen = 'PRECARGA'`, `confirmado_at = null` (muchos los cargó
   soporte, no el contador).
3. Script idempotente de precarga (patrón one-shot con PrismaClient) para cada empresa con
   Contabilidad: inserta los conceptos de la sección 1 que falten, con la cuenta de la columna
   "Precarga" y `origen = 'PRECARGA'`. Si la cuenta de referencia no existe, no inserta (queda
   "sin mapear" y genera la alerta al primer documento).
4. Seed de empresas nuevas (`MAPEO_DEFAULT`): `origen = 'PRECARGA'` + conceptos nuevos.
5. Guías de NovaIA (`docs/guias`), `seed-catalogo` del backend y re-ingesta.

## 9. Tests

- Por cada respaldo eliminado: sin mapear → sin asiento, causa `FALTA_MAPEO`, alerta registrada,
  la operación no falla.
- Compra y gasto imputados a importación van a su concepto; gasto con `SUMAR_A_PRINCIPAL` igual que hoy.
- Cierre: traslada solo lo que entró a la puente; compra mapeada a Mercaderías no se duplica;
  diferencia contra el costo informada.
- Precarga idempotente y sin cambio de asiento (mismo resultado antes/después para un documento de cada tipo).
- Confirmación y constancia en `audit_logs`.
- Catálogo: forma por mapeo y "falta mapear — recomendado".
- E2E de importaciones fase 2 actualizado.

## Ajustes durante la implementación

- Las transferencias bancarias sin asiento se reintentan desde Tesorería y Bancos → Transferencias con "Reintentar contabilización"; no entran a la lista "Sin asiento" de Conciliación.
- `DIFERENCIA_CAMBIO_*` es obligatorio en transferencias entre cuentas de distinta moneda (sin respaldo).
- `conceptos_req` de `imp_cierre` = `['INVENTARIO']`.
- Nueva causa de Conciliación `SIN_SALDO_PUENTE`: el cierre de importación no encuentra saldo en la cuenta puente.
- La recomendación de `IMPORTACION_PAGO_PROVEEDOR` es `PROVEEDORES_EXTERIOR` (esquema clásico).
- Seed de empresas nuevas (`MAPEO_DEFAULT`): `IMPORTACION_PAGO_PROVEEDOR` va a Proveedores del Exterior
  (2.1.1.06), alineado con la recomendación; con la puente en compra y pago a la vez el costo entraba dos veces.
- `CHEQUES_A_PAGAR` no se precarga (no reproducible con una sola cuenta); el dry-run lo informa como no reproducible.
- Criterio único de "mapeo usable" (`mapeo-usable.ts`): suma a la principal o cuenta activa que acepta
  movimientos. Lo usan la alerta del contador y Conciliación; un mapeo a una cuenta desactivada o de
  agrupación no cierra la alerta.
- La alerta del contador cuenta solo documentos vigentes: los que pasan el `filtro_extra` del registro de
  orígenes (el mismo de "Sin asiento"; excluye anulados). El conteo se hace en SQL y por lotes acotados.
- La cuenta puente es un interruptor de tres estados: sin mapeo = no se usa; mapeada a una cuenta que no
  sirve = el despacho/cierre queda pendiente con aviso (antes se trataba como "sin puente").
- La nota de crédito de una compra cargada a una importación revierte contra `IMPORTACION_COMPRA` (la misma
  cuenta que la compra), no contra `INVENTARIO`.
- "Confirmar todo" guarda en la constancia la lista confirmada (concepto, cuenta, modo, recomendado) y la
  recomendación vigente en cada fila.
