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

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Que el contador pueda agregar excepciones a cualquier concepto del mapeo (por sucursal, moneda, tipo de tercero, canal y, por ítem, categoría/rubro/tipo de producto), ver por qué cada línea de un asiento tiene su cuenta y probar el asiento de un documento real antes de activar una regla — sin que cambie ningún asiento mientras no haya reglas.

**Architecture:** Una tabla `cont_mapeo_reglas` con condiciones JSON evaluadas por funciones puras (`reglas-mapeo.ts`). `MapeoCuentasService.resolverConcepto` gana un `contexto` opcional y devuelve la traza; el integrador arma un **resolvedor por documento** (`crearResolvedor`) que lee las reglas una sola vez y anota la traza en cada línea, que `crearConfirmado` graba en tres columnas nuevas de `cont_asientos_det`. La vista previa y "probar contra 50" reutilizan la simulación sin escritura de `RecontabilizacionService`.

**Tech Stack:** NestJS + Prisma + PostgreSQL (`/var/www/html/proyectos/novasispy-backend-api`), React + styled-components + TanStack Query (`/var/www/html/proyectos/novasispy-erp`), Jest, Playwright para el recorrido.

**Spec:** `docs/superpowers/specs/2026-10-13-reglas-cuenta-por-dimension-design.md` (leerlo antes de cada tarea). Antecedente: `docs/superpowers/specs/2026-10-13-mapeo-sin-decisiones-internas-design.md`.

## Global Constraints

- **Sin reglas, ningún asiento cambia**: con la empresa sin reglas, Rehacer asientos → Simular en DOBA local da 0 diferencias.
- Las reglas siguen la regla de la casa: nada se decide en silencio. Regla con cuenta desactivada o de agrupación → `FaltaMapeoError('CUENTA_INUTILIZABLE')` con aviso, mensaje con prefijo `No hay cuenta mapeada para el concepto` y que nombra la regla.
- La operación del usuario nunca falla por una regla (los `integrar*` siguen envueltos en `conAvisoDeMapeo`).
- Una regla en `BORRADOR` nunca se aplica en un asiento real; solo en vista previa con `incluirBorradores`.
- Vigencia por **fecha contable del documento**. Activar una regla no recontabiliza documentos anteriores.
- Toda consulta filtra por `empresa_id`. Permisos: `CONTABILIDAD`/`CONT_MAP_MAPEO_EDITAR` (crear, editar, activar, retirar, reordenar) y `CONTABILIDAD`/`CONT_MAP_MAPEO_VER` (ver, probador, vista previa, probar). Sin permisos nuevos.
- Commits: **no commitear**. El usuario maneja el git a mano.
- Backend: tests con `npx jest <ruta>`; `NODE_OPTIONS=--max-old-space-size=6144 npx tsc --noEmit` sin errores nuevos (línea de base: 24).
- Migraciones: `prisma/migrations/<timestamp>_<nombre>/migration.sql`, `npx prisma migrate deploy` + `npx prisma generate`, solo contra la base local.
- Frontend: `docs/ui-standards.md` y `src/components/_standards/`; selects de datos con buscador; sin colores fijos; textos en español rioplatense neutro; nunca matar el vite del usuario en :5173.
- Pruebas manuales y Playwright sobre **DOBA en la base local** (empresa `40539a9d-ffcc-48c7-b932-5bb08b0828ac`, usuario `80144315`); dejar DOBA como estaba.

## Review Focus

1. **Ítem de una subcategoría con una regla sobre la categoría padre**: la regla aplica (la categoría cubre a sus hijas en cualquier profundidad). [RF-1] → Task 2.
2. **Documento con fecha anterior a `vigente_desde` o rehacer un asiento viejo después de retirar la regla**: se usa la regla que estaba vigente en la fecha contable, no la de hoy. [RF-2] → Task 2 y Task 3.
3. **Factura con ítems sin producto o sin categoría (ítem libre) y una regla de ítem**: esos ítems van a la cuenta por defecto y los totales por tasa no cambian. [RF-3] → Task 6.
4. **Venta en USD abierta por ítem**: la suma de las líneas por tasa, en moneda y en guaraníes, es igual al total de la tasa de la cabecera; el redondeo va a la línea mayor. [RF-4] → Task 6.
5. **Reversión espejo de un asiento con traza**: la reversión usa las mismas cuentas del original (no se re-resuelve) y conserva la traza. [RF-5] → Task 1.

Cada línea tiene su test en la tarea dueña (marcado `[RF-n]`).

---

## Mapa de archivos

Backend (`novasispy-backend-api`):

| Archivo | Responsabilidad |
|---|---|
| `prisma/migrations/20261020000000_mapeo_reglas/migration.sql` (nuevo) | Tabla `cont_mapeo_reglas`, columnas de traza en `cont_asientos_det` |
| `prisma/schema.prisma` | Reflejar la migración (con relaciones) |
| `src/contabilidad/dto/crear-asiento.dto.ts`, `services/asientos.service.ts` | Traza opcional por línea; `crearConfirmado` y la reversión la graban |
| `src/contabilidad/services/reglas-mapeo.ts` (nuevo) | Tipos, `DIMENSIONES_POR_ORIGEN`, evaluación pura de condiciones, elección de regla, frase legible |
| `src/contabilidad/services/mapeo-cuentas.service.ts` | `resolverConcepto(…, contexto?)` con traza; `crearResolvedor` |
| `src/contabilidad/services/contexto-documento.ts` (nuevo) | Arma las dimensiones de cabecera de cada documento |
| `src/contabilidad/services/apertura-items.ts` (nuevo) | Reparto de netos por ítem y agrupación por cuenta con ajuste de redondeo |
| `src/contabilidad/services/integracion.service.ts` | Resolvedor por documento en los 18 `integrar*`, traza, apertura por ítem |
| `src/contabilidad/services/reglas-mapeo.service.ts` + `controllers/reglas-mapeo.controller.ts` (nuevos) | CRUD, activar, retirar, reordenar, probador, auditoría |
| `src/contabilidad/controllers/mapeo-cuentas.controller.ts` | Endpoints `vista-previa` y `probar` |
| `src/contabilidad-conciliacion/recontabilizacion.service.ts`, `integrador-sombra.ts` | Simular por ids, con borradores; el colector conserva la traza |
| `src/contabilidad-conciliacion/salud-contable.service.ts` | Reglas activas con cuenta inutilizable en `mapeo_pendiente` |
| `src/contabilidad/services/catalogo-asientos.ts` / `previsualizacionAsientos` | Reglas por concepto en la respuesta del catálogo |
| `docs/guias/guia-contabilidad.md`, `src/ayuda-ia/ingesta/seed-catalogo.ts` | Documentación para NovaIA |

Frontend (`novasispy-erp`):

| Archivo | Responsabilidad |
|---|---|
| `src/api/contabilidad.service.js`, `src/tanstack/ContabilidadStack.jsx` | Llamadas y hooks de reglas, probador, vista previa, probar |
| `src/components/contabilidad/ReglasConceptoPanel.jsx` (nuevo) | "Excepciones (n)": lista, acciones |
| `src/components/contabilidad/ReglaDialog.jsx` (nuevo) | Crear/editar regla |
| `src/components/contabilidad/ProbadorReglasDialog.jsx` (nuevo) | "¿Qué cuenta usaría?" |
| `src/components/contabilidad/VistaPreviaDocumentoDialog.jsx` (nuevo) | Probar con un documento y contra los últimos 50 |
| `src/components/contabilidad/MapeoCuentasTab.jsx` | Integrar panel y botones |
| `src/components/contabilidad/AsientosEjemploPanel.jsx` | "+ n excepciones" |
| `src/components/contabilidad/AsientosTab.jsx` | "¿Por qué esta cuenta?" en el detalle del asiento |
| `docs/video-guias/contabilidad-guion.md` | Sumar lo nuevo al guion del video |

---

### Task 1: Esquema — reglas y traza; la traza viaja con el asiento

**Files:**
- Create: `prisma/migrations/20261020000000_mapeo_reglas/migration.sql`
- Modify: `prisma/schema.prisma` (modelo nuevo `cont_mapeo_reglas`; `cont_asientos_det` +3 columnas; back-relations en `empresas`, `usuario`, `cont_plan_cuentas`)
- Modify: `src/contabilidad/dto/crear-asiento.dto.ts` (`LineaAsientoDto` +3 opcionales), `src/contabilidad/services/asientos.service.ts` (`crearConfirmado` graba la traza; la reversión espejo la copia)
- Test: `src/contabilidad/services/asiento-traza.spec.ts` (nuevo)

**Interfaces:**
- Produces: tabla `cont_mapeo_reglas` (columnas del spec §3.1); `cont_asientos_det.{mapeo_concepto varchar(50), mapeo_regla_id uuid FK SET NULL, mapeo_nivel varchar(12)}`; `LineaAsientoDto.mapeo_concepto?`, `mapeo_regla_id?`, `mapeo_nivel?: 'REGLA' | 'DEFECTO' | 'FICHA' | 'MEDIO_PAGO'`.

- [ ] **Step 0: Línea de base** — `NODE_OPTIONS=--max-old-space-size=6144 npx tsc --noEmit 2>&1 | grep -c "error TS"` (esperado 24); anotar.

- [ ] **Step 1: Migración**

