Anulación fase 1: migración v42 + tipos de cola + payloads RNDC (9/28/29/32/54).

Cimientos para anular despachos ante el RNDC (el reverso LIFO de la creación):
- migracion_v42: columnas de motivo/observaciones/rndc_id/auditoría en manifiesto
  y remesa; documenta los estados anulacion_pendiente/anulado y el retorno de
  cumplido a 'pendiente' al anular el cumplido (re-cumplible).
- Cola: tipos anular_* en PROCESO (9/28/29/32/54) y ORDEN (reverso 70-100); el
  54 (cumplido inicial) queda sin slot fijo porque se inyecta de forma reactiva.
- Payloads puros para los 5 procesos, con test de XML exacto byte-a-byte contra
  el formato de referencia del Ministerio (35 tests en verde).

Sin orquestación ni UI todavía (fases 2 y 3).

Author: grachos

backend/src/modules/cola/cola.repo.ts

@@ -33,14 +33,28 @@ type Row = Record<string, any>;
 /** TTL for the nav-badge counts: high-frequency polls collapse to one query per window. */
 const BADGE_TTL_MS = 15_000;
 
-/** Send order per document type. */
+/**
+ * Send order per document type. Anulación is the reverse of creation (LIFO):
+ * you can only "pop" the top of the stack, so the anular_* orders run after the
+ * forward flow and in reverse (cumplido manifiesto → cumplido remesa →
+ * manifiesto → remesa). The `dependenciaPendiente()` check enforces this.
+ *
+ * anular_cumplido_inicial_remesa (proc 54) has no fixed slot: it is injected
+ * reactively at runtime with an orden just below the step that the RNDC says
+ * needs it — see the remediation logic in Phase 2.
+ */
 const ORDEN: Record<string, number> = {
   tercero: 10,
   vehiculo: 20,
   remesa: 30,
   manifiesto: 40,
   cumplido_remesa: 50,
   cumplido_manifiesto: 60,
+  anular_cumplido_manifiesto: 70,
+  anular_cumplido_remesa: 80,
+  anular_cumplido_inicial_remesa: 85, // nominal; real orden set on reactive injection
+  anular_manifiesto: 90,
+  anular_remesa: 100,
 };
 /** RNDC proceso per document type. */
 const PROCESO: Record<string, number> = {
@@ -50,6 +64,11 @@ const PROCESO: Record<string, number> = {
   manifiesto: 4,
   cumplido_remesa: 5,
   cumplido_manifiesto: 6,
+  anular_cumplido_manifiesto: 29,
+  anular_cumplido_remesa: 28,
+  anular_cumplido_inicial_remesa: 54,
+  anular_manifiesto: 32,
+  anular_remesa: 9,
 };
 
 async function fila(exec: Queryable, sql: string, params: unknown[]): Promise<Row | null> {
@@ -622,6 +641,84 @@ async function payloadCumplidoManifiesto(m: Row): Promise<string> {
   return xml;
 }
 
+// ---------- Anulación payloads (RNDC procesos 9 / 28 / 29 / 32 / 54) ----------
+//
+// Pure builders (NIT + motivo + observaciones as params) so they can be
+// characterization-tested for exact XML without a DB. Motivo codes differ per
+// proceso: cumplidos (28/29/54) usan D/O; manifiesto (32) D/S/R; remesa (9) D/S.
+// OBSERVACIONES es opcional en el RNDC pero siempre se emite (aunque vacía) para
+// calzar con los XML de referencia del Ministerio.
+
+/** Always-present <OBSERVACIONES> tag (matches the RNDC reference XMLs). */
+function tagObservaciones(obs: string): string {
+  return '<OBSERVACIONES>' + RndcClient.escaparXml(obs ?? '') + '</OBSERVACIONES>';
+}
+
+/** procesoid 29 — Anular Cumplido de Manifiesto. */
+export function payloadAnularCumplidoManifiesto(nit: string, numManifiesto: string, motivo: string, obs = ''): string {
+  const vars: RndcVars = {
+    NUMNITEMPRESATRANSPORTE: nit,
+    NUMMANIFIESTOCARGA: numManifiesto,
+    CODMOTIVOANULACIONCUMPLIDO: motivo, // D / O
+  };
+  return RndcClient.renderVariables(vars) + tagObservaciones(obs);
+}
+
+/** procesoid 28 — Anular Cumplido de Remesa. */
+export function payloadAnularCumplidoRemesa(nit: string, numRemesa: unknown, motivo: string, obs = ''): string {
+  const vars: RndcVars = {
+    NUMNITEMPRESATRANSPORTE: nit,
+    CONSECUTIVOREMESA: consecutivoRemesaRndc(numRemesa),
+    CODMOTIVOANULACIONCUMPLIDO: motivo, // D / O
+  };
+  return RndcClient.renderVariables(vars) + tagObservaciones(obs);
+}
+
+/**
+ * procesoid 54 — Anular Cumplido Inicial de Remesa. Se envía sólo de forma
+ * reactiva: cuando el RNDC rechaza un anular_cumplido_remesa / anular_remesa
+ * exigiendo que primero se anule el cumplido inicial (ver remediación, Fase 2).
+ */
+export function payloadAnularCumplidoInicialRemesa(
+  nit: string,
+  numRemesa: unknown,
+  numManifiesto: string,
+  motivo: string,
+  obs = '',
+): string {
+  const vars: RndcVars = {
+    NUMNITEMPRESATRANSPORTE: nit,
+    CONSECUTIVOREMESA: consecutivoRemesaRndc(numRemesa),
+    NUMMANIFIESTOCARGA: numManifiesto,
+    CODMOTIVOANULACIONCUMPLIDO: motivo, // D / O
+  };
+  return RndcClient.renderVariables(vars) + tagObservaciones(obs);
+}
+
+/** procesoid 32 — Anular Manifiesto de Carga. */
+export function payloadAnularManifiesto(nit: string, numManifiesto: string, motivo: string, obs = ''): string {
+  const vars: RndcVars = {
+    NUMNITEMPRESATRANSPORTE: nit,
+    NUMMANIFIESTOCARGA: numManifiesto,
+    MOTIVOANULACIONMANIFIESTO: motivo, // D / S / R
+  };
+  return RndcClient.renderVariables(vars) + tagObservaciones(obs);
+}
+
+/**
+ * procesoid 9 — Anular Remesa Terrestre de Carga. MOTIVOREVERSAREMESA='A'
+ * (anular; 'L' sería liberar para transbordo, que no usamos aquí).
+ */
+export function payloadAnularRemesa(nit: string, numRemesa: unknown, motivo: string, obs = ''): string {
+  const vars: RndcVars = {
+    NUMNITEMPRESATRANSPORTE: nit,
+    CONSECUTIVOREMESA: consecutivoRemesaRndc(numRemesa),
+    MOTIVOREVERSAREMESA: 'A',
+    MOTIVOANULACIONREMESA: motivo, // D / S
+  };
+  return RndcClient.renderVariables(vars) + tagObservaciones(obs);
+}
+
 // ---------- Reads for the monitor ----------
 
 const FILTROS: Record<string, string[]> = {

backend/test/anulacion_payloads.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Exact-XML characterization tests for the anulación payload builders
+ * (RNDC procesos 9 / 28 / 29 / 32 / 54). Byte-for-byte so a change in tag
+ * order/content is caught — these go to the RNDC and are irreversible.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  payloadAnularCumplidoManifiesto,
+  payloadAnularCumplidoRemesa,
+  payloadAnularCumplidoInicialRemesa,
+  payloadAnularManifiesto,
+  payloadAnularRemesa,
+} from '../src/modules/cola/cola.repo.js';
+
+const NIT = '8190041165';
+const MANIF = '0101211090';
+
+describe('anulación payloads', () => {
+  it('29 — anular cumplido manifiesto', () => {
+    expect(payloadAnularCumplidoManifiesto(NIT, MANIF, 'D', 'Error de digitación')).toBe(
+      '<NUMNITEMPRESATRANSPORTE>8190041165</NUMNITEMPRESATRANSPORTE>' +
+        '<NUMMANIFIESTOCARGA>0101211090</NUMMANIFIESTOCARGA>' +
+        '<CODMOTIVOANULACIONCUMPLIDO>D</CODMOTIVOANULACIONCUMPLIDO>' +
+        '<OBSERVACIONES>Error de digitación</OBSERVACIONES>',
+    );
+  });
+
+  it('28 — anular cumplido remesa (num_remesa se formatea a consecutivo de 10 dígitos)', () => {
+    expect(payloadAnularCumplidoRemesa(NIT, 'REM-00003', 'O', '')).toBe(
+      '<NUMNITEMPRESATRANSPORTE>8190041165</NUMNITEMPRESATRANSPORTE>' +
+        '<CONSECUTIVOREMESA>0000000003</CONSECUTIVOREMESA>' +
+        '<CODMOTIVOANULACIONCUMPLIDO>O</CODMOTIVOANULACIONCUMPLIDO>' +
+        '<OBSERVACIONES></OBSERVACIONES>',
+    );
+  });
+
+  it('54 — anular cumplido inicial remesa (incluye NUMMANIFIESTOCARGA)', () => {
+    expect(payloadAnularCumplidoInicialRemesa(NIT, '3', MANIF, 'D', 'x')).toBe(
+      '<NUMNITEMPRESATRANSPORTE>8190041165</NUMNITEMPRESATRANSPORTE>' +
+        '<CONSECUTIVOREMESA>0000000003</CONSECUTIVOREMESA>' +
+        '<NUMMANIFIESTOCARGA>0101211090</NUMMANIFIESTOCARGA>' +
+        '<CODMOTIVOANULACIONCUMPLIDO>D</CODMOTIVOANULACIONCUMPLIDO>' +
+        '<OBSERVACIONES>x</OBSERVACIONES>',
+    );
+  });
+
+  it('32 — anular manifiesto', () => {
+    expect(payloadAnularManifiesto(NIT, MANIF, 'S', '')).toBe(
+      '<NUMNITEMPRESATRANSPORTE>8190041165</NUMNITEMPRESATRANSPORTE>' +
+        '<NUMMANIFIESTOCARGA>0101211090</NUMMANIFIESTOCARGA>' +
+        '<MOTIVOANULACIONMANIFIESTO>S</MOTIVOANULACIONMANIFIESTO>' +
+        '<OBSERVACIONES></OBSERVACIONES>',
+    );
+  });
+
+  it('9 — anular remesa (MOTIVOREVERSAREMESA=A, no L)', () => {
+    expect(payloadAnularRemesa(NIT, 'REM-00003', 'D', '')).toBe(
+      '<NUMNITEMPRESATRANSPORTE>8190041165</NUMNITEMPRESATRANSPORTE>' +
+        '<CONSECUTIVOREMESA>0000000003</CONSECUTIVOREMESA>' +
+        '<MOTIVOREVERSAREMESA>A</MOTIVOREVERSAREMESA>' +
+        '<MOTIVOANULACIONREMESA>D</MOTIVOANULACIONREMESA>' +
+        '<OBSERVACIONES></OBSERVACIONES>',
+    );
+  });
+
+  it('escapa caracteres XML en las observaciones', () => {
+    expect(payloadAnularManifiesto(NIT, MANIF, 'D', 'Ruta A & B <x>')).toContain(
+      '<OBSERVACIONES>Ruta A &amp; B &lt;x&gt;</OBSERVACIONES>',
+    );
+  });
+});

database/migracion_v42_anulacion.sql

@@ -0,0 +1,25 @@
+-- migracion_v42_anulacion.sql
+-- Anulación de despachos ante el RNDC (procesos 9/28/29/32, y 54 reactivo).
+--
+-- Máquina de estados (estado_rndc es VARCHAR, no hace falta cambiar enum):
+--   remesa/manifiesto.estado_rndc:        aceptado -> anulacion_pendiente -> anulado
+--   remesa/manifiesto.cumplido_estado_rndc: aceptado -> (anular cumplido) -> pendiente
+--     (al anular el cumplido vuelve a 'pendiente' para poder re-cumplir y reenviar)
+--
+-- Columnas de auditoría/motivo de la anulación del documento base (procs 32/9).
+-- Los números de aceptación RNDC de los pasos intermedios (anular cumplido, etc.)
+-- quedan visibles en cola_envios.rndc_ingreso_id (monitor de la página Cola).
+
+ALTER TABLE manifiesto
+  ADD COLUMN IF NOT EXISTS anulacion_motivo        VARCHAR(1)   NULL COMMENT 'D=digitación S=cancelación R=cambio remesas',
+  ADD COLUMN IF NOT EXISTS anulacion_observaciones VARCHAR(255) NULL,
+  ADD COLUMN IF NOT EXISTS anulacion_rndc_id       VARCHAR(40)  NULL COMMENT 'ingreso RNDC de la anulación (proc 32)',
+  ADD COLUMN IF NOT EXISTS anulado_por             BIGINT UNSIGNED NULL COMMENT 'staff_users.id (auditoría, sin FK)',
+  ADD COLUMN IF NOT EXISTS anulado_at              DATETIME     NULL;
+
+ALTER TABLE remesa
+  ADD COLUMN IF NOT EXISTS anulacion_motivo        VARCHAR(1)   NULL COMMENT 'D=digitación S=cancelación',
+  ADD COLUMN IF NOT EXISTS anulacion_observaciones VARCHAR(255) NULL,
+  ADD COLUMN IF NOT EXISTS anulacion_rndc_id       VARCHAR(40)  NULL COMMENT 'ingreso RNDC de la anulación (proc 9)',
+  ADD COLUMN IF NOT EXISTS anulado_por             BIGINT UNSIGNED NULL COMMENT 'staff_users.id (auditoría, sin FK)',
+  ADD COLUMN IF NOT EXISTS anulado_at              DATETIME     NULL;