# Plan: Módulo Importaciones

## Objetivo

Implementar el módulo de importaciones para cubrir dos perfiles principales:

- **Autos Korea/Japón**: costeo específico por chasis, despacho aduanero, transferencia y escribanías.
- **Consumo masivo China**: costeo por lote/SKU, prorrateo de gastos compartidos e importación masiva de packing list/factura comercial.

El módulo debe calcular costo unitario real en Gs. a partir de componentes en USD/Gs., mantener trazabilidad por embarque, integrarse con contabilidad, inventario, tesorería/cuentas por pagar y dejar reportes operativos para liquidación y margen.

---

## Decisiones de diseño

| Decisión | Valor |
|---|---|
| Nombre del módulo backend | `ImportacionesModule` |
| Prefijo de tablas | `imp_` |
| Alcance inicial | Backend + contratos/API; UI solo como referencia funcional |
| Perfiles soportados | `AUTOS`, `CONSUMO_MASIVO` |
| Moneda base | PYG / Gs. |
| Moneda origen v1 | USD |
| Tipo de cambio | Usar `cont_tipo_cambio` cuando exista; permitir carga manual por componente |
| Costo autos | Costo específico por chasis |
| Costo consumo masivo | Costo unitario por SKU/línea de embarque |
| Prorrateo inicial | FOB |
| Prorrateo completo | FOB, peso, CBM, cantidad e igual |
| Contabilidad | Integración vía `ContabilidadIntegracionService`, respetando módulo Contabilidad activo |
| Inventario | Alta/actualización de stock con costo final calculado |
| Tesorería/CxP | Programar pagos a proveedor extranjero, despachante, transporte, puerto y escribanía |
| Parser PDF despachante | Fuera de alcance v1 |
| Tracking marítimo / AIS | Fase futura |
| Firma digital escribanía | Fase futura |

---

## Permisos del módulo `IMPORTACIONES`

### Códigos de permiso

| Código | Descripción | Roles sugeridos |
|---|---|---|
| `IMP_VER` | Ver embarques, ítems, costos y despachos | Operativo, Administración, Supervisor, Contador, Comercial |
| `IMP_CREAR_EMBARQUE` | Crear embarques e ítems | Operativo, Administración, Supervisor |
| `IMP_EDITAR_EMBARQUE` | Editar cabecera, ítems y datos operativos | Operativo, Administración, Supervisor |
| `IMP_CERRAR_DESPACHO` | Confirmar despacho y disparar cierre de costo | Administración, Supervisor |
| `IMP_GESTIONAR_COSTOS` | Crear/editar componentes de costo | Administración, Supervisor |
| `IMP_AUTORIZAR_GASTOS_EXTRA` | Autorizar gastos extras de gestión | Supervisor |
| `IMP_SELLAR_COSTO` | Sellar/desbloquear costo cerrado | Supervisor |
| `IMP_GESTIONAR_ESCRIBANIAS` | Crear escribanías, tarifarios y trámites | Administración, Supervisor |
| `IMP_VER_REPORTES` | Ver reportes del módulo | Supervisor, Contador, Gerente |
| `IMP_CONFIG` | Configurar conceptos, criterios y reglas del módulo | Admin, Supervisor |

### Asignación por rol sugerida

| Permiso | Admin | Supervisor | Administración | Operativo | Contador | Comercial |
|---|---|---|---|---|---|---|
| `IMP_VER` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `IMP_CREAR_EMBARQUE` | ✅ | ✅ | ✅ | ✅ | — | — |
| `IMP_EDITAR_EMBARQUE` | ✅ | ✅ | ✅ | ✅ | — | — |
| `IMP_CERRAR_DESPACHO` | ✅ | ✅ | ✅ | — | — | — |
| `IMP_GESTIONAR_COSTOS` | ✅ | ✅ | ✅ | — | — | — |
| `IMP_AUTORIZAR_GASTOS_EXTRA` | ✅ | ✅ | — | — | — | — |
| `IMP_SELLAR_COSTO` | ✅ | ✅ | — | — | — | — |
| `IMP_GESTIONAR_ESCRIBANIAS` | ✅ | ✅ | ✅ | — | — | — |
| `IMP_VER_REPORTES` | ✅ | ✅ | — | — | ✅ | — |
| `IMP_CONFIG` | ✅ | ✅ | — | — | — | — |

---

## Modelo de datos base

### Entidades principales sugeridas