```sql
-- Reglas de cuenta por dimensión (spec 2026-10-13, etapa 1).
CREATE TABLE IF NOT EXISTS cont_mapeo_reglas (
  id            uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
  empresa_id    uuid NOT NULL REFERENCES empresas(id) ON DELETE CASCADE,
  concepto      varchar(50) NOT NULL,
  orden         int NOT NULL DEFAULT 1,
  condiciones   jsonb NOT NULL,
  modo          varchar(20) NOT NULL DEFAULT 'CUENTA',
  cuenta_id     uuid REFERENCES cont_plan_cuentas(id) ON DELETE RESTRICT,
  estado        varchar(10) NOT NULL DEFAULT 'BORRADOR',
  vigente_desde date NOT NULL,
  vigente_hasta date,
  descripcion   varchar(200),
  creado_por    uuid REFERENCES usuario(id) ON DELETE SET NULL,
  activado_por  uuid REFERENCES usuario(id) ON DELETE SET NULL,
  activado_at   timestamp(6),
  retirado_por  uuid REFERENCES usuario(id) ON DELETE SET NULL,
  retirado_at   timestamp(6),
  created_at    timestamp(6) DEFAULT now(),
  updated_at    timestamp(6) DEFAULT now(),
  CONSTRAINT cont_mapeo_reglas_modo_check CHECK (modo IN ('CUENTA', 'SUMAR_A_PRINCIPAL')),
  CONSTRAINT cont_mapeo_reglas_cuenta_segun_modo CHECK ((modo = 'CUENTA' AND cuenta_id IS NOT NULL) OR (modo = 'SUMAR_A_PRINCIPAL' AND cuenta_id IS NULL)),
  CONSTRAINT cont_mapeo_reglas_estado_check CHECK (estado IN ('BORRADOR', 'ACTIVA', 'RETIRADA')),
  CONSTRAINT cont_mapeo_reglas_condiciones_check CHECK (jsonb_typeof(condiciones) = 'array' AND jsonb_array_length(condiciones) > 0)
);
CREATE INDEX IF NOT EXISTS idx_cont_mapeo_reglas_busqueda ON cont_mapeo_reglas (empresa_id, concepto, estado, orden);

-- Traza: por qué cada línea tiene su cuenta. Null en asientos anteriores.
ALTER TABLE cont_asientos_det
  ADD COLUMN IF NOT EXISTS mapeo_concepto varchar(50),
  ADD COLUMN IF NOT EXISTS mapeo_regla_id uuid REFERENCES cont_mapeo_reglas(id) ON DELETE SET NULL,
  ADD COLUMN IF NOT EXISTS mapeo_nivel varchar(12);
ALTER TABLE cont_asientos_det DROP CONSTRAINT IF EXISTS cont_asientos_det_mapeo_nivel_check;
ALTER TABLE cont_asientos_det ADD CONSTRAINT cont_asientos_det_mapeo_nivel_check
  CHECK (mapeo_nivel IS NULL OR mapeo_nivel IN ('REGLA', 'DEFECTO', 'FICHA', 'MEDIO_PAGO'));
```

- [ ] **Step 2: `schema.prisma`** — modelo `cont_mapeo_reglas` con las columnas de arriba, relaciones `empresa`, `cuenta` (`cont_plan_cuentas?`, `onDelete: Restrict`), `creador`/`activador`/`retirador` a `usuario` (`onDelete: SetNull`, nombres de relación explícitos `"regla_creador"`, `"regla_activador"`, `"regla_retirador"`), `lineas cont_asientos_det[]`; `@@index([empresa_id, concepto, estado, orden], map: "idx_cont_mapeo_reglas_busqueda")`. En `cont_asientos_det`: `mapeo_concepto String? @db.VarChar(50)`, `mapeo_regla_id String? @db.Uuid`, `mapeo_nivel String? @db.VarChar(12)`, `mapeo_regla cont_mapeo_reglas? @relation(fields: [mapeo_regla_id], references: [id], onDelete: SetNull)`. Back-relations en `empresas`, `usuario` (tres) y `cont_plan_cuentas`.

- [ ] **Step 3: Aplicar** — verificar que `DATABASE_URL` apunte a `localhost`; `npx prisma migrate deploy && npx prisma generate && npx prisma validate`. Verificar sin drift: `npx prisma migrate diff --from-schema-datasource prisma/schema.prisma --to-schema-datamodel prisma/schema.prisma --script` no debe mencionar `cont_mapeo_reglas` ni las columnas `mapeo_*`.

- [ ] **Step 4: Test que falla** (`src/contabilidad/services/asiento-traza.spec.ts`), con el patrón de `asiento-sin-usuario.spec.ts` (servicio con prisma mockeado):

```ts
it('crearConfirmado graba la traza de cada línea', async () => {
  const { service, create } = armarAsientosService(); // helper local: prisma mock con cont_asientos.findFirst/create y tipoCambio identidad
  await service.crearConfirmado('emp', null, 'doc', {
    periodo_id: 'p', fecha: '2026-10-13',
    lineas: [
      { cuenta_id: 'c1', debe_moneda: 100, haber_moneda: 0, mapeo_concepto: 'CLIENTES', mapeo_nivel: 'DEFECTO' },
      { cuenta_id: 'c2', debe_moneda: 0, haber_moneda: 100, mapeo_concepto: 'VENTAS_10', mapeo_nivel: 'REGLA', mapeo_regla_id: 'r1' },
    ],
  } as any);
  const lineas = create.mock.calls[0][0].data.lineas.create;
  expect(lineas[0]).toMatchObject({ mapeo_concepto: 'CLIENTES', mapeo_nivel: 'DEFECTO', mapeo_regla_id: null });
  expect(lineas[1]).toMatchObject({ mapeo_concepto: 'VENTAS_10', mapeo_nivel: 'REGLA', mapeo_regla_id: 'r1' });
});

it('[RF-5] la reversión espejo copia cuentas y traza del original', async () => {
  // AsientosService.revertir(id, empresaId, usuarioId) (~línea 282) crea el espejo dentro de $transaction
  // con tx.cont_asientos.create; armar el mock con el mismo helper (findFirst del asiento original con lineas,
  // períodos abiertos, cont_documentos.create/update) que usen los specs existentes de revertir/corregir.
  const original = {
    id: 'a1', empresa_id: 'emp', documento_id: 'd1', numero: 7, glosa: 'Venta', estado: 'CONFIRMADO', moneda_origen: 'PYG',
    tipo_cambio_id: null, total_debe_pyg: 100, total_haber_pyg: 100, fecha: new Date('2026-10-13'), periodo_id: 'p',
    lineas: [
      { cuenta_id: 'c1', centro_costo_id: null, descripcion: 'Clientes', debe_moneda: 100, haber_moneda: 0, debe_pyg: 100, haber_pyg: 0,
        mapeo_concepto: 'CLIENTES', mapeo_regla_id: null, mapeo_nivel: 'DEFECTO' },
      { cuenta_id: 'c2', centro_costo_id: null, descripcion: 'Ventas 10%', debe_moneda: 0, haber_moneda: 100, debe_pyg: 0, haber_pyg: 100,
        mapeo_concepto: 'VENTAS_10', mapeo_regla_id: 'r1', mapeo_nivel: 'REGLA' },
    ],
  };
  const { service, txCreate } = armarRevertir(original); // helper local del spec
  await service.revertir('a1', 'emp', 'u1');
  const espejo = txCreate.mock.calls[0][0].data.lineas.create;
  expect(espejo[0]).toMatchObject({ cuenta_id: 'c1', debe_moneda: 0, haber_moneda: 100, mapeo_concepto: 'CLIENTES', mapeo_nivel: 'DEFECTO' });
  expect(espejo[1]).toMatchObject({ cuenta_id: 'c2', debe_moneda: 100, haber_moneda: 0, mapeo_regla_id: 'r1', mapeo_nivel: 'REGLA' });
});
```

(`armarAsientosService` y `armarRevertir` son helpers locales del spec, armados con el patrón de `asiento-sin-usuario.spec.ts` y `corregir-asiento.spec.ts`. La reversión no re-resuelve ninguna cuenta.)

- [ ] **Step 5: Correr y ver que falla** — `npx jest src/contabilidad/services/asiento-traza.spec.ts` → FAIL (`mapeo_concepto` no está en `data.lineas.create`).

- [ ] **Step 6: Implementar**

En `LineaAsientoDto`:

```ts
  /** Traza: con qué concepto se resolvió la cuenta (lo completa el integrador). */
  @IsOptional() @IsString() mapeo_concepto?: string;
  @IsOptional() @IsUUID() mapeo_regla_id?: string;
  @IsOptional() @IsIn(['REGLA', 'DEFECTO', 'FICHA', 'MEDIO_PAGO']) mapeo_nivel?: 'REGLA' | 'DEFECTO' | 'FICHA' | 'MEDIO_PAGO';
```

En `crearConfirmado`, dentro de `lineas.create`:

```ts
                mapeo_concepto: l.mapeo_concepto ?? null,
                mapeo_regla_id: l.mapeo_regla_id ?? null,
                mapeo_nivel: l.mapeo_nivel ?? null,
```

En la reversión espejo: copiar `mapeo_concepto`, `mapeo_regla_id`, `mapeo_nivel` de cada línea original.

- [ ] **Step 7: Correr** — `npx jest src/contabilidad src/contabilidad-conciliacion` → PASS; tsc = línea de base.

---

### Task 2: Reglas puras — dimensiones, condiciones, elección y frase

**Files:**
- Create: `src/contabilidad/services/reglas-mapeo.ts`
- Test: `src/contabilidad/services/reglas-mapeo.spec.ts`

**Interfaces:**
- Produces:

```ts
export type Dimension = 'SUCURSAL' | 'MONEDA' | 'TIPO_PROVEEDOR' | 'TIPO_CLIENTE' | 'CANAL' | 'CATEGORIA_PRODUCTO' | 'RUBRO' | 'TIPO_ITEM';
export const DIMENSIONES_ITEM: ReadonlySet<Dimension>;            // CATEGORIA_PRODUCTO, RUBRO, TIPO_ITEM
export type CondicionRegla = { dimension: Dimension; operador: 'EN' | 'NO_EN'; valores: string[] };
export type ReglaMapeo = { id: string; concepto: string; orden: number; condiciones: CondicionRegla[];
  modo: 'CUENTA' | 'SUMAR_A_PRINCIPAL'; cuenta_id: string | null; estado: 'BORRADOR' | 'ACTIVA' | 'RETIRADA';
  vigente_desde: Date; vigente_hasta: Date | null };
export type DimensionesDocumento = Partial<Record<Dimension, string | null>>;
/** Ancestros de cada categoría (incluida ella misma), para que la regla sobre el padre cubra a las hijas. */
export type AncestrosCategoria = Map<string, string[]>;
export const DIMENSIONES_POR_ORIGEN: Record<string, Dimension[]>;
export function validarCondiciones(c: unknown): CondicionRegla[];   // lanza BadRequestException con mensaje claro
export function cumpleCondiciones(c: CondicionRegla[], dims: DimensionesDocumento, ancestros?: AncestrosCategoria): boolean;
export function elegirRegla(reglas: ReglaMapeo[], fecha: Date, dims: DimensionesDocumento, opciones?: { incluirBorradores?: boolean; ancestros?: AncestrosCategoria }): ReglaMapeo | null;
export function usaDimensionesDeItem(r: Pick<ReglaMapeo, 'condiciones'>): boolean;
export function fraseRegla(r: ReglaMapeo, nombres: (d: Dimension, valor: string) => string, cuenta: string): string;
```

- [ ] **Step 1: Tests que fallan**

