Módulo Presupuesto

En una frase

Elaboración y gestión del presupuesto municipal a lo largo de todo su ciclo legal (RD 500/1990 y TRLRHL): clasificaciones, líneas y créditos, ciclo legal de aprobación (vía expediente + UD CONTROL + firmas), activación, prórroga, modificaciones de crédito, liquidación y cierre, y un registro único de ejecución, el MovimientoPresupuestario (fases ADOP), que es el puente con la Contabilidad.

1. Propósito y alcance

Clasificaciones presupuestarias: orgánica, económica, funcional/por programa y proyectos (jerárquicas).
Presupuesto y líneas: cabecera con versión y estado, y líneas (aplicaciones presupuestarias) con sus créditos y ejecución.
Ciclo legal de aprobación: proyecto → previo → aprobación inicial (Pleno) → exposición pública y alegaciones → aprobación definitiva → activación.
Activación (genera asientos de apertura) y prórroga (presupuesto prorrogado cuando no hay uno nuevo el 1/1).
Modificaciones de crédito (8 tipos) con tramitación por Pleno o Alcaldía.
Liquidación y cierre: resultado presupuestario, remanente de tesorería y cálculos legales (estabilidad, regla de gasto, endeudamiento, ahorro neto).
Ejecución: el MovimientoPresupuestario registra cada fase del gasto y del ingreso, gestionado por el ServicioPresupuestario.

2. Estructura de archivos

app/modules/presupuesto/
├── presupuesto.py          # Blueprint principal (~6000 líneas): CRUD, líneas, analíticas, comprometidos
├── clasif_routes.py        # Clasificaciones (orgánica/económica/funcional/programas/proyectos)
├── presupuesto_clasificaciones.py  # Registro CRUD dinámico de clasificaciones
├── aprobacion_routes.py    # Ciclo legal: aprobación Pleno, exposición pública, alegaciones, docs
├── sprint4_routes.py       # Promover a "previo" (crea Expediente + UD CONTROL)
├── activacion_routes.py    # Activación + configuración contable
├── prorroga_routes.py      # Prórroga presupuestaria
├── modificaciones_routes.py# Modificaciones de crédito (~2250 líneas)
├── liquidacion.py          # Liquidación y cierre
├── liquidacion_calculos_legales.py  # Estabilidad, regla de gasto, endeudamiento, ahorro
├── sprint2_routes.py       # Edición masiva, escenarios, presets
├── sprint3_routes.py       # Propuestas colaborativas, comentarios, validación de líneas
├── reglas_fiscales.py      # Evaluadores de estabilidad presupuestaria (what-if)
├── firma_callbacks.py / firma_callbacks_modificaciones.py  # Callbacks del sistema de firmas
├── guards.py / logic_transitions.py   # Reglas de edición y transiciones de estado
├── permiso_resolver.py     # Resolución de permisos por área/clasificación
├── export_services.py      # Exportación a matrices
├── models*.py              # Modelos (ver §3)
└── services/               # ServicioPresupuestario, edicion_masiva, auditoría IA

Blueprints (registrados en app/__init__.py):

Blueprint	url_prefix
`presupuesto_bp` (+ activación, prórroga)	`/api/presupuesto`
`clasif_bp`	`/api/clasif`
`aprobacion_bp`, `sprint2_bp`, `sprint3_bp`, `sprint4_bp`, `modificaciones_bp`, `liquidacion_bp`	`/api/presupuesto`

3. Modelos de datos

3.1 Presupuesto y líneas

Modelo	Tabla	Propósito
`Presupuesto`	`presupuesto`	Cabecera: `ejercicio`, `version` (Proyecto/Previo/Definitivo/Real/Prorrogado), `estado` (Borrador/Abierto/Cerrado/Aprobado/Activo/Liquidado), y enlaces al ciclo legal (`expediente_id`, `ud_control_id`, `procedimiento_control_id`, `prorrogado_desde_id`).
`PresupuestoLinea`	`presupuesto_linea`	Aplicación presupuestaria: clasificaciones (económica/orgánica/funcional/programa/proyecto), `importe_inicial`, `modificaciones`, ejecución (`comprometido`, `obligaciones`, `pagado`), `es_recurrente` (para prórroga) y `estado_validacion`.
`PresupuestoPermisoUsuario`	—	Permiso local por usuario y combinación de clasificaciones (resuelto por especificidad).

3.2 Movimiento presupuestario (clave)

MovimientoPresupuestario (models_movimiento.py) es la tabla única de eventos de ejecución. Cada operación añade una fila (nunca se modifica), y los saldos se calculan sumando importe * signo.

