Módulo Tesorería

En una frase

Gestión del dinero del ayuntamiento: cuentas bancarias, órdenes de pago y pagos (con ficheros bancarios y SEPA), cobros, conciliación bancaria (extractos Norma 43), pagos a justificar, endosos, embargos, compensaciones, proyección de liquidez y el cálculo del PMP. Cierra las fases O→P (pagos) y DR→C (cobros) del ciclo presupuestario.

1. Propósito y alcance

Cuentas bancarias y caja: cuentas con su tipo, estado y cuenta contable.
Órdenes de pago y pagos: del registro de la obligación al pago efectivo, con bloqueos, ficheros bancarios y SEPA (pain.008 / Norma 34).
Cobros: ingresos, ligados a la deuda de Recaudación.
Conciliación bancaria: importación de extractos Norma 43, conciliación manual/asistida/automática por reglas y contabilización.
Pagos a justificar (PJ), endosos (cesión de crédito), embargos (diligencias) y compensaciones de deuda.
Proyección de liquidez: previsión de saldos futuros en tres escenarios, simulación what-if, previsiones manuales y alertas.
PMP: registro del periodo medio de pago a proveedores.

2. Estructura de archivos

app/modules/tesoreria/
├── tesoreria.py          # Blueprint principal (~4500 líneas): cuentas, pagos, cobros, ficheros, SEPA, dashboard
├── conciliacion.py       # Conciliación bancaria (~3000 líneas): extractos N43, sesiones, reglas, contabilización
├── pagos_justificar.py   # Pagos a justificar (RD 500/1990) + pj_scheduler.py (cron de aviso)
├── endosos.py            # Endosos / cesión de crédito
├── embargos.py           # Embargos / diligencias
├── compensaciones.py     # Compensación de deudas
├── proyeccion/           # Proyección de liquidez: motor, routes, historico, alertas_evaluador
├── servicios/            # norma43_parser, conciliacion_*, pmp_service, asientos_pj, ia_explicativa
├── models.py             # Modelos del módulo (cuentas, pagos, cobros, conciliación, proyección…)
└── constantes.py

Blueprints (todos registrados en app/__init__.py):

Blueprint	url_prefix
`tesoreria_bp`	`/api/tesoreria`
`conciliacion_bp`	`/api/tesoreria/conciliacion`
`pagos_justificar_bp`, `endosos_bp`, `embargos_bp`, `compensaciones_bp`, `proyeccion_bp`	`/api/tesoreria`

Dónde viven los modelos

Las áreas de cuentas, pagos, cobros, conciliación, ficheros, PMP y proyección tienen sus modelos en app/modules/tesoreria/models.py. Los modelos de pagos a justificar, endosos, embargos y compensaciones están en el app/models.py global (porque se relacionan 1:1 con una unidad documental del módulo Documental).

3. Modelos de datos

3.1 Cuentas y configuración

Modelo	Tabla	Propósito
`TesoreriaCuenta`	`tesoreria_cuenta`	Cuenta bancaria: `iban`/`bic`, `estado` (activa/restringida/bloqueada/cerrada), `permite_pagos`, vínculo a cuenta contable.
`TesoreriaCuentaTipo`	`tesoreria_cuenta_tipo`	Tipología funcional (GASTOS, RECAUDACION, NOMINAS…).
`TesoreriaConfiguracion`	`tesoreria_configuracion`	Parámetros clave-valor por entidad.

3.2 Órdenes de pago y pagos

Modelo	Tabla	Propósito
`TesoreriaOrdenPago`	`tesoreria_orden_pago`	Orden de pago: `tercero`, `importe`, `estado`, `regla_contable_codigo` + `datos_contables` (JSON), origen.
`TesoreriaOrdenPagoEstado`	`tesoreria_orden_pago_estado`	Auditoría de cambios de estado.
`TesoreriaMotivoBloqueo` / `TesoreriaOrdenPagoBloqueo`	`tesoreria_motivo_bloqueo` / `…_bloqueo`	Catálogo de motivos y bloqueos activos (con flag `impacta_pmp`).
`TesoreriaPago` / `TesoreriaPagoEstado`	`tesoreria_pago` / `…_estado`	Ejecución física del pago y su historial.