```ts
import { cumpleCondiciones, elegirRegla, validarCondiciones, usaDimensionesDeItem, fraseRegla, DIMENSIONES_POR_ORIGEN } from './reglas-mapeo';

const r = (over: any) => ({ id: 'r', concepto: 'VENTAS_10', orden: 1, modo: 'CUENTA', cuenta_id: 'c', estado: 'ACTIVA',
  vigente_desde: new Date('2026-01-01'), vigente_hasta: null, condiciones: [{ dimension: 'MONEDA', operador: 'EN', valores: ['USD'] }], ...over });

describe('cumpleCondiciones', () => {
  it('EN y NO_EN', () => {
    expect(cumpleCondiciones([{ dimension: 'MONEDA', operador: 'EN', valores: ['USD'] }], { MONEDA: 'USD' })).toBe(true);
    expect(cumpleCondiciones([{ dimension: 'MONEDA', operador: 'NO_EN', valores: ['USD'] }], { MONEDA: 'USD' })).toBe(false);
  });
  it('todas las condiciones (Y)', () => {
    const c = [{ dimension: 'MONEDA', operador: 'EN', valores: ['USD'] }, { dimension: 'SUCURSAL', operador: 'EN', valores: ['s1'] }] as any;
    expect(cumpleCondiciones(c, { MONEDA: 'USD', SUCURSAL: 's2' })).toBe(false);
    expect(cumpleCondiciones(c, { MONEDA: 'USD', SUCURSAL: 's1' })).toBe(true);
  });
  it('dimensión que el documento no tiene: la regla no aplica (ni con NO_EN)', () => {
    expect(cumpleCondiciones([{ dimension: 'CATEGORIA_PRODUCTO', operador: 'NO_EN', valores: ['x'] }], { MONEDA: 'PYG' })).toBe(false);
  });
  it('[RF-1] la categoría padre cubre a las hijas', () => {
    const ancestros = new Map([['nieta', ['nieta', 'hija', 'padre']]]);
    expect(cumpleCondiciones([{ dimension: 'CATEGORIA_PRODUCTO', operador: 'EN', valores: ['padre'] }], { CATEGORIA_PRODUCTO: 'nieta' }, ancestros)).toBe(true);
    expect(cumpleCondiciones([{ dimension: 'CATEGORIA_PRODUCTO', operador: 'NO_EN', valores: ['padre'] }], { CATEGORIA_PRODUCTO: 'nieta' }, ancestros)).toBe(false);
  });
});

describe('elegirRegla', () => {
  it('gana la primera por orden que cumple', () => {
    const a = r({ id: 'a', orden: 2 }); const b = r({ id: 'b', orden: 1 });
    expect(elegirRegla([a, b], new Date('2026-10-13'), { MONEDA: 'USD' })?.id).toBe('b');
  });
  it('[RF-2] vigencia por fecha contable, con bordes', () => {
    const v = r({ vigente_desde: new Date('2026-10-01'), vigente_hasta: new Date('2026-10-31') });
    expect(elegirRegla([v], new Date('2026-09-30'), { MONEDA: 'USD' })).toBeNull();
    expect(elegirRegla([v], new Date('2026-10-01'), { MONEDA: 'USD' })?.id).toBe('r');
    expect(elegirRegla([v], new Date('2026-10-31'), { MONEDA: 'USD' })).toBeNull(); // vigente_hasta es exclusivo
  });
  it('borrador solo con incluirBorradores; retirada nunca', () => {
    expect(elegirRegla([r({ estado: 'BORRADOR' })], new Date('2026-10-13'), { MONEDA: 'USD' })).toBeNull();
    expect(elegirRegla([r({ estado: 'BORRADOR' })], new Date('2026-10-13'), { MONEDA: 'USD' }, { incluirBorradores: true })?.id).toBe('r');
    expect(elegirRegla([r({ estado: 'RETIRADA' })], new Date('2026-10-13'), { MONEDA: 'USD' }, { incluirBorradores: true })).toBeNull();
  });
});

describe('validarCondiciones', () => {
  it('rechaza vacío, dimensión desconocida, operador inválido y valores vacíos', () => {
    expect(() => validarCondiciones([])).toThrow(/al menos una condición/);
    expect(() => validarCondiciones([{ dimension: 'COLOR', operador: 'EN', valores: ['x'] }])).toThrow(/dimensión/);
    expect(() => validarCondiciones([{ dimension: 'MONEDA', operador: 'ES', valores: ['x'] }])).toThrow(/operador/);
    expect(() => validarCondiciones([{ dimension: 'MONEDA', operador: 'EN', valores: [] }])).toThrow(/valor/);
  });
});

it('usaDimensionesDeItem', () => {
  expect(usaDimensionesDeItem(r({}))).toBe(false);
  expect(usaDimensionesDeItem(r({ condiciones: [{ dimension: 'RUBRO', operador: 'EN', valores: ['x'] }] }))).toBe(true);
});

it('fraseRegla', () => {
  expect(fraseRegla(r({}), (_d, v) => v, '4.1.1.02 Ventas exterior')).toBe('Si moneda es USD → 4.1.1.02 Ventas exterior');
});

it('las dimensiones de ítem solo las publican ventas, NC de venta, compras y NC de compra', () => {
  for (const [origen, dims] of Object.entries(DIMENSIONES_POR_ORIGEN)) {
    const tieneItem = dims.some((d) => ['CATEGORIA_PRODUCTO', 'RUBRO', 'TIPO_ITEM'].includes(d));
    expect(tieneItem).toBe(['factura_cab', 'nota_credito_cab', 'compra_cab', 'nota_credito_compra_cab'].includes(origen));
  }
});
```

- [ ] **Step 2: Correr y ver que falla** — `npx jest src/contabilidad/services/reglas-mapeo.spec.ts` → FAIL (módulo no existe).

- [ ] **Step 3: Implementar** `reglas-mapeo.ts`:

```ts
import { BadRequestException } from '@nestjs/common';

export type Dimension = 'SUCURSAL' | 'MONEDA' | 'TIPO_PROVEEDOR' | 'TIPO_CLIENTE' | 'CANAL' | 'CATEGORIA_PRODUCTO' | 'RUBRO' | 'TIPO_ITEM';
const DIMENSIONES: readonly Dimension[] = ['SUCURSAL', 'MONEDA', 'TIPO_PROVEEDOR', 'TIPO_CLIENTE', 'CANAL', 'CATEGORIA_PRODUCTO', 'RUBRO', 'TIPO_ITEM'];
export const DIMENSIONES_ITEM: ReadonlySet<Dimension> = new Set(['CATEGORIA_PRODUCTO', 'RUBRO', 'TIPO_ITEM']);

export const ETIQUETA_DIMENSION: Record<Dimension, string> = {
  SUCURSAL: 'sucursal', MONEDA: 'moneda', TIPO_PROVEEDOR: 'tipo de proveedor', TIPO_CLIENTE: 'tipo de cliente',
  CANAL: 'canal', CATEGORIA_PRODUCTO: 'categoría', RUBRO: 'rubro', TIPO_ITEM: 'tipo de ítem',
};

export type CondicionRegla = { dimension: Dimension; operador: 'EN' | 'NO_EN'; valores: string[] };
export type ReglaMapeo = {
  id: string; concepto: string; orden: number; condiciones: CondicionRegla[];
  modo: 'CUENTA' | 'SUMAR_A_PRINCIPAL'; cuenta_id: string | null;
  estado: 'BORRADOR' | 'ACTIVA' | 'RETIRADA'; vigente_desde: Date; vigente_hasta: Date | null;
};
export type DimensionesDocumento = Partial<Record<Dimension, string | null>>;
export type AncestrosCategoria = Map<string, string[]>;

const CABECERA_VENTA: Dimension[] = ['SUCURSAL', 'MONEDA', 'TIPO_CLIENTE', 'CANAL'];
const ITEM: Dimension[] = ['CATEGORIA_PRODUCTO', 'RUBRO', 'TIPO_ITEM'];

/**
 * Qué dimensiones publica cada documento al contabilizarse. La pantalla lo usa
 * para avisar que una condición nunca va a aplicar a un concepto; los tests,
 * para que el integrador y esta tabla no se separen.
 */
export const DIMENSIONES_POR_ORIGEN: Record<string, Dimension[]> = {
  factura_cab: [...CABECERA_VENTA, ...ITEM],
  nota_credito_cab: [...CABECERA_VENTA, ...ITEM],
  compra_cab: ['SUCURSAL', 'MONEDA', 'TIPO_PROVEEDOR', ...ITEM],
  nota_credito_compra_cab: ['SUCURSAL', 'MONEDA', 'TIPO_PROVEEDOR', ...ITEM],
  gasto_cab: ['SUCURSAL', 'MONEDA', 'TIPO_PROVEEDOR'],
  imp_despacho: ['MONEDA', 'TIPO_PROVEEDOR'],
  imp_cierre: ['MONEDA'],
  recibos_cobro: ['SUCURSAL', 'MONEDA', 'TIPO_CLIENTE'],
  recibos_multi: ['SUCURSAL', 'MONEDA', 'TIPO_CLIENTE'],
  pagos_proveedor: ['SUCURSAL', 'MONEDA', 'TIPO_PROVEEDOR'],
  orden_pago_proveedor_cab: ['SUCURSAL', 'MONEDA', 'TIPO_PROVEEDOR'],
  tes_movimientos: ['MONEDA'],
  tes_transferencias: ['MONEDA'],
  pago_bancard: ['MONEDA'],
  rrhh_liquidacion: ['MONEDA'],
  liquidacion_comisiones_deveng: ['MONEDA'],
  liquidacion_comisiones_pago: ['MONEDA'],
  comision_supervisor: ['MONEDA'],
  rendicion_adelanto: ['MONEDA'],
  rendicion_devolucion: ['MONEDA'],
};

export function validarCondiciones(c: unknown): CondicionRegla[] {
  if (!Array.isArray(c) || c.length === 0) throw new BadRequestException('La regla necesita al menos una condición.');
  return c.map((x, i) => {
    const n = i + 1;
    if (!x || !DIMENSIONES.includes(x.dimension)) throw new BadRequestException(`Condición ${n}: dimensión desconocida.`);
    if (x.operador !== 'EN' && x.operador !== 'NO_EN') throw new BadRequestException(`Condición ${n}: operador inválido.`);
    if (!Array.isArray(x.valores) || x.valores.length === 0 || x.valores.some((v: unknown) => typeof v !== 'string' || !v)) {
      throw new BadRequestException(`Condición ${n}: elegí al menos un valor.`);
    }
    return { dimension: x.dimension, operador: x.operador, valores: [...new Set<string>(x.valores)] };
  });
}

export function cumpleCondiciones(c: CondicionRegla[], dims: DimensionesDocumento, ancestros?: AncestrosCategoria): boolean {
  return c.every((cond) => {
    const valor = dims[cond.dimension];
    // El documento no publica esa dimensión (o la tiene vacía): la regla no aplica.
    if (valor === undefined || valor === null || valor === '') return false;
    const candidatos = cond.dimension === 'CATEGORIA_PRODUCTO' ? ancestros?.get(valor) ?? [valor] : [valor];
    const coincide = candidatos.some((v) => cond.valores.includes(v));
    return cond.operador === 'EN' ? coincide : !coincide;
  });
}

const soloFecha = (d: Date) => d.toISOString().slice(0, 10);

export function elegirRegla(
  reglas: ReglaMapeo[],
  fecha: Date,
  dims: DimensionesDocumento,
  opciones: { incluirBorradores?: boolean; ancestros?: AncestrosCategoria } = {},
): ReglaMapeo | null {
  const f = soloFecha(fecha);
  const candidatas = reglas
    .filter((r) => r.estado === 'ACTIVA' || (opciones.incluirBorradores && r.estado === 'BORRADOR'))
    .filter((r) => soloFecha(r.vigente_desde) <= f && (!r.vigente_hasta || f < soloFecha(r.vigente_hasta)))
    .sort((a, b) => a.orden - b.orden);
  return candidatas.find((r) => cumpleCondiciones(r.condiciones, dims, opciones.ancestros)) ?? null;
}

export const usaDimensionesDeItem = (r: Pick<ReglaMapeo, 'condiciones'>) => r.condiciones.some((c) => DIMENSIONES_ITEM.has(c.dimension));

export function fraseRegla(r: ReglaMapeo, nombres: (d: Dimension, valor: string) => string, cuenta: string): string {
  const partes = r.condiciones.map((c) => {
    const valores = c.valores.map((v) => nombres(c.dimension, v)).join(' o ');
    return `${ETIQUETA_DIMENSION[c.dimension]} ${c.operador === 'EN' ? 'es' : 'no es'} ${valores}`;
  });
  return `Si ${partes.join(' y ')} → ${cuenta}`;
}
```

