# Reglas de cuenta por dimensión, traza y vista previa real (etapa 1)

**Fecha:** 2026-10-13
**Estado:** implementado
**Repos:** `novasispy-backend-api` (principal: `src/contabilidad/`) · `novasispy-erp` (Mapeo de cuentas, catálogo, detalle de asiento)
**Antecedentes:**
- `docs/superpowers/specs/2026-10-13-mapeo-sin-decisiones-internas-design.md` (parte A, implementada): el contador decide todas las cuentas; constancia, recomendaciones, avisos y Conciliación.
- Análisis del plan externo "Modelos de asiento y cuentas de referencia" (CONT-MA): esta etapa toma de ese plan las reglas por dimensión, la traza y la vista previa real, **sin** reemplazar el integrador. Los modelos de asiento editables quedan para una etapa posterior, solo si los contadores los piden.

**Pregunta guía:** ¿el contador puede ver, antes y después, a qué cuenta va cada línea y por qué, sin leer código?

---

## 1. Problema

`cont_mapeo_cuentas` asigna una sola cuenta por concepto para toda la empresa. El contador no puede decir "las ventas en USD van a otra cuenta", "lo que vende la sucursal de Ciudad del Este va a su propia cuenta de ventas" ni "los servicios se registran aparte de las mercaderías". Hoy la única salida es abrir cuentas a mano después.

Además, cuando mira un asiento no puede saber de dónde salió cada cuenta (del mapeo, de la ficha del proveedor, del tipo de gasto, de la cuenta de tesorería o del medio de pago), y no tiene forma de ver qué asiento saldría para un documento real antes de cambiar el mapeo.

## 2. Objetivo y criterios de éxito

1. El contador puede agregar, a cualquier concepto, **excepciones** con condiciones sobre el documento. Primero entran las de cabecera (sucursal, moneda, tipo de tercero, canal) y después las de ítem (categoría de producto, rubro, tipo producto/servicio).
2. **Sin reglas, ningún asiento cambia.** Se verifica con Rehacer asientos → Simular en DOBA local: 0 diferencias.
3. Cada línea de los asientos nuevos guarda **por qué** tiene esa cuenta, y la pantalla lo muestra.
4. Antes de activar una regla, el contador puede ver el asiento que saldría para **un documento real** y el resumen contra los **últimos 50** documentos del concepto. Ninguna de las dos cosas escribe nada.
5. Las reglas siguen la misma regla de la casa que el mapeo: nada se decide en silencio. Una regla con una cuenta inutilizable es **falta de mapeo** con aviso. Cada regla deja constancia de quién la creó, quién la activó y cuándo.

## 3. Modelo de datos

### 3.1 `cont_mapeo_reglas` (nueva)

| Columna | Tipo | Notas |
|---|---|---|
| `id` | uuid PK | |
| `empresa_id` | uuid FK empresas, CASCADE | toda consulta filtra por empresa |
| `concepto` | varchar(50) | uno de los conceptos de `cont_mapeo_cuentas` |
| `orden` | int | se evalúa ascendente; gana la primera regla que cumple |
| `condiciones` | jsonb | ver 3.2; al menos una condición |
| `modo` | varchar(20) | `CUENTA` \| `SUMAR_A_PRINCIPAL` (solo en los conceptos de `CONCEPTOS_CON_MODO`) |
| `cuenta_id` | uuid FK cont_plan_cuentas, RESTRICT, null | CHECK igual que el mapeo: `CUENTA` ⇒ no nulo; `SUMAR` ⇒ nulo |
| `estado` | varchar(10) | `BORRADOR` \| `ACTIVA` \| `RETIRADA` |
| `vigente_desde` | date | fecha contable desde la que aplica |
| `vigente_hasta` | date null | se completa al retirarla |
| `descripcion` | varchar(200) null | nota del contador |
| `creado_por`, `created_at` | uuid FK usuario SET NULL, timestamp | |
| `activado_por`, `activado_at` | uuid FK usuario SET NULL, timestamp null | constancia de la decisión |
| `retirado_por`, `retirado_at` | uuid FK usuario SET NULL, timestamp null | |
| `updated_at` | timestamp | |

Índices: `(empresa_id, concepto, estado, orden)`.