Campo	Significado
`ejercicio`	Año presupuestario afectado (puede diferir de la fecha en plurianuales).
`fase`	A (autorización), D (disposición/compromiso), O (obligación), P (pago), M (modificación), DR (derecho reconocido), C (cobro), CIERRE, ASUNCION_PRORROGA.
`signo`	`+1` (alta) o `-1` (reverso/anulación); el `importe` siempre es positivo.
`linea_id`	Aplicación presupuestaria afectada.
`origen_tipo` / `origen_id`	Qué objeto provocó el movimiento (propuesta, compromiso, factura, orden_pago, cobro, modificacion, derecho_ingreso…).

flowchart LR
    A["A · Autorización"] --> D["D · Disposición"] --> O["O · Obligación"] --> P["P · Pago"]
    DR["DR · Derecho"] --> C["C · Cobro"]
    M["M · Modificación de crédito"] -.altera crédito.-> L[(PresupuestoLinea)]

3.3 Ciclo legal de aprobación

Modelo	Tabla	Propósito
`PresupuestoAprobacionPleno`	`presupuesto_aprobacion_pleno`	Aprobación (tipo INICIAL/DEFINITIVA/PRORROGA, estado PENDIENTE/APROBADA/RECHAZADA).
`PresupuestoExposicionPublica`	`presupuesto_exposicion_publica`	Exposición pública (PENDIENTE/ABIERTA/CERRADA/PRORROGADA), fechas y nº BOP.
`PresupuestoAlegacion`	`presupuesto_alegacion`	Alegaciones (PENDIENTE/ADMITIDA/ESTIMADA/DESESTIMADA).
`PresupuestoDocumentoObligatorio`	`presupuesto_documento_obligatorio`	Checklist de documentos (MEMORIA, INFORME_ECONOMICO, BASES_EJECUCION…).
`PresupuestoCicloVidaAuditoria`	`presupuesto_ciclo_vida_auditoria`	Traza de fases del ciclo de vida.
`ConfiguracionPresupuestoEntidad`	`presupuesto_configuracion_entidad`	Reglas contables de apertura/cierre por entidad.

3.4 Modificaciones de crédito

Modelo	Tabla	Propósito
`PresupuestoModificacion`	`presupuesto_modificacion`	Cabecera: `tipo`, `organo_competente` (PLENO/ALCALDE), `estado`, número, importes calculados.
`PresupuestoModificacionLinea`	`presupuesto_modificacion_linea`	Operación: AUMENTO / BAJA / CREACION sobre aplicaciones.
`PresupuestoModificacionFinanciacion`	`presupuesto_modificacion_financiacion`	Origen de financiación (LINEA_BAJA, MAYORES_INGRESOS, REMANENTE_LIQUIDO, RECURSOS_AFECTADOS, NUEVO_INGRESO).
`PresupuestoModifDocumento`	`presupuesto_modif_documento`	Checklist de documentos obligatorios.

3.5 Liquidación, escenarios y colaboración

Modelo	Tabla	Propósito
`PresupuestoLiquidacion` / `…Linea`	`presupuesto_liquidacion` / …	Cierre fiscal: resultado presupuestario (DRN/ORN), remanente de tesorería, y secciones legales D (estabilidad), E (regla de gasto), F (endeudamiento), H (ahorro neto).
`PresupuestoEscenario`	—	Snapshot etiquetado del presupuesto (Sprint 2).
`PresupuestoOperacionPreset`	—	Operación de edición masiva guardada (Sprint 2).
`PresupuestoPropuesta`	—	Propuesta de cambio colaborativa (Sprint 3).
`PresupuestoLineaComentario`	—	Hilo de comentarios por línea (Sprint 3).

4. El ciclo legal de aprobación

Se articula sobre el módulo Documental: un Expediente y una unidad documental de control ("UD CONTROL") cuyo workflow refleja las fases legales, y el sistema genérico de firmas que, al completarse cada paso, dispara un callback (firma_callbacks.py) que sincroniza la versión/estado del presupuesto.

flowchart TD
    P0["Proyecto<br/>(elaboración de líneas)"] -->|promover-a-previo<br/>crea Expediente + UD CONTROL| P1["Previo"]
    P1 -->|documentos obligatorios completos| AI["Aprobación inicial (Pleno)<br/>firmas Secretario→Alcalde"]
    AI --> EP["Exposición pública<br/>(alegaciones)"]
    EP -->|cerrada + alegaciones resueltas| AD["Aprobación definitiva (Pleno)<br/>firmas"]
    AD --> ACT["Activación<br/>(asientos SYS-APE-*)"]
    ACT --> V["Definitivo · Activo (vigente)"]