- [ ] **Step 4: Correr** — `npx jest src/contabilidad/services/reglas-mapeo.spec.ts` → PASS.

---

### Task 3: Resolución con contexto y resolvedor por documento

**Files:**
- Modify: `src/contabilidad/services/mapeo-cuentas.service.ts` (`resolverConcepto` ~402, `getCuentaPorConcepto` ~387; nuevo `crearResolvedor`)
- Test: `src/contabilidad/services/mapeo-reglas-resolucion.spec.ts` (nuevo)

**Interfaces:**
- Consumes: `elegirRegla`, `ReglaMapeo`, `DimensionesDocumento`, `AncestrosCategoria` (Task 2); `FaltaMapeoError` (existente: `new FaltaMapeoError(empresaId, conceptos, detalle?, motivo?, cuentaCodigo?)`).
- Produces:

```ts
export type TrazaMapeo = { concepto: string; nivel: 'REGLA' | 'DEFECTO'; reglaId?: string };
export type ContextoMapeo = { fecha: Date; dimensiones: DimensionesDocumento; incluirBorradores?: boolean; ancestros?: AncestrosCategoria };
// MapeoCuentasService
resolverConcepto(empresaId, concepto, contexto?: ContextoMapeo, reglas?: ReglaMapeo[]):
  Promise<({ modo: 'CUENTA'; cuentaId: string } | { modo: 'SUMAR_A_PRINCIPAL' }) & { traza: TrazaMapeo }>;
getCuentaPorConcepto(empresaId, concepto, contexto?): Promise<string>;   // sin contexto: idéntico a hoy
crearResolvedor(empresaId: string, contexto: ContextoMapeo): Promise<ResolvedorMapeo>;
export interface ResolvedorMapeo {
  /** Cuenta del concepto con las dimensiones del documento (más las del ítem si se pasan). */
  cuenta(concepto: string, dimsItem?: DimensionesDocumento): Promise<string>;
  resolver(concepto: string, dimsItem?: DimensionesDocumento): ReturnType<MapeoCuentasService['resolverConcepto']>;
  /** Marca una cuenta que salió de una ficha o de un medio de pago (para la traza). */
  marcar(cuentaId: string, nivel: 'FICHA' | 'MEDIO_PAGO'): string;
  /** Completa mapeo_* en las líneas según cómo se resolvió cada cuenta. */
  anotar<T extends { cuenta_id: string }>(lineas: T[]): Array<T & { mapeo_concepto?: string; mapeo_regla_id?: string; mapeo_nivel?: string }>;
  /** ¿Hay reglas (activas o, en vista previa, borrador) de este concepto que usen dimensiones de ítem? */
  tieneReglasDeItem(concepto: string): boolean;
  /** Carga los ancestros de estas categorías (una consulta) antes de resolver por ítem. */
  prepararCategorias(ids: string[]): Promise<void>;
  contexto: ContextoMapeo;
}
```

- [ ] **Step 1: Tests que fallan** (patrón `Object.create(MapeoCuentasService.prototype)` con prisma mockeado, como `mapeo-cuentas-constancia.spec.ts`):

```ts
const crear = ({ mapeo, reglas = [], categorias = [] }: any) => {
  const s = Object.create(MapeoCuentasService.prototype) as any;
  s.prisma = {
    cont_mapeo_cuentas: { findUnique: jest.fn().mockResolvedValue(mapeo) },
    cont_mapeo_reglas: { findMany: jest.fn().mockResolvedValue(reglas) },
    cont_plan_cuentas: { findUnique: jest.fn().mockImplementation(({ where }) => Promise.resolve(
      { id: where.id, codigo: where.id === 'muerta' ? '9.9' : '4.1', active: where.id !== 'muerta', acepta_movimientos: true })) },
    categorias: { findMany: jest.fn().mockResolvedValue(categorias) },
  };
  return s as MapeoCuentasService;
};
const def = { cuenta_id: 'def', modo: 'CUENTA', cuenta: { codigo: '4.1.1.01', active: true, acepta_movimientos: true } };
const regla = (over: any = {}) => ({ id: 'r1', concepto: 'VENTAS_10', orden: 1, modo: 'CUENTA', cuenta_id: 'usd', estado: 'ACTIVA',
  vigente_desde: new Date('2026-01-01'), vigente_hasta: null, condiciones: [{ dimension: 'MONEDA', operador: 'EN', valores: ['USD'] }], ...over });

it('sin contexto: idéntico a hoy, traza DEFECTO', async () => {
  const r = await crear({ mapeo: def, reglas: [regla()] }).resolverConcepto('emp', 'VENTAS_10');
  expect(r).toEqual({ modo: 'CUENTA', cuentaId: 'def', traza: { concepto: 'VENTAS_10', nivel: 'DEFECTO' } });
});

it('con contexto aplica la regla y lo dice en la traza', async () => {
  const res = await crear({ mapeo: def, reglas: [regla()] }).crearResolvedor('emp', { fecha: new Date('2026-10-13'), dimensiones: { MONEDA: 'USD' } });
  expect(await res.cuenta('VENTAS_10')).toBe('usd');
  expect(res.anotar([{ cuenta_id: 'usd' }])[0]).toMatchObject({ mapeo_concepto: 'VENTAS_10', mapeo_nivel: 'REGLA', mapeo_regla_id: 'r1' });
});

it('[RF-2] regla retirada después de la fecha del documento sigue aplicando a ese documento', async () => {
  const res = await crear({ mapeo: def, reglas: [regla({ estado: 'RETIRADA', vigente_hasta: new Date('2026-11-01') })] })
    .crearResolvedor('emp', { fecha: new Date('2026-10-13'), dimensiones: { MONEDA: 'USD' } });
  expect(await res.cuenta('VENTAS_10')).toBe('usd');
});

it('regla con cuenta desactivada → FaltaMapeoError CUENTA_INUTILIZABLE que nombra la regla', async () => {
  const res = await crear({ mapeo: def, reglas: [regla({ cuenta_id: 'muerta' })] }).crearResolvedor('emp', { fecha: new Date('2026-10-13'), dimensiones: { MONEDA: 'USD' } });
  const err = await res.cuenta('VENTAS_10').catch((e) => e);
  expect(err).toBeInstanceOf(FaltaMapeoError);
  expect(err.motivo).toBe('CUENTA_INUTILIZABLE');
  expect(err.message).toMatch(/^No hay cuenta mapeada para el concepto/);
  expect(err.message).toMatch(/regla n\.º 1/);
});

it('sin fila de mapeo y ninguna regla aplica → SIN_MAPEO', async () => {
  const res = await crear({ mapeo: null }).crearResolvedor('emp', { fecha: new Date('2026-10-13'), dimensiones: { MONEDA: 'PYG' } });
  await expect(res.cuenta('VENTAS_10')).rejects.toMatchObject({ motivo: 'SIN_MAPEO' });
});

it('lee las reglas una sola vez por documento', async () => {
  const s = crear({ mapeo: def, reglas: [regla()] }) as any;
  const res = await s.crearResolvedor('emp', { fecha: new Date('2026-10-13'), dimensiones: { MONEDA: 'USD' } });
  await res.cuenta('VENTAS_10'); await res.cuenta('VENTAS_10'); await res.cuenta('VENTAS_5');
  expect(s.prisma.cont_mapeo_reglas.findMany).toHaveBeenCalledTimes(1);
});

it('marcar deja FICHA/MEDIO_PAGO en la traza', async () => {
  const res = await crear({ mapeo: def }).crearResolvedor('emp', { fecha: new Date('2026-10-13'), dimensiones: {} });
  res.marcar('prov', 'FICHA');
  expect(res.anotar([{ cuenta_id: 'prov' }])[0]).toMatchObject({ mapeo_nivel: 'FICHA' });
});
```

- [ ] **Step 2: Correr y ver que falla** — `npx jest src/contabilidad/services/mapeo-reglas-resolucion.spec.ts`.

- [ ] **Step 3: Implementar**