Una regla en `BORRADOR` nunca se aplica en un asiento: solo se usa en la vista previa cuando se tilda "incluir borradores".

Retirar una regla no la borra. Se borra solo si nunca estuvo activa.

### 3.2 Condiciones

```json
[{ "dimension": "MONEDA", "operador": "EN", "valores": ["USD"] },
 { "dimension": "SUCURSAL", "operador": "NO_EN", "valores": ["<uuid>"] }]
```

- Todas las condiciones de una regla tienen que cumplirse (Y). Para expresar una O se crean dos reglas.
- Operadores: `EN` (es uno de) y `NO_EN` (no es ninguno de).
- Dimensiones de la primera versión:

| Dimensión | Nivel | Valores | De dónde sale |
|---|---|---|---|
| `SUCURSAL` | cabecera | `empresas_sucursales.id` | `sucursal_id` del documento. En la factura y NC de venta se toma la sucursal cuyo `punto_establecimiento` = `dest` del documento |
| `MONEDA` | cabecera | código ISO | moneda del documento; en tesorería, la moneda de la cuenta de tesorería |
| `TIPO_PROVEEDOR` | cabecera | `PROVEEDOR_LOCAL` \| `PROVEEDOR_EXTERIOR` \| `ACREEDOR_VARIO` | `proveedores.tipo_entidad` |
| `TIPO_CLIENTE` | cabecera | valores distintos de `clientes.tipo_cliente` en la empresa | `clientes.tipo_cliente` |
| `CANAL` | cabecera (ventas) | `POS` \| `FACTURA` | `POS` si la factura tiene una forma de pago con `sesion_caja_id`; si no, `FACTURA` |
| `CATEGORIA_PRODUCTO` | ítem | `categorias.id` | categoría del producto del ítem. Una regla sobre una categoría cubre también a todas sus subcategorías (`padre_id`) |
| `RUBRO` | ítem | `rubros.id` | rubro de la categoría del producto (o del producto si lo tiene propio) |
| `TIPO_ITEM` | ítem | valores de `productos.tipo` | tipo del producto del ítem |

- Cada documento **publica** solo las dimensiones que tiene. Si una regla usa una dimensión que el documento no tiene, no aplica, y no es un error.
- La tabla de qué dimensiones publica cada `integrar*` vive en código (`DIMENSIONES_POR_ORIGEN`). La usan la pantalla, para avisar al crear una regla que no va a aplicar nunca a ese concepto, y los tests.
- Las dimensiones de ítem solo se publican en factura de venta, NC de venta, factura de compra y NC de compra.

### 3.3 Traza en `cont_asientos_det` (columnas nuevas, null en asientos anteriores)

| Columna | Valores |
|---|---|
| `mapeo_concepto` | concepto con el que se resolvió la línea, o null si la cuenta no salió del mapeo |
| `mapeo_regla_id` | uuid de la regla que aplicó (FK SET NULL), o null |
| `mapeo_nivel` | `REGLA` \| `DEFECTO` \| `FICHA` (cuenta propia del proveedor, tipo de gasto, cuenta de tesorería, categoría de tesorería) \| `MEDIO_PAGO` (configuración del medio de pago) |

## 4. Resolución

`MapeoCuentasService.resolverConcepto(empresaId, concepto, contexto?)`. La firma actual se mantiene y `contexto` es opcional:

```ts
type ContextoMapeo = {
  fecha: Date;                                   // fecha contable del documento
  dimensiones: Partial<Record<Dimension, string | string[]>>;  // valores del documento o del ítem
  incluirBorradores?: boolean;                   // solo vista previa
};
// devuelve además la traza:
{ modo: 'CUENTA'; cuentaId; traza: { concepto; nivel: 'REGLA' | 'DEFECTO'; reglaId?: string } } | { modo: 'SUMAR_A_PRINCIPAL'; traza }
```