3.3 Cobros

Modelo	Tabla	Propósito
`TesoreriaCobro` / `TesoreriaCobroEstado`	`tesoreria_cobro` / `…_estado`	Ingreso, ligado a `deuda_id` (Recaudación) y a un movimiento de extracto.

3.4 Conciliación bancaria

Modelo	Tabla	Propósito
`ExtractoBancario`	`tesoreria_extracto_bancario`	Extracto Norma 43 importado.
`TesoreriaExtractoMovimiento`	`tesoreria_extracto_movimiento`	Apunte individual del extracto (signo D/H, saldo).
`TesoreriaMovimientoBancario`	`tesoreria_movimiento_bancario`	Movimiento bancario con su `estado_conciliacion`.
`TesoreriaConciliacion` / `…Detalle` / `…Log`	`tesoreria_conciliacion` / …	Sesión de conciliación, sus vínculos (movimiento↔pago/cobro) y su log.
`TesoreriaParametrosConciliacion`	`tesoreria_parametros_conciliacion`	Reglas de matching y tolerancias por cuenta.

3.5 Ficheros bancarios y SEPA

Modelo	Tabla	Propósito
`TesoreriaFicheroBancario` / `TesoreriaFicheroPago`	`tesoreria_fichero_bancario` / `…_pago`	Fichero de pagos (sepa/norma34/manual) y sus órdenes.
`TesoreriaFicheroSEPA` / `…Pago`	`tesoreria_fichero_sepa` / `…_pago`	Fichero SEPA con el XML generado.

3.6 Proyección de liquidez, PMP, comisiones y alertas

Modelo	Tabla	Propósito
`TesoreriaProyeccionParametro`	`tesoreria_proyeccion_parametros`	Retraso/impago por concepto (auto del histórico + override manual).
`TesoreriaPrevisionManual`	`tesoreria_previsiones_manuales`	Cobros/pagos extraordinarios, con recurrencia.
`TesoreriaAlertaConfig`	`tesoreria_alertas_config`	Config de alertas de proyección (umbral, escenario, destinatarios).
`TesoreriaProyeccionSnapshot`	`tesoreria_proyeccion_snapshots`	Caché de la última proyección (series por escenario).
`PmpRegistro`	`pmp_registro`	Registro para el periodo medio de pago.
`ComisionBancariaConfig` / `…Aplicada`	—	Reglas de comisiones bancarias y su aplicación.
`TesoreriaAlerta` / `…Tipo` / `…Configuracion`	`tesoreria_alerta*`	Alertas operativas generales.

3.7 PJ, endosos, embargos y compensaciones (en `app/models.py`)

Modelo	Propósito
`PagoAJustificar` / `PagoAJustificarGasto`	Anticipo a justificar y sus gastos. Código `PJ-{año}-{nnnnn}`.
`EndosoPago`	Cesión de una factura a un cesionario. Código `EN-{año}-{nnnnn}`.
`EmbargoPago` / `EmbargoAplicacion`	Diligencia de embargo y cada retención aplicada. Código `EMB-…`.
`CompensacionDeuda` / `CompensacionDeudaLinea`	Compensación factura↔deudas. Código `CO-…`.

Todos se relacionan 1:1 con una UnidadDocumental, de modo que su tramitación y aprobación pasan por el workflow y la firma del módulo Documental.

4. El ciclo de pago y la conciliación

flowchart LR
    F["Factura conforme<br/>(Contabilidad)"] --> OP["Orden de pago"]
    OP -->|agrupar| FB["Fichero bancario / SEPA"]
    FB -->|enviar| BANCO[(Banco)]
    BANCO -->|extracto N43| EX["Movimiento bancario"]
    EX -->|conciliar| OP
    EX -.también.-> COB["Cobro"]

Una factura conforme genera una orden de pago (puede bloquearse por motivos tipificados, algunos con impacto en PMP).
Las órdenes se agrupan en un fichero bancario; si la cuenta tiene IBAN/BIC, se genera el XML SEPA (pain.008). Al enviarse, los pagos pasan a enviado.
El banco devuelve un extracto Norma 43 que se importa; cada apunte se concilia (manual, asistida o automática) contra órdenes de pago o cobros.
La conciliación validada contabiliza el asiento y registra el PMP.

