Movimientos Service

MovimientosService gobierna los movimientos bancarios visibles para conciliación. Distingue movimientos importados o del sistema de movimientos manuales creados por el usuario.

Operaciones

Método	Uso
getMovimientos(ctx, filter)	Lista movimientos bancarios por banco, periodo, tipo, estado, texto, rango de monto e inclusión de anticipos proveedor.
createMovimiento(ctx, data)	Crea movimiento manual. Si incluye categoria_movimiento_id, encola movimiento:vinculado.
getMovimientosSistema(ctx, filter)	Lista documentos del sistema candidatos a conciliación.
updateMovimiento(ctx, id, data)	Edita movimiento manual solo si está PENDIENTE. Si asigna categoría, encola movimiento:vinculado.
deleteMovimiento(ctx, id)	Elimina movimiento solo si está PENDIENTE.
triggerEtlBancoEstado(ctx, data)	Valida bancoId y periodo; la ruta ejecuta el proceso Python.

Validaciones

Campo o estado	Regla
tipo_movimiento	Debe ser ABONO o CARGO.
monto	Debe ser mayor a 0.
categoria_movimiento_id	Si se informa, debe existir en FinancierosRepository.findCategoriaMovimientoById.
Edición	Solo se permite sobre movimientos en estado PENDIENTE.
Eliminación	Solo se permite sobre movimientos en estado PENDIENTE.
periodo ETL	Debe tener formato YYYY-MM.

Evento Emitido

movimiento:vinculado

El servicio lo encola dentro de withTransaction cuando un movimiento queda asociado a una categoría contable.

Trigger	Condición
createMovimiento	categoria_movimiento_id != null
updateMovimiento	categoria_movimiento_id != null

El payload se resuelve desde MovimientosRepository.findMovimientoVinculadoEventPayload, para no duplicar armado de datos en el servicio.

Puente ETL BancoEstado

La ruta /api/financieros/movimientos/etl valida el request y ejecuta python -m accounting_system.banco_estado_loader con --banco-id y --periodo, usando c:\dev\Nostromo como cwd.

Responsabilidad dividida

El servicio valida el comando lógico (bancoId, periodo), pero el proceso externo se lanza desde routes/financieros/movimientos.ts. Si se requiere auditoría o reintentos, esa frontera debe moverse a un servicio de infraestructura.

Endpoints

Método	Ruta	Service call
GET	/api/financieros/movimientos	getMovimientos(ctx, filter)
GET	/api/financieros/movimientos-sistema	getMovimientosSistema(ctx, filter)
POST	/api/financieros/movimientos	createMovimiento(ctx, body)
PUT	/api/financieros/movimientos/:id	updateMovimiento(ctx, id, body)
DELETE	/api/financieros/movimientos/:id	deleteMovimiento(ctx, id)
POST	/api/financieros/movimientos/etl	triggerEtlBancoEstado(ctx, body) y spawn Python desde la ruta