Guards y transiciones (guards.py, logic_transitions.py): controlan qué se puede editar en cada versión (en Previo/Prorrogado solo campos limitados; en Definitivo nada) y validan que los saltos de versión/estado sean legales.
Activación (activacion_routes.py): comprueba déficits y aplicaciones sin equivalente contable, asume la ejecución del prorrogado anterior si existe, desactiva el activo previo (un único presupuesto Activo por entidad/ejercicio) y genera los asientos de apertura (SYS-APE-GASTOS / SYS-APE-INGRESOS) según la ConfiguracionPresupuestoEntidad.
Prórroga (prorroga_routes.py): cuando el 1/1 no hay presupuesto definitivo, clona del ejercicio anterior solo las líneas es_recurrente (solo el crédito inicial, sin ejecución) y nace ya en estado Activo. Al aprobarse después el definitivo, este asume la ejecución y el prorrogado se cierra.

5. Modificaciones de crédito

Ocho tipos (TRLRHL arts. 177-182 / RD 500/1990): crédito extraordinario, suplemento de crédito, ampliación, transferencia, generación por ingresos, incorporación de remanentes, baja por anulación y ajuste por prórroga. Cada tipo determina el órgano competente (Pleno o Alcaldía) y si requiere exposición pública.

flowchart LR
    B["Borrador<br/>(líneas alta/baja + financiación)"] --> PR["Propuesta<br/>(nº + expediente + UD)"]
    PR --> IN["Informe Intervención"]
    IN -->|Pleno| AI2["Aprob. inicial → Exposición → Aprob. definitiva → BOP"]
    IN -->|Alcaldía| RES["Resolución de Alcaldía"]
    AI2 --> AP["Aplicar"]
    RES --> AP
    AP --> VG["Vigente<br/>(altera créditos vía Movimiento fase M)"]

Cuadre obligatorio: la suma de altas/creaciones debe igualar la financiación.
Cada paso de firma usa el sistema genérico (resource_type = MODIF_CREDITO_INFORME / …_APROB_INICIAL / …_APROB_DEFINITIVA / …_RESOLUCION) con sus callbacks en firma_callbacks_modificaciones.py.
Al aplicar, ServicioPresupuestario genera movimientos de fase M que alteran PresupuestoLinea.modificaciones (y crea líneas nuevas en CREACION), con auditoría de antes/después. Una modificación VIGENTE es inmutable.

6. Liquidación y cierre

liquidacion.py (+ liquidacion_calculos_legales.py) implementa el cierre formal (ICAL 2013): fases BORRADOR → CALCULADA → REVISADA → APROBADA → CERRADA. Calcula el resultado presupuestario (derechos reconocidos netos − obligaciones reconocidas netas), el remanente de tesorería (con ajuste por dudoso cobro) y las secciones legales D (estabilidad), E (regla de gasto), F (endeudamiento) y H (ahorro neto), con posibilidad de sobrescritura manual.

Al cerrar: el presupuesto pasa a Liquidado, se genera el asiento de cierre vía el motor contable y se crea automáticamente una modificación de incorporación de remanentes en el ejercicio siguiente.

7. Endpoints REST

Más de 150 endpoints. Resumen por área (bajo /api/presupuesto salvo clasificaciones, en /api/clasif):

Área	Rutas (ejemplos)	Permiso típico
Presupuestos	`/`, `/<id>`, `/<id>/clone`, `/<id>/version`, `/<id>/estado`, `/dashboard`	`presupuesto:ver`, `:creacion:gestionar`
Líneas	`/<id>/lineas`, `/lineas/<id>`, `/<id>/import_csv`, `/<id>/seed_from_*`, `/lineas/<id>/saldos`	`presupuesto:lineas:ver/crear/editar/borrar`
Clasificaciones	`/api/clasif/{economica,organica,funcional,programas,proyectos}` (+ `/tree`)	`presupuesto:clasificacion:*`, `:administrar`
Analítica / export	`/<id>/analytics`, `/<id>/resumen/*`, `/<id>/export_csv`, `/export/pdf`, `/export/excel`	`presupuesto:ver`
Ciclo legal	`/<id>/promover-a-previo`, `/<id>/aprobaciones-pleno/...`, `/<id>/exposicion-publica`, `/alegaciones`, `/<id>/documentos-obligatorios`, `/<id>/ciclo-legal`	`presupuesto:transicion:solicitar`, `:aprobacion:pleno`, `:exposicion:gestionar`
Activación / prórroga	`/configuracion-contable`, `/<id>/activar` (+ `/preview`), `/prorroga/estado`, `/prorroga/generar`	`presupuesto:activar`, `:configuracion:gestionar`, `:prorrogar`
Modificaciones	`/<id>/modificaciones`, `/lineas`, `/financiacion`, `/proponer`, `/solicitar-*`, `/aplicar`, `/anular`, `/timeline`	`presupuesto:mod_credito:*`
Liquidación	`/liquidaciones`, `/<id>/calcular`, `/revisar`, `/aprobar`, `/calcular-legales`	`presupuesto:liquidar:proponer`, `:cerrar`
Sprint 2	`/<id>/edicion-masiva/{preview,aplicar}`, `/escenarios`, `/operaciones-preset`	`presupuesto:edicion_masiva:aplicar`, `:escenarios:gestionar`
Sprint 3	`/<id>/propuestas`, `/propuestas/<id>/{aceptar,rechazar,devolver}`, `/lineas/<id>/comentarios`	`presupuesto:propuestas:*`, `:lineas:comentar/validar`
Comprometidos	`/expedientes/<id>/comprometidos`, `/comprometidos/<id>/{confirmar,anular}`	`presupuesto:comprometidos:*`
Reglas fiscales	`/<id>/reglas-fiscales/simular`	`presupuesto:ver`