| Tabla | Propósito |
|---|---|
| `imp_embarques` | Cabecera del expediente de importación |
| `imp_embarque_items` | Vehículos o SKUs incluidos en el embarque |
| `imp_conceptos_costo` | Catálogo configurable de conceptos de costo |
| `imp_componentes_costo` | Líneas de costo directas o compartidas |
| `imp_despachos` | Datos del despacho aduanero y liquidación |
| `imp_recostificaciones` | Historial de cambios de costo posterior al cierre |
| `imp_escribanias` | Maestro de escribanías para perfil autos |
| `imp_escribania_tarifarios` | Tarifas por tipo de trámite |
| `imp_tramites_transferencia` | Seguimiento de transferencia/patentamiento |
| `imp_sku_alias_proveedor` | Memoria SKU proveedor → SKU interno |

### Campos transversales

- `id` UUID como PK.
- `empresa_id` obligatorio en todas las tablas operativas.
- `created_at`, `updated_at`, `usuario` donde aplique.
- Relaciones con `proveedores`, `productos`, `clientes`, `factura_cab`, `cont_documentos`, `tes_movimientos` o CxP según corresponda.

### Estados sugeridos

**Embarque**

```text
BORRADOR → EN_TRANSITO → ARRIBADO → EN_DESPACHO → DESPACHADO → LIBERADO → CERRADO → SELLADO
```

**Ítem autos**

```text
PENDIENTE_EMBARQUE → EN_TRANSITO → ARRIBADO → DISPONIBLE → RESERVADO → VENDIDO → ENTREGADO
```

**Trámite de transferencia**

```text
ASIGNADO → EN_CURSO → FIRMADO → INSCRITO → ENTREGADO
```

### Conceptos de costo iniciales

| Grupo | Conceptos |
|---|---|
| Origen | FOB, inland origen, impuestos origen, comisión subasta/broker, puerto origen, inspección pre-embarque |
| Tránsito | flete marítimo, seguro internacional, BAF, CAF, THC destino |
| Aduana | arancel, IVA importación, ISC, INC, anticipo IRE, tasa ANA, honorarios despachante, manifiesto/DTA/MIC, almacén fiscal |
| Logística local | transporte puerto-depósito, descarga, estibaje, traslado entre depósitos, seguro local |
| Financieros/otros | gastos bancarios, diferencia de cambio, gastos extras de gestión, otros gastos operativos |

---

## Fases de implementación

### Fase 1 — Base del módulo y costeo simple

**Objetivo**

Tener el expediente de importación operativo con carga manual y costo unitario preliminar.

**Backend**

- Crear `ImportacionesModule` e incorporarlo en `AppModule`.
- Crear controllers/services separados por responsabilidad:
  - embarques
  - ítems del embarque
  - componentes de costo
  - costeo
- Crear modelos base Prisma:
  - `imp_embarques`
  - `imp_embarque_items`
  - `imp_conceptos_costo`
  - `imp_componentes_costo`
- Soportar perfiles `AUTOS` y `CONSUMO_MASIVO`.
- Implementar estados iniciales del embarque.
- Implementar CRUD básico de embarques e ítems.
- Validar chasis único para perfil autos.
- Permitir carga manual de líneas SKU para consumo masivo.

**Costeo**

- Calcular costos directos al ítem.
- Calcular costos compartidos prorrateados por FOB.
- Convertir USD a Gs. usando cotización cargada en el componente.
- Persistir `costo_unitario_gs` en cada ítem.

**Resultado esperado**

✔ Se puede crear un embarque, cargar autos/SKUs, cargar costos básicos y ver costo unitario preliminar en Gs.

---

### Fase 2 — Despacho aduanero, impuestos y prorrateo completo

**Objetivo**

Cerrar el despacho con liquidación aduanera y distribuir todos los costos relevantes.

**Backend**

- Crear `imp_despachos`.
- Registrar número de despacho, fecha, despachante, documentos y liquidación.
- Soportar más de un despacho por embarque si se requiere despacho parcial.
- Bloquear cierre si el embarque no tiene ítems.
- Bloquear cierre si hay componentes USD sin cotización.
- Bloquear componentes compartidos sin criterio de prorrateo.

**Costeo**

- Completar criterios:
  - `FOB`
  - `PESO`
  - `CBM`
  - `CANTIDAD`
  - `IGUAL`