1. Reglas `ACTIVA` del concepto (más `BORRADOR` si `incluirBorradores`) con `vigente_desde ≤ fecha` y (`vigente_hasta` null o `> fecha`), ordenadas por `orden`. Gana la primera cuyas condiciones se cumplen todas.
2. Si ninguna cumple, se usa la fila de `cont_mapeo_cuentas`, como hoy.
3. Si no hay fila, `FaltaMapeoError(SIN_MAPEO)`, como hoy.
4. Si la cuenta elegida, sea de la regla o la por defecto, está desactivada o es de agrupación, `FaltaMapeoError(CUENTA_INUTILIZABLE)`. El mensaje nombra la regla si vino de una: `concepto VENTAS_10, regla n.º 2 → 4.1.1.02 está desactivada`.
5. Sin `contexto`, el comportamiento es idéntico al de hoy. Así ningún llamador existente cambia hasta que se le pase el contexto.

Rendimiento: las reglas de la empresa se leen una vez por documento (caché por llamada de `integrar*`), no una vez por línea.

Para la categoría jerárquica se precalcula, una vez por documento, el conjunto de ancestros de cada categoría usada.

## 5. Integrador

### 5.1 Contexto de cabecera

Un helper por familia de documento (`contextoDocumento(origenTipo, documento)`) arma `{ fecha, dimensiones }` una sola vez. Cada `integrar*` lo pasa a todas sus resoluciones de concepto. Las líneas del asiento no cambian de forma.

Las cuentas que salen de fichas o de medios de pago **no** pasan por reglas en esta etapa: se resuelven como hoy y solo se marcan en la traza con `FICHA` o `MEDIO_PAGO`.

### 5.2 Apertura por ítem

Aplica a los conceptos `VENTAS_10`, `VENTAS_5`, `VENTAS_EXENTAS`, `INVENTARIO` e `IMPORTACION_COMPRA`, en factura y NC de venta y en factura y NC de compra. Se activa solo si la empresa tiene al menos una regla `ACTIVA` (o borrador en vista previa) de ese concepto con alguna dimensión de ítem:

1. Se leen los ítems del propio documento (`factura_det`, `nota_credito_det`, `compra_det`, `nota_credito_compra_det`) con producto, categoría, rubro y tipo.
2. Se calcula el neto de cada ítem por tasa de IVA, con la misma base que hoy usa la cabecera.
3. Se resuelve la cuenta de cada ítem con el contexto de cabecera más el del ítem.
4. **Se agrupa por cuenta resultante**: una línea por cuenta y tasa, no una por ítem.
5. La suma por tasa tiene que ser igual al total de esa tasa en la cabecera. La diferencia de redondeo se ajusta en la línea de mayor importe.
6. Si un ítem no tiene producto o categoría, sus dimensiones de ítem quedan vacías: solo aplican las reglas que no las usan, y si no aplica ninguna, va a la cuenta por defecto.

Sin reglas de ítem no se leen los ítems: el asiento y el costo son los de hoy.

### 5.3 Sin cambios

Reversión espejo, períodos, idempotencia, `conAvisoDeMapeo`, avisos, constancia del mapeo, cierre de importación y simulación de Conciliación. Esta última pasa a resolver con reglas porque usa el mismo integrador.

## 6. Pantallas (ERP)

### 6.1 Mapeo de cuentas: excepciones

- Debajo de cada concepto, "Excepciones (n)" desplegable.
- **Lista ordenada:**
  - cada regla se muestra en una frase ("Si moneda es USD y sucursal es Ciudad del Este → 4.1.1.02 Ventas exterior"), con su estado, su vigencia y la constancia (creada por, activada por);
  - se reordena con subir/bajar;
  - acciones: editar, activar, retirar y duplicar; borrar solo si nunca estuvo activa.
- **Diálogo de regla:**
  - filas de condición con dimensión, operador ("es uno de" / "no es ninguno de") y valores;
  - los valores se eligen de una lista con buscador; la categoría, de un árbol;
  - cuenta, o modo sumar si el concepto lo admite;
  - vigencia desde y nota.
  - Si la dimensión no la publica ningún documento que use ese concepto, avisa "esta condición no va a aplicar nunca a este concepto".
  - Se guarda como borrador. "Activar" pide confirmación y deja constancia.
- **Probador "¿qué cuenta usaría?":** se eligen valores de las dimensiones y muestra la cuenta con su traza: regla n.º X, por defecto o falta de mapeo.
- Kit estándar de `_standards`, selects con buscador y sin colores fijos (`docs/ui-standards.md`).

### 6.2 Vista previa con un documento real

En Mapeo hay un botón "Probar con un documento" que funciona así:

1. Se elige el tipo de documento y se busca uno por número.
2. La pantalla muestra lado a lado el **asiento vigente** y el **asiento que saldría hoy**, con el mapeo guardado y las reglas activas (más los borradores si se tilda "incluir borradores").
3. Cada línea muestra su traza y las diferencias quedan resaltadas.
4. "Probar contra los últimos 50" del concepto devuelve un resumen (iguales / cambian de cuenta / no se podrían asentar) y el detalle por documento.

Backend:
- `POST contabilidad/mapeo-cuentas/vista-previa` `{ origenTipo, origenId, incluirBorradores }`
- `POST contabilidad/mapeo-cuentas/probar` `{ concepto, ultimos: 50, incluirBorradores }`

Los dos reutilizan la simulación sin escritura de Rehacer asientos (`integrador-sombra.ts`). Tiempo objetivo: menos de 5 segundos para 50 documentos.

### 6.3 Catálogo de asientos

En las líneas cuyo concepto tiene reglas activas, muestra la cuenta por defecto y "+ n excepciones". Al pasar el mouse aparece la lista en frases.

### 6.4 Detalle de asiento

Cada línea tiene "¿Por qué esta cuenta?", que muestra el concepto, el nivel, la regla (con su frase y quién la activó) y los valores del documento con que coincidió. Los asientos anteriores dicen "Anterior a la traza".

### 6.5 Permisos

Se reutilizan los del mapeo: `CONTABILIDAD`/`CONT_MAP_MAPEO_EDITAR` para crear, editar, activar y retirar reglas, y `CONT_MAP_MAPEO_VER` para ver, el probador, la vista previa y "probar contra 50". No se crean permisos nuevos.

## 7. Avisos, Conciliación y Salud contable

- Una regla activa que apunta a una cuenta inutilizable produce, al asentar, `FaltaMapeoError(CUENTA_INUTILIZABLE)`, con aviso al contador y a quien cargó el documento, y aparece en Conciliación con la causa de siempre. El texto nombra la regla.
- Salud contable suma al control "mapeo pendiente" las **reglas activas con cuenta inutilizable**, como ERROR, con la ruta a Mapeo.
- `mapeo_sin_confirmar` no cambia. Las reglas no tienen precarga: toda regla activa la activó un usuario.

## 8. Auditoría

`audit_logs` registra estas acciones:

| Acción | Cuándo |
|---|---|
| `CONT_REGLA_CREAR` | al crear una regla |
| `CONT_REGLA_EDITAR` | al editarla |
| `CONT_REGLA_ACTIVAR` | al activarla |
| `CONT_REGLA_RETIRAR` | al retirarla |
| `CONT_REGLA_ORDEN` | al reordenar |

Todas usan `entity_type` = `cont_mapeo_reglas` y guardan en `old_value`/`new_value` la regla completa (concepto, condiciones, cuenta y código, modo, orden y vigencia).

## 9. Pruebas

- **Resolución:**
  - primera regla que cumple;
  - orden;
  - vigencia por fecha contable, incluidos los bordes;
  - borrador ignorado salvo en la vista previa;
  - dimensión ausente → no aplica;
  - categoría padre cubre hija;
  - cuenta inutilizable en regla → `CUENTA_INUTILIZABLE` con la regla en el mensaje;
  - sin `contexto` → idéntico a hoy;
  - modo sumar en regla.
- **Integrador, por documento:**
  - sin reglas, el asiento sale idéntico;
  - una regla de cabecera cambia solo la cuenta de ese concepto;
  - regla de ítem:
    - la venta o compra se abre por cuenta y tasa;
    - los totales por tasa se conservan;
    - el redondeo se ajusta en la línea mayor;
    - un ítem sin categoría va a la cuenta por defecto;
  - la traza queda grabada en cada línea (`REGLA` / `DEFECTO` / `FICHA` / `MEDIO_PAGO`);
  - la NC se abre con sus propios ítems (`nota_credito_det` / `nota_credito_compra_det`, que tienen producto) y con las reglas vigentes a la fecha de la NC.
- **Vista previa y probar:**
  - no escriben;
  - con borradores incluidos aplican el borrador;
  - el documento de otra empresa da 404.
