Servicios de Finanzas

Propósito

El dominio Finanzas del Orchestrator vive en orchestrator/src/domain/financieros/ y coordina la operación bancaria del tenant: cuentas bancarias, movimientos, libro banco, conciliación, anticipos de proveedor y préstamos.

El enfoque de esta sección es dev/orchestrator. Por lo tanto, documenta servicios, routers, repositorios, eventos y reglas de validación. La lectura contable general se mantiene en Finanzas · contable y los estados financieros se documentan en Balances.

Mapa del Dominio

flowchart TB
  subgraph ROUTES["routes/financieros/"]
    IDX["index.ts<br/>monta sub-routers"]
    RB["bancos.ts"]
    RM["movimientos.ts"]
    RC["conciliacion.ts"]
    RA["anticipos.ts"]
    RP["prestamos.ts"]
    RL["libro-banco.ts"]
    RCM["categorias-movimiento.ts"]
    RR["resoluciones-conciliacion.ts"]
  end

  subgraph DOMAIN["domain/financieros/"]
    FS["FinancierosService"]
    MS["MovimientosService"]
    CS["ConciliacionService"]
    AS["AnticiposProveedorService"]
    PS["PrestamosService"]
    FR["FinancierosRepository"]
    MR["MovimientosRepository"]
    CR["ConciliacionRepository"]
    AR["AnticiposProveedorRepository"]
    PR["PrestamosRepository"]
    RCR["ResolucionesConciliacionRepository"]
    TYPES["types.ts<br/>(DTOs e interfaces)"]
    LST["listeners.ts"]
  end

  subgraph DB["Mother · schema financieros"]
    CATB[("categorias_bancarias")]
    BAN[("bancos")]
    MOV[("movimientos_bancarios")]
    CATM[("categorias_movimiento")]
    CON[("conciliacion_bancaria")]
    ANT[("aplicaciones_anticipos_proveedor")]
    PRE[("prestamos")]
    AMO[("amortizacion_cuotas")]
    RES[("resoluciones_conciliacion")]
  end

  subgraph EXT["Schemas externos consumidos"]
    PC[("administracion.plan_contable")]
    CVD[("operaciones_sii.compras_ventas_detalle")]
    F29[("declaraciones.declaraciones_f29")]
    HON[("remuneraciones.honorarios")]
  end

  subgraph EVENTS["domain/common/events"]
    BUS["DomainEventBus"]
  end

  IDX --> RB
  IDX --> RM
  IDX --> RC
  IDX --> RA
  IDX --> RP
  IDX --> RL
  IDX --> RCM
  IDX --> RR

  RB --> FS
  RCM --> FS
  RL --> FS
  RM --> MS
  RC --> CS
  RA --> AS
  RP --> PS
  RR --> CS

  FS -.usa.-> FR
  MS -.usa.-> MR
  MS -.valida categorías.-> FR
  CS -.usa.-> CR
  CS -.lee movimientos.-> MR
  CS -.categoriza.-> FR
  CS -.anticipos.-> AR
  CS -.resoluciones.-> RCR
  AS -.usa.-> AR
  PS -.usa.-> PR

  FR --> CATB
  FR --> BAN
  FR --> CATM
  FR --> CON
  MR --> MOV
  CR --> CON
  AR --> ANT
  PR --> PRE
  PR --> AMO
  RCR --> RES

  FR -.valida cuenta.-> PC
  CR -.valida documentos.-> CVD
  CR -.pago F29.-> F29
  CR -.pago honorarios.-> HON

  MS -- "outbox.queue<br/>movimiento:vinculado" --> BUS
  CS -- "outbox.queue<br/>conciliacion:matched" --> BUS
  CS -- "outbox.queue<br/>conciliacion:desconciliada" --> BUS
  BUS -- "compra:contabilizada" --> LST
  LST -- "solicitarMatch()" --> CS

Servicios

Servicio	Responsabilidad
FinancierosService	Mantiene categorías bancarias, bancos, categorías de movimiento, libro banco y lectura base de conciliación. Valida cuentas contra administracion.plan_contable cuando corresponde.
MovimientosService	Lista, crea, edita y elimina movimientos bancarios manuales. Valida ABONO/CARGO, monto positivo, estado PENDIENTE para cambios destructivos y dispara ETL BancoEstado desde ruta.
ConciliacionService	Vincula movimientos con compras/ventas, F29 u honorarios; registra conciliación manual; desconcilia; marca incobrables; castiga contra estimación; compensa documentos cliente/proveedor.
AnticiposProveedorService	Expone anticipos disponibles de proveedor y aplica saldos contra facturas de compra pendientes. Requiere categoría ANTICIPO-PROV con cuenta contable configurada.
PrestamosService	Registra préstamos, genera tabla de amortización francesa, lista cuotas y marca cuotas pagadas. Bloquea eliminación si existen cuotas pagadas.

FinancierosService Catálogos financieros, bancos, categorías de movimiento, libro banco y lectura base de conciliación.

MovimientosService Movimientos bancarios manuales, validación de estados, categoría contable y puente ETL BancoEstado.

ConciliacionService Vinculación bancaria, conciliación manual, anticipos, compensaciones, incobrables y eventos.

AnticiposProveedorService Aplicación de anticipos de proveedor contra documentos de compra pendientes.

PrestamosService Préstamos, amortización francesa, cuotas y bloqueo de eliminación con pagos.

Financieros API Endpoints HTTP del dominio: bancos, movimientos, conciliación, anticipos, préstamos y libro banco.