- Incorporar arancel, IVA importación, ISC, INC, anticipo IRE, tasa ANA, honorarios despachante, gastos de puerto y transporte interno.
- Congelar `cotizacion_cierre` al cerrar despacho.
- Registrar `"Gastos extras de gestión"` como concepto genérico con motivo y usuario autorizante.

**Reglas importantes**

- Los gastos extras no deben exponer contraparte ni persona externa.
- Contablemente deben ir a una cuenta de gastos operativos varios.
- Solo roles con permiso `IMP_AUTORIZAR_GASTOS_EXTRA` pueden autorizarlos.

**Resultado esperado**

✔ El embarque puede pasar a `DESPACHADO` con costo unitario completo y trazable por componente.

---

### Fase 3 — Contabilidad, inventario y pagos

**Objetivo**

Integrar el cierre de importación con los módulos financieros y de stock.

**Contabilidad**

- Agregar método de integración de importaciones en `ContabilidadIntegracionService`.
- Verificar módulo Contabilidad activo antes de generar asiento.
- Generar documento contable idempotente con `origen_tipo = 'imp_embarques'`.
- Referenciar el embarque desde el asiento.

**Asiento contable base**

| Evento | DEBE | HABER |
|---|---|---|
| Cierre despacho | Inventario / Mercadería importada | Mercadería en tránsito |
| IVA importación | IVA Crédito importación | Proveedor / Despachante / Aduana |
| Gastos despacho | Inventario o gasto según concepto | Proveedor / Despachante |
| Gastos extras gestión | Gastos operativos varios | Caja/Banco/CxP |

**Inventario**

- Autos: alta o actualización de stock por chasis con costo específico.
- Consumo masivo: alta/actualización por SKU con costo unitario final.
- Si un SKU no está mapeado, dejar la línea en estado pendiente de mapeo y no liberar stock comercial.

**Tesorería / CxP**

- Programar pagos a:
  - proveedor extranjero
  - despachante
  - puerto/logística
  - transporte interno
  - escribanía cuando corresponda
- Mantener idempotencia para evitar duplicar pagos, movimientos o cuentas por pagar.

**Resultado esperado**

✔ Cerrar despacho impacta contabilidad, stock y pagos sin duplicaciones ante reintentos.

---

### Fase 4 — Escribanías y mapeo masivo de SKUs

**Objetivo**

Cubrir las particularidades de autos y consumo masivo.

**Autos — escribanías**

- Crear maestro de escribanías.
- Crear tarifario por tipo de trámite:
  - transferencia
  - transferencia con prenda
  - primera inscripción
  - chapa
  - cédula verde
- Crear trámites de transferencia vinculados a venta, vehículo y cliente.
- Congelar honorarios al asignar escribanía.
- Permitir escribanía ad-hoc cuando el cliente propone la suya.
- Emitir orden de trabajo con datos del vehículo y comprador.
- Alertar trámites con más de N días sin movimiento.

**Consumo masivo — SKUs**

- Implementar import Excel/CSV con `xlsx`.
- Definir plantilla estándar descargable.
- Parsear líneas válidas y reportar warnings por línea inválida.
- Crear tabla de memoria `imp_sku_alias_proveedor`.
- Resolver mapeo por coincidencia exacta proveedor+SKU.
- Dejar fuzzy match por descripción como P1 si excede el alcance.

**Resultado esperado**

✔ Autos tienen flujo de escribanía/trámite y consumo masivo permite carga masiva con memoria de SKU.

---

### Fase 5 — Recostificación, reportes y consolidación

**Objetivo**

Cerrar el módulo con ajustes posteriores, sellado y reportes operativos.

**Recostificación**

- Crear `imp_recostificaciones`.
- Cuando ingresa un gasto posterior al cierre:
  - registrar componente marcado como posterior
  - recalcular costo unitario
  - guardar costo anterior, costo nuevo, diferencial y motivo
  - generar ajuste contable si corresponde
- Si el ítem está en stock, ajustar valuación de inventario.
- Si el ítem ya fue vendido, registrar ajuste de resultado.

**Sellado**

- Implementar estado `SELLADO`.
- Bloquear nuevos componentes sin permiso `IMP_SELLAR_COSTO`.
- Registrar auditoría del desbloqueo o ajuste posterior.

**Reportes**

- Liquidación de embarque PDF/XLSX.
- Margen por embarque.
- Stock valuado al costo final.
- Trámites por escribanía.
- Gastos extras por período.
- Embarques con recostificación pendiente.