- **DOBA local:**
  - sin reglas, Rehacer asientos → Simular da 0 diferencias;
  - con una regla de prueba (ventas en USD a otra cuenta y una regla por categoría), solo cambian los documentos esperados.
  - Recorrido con Playwright: crear una regla, probarla con un documento, activarla y ver "¿Por qué esta cuenta?".

## 10. Fuera de alcance

- Modelos de asiento editables y eventos contables (etapa 3 del análisis CONT-MA).
- Reglas sobre cuentas de fichas o de medios de pago (proveedor, tipo de gasto, tesorería, medio de pago): siguen como hoy y solo se marcan en la traza.
- Gastos por categoría de producto: el gasto ya se abre por tipo de gasto.
- Recontabilizar al activar una regla: para eso está Rehacer asientos.
- Dimensiones nuevas (centro de costo como condición, proyecto inmobiliario, vendedor): se suman a `DIMENSIONES_POR_ORIGEN` si se piden.
- Limpieza de conceptos sin uso (`BANCO_PYG`, `COSTO_VENTAS`) y unificación de los `reintentar-contabilidad` en Conciliación (etapa 2).

## 11. Despliegue

1. Migración: tabla `cont_mapeo_reglas` y las tres columnas de traza. No hay precarga.
2. Backend y frontend.
3. Re-ingesta de NovaIA. Las guías de Mapeo y Conciliación y el catálogo de ayuda (`seed-catalogo.ts`) se actualizan en el mismo trabajo.

Sin reglas creadas, nada cambia en los asientos.

---

## 12. Ajustes durante la implementación

Lo que quedó distinto de lo escrito arriba, con la razón. Manda esta sección.