BaseService Contrato compartido de transacciones, validaciones, outbox y resultados de servicio.

Islas de Finanzas Superficie frontend que consume los servicios financieros desde Sevastopol.

Routers HTTP

El router principal routes/financieros/index.ts aplica authenticateToken una vez y monta sub-routers especializados. Todas las rutas quedan bajo /api/financieros.

Router	Familias de endpoints	Servicio principal
bancos.ts	/categorias, /bancos	FinancierosService
categorias-movimiento.ts	/categorias-movimiento	FinancierosService
libro-banco.ts	/libro-banco?bancoId&anio&mes	FinancierosService
movimientos.ts	/movimientos, /movimientos-sistema, /movimientos/:id, /movimientos/etl	MovimientosService
conciliacion.ts	/conciliacion/*	ConciliacionService
anticipos.ts	/anticipos-proveedor/*	AnticiposProveedorService
prestamos.ts	/prestamos/*	PrestamosService
resoluciones-conciliacion.ts	/resoluciones-conciliacion	ConciliacionService

Reglas de Conciliación

ConciliacionService.vincular(ctx, dto) es el flujo central. Valida que exista el movimiento bancario, que el total asignado no exceda el monto disponible y que los documentos estén en un estado conciliable.

Contrapartida	Validación	Efecto
COMPRA_VENTA	Documento en operaciones_sii.compras_ventas_detalle con estado CONTABILIZADO.	Marca documentos como pagados y actualiza estados de conciliación.
DECLARACION	F29 con total_a_pagar > 0 y estado distinto de ANULADO.	Registra fecha_pago con la fecha del movimiento bancario.
HONORARIO	Honorario en estado CONTABILIZADO.	Cambia a PAGADA, registra fecha_pago_real y forma_pago.
MANUAL	Movimiento con categoría contable y sin conciliaciones parciales previas.	Cierra el movimiento como conciliado sin documento externo.

La forma de pago se deriva del banco: si tipo_cuenta = 'CAJA', se usa EFECTIVO; en los demás casos se usa TRANSFERENCIA.

Categorías Automáticas

Cuando el movimiento no tiene categoría manual, conciliación asigna una categoría de movimiento por código de negocio:

Código	Caso
PAGO-IMP	Pago de declaración F29 sin otros documentos.
PAGO-HON	Pago de honorario sin otros documentos.
PAGO-PROV	Documento de compra/proveedor.
COBRO-CLTE	Documento de venta o boleta.
ANTICIPO-PROV	Movimiento de cargo tratado como anticipo a proveedor. Debe tener cuenta_contable_codigo.

Anticipos de proveedor

Los anticipos a proveedor solo se aplican contra documentos de compra. El servicio rechaza facturas clasificadas como venta, saldos negativos, saldos ya cubiertos o aplicaciones mayores al saldo pendiente.

Hooks Emitidos y Consumidos

Dirección	Evento	Trigger	Servicio
Emite	movimiento:vinculado	Movimiento manual creado o actualizado con categoría de movimiento; conciliación que asigna categoría automática.	MovimientosService, ConciliacionService
Emite	conciliacion:matched	Vinculación bancaria exitosa contra documentos comerciales.	ConciliacionService
Emite	conciliacion:desconciliada	Desconciliación de un movimiento.	ConciliacionService
Consume	compra:contabilizada	Compra contabilizada con formaPago transferencia o cheque.	listeners.ts llama ConciliacionService.solicitarMatch.

El outbox transaccional de BaseService.withTransaction encola los eventos dentro de la transacción y los publica al DomainEventBus después del COMMIT. Si la transacción falla, los eventos no se emiten.

Préstamos

PrestamosService.generarAmortizacion(ctx, prestamoId, overrides) calcula amortización francesa. La tasa anual se transforma a tasa periódica según periodicidad (MENSUAL, TRIMESTRAL, SEMESTRAL, ANUAL) y la última cuota ajusta el capital restante para evitar residuos por redondeo.

Operacion	Regla
Crear préstamo	Requiere banco, nombre, tipo, monto original, tasa, fecha inicio, vencimiento y número de cuotas.
Generar amortización	Borra cuotas previas del préstamo e inserta la nueva tabla calculada.
Pagar cuota	Requiere fecha de pago y monto pagado positivo.
Eliminar préstamo	Se bloquea si existen cuotas pagadas.

Schemas SQL Involucrados

Schema	Uso
financieros	Tablas propias del dominio: bancos, movimientos, categorías, conciliación, resoluciones, anticipos, préstamos y cuotas.
administracion	Validación de cuentas contables contra plan_contable.
operaciones_sii	Documentos comerciales conciliables y estados de pago.
declaraciones	F29 conciliable contra movimientos bancarios.
remuneraciones	Honorarios conciliables y cambio de estado a pagado.

Patrones Compartidos

Patrón	Cómo se aplica
BaseService.withTransaction(ctx, cb)	Mutaciones de bancos, categorías, movimientos, conciliación, anticipos y préstamos se ejecutan con transacción cuando cambian estado.
Repository estático	Cada repositorio expone métodos static async y se consume desde el servicio correspondiente.
Transactional Outbox	Movimientos y conciliación encolan eventos dentro de la TX y los publican post-COMMIT.
Observer	listeners.ts escucha compra:contabilizada y solicita match automático cuando la forma de pago es transferencia o cheque.
Validación defensiva	El servicio valida estado, monto disponible, cuentas contables, tipo de documento y cobertura antes de persistir.