**Resultado esperado**

✔ El módulo soporta operación real, cierre contable y análisis posterior de rentabilidad.

---

## Integraciones

### Contabilidad

- Usar `cont_tipo_cambio` como referencia de tipo de cambio cuando exista.
- Usar `ContabilidadIntegracionService` para asientos automáticos.
- No generar asientos si la empresa no tiene módulo Contabilidad activo.
- Garantizar idempotencia por `origen_tipo` + `origen_id`.

### Inventario

- Autos se valorizan por costo específico por chasis.
- Consumo masivo se valoriza por costo unitario calculado.
- Los ítems pendientes de mapeo no deben quedar disponibles para venta.

### Tesorería / pagos proveedor

- Los componentes pagables deben poder generar programación de pago o CxP.
- No duplicar pagos ante recálculos o reintentos.
- Las diferencias de cambio deben quedar visibles para contabilidad.

### Facturación / ventas

- Autos vendidos deben vincular el trámite de transferencia a la venta.
- El costo final del ítem debe permitir reporte de margen.
- Los honorarios de escribanía trasladados al cliente no forman parte del costo del vehículo.

---

## Casos de prueba mínimos

### Costeo unitario

- Dado un embarque con componentes directos y compartidos por FOB, el costo por ítem coincide con el cálculo manual del Anexo A del PRD.
- Dado un componente compartido por CBM, el sistema distribuye el costo según el CBM total de cada ítem.
- Dado un componente compartido por peso, el sistema distribuye según peso total.
- Dado un componente compartido por cantidad, el sistema distribuye según cantidad.
- Dado un componente compartido igual, el sistema divide el costo entre la cantidad de ítems.

### Validaciones

- Chasis duplicado en perfil autos debe rechazarse.
- Componente en USD sin cotización debe rechazarse.
- Componente compartido sin criterio de prorrateo debe rechazarse.
- Cierre de despacho sin ítems debe rechazarse.
- Gasto extra sin motivo o autorizante debe rechazarse.

### Cierre e integraciones

- Cerrar despacho genera asiento contable una sola vez.
- Reintentar cierre no duplica asiento, stock ni pagos.
- Ítem consumo masivo sin SKU interno queda pendiente de mapeo.
- Ítem mapeado se libera a inventario con costo final.

### Recostificación

- Gasto posterior al cierre recalcula costo y guarda historial.
- Ítem en stock genera ajuste de valuación.
- Ítem vendido genera ajuste contable de resultado.
- Embarque sellado bloquea nuevos componentes sin permiso supervisor.

### Import Excel/CSV

- Archivo con líneas válidas crea ítems.
- Archivo con errores parciales muestra warnings y permite continuar con válidas.
- SKU proveedor previamente mapeado se resuelve automáticamente.
- SKU nuevo queda pendiente de mapeo manual.

---

## Preguntas abiertas

| # | Pregunta | Responsable | Bloqueante |
|---|---|---|---|
| Q-01 | ¿El ISC de vehículos se calcula según tabla SET vigente al año del modelo o a la fecha del despacho? | Contador / Producto | Sí |
| Q-02 | ¿Qué tipo de cambio se usa para IVA importación: despacho, pago o cierre del embarque? | Contador | Sí |
| Q-03 | ¿Se permitirá EUR u otra moneda además de USD en v1? | Producto | No |
| Q-04 | ¿El trámite de chapa será tipo de trámite independiente o sub-trámite de transferencia? | Producto | No |
| Q-05 | ¿Quién autoriza gastos extras: Administración o solo Supervisor? | Negocio | Sí |
| Q-06 | ¿Se cargará tabla NCM propia o se ingresarán arancel/ISC manualmente en v1? | Producto / Contador | Sí |
| Q-07 | ¿Se requiere despacho parcial en el primer release? | Producto | No |
| Q-08 | ¿Los honorarios de escribanía se cobran por factura propia, pago directo del cliente o ambos? | Negocio | No |

---

## Fuera de alcance v1

- Integración oficial con Sofia, MIC/DTA o sistemas aduaneros.
- Parser automático de liquidaciones PDF del despachante.
- Tracking marítimo en tiempo real.
- Subastas Korea/Japón en vivo.
- Firma digital con escribanías.
- E-commerce de vehículos.
- BI/ML para sugerir criterios de prorrateo.