Conciliación automática por reglas

servicios/conciliacion_rules.py puntúa cada candidato (importe exacto, fecha, referencia, cuenta, estado). Con TesoreriaParametrosConciliacion se fijan tolerancias (importe/días) y criterios; por encima de un umbral se concilia sola, por debajo se propone. servicios/norma43_parser.py parsea el fichero (con detección de devoluciones y hash para evitar duplicados).

5. Pagos a justificar, endosos, embargos y compensaciones

Estos cuatro flujos comparten patrón: son una UD del módulo Documental que, al aprobarse (al completar su firma), disparan un hook que aplica sus efectos en Tesorería, Presupuesto y Contabilidad.

Submódulo	Qué hace al aprobarse	Reglas contables
Pago a justificar	Registra fases A+D+O y, al pagar, P; al cerrar la justificación, revierte el sobrante y genera un cobro de reintegro.	`tesoreria.pj.regla_contable_pago` / `…_justificacion` / `…_reintegro` (`SYS-PJ-ENT`…).
Endoso	Marca la cesión ACTIVA; al pagar la factura cedida, el destinatario pasa a ser el cesionario.	`tesoreria.endoso.regla_contable` (`SYS-ENDOSO`).
Embargo	Activa la diligencia; al pagar al tercero embargado, retiene parte hacia el IBAN del embargante por prioridad legal (Judicial > AEAT > SS > AAPP > Civil).	— (se aplica en el pago).
Compensación	Registra cobros contra las deudas (fase C) y descuenta la factura de la orden de pago.	`tesoreria.compensacion.regla_contable` (`SYS-COMP`).

flowchart TD
    UD["UD aprobada (firma completa)"] --> H{Tipo}
    H -->|Pago a justificar| PJ["A+D+O + asiento de entrega"]
    H -->|Endoso| EN["Estado ACTIVO"]
    H -->|Embargo| EM["Estado ACTIVO"]
    H -->|Compensación| CO["Cobros fase C + descuento factura"]

Aviso de vencimiento de PJ

pj_scheduler.py registra la acción MOS tesoreria.pj.aviso_vencimiento (cron diario): avisa de los pagos a justificar cuyo plazo de justificación está por vencer y marca los vencidos.

6. Proyección de liquidez

proyeccion/motor.py calcula la previsión de saldos para un horizonte (30/60/90 días) y granularidad (diaria/semanal/mensual), en tres escenarios (optimista/realista/pesimista):

Parte del saldo actual de las cuentas.
Recopila los eventos previstos: planes de pago (Recaudación), órdenes de pago pendientes, previsiones manuales y derechos por cobrar.
Aplica retraso e impago por concepto (parámetros auto del histórico o manuales) según el escenario.
Acumula y devuelve las series temporales y un resumen (saldo mínimo, fecha).
Simulación what-if: POST /proyeccion/simular recalcula añadiendo cobros/pagos hipotéticos sin persistirlos.
Acciones MOS: tesoreria.proyeccion.recalcular_historico (trimestral, recalcula percentiles de retraso e impago) y tesoreria.proyeccion.evaluar_alertas (diaria: saldo bajo, descubierto previsto, necesidad de crédito), con anti-spam y destinatarios por rol/usuario.

7. Endpoints REST

Del orden de 150 endpoints. Resumen por área (bajo /api/tesoreria):