`resolverConcepto(empresaId, concepto, contexto?, reglas?)`:
1. Si hay `contexto`: `const regla = elegirRegla(reglas ?? await this.reglasDe(empresaId), contexto.fecha, contexto.dimensiones, { incluirBorradores: contexto.incluirBorradores, ancestros: contexto.ancestros })` filtrando por `concepto`.
2. Si hay regla: modo SUMAR → `{ modo: 'SUMAR_A_PRINCIPAL', traza: { concepto, nivel: 'REGLA', reglaId } }`; modo CUENTA → validar la cuenta (`cont_plan_cuentas.findUnique({ select: { codigo, active, acepta_movimientos } })`); desactivada/de agrupación → `throw new FaltaMapeoError(empresaId, [concepto], \`regla n.º ${regla.orden}: ${cuenta.codigo} está desactivada\` /* o "es de agrupación" */, 'CUENTA_INUTILIZABLE', cuenta.codigo)`; si no, `{ modo: 'CUENTA', cuentaId, traza: { concepto, nivel: 'REGLA', reglaId: regla.id } }`.
3. Si no hay regla: el código actual tal cual, devolviendo además `traza: { concepto, nivel: 'DEFECTO' }`.

`reglasDe(empresaId)`: `cont_mapeo_reglas.findMany({ where: { empresa_id, estado: { in: ['ACTIVA', 'BORRADOR', 'RETIRADA'] } }, orderBy: { orden: 'asc' } })` mapeado a `ReglaMapeo` (las retiradas se necesitan para documentos con fecha dentro de su vigencia).

`crearResolvedor(empresaId, contexto)`: carga `reglasDe` una vez; mantiene `Map<cuentaId, traza>`; `cuenta(concepto, dimsItem)` llama `resolverConcepto(empresaId, concepto, { ...contexto, dimensiones: { ...contexto.dimensiones, ...dimsItem } }, reglas)` y registra la traza por `cuentaId` (si la misma cuenta aparece por dos caminos, gana la primera; documentarlo en un comentario); `prepararCategorias(ids)` lee `categorias` (`id, padre_id`) de la empresa una vez y arma `contexto.ancestros` caminando `padre_id` (con corte por ciclos); `tieneReglasDeItem(concepto)` usa `usaDimensionesDeItem` sobre las reglas ACTIVAS (o BORRADOR si `incluirBorradores`) de ese concepto.

`getCuentaPorConcepto(empresaId, concepto, contexto?)` delega en `resolverConcepto` y devuelve `cuentaId` (mismo error que hoy con modo SUMAR).

- [ ] **Step 4: Correr** — el spec nuevo + `npx jest src/contabilidad` → PASS (los specs existentes que comparan `resolverConcepto` con `toEqual` exacto se ajustan para aceptar `traza`; solo eso).

---

### Task 4: Contexto de cabecera y resolvedor en ventas, compras, gastos e importaciones

**Files:**
- Create: `src/contabilidad/services/contexto-documento.ts`
- Modify: `src/contabilidad/services/integracion.service.ts` — `integrarFacturaVenta` (~226), `integrarNotaCredito` (~373), `integrarFacturaCompra` (~467), `integrarNotaCreditoCompra` (~653), `integrarCierreDespacho` (~752), `integrarCierreImportacion` (~932), `integrarGasto` (~1029); helpers `resolverCuentaPasivo`, `cuentaConRespaldo`, `cuentaCostoCompra`, `agregarChequeAlMapa`, `repartirPorMedio`
- Modify: `src/contabilidad/services/__helpers__/integracion-mock.ts` (el mock de `mapeo` gana `crearResolvedor`)
- Test: `src/contabilidad/services/integracion-reglas-cabecera.spec.ts` (nuevo)

**Interfaces:**
- Consumes: `crearResolvedor`, `ResolvedorMapeo` (Task 3); `DIMENSIONES_POR_ORIGEN` (Task 2).
- Produces: `contextoDocumento.ts`:

```ts
export async function dimensionesVenta(prisma, empresaId: string, f: { dest: string | null; cliente_id: string | null; moneda?: { codigo: string } | null; factura_forma_pagos?: Array<{ sesion_caja_id?: string | null }> }): Promise<DimensionesDocumento>;
export async function dimensionesProveedor(prisma, empresaId: string, d: { sucursal_id?: string | null; proveedor_id?: string | null; moneda?: { codigo: string } | null }): Promise<DimensionesDocumento>;
export async function dimensionesCliente(prisma, empresaId: string, d: { sucursal_id?: string | null; cliente_id?: string | null; moneda?: { codigo: string } | null }): Promise<DimensionesDocumento>;
export const dimensionMoneda = (codigo?: string | null): DimensionesDocumento => ({ MONEDA: codigo ?? 'PYG' });
```

- `SUCURSAL` en ventas: `empresas_sucursales.findFirst({ where: { empresa_id, punto_establecimiento: dest }, select: { id: true } })`.
- `CANAL`: `'POS'` si alguna forma de pago tiene `sesion_caja_id`; si no, `'FACTURA'` (agregar `sesion_caja_id: true` al select de `factura_forma_pagos`).
- `TIPO_CLIENTE`: `clientes.tipo_cliente`; `TIPO_PROVEEDOR`: `proveedores.tipo_entidad`.

- [ ] **Step 1: Tests que fallan** — con `crearIntegracionMock` (actualizado para que `mapeo.crearResolvedor` devuelva un resolvedor real construido sobre el mock de `getCuentaPorConcepto` + una lista de reglas configurable):

```ts
import { crearIntegracionMock } from './__helpers__/integracion-mock';

const lineas = (s: any) => s.asientos.crearConfirmado.mock.calls[0][3].lineas;
const facturaVenta = (over: any = {}) => ({
  id: 'f1', empresa_id: 'emp', estado: 'Aprobado', cliente_id: 'cli1', dest: '002', dpunexp: '001', dnumdoc: '0000010',
  dfeemide: new Date('2026-10-13'), cobro_diferido: false, condicion_operacion: { codigo: 2 }, moneda: { codigo: 'PYG' }, dticam: 1,
  factura_subtotales: [{ dtotgralope: 1100, diva10: 100, diva5: 0, dsub10: 1100, dsub5: 0, dsubexe: 0, dsubexo: 0 }],
  factura_forma_pagos: [], ...over,
});
const baseVenta = (f: any, extra: any = {}) => ({
  factura_cab: { findUnique: jest.fn().mockResolvedValue(f) },
  inm_cobros: { findFirst: jest.fn().mockResolvedValue(null) },
  empresas_sucursales: { findFirst: jest.fn().mockResolvedValue({ id: 'suc-cde' }) },
  clientes: { findUnique: jest.fn().mockResolvedValue({ tipo_cliente: 'mayorista' }) },
  ...extra,
});

it('sin reglas, la factura de venta arma exactamente las mismas líneas que antes', async () => {
  const s = crearIntegracionMock(baseVenta(facturaVenta()));
  await s.integrarFacturaVenta('f1');
  expect(lineas(s).map((l: any) => [l.cuenta_id, l.debe_moneda, l.haber_moneda, l.descripcion])).toEqual([
    ['cta-CLIENTES', 1100, 0, 'Clientes'],
    ['cta-VENTAS_10', 0, 1000, 'Ventas 10%'],
    ['cta-IVA_DEBITO_10', 0, 100, 'IVA Débito 10%'],
  ]);
  expect(lineas(s).every((l: any) => l.mapeo_nivel === 'DEFECTO')).toBe(true);
});

it('regla MONEDA=USD en VENTAS_10 cambia solo esa cuenta y deja traza REGLA', async () => {
  const s = crearIntegracionMock(baseVenta(facturaVenta({ moneda: { codigo: 'USD' }, dticam: 7300 })), [], {}, [
    { id: 'r1', concepto: 'VENTAS_10', orden: 1, modo: 'CUENTA', cuenta_id: 'cta-VENTAS_USD', estado: 'ACTIVA',
      vigente_desde: new Date('2026-01-01'), vigente_hasta: null, condiciones: [{ dimension: 'MONEDA', operador: 'EN', valores: ['USD'] }] },
  ]);
  await s.integrarFacturaVenta('f1');
  const ventas = lineas(s).find((l: any) => l.descripcion === 'Ventas 10%');
  expect(ventas).toMatchObject({ cuenta_id: 'cta-VENTAS_USD', mapeo_nivel: 'REGLA', mapeo_regla_id: 'r1', mapeo_concepto: 'VENTAS_10' });
  expect(lineas(s).find((l: any) => l.descripcion === 'Clientes').cuenta_id).toBe('cta-CLIENTES');
});

it('venta: SUCURSAL sale de la sucursal cuyo punto_establecimiento es el dest de la factura', async () => {
  const s = crearIntegracionMock(baseVenta(facturaVenta()), [], {}, [
    { id: 'r1', concepto: 'VENTAS_10', orden: 1, modo: 'CUENTA', cuenta_id: 'cta-VENTAS_CDE', estado: 'ACTIVA',
      vigente_desde: new Date('2026-01-01'), vigente_hasta: null, condiciones: [{ dimension: 'SUCURSAL', operador: 'EN', valores: ['suc-cde'] }] },
  ]);
  await s.integrarFacturaVenta('f1');
  expect(s.prisma.empresas_sucursales.findFirst.mock.calls[0][0].where).toEqual({ empresa_id: 'emp', punto_establecimiento: '002' });
  expect(lineas(s).find((l: any) => l.descripcion === 'Ventas 10%').cuenta_id).toBe('cta-VENTAS_CDE');
});

it('venta POS: CANAL = POS cuando una forma de pago tiene sesión de caja', async () => {
  const f = facturaVenta({ condicion_operacion: { codigo: 1 }, factura_forma_pagos: [{ medio_pago_id: 1, dmontipag: 1100, dticamtipag: null, sesion_caja_id: 'ses1' }] });
  const s = crearIntegracionMock(baseVenta(f), [], {}, [
    { id: 'r1', concepto: 'VENTAS_10', orden: 1, modo: 'CUENTA', cuenta_id: 'cta-VENTAS_POS', estado: 'ACTIVA',
      vigente_desde: new Date('2026-01-01'), vigente_hasta: null, condiciones: [{ dimension: 'CANAL', operador: 'EN', valores: ['POS'] }] },
  ]);
  await s.integrarFacturaVenta('f1');
  expect(lineas(s).find((l: any) => l.descripcion === 'Ventas 10%').cuenta_id).toBe('cta-VENTAS_POS');
});

it('regla SUCURSAL en INVENTARIO de una compra (sucursal_id de la compra)', async () => {
  const compra = { id: 'c1', empresa_id: 'emp', sucursal_id: 'suc-cde', condicion_compra: 'CREDITO', total: 1100, total_iva_10: 100, total_iva_5: 0,
    moneda: { codigo: 'PYG' }, cotizacion: null, fecha_emision: new Date('2026-10-13'), proveedor_id: 'p1', numero: '1', estado: 'confirmada' };
  const s = crearIntegracionMock({ compra_cab: { findUnique: jest.fn().mockResolvedValue(compra) }, proveedores: { findFirst: jest.fn().mockResolvedValue({ tipo_entidad: 'PROVEEDOR_LOCAL', cuenta_contable_id: null }) } }, [], {}, [
    { id: 'r1', concepto: 'INVENTARIO', orden: 1, modo: 'CUENTA', cuenta_id: 'cta-INV_CDE', estado: 'ACTIVA',
      vigente_desde: new Date('2026-01-01'), vigente_hasta: null, condiciones: [{ dimension: 'SUCURSAL', operador: 'EN', valores: ['suc-cde'] }] },
  ]);
  await s.integrarFacturaCompra('c1');
  expect(lineas(s).find((l: any) => l.cuenta_id === 'cta-INV_CDE')).toMatchObject({ mapeo_nivel: 'REGLA', mapeo_concepto: 'INVENTARIO' });
});

it('la cuenta propia del proveedor queda con traza FICHA', async () => {
  // misma compra; proveedores.findFirst → { tipo_entidad: 'PROVEEDOR_LOCAL', cuenta_contable_id: 'cta-PROPIA' } y
  // cont_plan_cuentas.findUnique → { id: 'cta-PROPIA', active: true, acepta_movimientos: true }
  // → la línea del haber tiene cuenta_id 'cta-PROPIA' y mapeo_nivel 'FICHA'.
});
```