8. ServicioPresupuestario

services/ contiene el ServicioPresupuestario, fachada de la ejecución presupuestaria que usan otros módulos (Contabilidad, Tesorería). Sus operaciones (autorizar, disponer, obligar, pagar, reconocer derecho, cobrar, aplicar modificación) registran un MovimientoPresupuestario con la fase y el signo correspondientes y validan el crédito disponible (con posible bypass auditado).

# patrón de uso desde otros módulos
ServicioPresupuestario.disponer_credito(importe, partida, origen_tipo="compromiso", origen_id=...)

También en services/: edición masiva (operaciones por lote: % , fijo, IPC, media de N años, igual a ejecutado N-1…) y los servicios de auditoría con IA.

9. Permisos y roles

~65 permisos presupuesto:* en 11 categorías. Principales:

Categoría	Permisos (ejemplos)
Visualización	`presupuesto:ver`, `:dashboard:ver`, `:gestion:ver`, `:auditoria:ver`.
Creación	`presupuesto:creacion:gestionar`, `:creacion:seed`, `:creacion:import_csv`, `:creacion:clonar`.
Líneas	`presupuesto:lineas:ver/crear/editar/borrar`, `:lineas:editar_areas`, `:lineas:comentar`, `:lineas:validar`.
Estados/fases	`presupuesto:estado:cambiar`, `:proyecto/previo/definitivo:editar`, `:transicion:solicitar`.
Modificaciones	`presupuesto:mod_credito:crear/ver/gestionar/proponer/aprobar/anular`.
Ciclo legal	`presupuesto:elaboracion:gestionar`, `:aprobacion:pleno`, `:aprobacion:intervenir`, `:exposicion:gestionar`, `:alegaciones:gestionar/resolver`, `:minhap:comunicar`.
Activación/prórroga	`presupuesto:activar`, `:configuracion:gestionar`, `:prorrogar`, `:prorroga:depurar`.
Liquidación	`presupuesto:liquidar:proponer`, `:cerrar`.
Sprint 2/3	`presupuesto:edicion_masiva:aplicar`, `:escenarios:gestionar`, `:presets:gestionar`, `:propuestas:crear/editar_propias/resolver`.
Excepción	`presupuesto:saldo:bypass`.

Rol base principal: Jefe de Presupuestos (≈38 permisos). El permiso presupuesto:minhap:comunicar se asigna a Jefe de Tesorería.

Resolución de permisos por área

permiso_resolver.py permite asignar permisos acotados a combinaciones de clasificación (un usuario edita solo su orgánica/programa). Gana el permiso más específico; quien tenga presupuesto:lineas:editar o :creacion:gestionar puede editar todo (bypass).

10. Integraciones

Documental: el ciclo legal y las modificaciones se materializan en expedientes y UDs de control, con el sistema genérico de firmas.
Contabilidad: la activación, el cierre y las operaciones del ServicioPresupuestario generan asientos a través del motor contable (RCF); MovimientoPresupuestario es la contrapartida presupuestaria de cada hecho.
Tesorería / Recaudación: el reconocimiento de derechos y los cobros/pagos registran sus fases (DR/C, O/P).
IA (Gemini): auditoría inteligente del presupuesto y explicación de cambios.

Errores

Códigos PRES-* por área (PRES-LIN-*, PRES-APR-*, PRES-EXP-*, PRES-ALG-*, PRES-DOC-*, PRES-ACT-*, PRES-PRO-*, PRES-TRA-*, PRES-MOD-*).