Área	Rutas (ejemplos)	Permiso
Cuentas	`/cuentas`, `/cuentas/<id>/saldo`, `/cuentas/tipos`	`tesoreria:cuentas:`, `:configuracion:`
Órdenes de pago	`/ordenes-pago`, `/<id>/bloquear`, `/desbloquear`, `/anular`, `/motivos-bloqueo`	`tesoreria:orden_pago:`, `:motivos_bloqueo:`
Pagos y ficheros	`/ordenes-pago/<id>/pagar`, `/pagos`, `/ficheros-bancarios/generar`, `/generar-sepa`, `/enviar`	`tesoreria:pago:`, `:ficheros:`
Cobros y remesas	`/cobros`, `/cobros/<id>/incidencia`, `/remesas`	`tesoreria:cobro:*`
Conciliación	`/conciliacion/extractos/importar`, `/conciliacion`, `/<id>/conciliar`, `/validar`, `/parametros`	`tesoreria:conciliacion:*`
Pagos a justificar	`/pagos-justificar`, `/<id>/pagar`, `/gastos`, `/cerrar-justificacion`	`tesoreria:pj:ver/gestionar/justificar`
Endosos	`/endosos`, `/endosos/por-factura/<id>`, `/<id>/anular`	`tesoreria:endoso:ver/gestionar`
Embargos	`/embargos`, `/embargos/por-tercero/<id>`, `/<id>/anular`	`tesoreria:embargo:ver/gestionar`
Compensaciones	`/compensaciones`, `/compensaciones/candidatas`, `/<id>/anular`	`tesoreria:compensacion:ver/gestionar`
Proyección	`/proyeccion`, `/proyeccion/simular`, `/parametros`, `/previsiones-manuales`, `/alertas-config`	`tesoreria:proyeccion:ver/simular/parametros/previsiones/alertas`
Dashboard / alertas	`/dashboard`, `/dashboard/operativo`, `/alertas`	`tesoreria:dashboard:ver`, `:alertas:*`

8. Servicios internos

Servicio	Responsabilidad
`norma43_parser.py`	Parseo de extractos Norma 43/Q43 (fechas flexibles, signo, devoluciones, hash anti-duplicado).
`conciliacion_rules.py`	Motor de propuestas de conciliación por scoring.
`conciliacion_service.py`	Conciliación automática de movimientos contra órdenes.
`conciliacion_contable.py`	Generación del asiento al validar la conciliación.
`conciliacion_events.py`	Orquesta el post-validación (marca órdenes, asiento, PMP, auditoría).
`pmp_service.py`	Registro del periodo medio de pago.
`asientos_pj.py`	Asientos de los pagos a justificar (entrega/justificación/reintegro).
`ia_explicativa.py`	Explicación en lenguaje natural de una conciliación.
`auditoria_service.py`	Registro de eventos de auditoría.

9. Permisos y roles

~48 permisos tesoreria:*. Categorías:

Categoría	Permisos (ejemplos)
Cuentas / configuración	`tesoreria:cuentas:ver/crear/editar/eliminar`, `:configuracion:ver/editar`.
Órdenes y pagos	`tesoreria:orden_pago:ver/crear/bloquear/desbloquear/anular`, `:pago:ver/ejecutar/incidencia`, `:ficheros:*`.
Cobros	`tesoreria:cobro:ver/crear/confirmar/incidencia`.
Conciliación	`tesoreria:conciliacion:ver/importar/crear/conciliar/validar/anular/parametros:*`.
PJ / endosos / embargos / compensaciones	`tesoreria:pj:`, `:endoso:`, `:embargo:`, `:compensacion:`.
Proyección	`tesoreria:proyeccion:ver/simular/previsiones:gestionar/parametros:gestionar/alertas:gestionar`.
Alertas / dashboard	`tesoreria:dashboard:ver`, `:alertas:ver/gestionar/configurar`.

Roles base: Jefe de Tesorería (acceso total, incluida proyección), Supervisor de Tesorería (lectura + simulación + alertas) e Interventor (lectura y simulación de la proyección).

10. Integraciones

Contabilidad: cada pago/cobro/conciliación genera asientos a través del motor contable (reglas SYS-PAG-OBL, SYS-COB-DER, SYS-PJ-*, SYS-ENDOSO, SYS-COMP, comisiones…).
Presupuesto: el ServicioPresupuestario registra las fases O/P (pagos) y DR/C (cobros) como MovimientoPresupuestario.
Recaudación: los cobros y las compensaciones liquidan deudas.
Documental: PJ, endosos, embargos y compensaciones son UDs con su workflow y firma; los hooks se disparan al aprobarlas.
Banca: ficheros SEPA pain.008 / Norma 34 de salida y extractos Norma 43 de entrada.

Errores

Catálogo servicios/errors.py con códigos por área (TESO-TES-*, TESO-CONC-*, etc.).