(El último test sigue el mismo armado que el anterior con los dos mocks indicados; los nombres de campos de los documentos se ajustan a lo que lee cada `integrar*`. `crearIntegracionMock` gana un cuarto parámetro `reglas: ReglaMapeo[] = []`: su `mapeo.crearResolvedor` construye un resolvedor real (`MapeoCuentasService.prototype.crearResolvedor` con el `resolverConcepto` del mock) para que la lógica de reglas sea la de producción.)

- [ ] **Step 2: Correr y ver que fallan** — `npx jest src/contabilidad/services/integracion-reglas-cabecera.spec.ts`.

- [ ] **Step 3: Implementar.** En cada `integrar*` de esta tarea, una vez leído el documento y antes de resolver cuentas:

```ts
      const res = await this.mapeo.crearResolvedor(empresaId, {
        fecha,
        dimensiones: await dimensionesVenta(this.prisma, empresaId, factura),
        incluirBorradores: this.opcionesMapeo?.incluirBorradores,
      });
```

y reemplazar **todas** las `this.mapeo.getCuentaPorConcepto(empresaId, X)` / `this.mapeo.resolverConcepto(empresaId, X)` del método por `res.cuenta(X)` / `res.resolver(X)`. Los helpers reciben `res` en lugar de `empresaId` donde resuelven conceptos (`resolverCuentaPasivo(proveedorId, res)`: la cuenta propia del proveedor se devuelve con `res.marcar(id, 'FICHA')`; `cuentaConRespaldo(res, especifico, general)`; `cuentaCostoCompra(res, compraId)`; las cuentas de `mediosPago.resolverPorMedio` se marcan `MEDIO_PAGO` al usarlas; las de tipo de gasto y tesorería, `FICHA`). Antes de `crearConfirmado`: `lineas: res.anotar(lineas)`.

Agregar a la clase `opcionesMapeo?: { incluirBorradores?: boolean }` (lo setea solo la simulación, Task 7).

- [ ] **Step 4: Correr** — spec nuevo + `npx jest src/contabilidad src/contabilidad-conciliacion` → PASS (los specs existentes no cambian de expectativas: sin reglas, mismas líneas).

---

### Task 5: Resolvedor en cobros, pagos, tesorería, RRHH, recibos y comisiones

**Files:**
- Modify: `src/contabilidad/services/integracion.service.ts` — `integrarCobro` (~1334), `integrarPago` (~1422), `integrarOrdenPago` (~1503), `integrarMovimientoTesoreria` (~1761), `integrarTransferenciaTes` (~1935), `integrarPagoBancard` (~2077), `integrarLiquidacionRrhh` (~2168), `integrarReciboMulti` (~2430), `integrarDevengamientoComisiones` (~2790), `integrarPagoComisiones` (~2870), `integrarComisionSupervisor` (~2943)
- Modify: `src/rendicion-viaticos/rendicion-viaticos-contabilidad.service.ts` (sus `getCuentaPorConcepto` pasan contexto `dimensionMoneda`)
- Test: `src/contabilidad/services/integracion-reglas-tesoreria.spec.ts` (nuevo)

**Interfaces:**
- Consumes: Task 3 y Task 4 (`crearResolvedor`, `dimensionesCliente`, `dimensionesProveedor`, `dimensionMoneda`, helpers con `res`).

- [ ] **Step 1: Tests que fallan**

Cada test reutiliza **el mismo armado de documento** del spec existente indicado y agrega una regla con `crearIntegracionMock(prisma, faltan, modos, reglas)`:

| Test | Armado de | Regla | Expectativa |
|---|---|---|---|
| recibo multi en USD | `asientos-cobros-pagos.spec.ts` (recibo multi con saldo a favor) con moneda USD | `ANTICIPOS_CLIENTES`, `MONEDA EN [USD]` → `cta-ANT_USD` | la línea de anticipo usa `cta-ANT_USD`, `mapeo_nivel: 'REGLA'`; el resto `DEFECTO`/`MEDIO_PAGO` |
| orden de pago con cheque | `integracion-sin-respaldos.spec.ts` (OP con cheque) con proveedor `PROVEEDOR_EXTERIOR` | `CHEQUES_A_PAGAR`, `TIPO_PROVEEDOR EN [PROVEEDOR_EXTERIOR]` → `cta-CHQ_EXT` | la línea "Cheque emitido a pagar" usa `cta-CHQ_EXT` |
| movimiento con concepto | `movimiento-concepto-contable.spec.ts` (detalle `DESCUENTOS_VARIOS_RRHH`) en cuenta de tesorería USD | `DESCUENTOS_VARIOS_RRHH`, `MONEDA EN [USD]` → `cta-DESC_USD` | la línea del detalle usa `cta-DESC_USD`; la línea de la cuenta de tesorería `mapeo_nivel: 'FICHA'` |
| liquidación RRHH | spec de liquidación existente en `asientos-cobros-pagos.spec.ts` o `integracion-sin-respaldos.spec.ts` | ninguna | mismas líneas que hoy (comparar `[cuenta_id, debe, haber]`), todas `DEFECTO` |
| faltantes juntos | `asientos-cobros-pagos.spec.ts` [RF-1] (recibo con retención y cheque sin mapear) | una regla activa cualquiera en otro concepto | `registrarFaltaMapeo` recibe ambos conceptos, como hoy |

- [ ] **Step 2: Correr y ver que fallan.**

- [ ] **Step 3: Implementar** — mismo patrón que la Task 4 en cada método: `const res = await this.mapeo.crearResolvedor(empresaId, { fecha, dimensiones: …, incluirBorradores: this.opcionesMapeo?.incluirBorradores })`; reemplazar todas las resoluciones del método; `soloFaltaMapeo` y los acumuladores de faltantes (`necesito`, `faltan`) se mantienen tal cual, ahora sobre `res`; `lineas: res.anotar(lineas)` antes de `crearConfirmado`. Dimensiones: cobros y recibos → `dimensionesCliente`; pagos y OP → `dimensionesProveedor`; tesorería → `dimensionMoneda(moneda de la cuenta de tesorería)`; RRHH, Bancard, comisiones → `dimensionMoneda('PYG')` o la del documento si la tiene.

Al terminar, verificar que no queden resoluciones sin contexto en el integrador: `rtk proxy grep -n "this.mapeo.getCuentaPorConcepto\|this.mapeo.resolverConcepto" src/contabilidad/services/integracion.service.ts` → sin resultados (todo pasa por `res`).

- [ ] **Step 4: Correr** — spec nuevo + `npx jest src/contabilidad src/contabilidad-conciliacion src/rendicion-viaticos src/rrhh src/tesoreria` → PASS (preexistente conocido: `liquidaciones.controller.spec`).

---

### Task 6: Apertura por ítem en ventas, NC de venta, compras y NC de compra

**Files:**
- Create: `src/contabilidad/services/apertura-items.ts`
- Modify: `src/contabilidad/services/integracion.service.ts` (los cuatro integradores; select de ítems)
- Test: `src/contabilidad/services/apertura-items.spec.ts` (puro) y `src/contabilidad/services/integracion-apertura-items.spec.ts`

**Interfaces:**
- Consumes: `ResolvedorMapeo.cuenta(concepto, dimsItem)`, `tieneReglasDeItem`, `prepararCategorias` (Task 3).
- Produces:

```ts
export type ItemNeto = { neto: number; dims: DimensionesDocumento };
/** Agrupa los netos por la cuenta que resuelve cada ítem y ajusta el redondeo para que la suma sea exactamente `totalTasa`. */
export async function abrirPorCuenta(items: ItemNeto[], totalTasa: number, cuentaDe: (dims: DimensionesDocumento) => Promise<string>, decimales: number): Promise<Map<string, number>>;
```

- [ ] **Step 1: Tests puros que fallan**