1. **«Probar contra los últimos N» es por tipo de documento**, no por concepto (§6.2): la simulación es por origen (`integrador-sombra.ts`). El usuario elige el tipo de documento; al abrirlo desde un concepto, los tipos que lo usan van primero. Endpoint: `POST contabilidad/mapeo-cuentas/probar` con `{ origenTipo, ultimos, incluirBorradores }`.
2. **Una regla ACTIVA no se edita** (400): se retira y se duplica (§6.1 decía «editar, activar, retirar y duplicar»). Así los asientos de su vigencia se pueden rehacer igual. Solo el borrador se edita; solo el borrador que nunca se activó se borra.
3. **Los borradores no miran vigencia en vista previa y probar** con `incluirBorradores`: si no, probar una regla nueva sobre documentos viejos daba siempre «igual». En asientos reales un borrador nunca aplica.
4. **La traza es por línea, no por cuenta**: cada línea lleva su concepto, regla y nivel (en DOBA varios conceptos comparten cuenta y la traza por cuenta salía no determinista). Cuando la cuenta se congeló o viene escrita en la ficha/detalle, el nivel es `FICHA`, no null.
5. **La cuenta de la CxP se congela con el contexto del documento** (sucursal, moneda, tipo de proveedor y fecha): el pago debita la misma cuenta que acreditó el documento aunque las reglas cambien después. Compra y gasto **no** acreditan la cuenta congelada (en DOBA rompía gastos con CxP congeladas con el plan viejo). Pendiente: si una regla se edita entre la confirmación y la integración, CxP y asiento pueden divergir; realinear al rehacer asientos.
6. **«¿Por qué esta cuenta?» muestra la frase de la regla** (condición, estado, quién la activó), no los valores del documento con que coincidió (§6.4): esos valores no se guardan en la línea; guardarlos pide otra columna.
7. **SUCURSAL de la NC de compra se deriva de su compra** (`compra_cab.sucursal_id`); la NC no la tiene. Sin compra, no la publica.
8. **CANAL no aplica a la NC de venta**: no tiene formas de pago. Solo la factura de venta publica CANAL.
9. **Los pagos a proveedor no publican SUCURSAL** (no tienen). Tampoco tesorería, Bancard, RRHH ni comisiones, que publican solo MONEDA.
10. **Bancard (cuenta por liquidar) → nivel `MEDIO_PAGO`; RRHH publica solo MONEDA**: sin reglas por sucursal en RRHH por ahora.
11. **Vista previa, probar y buscador de documentos viven en un controlador nuevo de Conciliación**, con la misma ruta base `contabilidad/mapeo-cuentas` (evita un ciclo de módulos). Sin cambio para el frontend ni para los permisos.
12. **Estado `SOBRA` en la vista previa**: el documento tiene asiento vigente pero hoy no se generaría ninguno (p. ej. anulado sin reversión). Se suma a IGUAL / CAMBIA / ERROR, por coherencia con Rehacer asientos.
13. **Auditoría `CONT_REGLA_BORRAR`** además de las acciones del §8, para dejar rastro del borrado de un borrador.
14. **Reordenar se permite también con reglas ACTIVAS/RETIRADAS** (queda auditado `CONT_REGLA_ORDEN`); la pantalla avisa que puede cambiar qué regla gana al rehacer períodos anteriores.
15. **Vigencia en UTC**: se compara la fecha del documento como `toISOString` (UTC), el mismo criterio con que los integradores graban la fecha del asiento. Retirar fija `vigente_hasta` (exclusivo); una retirada aplica a documentos con fecha dentro de su vigencia.
16. **Apertura por categoría**: la línea mayor toma `total − suma de las otras` (cierra los totales por tasa sin acumular redondeo); las compras se abren por cuenta, no por cuenta y tasa. Una regla de ítem retirada vigente a la fecha del documento también abre el asiento al rehacerlo.
17. **El buscador de documentos no muestra total** (el endpoint no trae la moneda del documento; el estándar exige `fmtMoneda` con su moneda).
18. **Sin reglas ni documentos de prueba, DOBA queda como estaba**; los resultados de la verificación final están en `.superpowers/sdd/2026-10-13-reglas-cuenta-por-dimension/task-10-report.md`.
19. **Una regla rota frena y avisa aunque el defecto sirva** (revisión final): `FaltaMapeoError` lleva la regla (`regla: { id, orden }`) cuando la cuenta inutilizable vino de una regla; la constancia `CONT_FALTA_MAPEO` guarda `motivo` y `regla` (`{ id, orden, concepto }`). Las alertas y la causa de Conciliación no dan por resuelto un concepto con una regla **ACTIVA** de cuenta que no sirve, ni uno cuya constancia nombra una regla todavía rota y vigente para su período (retirada con `vigente_hasta > vigente_desde`). Los textos dicen «la regla n.º X de {concepto} apunta a una cuenta que no sirve» y el diagnóstico de Conciliación da `CUENTA_OLD` con «retirala y duplicala con otra cuenta». Los asientos que juntan varias faltas en un solo error (recibo multi, RRHH, varios conceptos en tesorería) no llevan la regla en la constancia: el aviso la toma de las reglas activas rotas del concepto.
20. **Datos de ítem solo en conceptos que se abren por ítem**: `CONCEPTOS_CON_APERTURA_ITEM` (`VENTAS_10`, `VENTAS_5`, `VENTAS_EXENTAS`, `INM_VENTAS_5`, `INM_VENTAS_EXENTAS`, `INVENTARIO`, `IMPORTACION_COMPRA`) en `reglas-mapeo.ts`. Crear, editar o activar una regla con categoría, rubro o tipo de ítem en otro concepto da 400; el probador las ignora y devuelve `advertencia`; la apertura también lo exige; `GET mapeo-reglas/dimensiones` expone `conceptosConItem` y el diálogo no las ofrece en los demás conceptos.
21. **Retirar con fecha elegida**: `POST mapeo-reglas/:id/retirar` acepta `{ vigenteHasta? }` (por defecto hoy; no anterior a `vigente_desde`; igual = «nunca aplicó») y devuelve `asientos_desde_fin`: cuántos asientos (no revertidos) con líneas de esa regla tienen fecha ≥ fin. La lista muestra «sin vigencia (nunca aplicó)» cuando desde ≥ hasta.
22. **Aviso de pasivo**: en reglas sobre `PROVEEDORES`, `PROVEEDORES_EXTERIOR` y `ACREEDORES_VARIOS`, el diálogo y la confirmación de Activar avisan que las CxP ya generadas conservan su cuenta congelada (ver 5). La confirmación de Activar también dice que, con vigencia desde hoy, rehacer documentos anteriores no aplica la regla.
23. **Índice parcial** `idx_cont_asientos_det_mapeo_regla` (migración `20261021000000_mapeo_reglas_indice`), solo en SQL: Prisma no declara índices parciales.