```ts
it('agrupa por cuenta y conserva el total exacto', async () => {
  const m = await abrirPorCuenta(
    [{ neto: 100, dims: { CATEGORIA_PRODUCTO: 'serv' } }, { neto: 50, dims: { CATEGORIA_PRODUCTO: 'merc' } }, { neto: 25, dims: { CATEGORIA_PRODUCTO: 'serv' } }],
    175, async (d) => (d.CATEGORIA_PRODUCTO === 'serv' ? 'c-serv' : 'c-merc'), 0);
  expect(Object.fromEntries(m)).toEqual({ 'c-serv': 125, 'c-merc': 50 });
});
it('[RF-4] el redondeo va a la línea mayor y la suma da el total de la tasa', async () => {
  const m = await abrirPorCuenta(
    [{ neto: 33.333, dims: { TIPO_ITEM: 'A' } }, { neto: 33.333, dims: { TIPO_ITEM: 'B' } }, { neto: 33.334, dims: { TIPO_ITEM: 'B' } }],
    100, async (d) => `c-${d.TIPO_ITEM}`, 2);
  expect([...m.values()].reduce((a, b) => a + b, 0)).toBeCloseTo(100, 10);
  expect(m.get('c-B')).toBeCloseTo(66.67, 10);
});
it('[RF-3] ítem sin categoría va a la cuenta que resuelva sin dimensiones de ítem', async () => {
  const m = await abrirPorCuenta([{ neto: 10, dims: {} }, { neto: 5, dims: { CATEGORIA_PRODUCTO: 'serv' } }], 15,
    async (d) => (d.CATEGORIA_PRODUCTO ? 'c-serv' : 'c-def'), 0);
  expect(Object.fromEntries(m)).toEqual({ 'c-def': 10, 'c-serv': 5 });
});
it('si los netos no suman el total (ítems en otra moneda redondeados), se prorratea al total', async () => {
  const m = await abrirPorCuenta([{ neto: 60, dims: { TIPO_ITEM: 'A' } }, { neto: 40, dims: { TIPO_ITEM: 'B' } }], 101, async (d) => `c-${d.TIPO_ITEM}`, 0);
  expect([...m.values()].reduce((a, b) => a + b, 0)).toBe(101);
});
```

Integración (`integracion-apertura-items.spec.ts`): factura con 3 ítems de dos categorías (una subcategoría de la categoría de la regla) y una regla `CATEGORIA_PRODUCTO EN [padre]` en `VENTAS_10` → dos líneas de ventas 10% (regla y defecto) que suman `base10`; sin reglas de ítem → **no** se consultan los ítems (`factura_det.findMany` no llamado) y sale la línea única de hoy; NC de venta con sus propios ítems; compra con `INVENTARIO`; compra de importación con `IMPORTACION_COMPRA`; **[RF-4]** venta en USD: la suma de las líneas abiertas en moneda es igual a `base10` en moneda.

- [ ] **Step 2: Correr y ver que fallan.**

- [ ] **Step 3: Implementar** `apertura-items.ts`:

```ts
const redondear = (n: number, d: number) => Math.round(n * 10 ** d) / 10 ** d;

export async function abrirPorCuenta(items: ItemNeto[], totalTasa: number, cuentaDe: (dims: DimensionesDocumento) => Promise<string>, decimales: number) {
  const sumaNetos = items.reduce((a, i) => a + i.neto, 0);
  const factor = sumaNetos > 0 ? totalTasa / sumaNetos : 0; // prorrateo al total de la cabecera
  const porCuenta = new Map<string, number>();
  for (const it of items) {
    const cuenta = await cuentaDe(it.dims);
    porCuenta.set(cuenta, (porCuenta.get(cuenta) ?? 0) + it.neto * factor);
  }
  for (const [c, v] of porCuenta) porCuenta.set(c, redondear(v, decimales));
  const diferencia = redondear(totalTasa - [...porCuenta.values()].reduce((a, b) => a + b, 0), decimales);
  if (diferencia !== 0 && porCuenta.size > 0) {
    const mayor = [...porCuenta.entries()].sort((a, b) => b[1] - a[1])[0][0];
    porCuenta.set(mayor, redondear(porCuenta.get(mayor)! + diferencia, decimales));
  }
  return porCuenta;
}
```

En cada integrador, para cada concepto de ventas/costo con `res.tieneReglasDeItem(concepto)`:
1. Leer los ítems del propio documento (`factura_det` / `nota_credito_det` / `compra_det` / `nota_credito_compra_det`) con `productos: { select: { tipo: true, rubro_id: true, categoria_id: true, categorias: { select: { rubro_id: true } } } }` (verificar nombres de relación en el schema) y su tasa (`dtasiva` en venta; `porcentaje_iva` en compra) y neto (venta: base gravada del ítem; compra: `subtotal - monto_iva`).
2. `await res.prepararCategorias(ids de categoría)`.
3. Por tasa: `abrirPorCuenta(itemsDeEsaTasa, baseDeEsaTasa, (dims) => res.cuenta(concepto, dims), esPYG ? 0 : 2)` → una línea por cuenta con la misma descripción de hoy ("Ventas 10%").
4. Dimensiones de ítem: `{ CATEGORIA_PRODUCTO: categoria_id, RUBRO: producto.rubro_id ?? categoria.rubro_id, TIPO_ITEM: producto.tipo }`; ítem sin producto → `{}`.
5. Sin reglas de ítem para el concepto: el código de hoy, sin leer ítems.

- [ ] **Step 4: Correr** — specs nuevos + `npx jest src/contabilidad src/contabilidad-conciliacion` → PASS.

---

### Task 7: API de reglas, auditoría, vista previa, probar y Salud contable

**Files:**
- Create: `src/contabilidad/services/reglas-mapeo.service.ts`, `src/contabilidad/controllers/reglas-mapeo.controller.ts`, `src/contabilidad/dto/regla-mapeo.dto.ts`
- Modify: `src/contabilidad/contabilidad.module.ts` (provider + controller)
- Modify: `src/contabilidad/controllers/mapeo-cuentas.controller.ts` (`POST vista-previa`, `POST probar`)
- Modify: `src/contabilidad-conciliacion/recontabilizacion.service.ts` (`simular` acepta `{ ids?, incluirBorradores?, ultimos? }`), `src/contabilidad-conciliacion/integrador-sombra.ts` (`LineaSimulada` + traza; `crearIntegradorSombra` acepta `opcionesMapeo`)
- Modify: `src/contabilidad-conciliacion/salud-contable.service.ts` (`mapeo_pendiente`)
- Test: `src/contabilidad/services/reglas-mapeo.service.spec.ts`, `src/contabilidad-conciliacion/vista-previa.spec.ts`, ajuste en `salud-contable.service.spec.ts`

**Interfaces:**
- Consumes: Tasks 1–6.
- Produces (endpoints, todos con `@RequirePermission('CONTABILIDAD', …)`):

| Método y ruta | Permiso | Body / respuesta |
|---|---|---|
| `GET contabilidad/mapeo-reglas?concepto=` | VER | lista con `frase`, `cuenta {codigo, descripcion}`, constancia (`creado_por_nombre`, `activado_por_nombre`, fechas) |
| `POST contabilidad/mapeo-reglas` | EDITAR | `{ concepto, condiciones, modo?, cuenta_id?, vigente_desde, descripcion? }` → regla en BORRADOR, `orden` = último + 1 |
| `PUT contabilidad/mapeo-reglas/:id` | EDITAR | mismos campos; solo BORRADOR o ACTIVA (una ACTIVA editada vuelve a BORRADOR y pide activar de nuevo) |
| `POST contabilidad/mapeo-reglas/:id/activar` | EDITAR | → ACTIVA, `activado_por/at`; valida cuenta usable y `CONCEPTOS_CON_MODO` |
| `POST contabilidad/mapeo-reglas/:id/retirar` | EDITAR | → RETIRADA, `vigente_hasta` = hoy, `retirado_por/at` |
| `DELETE contabilidad/mapeo-reglas/:id` | EDITAR | solo si nunca estuvo activa (`activado_at` null); si no, 400 "retirala" |
| `PUT contabilidad/mapeo-reglas/orden` | EDITAR | `{ concepto, ids: string[] }` → reasigna `orden` 1..n |
| `POST contabilidad/mapeo-reglas/probador` | VER | `{ concepto, dimensiones, fecha?, incluirBorradores? }` → `{ cuentaId, cuenta, traza }` o `{ falta: { motivo, mensaje } }` |
| `GET contabilidad/mapeo-reglas/dimensiones` | VER | `{ porOrigen: DIMENSIONES_POR_ORIGEN, valores: { SUCURSAL: [{id, nombre}], MONEDA: […], TIPO_PROVEEDOR: […], TIPO_CLIENTE: [distintos], CANAL: ['POS','FACTURA'], CATEGORIA_PRODUCTO: [{id, nombre, padre_id}], RUBRO: […], TIPO_ITEM: [distintos de productos.tipo] } }` |
| `POST contabilidad/mapeo-cuentas/vista-previa` | VER | `{ origenTipo, origenId, incluirBorradores? }` → `{ vigente: lineas, saldria: lineas (con traza), estado: IGUAL/CAMBIA/ERROR, error? }` |
| `POST contabilidad/mapeo-cuentas/probar` | VER | `{ origenTipo, ultimos: 50, incluirBorradores? }` → `{ iguales, cambian, error, items: [...] }` |

Ajuste al spec (§6.2 dice "últimos 50 del concepto"): se prueba por **tipo de documento**, porque la simulación trabaja por origen; la pantalla ofrece primero los tipos de documento que usan el concepto (derivados del catálogo de asientos). Anotarlo en "Ajustes durante la implementación" del spec (Task 10).

- [ ] **Step 1: Tests que fallan** — servicio de reglas: crear valida condiciones (`validarCondiciones`) y concepto existente en `MAPEO_DEFAULT`/mapeo de la empresa, modo SUMAR solo en `CONCEPTOS_CON_MODO`; activar con cuenta desactivada → 400; activar deja constancia y audita `CONT_REGLA_ACTIVAR` con `new_value` completo (concepto, condiciones, `cuenta_codigo`, modo, orden, vigencia); retirar no borra y cierra vigencia; borrar una regla que estuvo activa → 400; reordenar audita `CONT_REGLA_ORDEN`; todas las consultas filtran por `empresa_id` (regla de otra empresa → 404). Vista previa: documento de otra empresa → 404; no escribe (prisma real con `create`/`update` espiados sin llamadas); con `incluirBorradores` aplica la regla borrador; la respuesta trae la traza por línea. Salud contable: una regla ACTIVA con cuenta desactivada aparece en `mapeo_pendiente` como ERROR con ruta `/contabilidad?tab=mapeo`.

- [ ] **Step 2: Correr y ver que fallan.**

- [ ] **Step 3: Implementar.**
- `ReglasMapeoService` con los métodos de la tabla; auditoría con el mismo formato que `CONT_MAPEO_CAMBIO` (`audit_logs.create({ data: { empresa_id, user_id, action, entity_type: 'cont_mapeo_reglas', entity_id, old_value, new_value, descripcion } })`); después de activar/retirar/editar, `avisos.sincronizar(empresaId)` (en try/catch con log, como `actualizarBulk`).
- `RecontabilizacionService.simular(empresaId, origenTipo, filtros, opciones?: { ids?: string[]; incluirBorradores?: boolean; ultimos?: number })`: `ids` → `candidatos(…, ids)`; `ultimos` → los N más recientes (`orderBy created_at desc`, `take`); `crearIntegradorSombra(servicio, prismaSombra, colector, { opcionesMapeo: { incluirBorradores } })` setea `opcionesMapeo` en la sombra. El colector conserva `mapeo_concepto`, `mapeo_regla_id`, `mapeo_nivel` en `LineaSimulada`.
- `vista-previa`: valida que el documento sea de la empresa, llama `simular` con `ids: [origenId]` y devuelve vigente vs. saldría (usar `fotoAsientoDeDocumento` para el vigente con traza). Documento sin asiento vigente: responder `{ vigente: null, saldria, estado }` (simular el integrador directamente con la sombra).
- `probar`: `simular` con `ultimos` (máx. 100) y resumen.
- Salud contable: en `mapeo_pendiente`, sumar `cont_mapeo_reglas` ACTIVA cuyo `cuenta` no es usable (`esCuentaUsable` de `mapeo-usable.ts`).

- [ ] **Step 4: Correr** — specs nuevos + `npx jest src/contabilidad src/contabilidad-conciliacion` → PASS; tsc = base.

---

### Task 8: Frontend — excepciones en Mapeo de cuentas

**Files:**
- Create: `src/components/contabilidad/ReglasConceptoPanel.jsx`, `ReglaDialog.jsx`, `ProbadorReglasDialog.jsx` (ERP)
- Modify: `src/components/contabilidad/MapeoCuentasTab.jsx`, `src/api/contabilidad.service.js`, `src/tanstack/ContabilidadStack.jsx`

**Interfaces:**
- Consumes: endpoints de la Task 7.
- Produces (hooks): `useReglasMapeoQuery(concepto?)`, `useDimensionesReglasQuery()`, `useCrearReglaMutation`, `useEditarReglaMutation`, `useActivarReglaMutation`, `useRetirarReglaMutation`, `useBorrarReglaMutation`, `useOrdenReglasMutation`, `useProbadorReglaMutation`. Todas las mutaciones invalidan `["mapeo-reglas"]`, `["mapeo-cuentas"]` y `["asientos-ejemplo"]`.

- [ ] **Step 1: API y hooks** — funciones en `contabilidad.service.js` con el mismo cliente `api` y estilo que `getMapeoCuentas` (rutas de la Task 7); hooks en `ContabilidadStack.jsx` con el patrón de `useConfirmarMapeoMutation`.

- [ ] **Step 2: `ReglasConceptoPanel`** — props `{ concepto, canConfig }`. Botón "Excepciones (n)" que despliega la lista: cada regla en una fila con la `frase`, chip de estado (Borrador / Activa / Retirada), vigencia (`fmtFechaCalendario`), "creada por / activada por", y acciones (subir/bajar → `useOrdenReglasMutation`; Editar; Activar con confirmación "La regla se aplica desde {vigente_desde} y queda registrada a tu nombre"; Retirar; Borrar solo si nunca estuvo activa; Duplicar). Lista vacía: `EmptyState` con CTA "Agregar excepción".

- [ ] **Step 3: `ReglaDialog`** — filas de condición: `Seleccion` (o el select con buscador del kit disponible en la rama; si no existe `Seleccion`, el mismo componente que use `MapeoCuentasTab` hoy) para dimensión, operador ("es uno de" / "no es ninguno de") y valores (multi; categoría con jerarquía indentada por `padre_id`). Aviso con `InlineValidationBanner` si la dimensión no está en ninguna de las `porOrigen` de los documentos que usan el concepto (derivar con el catálogo de asientos: situaciones cuyas líneas usan el concepto → `documento`; si no se puede derivar, no avisar). Cuenta con el mismo Autocomplete de cuentas de `MapeoCuentasTab`; modo sumar solo si el concepto `conModo`. Vigencia desde (date) y nota. Guarda como borrador.

- [ ] **Step 4: `ProbadorReglasDialog`** — elige valores de dimensiones y fecha; muestra "Usaría {cuenta} — {Regla n.º X: frase | Cuenta por defecto}" o la falta de mapeo con su mensaje; casilla "incluir borradores".

- [ ] **Step 5: Integrar en `MapeoCuentasTab`** — debajo de cada concepto, `<ReglasConceptoPanel concepto={item.key} canConfig={canConfig} />`; botón "Probar cuenta" por concepto que abre el probador.

- [ ] **Step 6: Verificar** — `curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5173/src/components/contabilidad/<archivo>.jsx` → 200 para cada archivo; eslint de los archivos tocados sin errores nuevos.

---

### Task 9: Frontend — vista previa, catálogo y "¿Por qué esta cuenta?"

**Files:**
- Create: `src/components/contabilidad/VistaPreviaDocumentoDialog.jsx` (ERP)
- Modify: `src/components/contabilidad/MapeoCuentasTab.jsx` (botón "Probar con un documento"), `AsientosEjemploPanel.jsx` ("+ n excepciones"), `AsientosTab.jsx` (detalle del asiento)
- Modify (backend): `previsualizacionAsientos` en `mapeo-cuentas.service.ts` devuelve `reglas_por_concepto: Record<concepto, Array<{ frase, estado }>>` (solo ACTIVA); el endpoint de detalle de asiento (`asientos.service.ts` ~65, `include` de `lineas`) agrega `mapeo_concepto`, `mapeo_nivel`, `mapeo_regla: { orden, condiciones, activado_por, activado_at }`
- Test (backend): ajuste en `catalogo-asientos.spec.ts` (con una regla activa, `reglas_por_concepto.VENTAS_10` tiene su frase) y en el spec del detalle de asiento si existe

- [ ] **Step 1: Backend** — test que falla para `reglas_por_concepto` y para la traza en el detalle; implementar; `npx jest src/contabilidad` → PASS.

- [ ] **Step 2: `VistaPreviaDocumentoDialog`** — tipo de documento (`Seleccion` con los orígenes de `DIMENSIONES_POR_ORIGEN` con nombres legibles) y búsqueda por número (endpoint de listado existente de cada módulo, o un buscador nuevo `GET contabilidad/mapeo-cuentas/documentos?origenTipo=&q=` si no hay uno común: agregarlo en esta tarea con test). Dos columnas: asiento vigente y asiento que saldría, líneas con cuenta, debe, haber y la traza en texto ("Regla n.º 2", "Por defecto", "Ficha del proveedor", "Medio de pago"); diferencias resaltadas con los tokens del theme. Casilla "incluir borradores". Botón "Probar contra los últimos 50" → resumen (iguales / cambian / no se podrían asentar) y tabla por documento.

- [ ] **Step 3: Catálogo** — en `AsientosEjemploPanel`, si `reglas_por_concepto[linea.concepto]?.length`, mostrar "+ n excepciones" con tooltip que lista las frases.

- [ ] **Step 4: Detalle del asiento** — en `AsientosTab`, en cada línea del detalle, ícono "¿Por qué esta cuenta?" con popover: concepto (con su etiqueta), nivel, regla (frase, activada por y fecha); `mapeo_nivel` null → "Anterior a la traza".

- [ ] **Step 5: Verificar** — transform 200 de cada archivo; eslint.

---

### Task 10: Documentación, guion del video y verificación en DOBA local

**Files:**
- Modify: `novasispy-backend-api/docs/guias/guia-contabilidad.md`, `novasispy-backend-api/src/ayuda-ia/ingesta/seed-catalogo.ts`
- Modify: `novasispy-erp/docs/video-guias/contabilidad-guion.md` (Parte 9 y lo que haya cambiado)
- Modify: `novasispy-backend-api/docs/superpowers/specs/2026-10-13-reglas-cuenta-por-dimension-design.md` (sección "Ajustes durante la implementación" si los hubo)

- [ ] **Step 1: Guías** — en `guia-contabilidad.md`, sección "Excepciones por sucursal, moneda, categoría…": qué es una regla, el orden, la vigencia, borrador → probar → activar, el probador, la vista previa, "probar contra los últimos 50", "¿Por qué esta cuenta?", que activar no recontabiliza (Rehacer asientos). Nombres de botones verificados contra el código. `seed-catalogo.ts`: actualizar la descripción de `contabilidad/mapeo`.

- [ ] **Step 2: Guion del video** — en `contabilidad-guion.md` marcar como disponibles los puntos de la Parte 9 y sumar cualquier pantalla o caso nuevo.

- [ ] **Step 3: Verificación en DOBA local**
  1. Sin reglas: Conciliación → Rehacer asientos → Simular para facturas de venta, compras, gastos, recibos, órdenes de pago y movimientos de tesorería → **0 diferencias**. Anotar los conteos.
  2. Crear una regla de prueba `VENTAS_10, MONEDA EN [USD] → una cuenta de ventas distinta` en borrador; "Probar con un documento" sobre una factura en USD (o PYG si no hay USD: entonces regla por `CANAL`) → la línea de ventas cambia y muestra "Regla n.º 1"; "Probar contra los últimos 50" → solo cambian los que cumplen.
  3. Regla por categoría en `VENTAS_10` → la vista previa de una factura con ítems de esa categoría abre la línea de ventas en dos; los totales por tasa no cambian.
  4. Activar, cargar (o regenerar) un documento → el asiento tiene traza; el detalle muestra "¿Por qué esta cuenta?".
  5. Retirar y borrar las reglas de prueba; dejar DOBA como estaba.
  Recorrido con Playwright (memoria del entorno: `dispatchEvent('click')`, quitar `.tsqd-parent-container`, `storageState` por el límite de login) con capturas.

- [ ] **Step 4: Suite final** — `npx jest src/contabilidad src/contabilidad-conciliacion src/alertas-empresa src/rrhh src/rendicion-viaticos src/tesoreria` (preexistente conocido: `liquidaciones.controller.spec`) y `npx jest --rootDir . scripts/data_script/precarga-mapeo-sin-decisiones.spec.ts`; tsc = 24.

---

## Despliegue (checklist para el usuario)

1. `pg_dump` → `prisma migrate deploy` (`20261020000000_mapeo_reglas`) → build → reinicio. No hay precarga: sin reglas nada cambia.
2. Frontend.
3. Re-ingesta de NovaIA (`POST /api/v1/ayuda-ia/config/ingesta/run {"source":"docs"}` con usuario holding).
4. Al final del trabajo contable: grabar el video según `novasispy-erp/docs/video-guias/contabilidad-guion.md`.
