Módulo Contabilidad

En una frase

El núcleo económico-financiero: plan de cuentas, asientos, periodos contables, facturas (recibidas y emitidas), compromisos y contratos de gasto (ciclo ADOP), derechos de ingreso, cuenta 413, estados contables y un motor de reglas (RCF) que contabiliza automáticamente. Es el módulo más extenso de la plataforma (contabilidad.py supera las 10.000 líneas).

1. Propósito y alcance

Implementa la contabilidad presupuestaria y financiera del ayuntamiento:

Plan de cuentas jerárquico y terceros (proveedores/clientes).
Asientos contables (manuales y automáticos) y periodos (apertura, cierre, liquidación, distribución de resultado, amortización).
Facturas recibidas (RCF — Registro Contable de Facturas, con integración FACe) y facturas emitidas (con rectificativas).
Compromisos de gasto y contratos de gasto (ciclo ADOP: Autorización, Disposición, Obligación, Pago) y sus modificaciones.
Derechos de ingreso (arrendamientos, concesiones…) y cuenta 413 (facturas pendientes de aplicar).
Estados contables: balance, cuenta de resultados, sumas y saldos, ECPN, EFE, memoria, PMP.
Motor contable (RCF): reglas + plantillas que generan asientos automáticamente a partir de eventos.

2. Estructura de archivos

app/modules/contabilidad/
├── contabilidad.py        # Blueprint principal (~10.500 líneas): terceros, cuentas,
│                          #   asientos, periodos, cierre, facturas, informes, dashboard
├── rcf.py                 # Registro Contable de Facturas + FACe
├── configuracion.py       # Tablas maestras del motor (reglas, plantillas, tipos)
├── motor_contable.py      # Motor que interpreta reglas y genera asientos
├── seed_reglas_sistema.py # Reglas predefinidas del sistema (~29 + legacy)
├── models.py              # Modelos del motor (ReglaContable, PlantillaAsiento…)
├── compromisos.py / compromiso_models.py    # Compromisos de gasto (ADOP)
├── contratos.py / contrato_models.py        # Contratos de gasto
├── contrato_modificaciones.py               # Modificaciones de contrato
├── aprobacion_reglas.py / aprobacion_flujo.py  # Aprobación configurable + firmas
├── timeline.py            # Timeline unificado contratos/compromisos
├── facturas_emitidas.py   # Facturas emitidas + rectificativas
├── derechos_ingreso.py / derechos_ingreso_scheduler.py  # Derechos de ingreso
├── cuenta_413.py          # Cuenta 413 (acreedores pendientes de aplicar)
├── dashboard_departamento.py   # KPIs del departamento
├── validacion_tolerancia.py / validacion_desviacion.py  # Validaciones de importe
├── sla_facturas.py / liberacion_facturas.py  # Acciones MOS
├── factura_pdf.py         # Generación de PDF de factura
├── errors.py              # Catálogo de errores (CONT-*)
└── servicios/             # servicio_contable, asientos_factura, audit_service…

Blueprint contabilidad_bp registrado con prefijo /api (las rutas cuelgan de /api/contabilidad/...). Varios archivos auxiliares registran endpoints sobre ese mismo blueprint.

3. Modelos de datos

3.1 Plan de cuentas y terceros

Modelo	Tabla	Propósito
`PlanContableCuenta`	`plan_contable_cuentas`	Cuenta contable jerárquica (`padre_id`), naturaleza DEBE/HABER, `permite_tercero`, `es_pgc_oficial`.
`Tercero`	`terceros`	Proveedor/cliente. `nif`, `tipo_tercero`, `forma_pago`, `iban`/`swift` cifrados, `tipo_iva`, `retencion_irpf`, y cuentas contables asociadas (acreedor/deudor y gasto por defecto).

3.2 Asientos y periodos

Modelo	Tabla	Propósito
`PeriodoContable`	`periodos_contables`	Ejercicio con estado `abierto`, fechas de apertura/cierre.
`Asiento`	`asientos`	Asiento: `fecha_asiento`, `concepto`, `origen`, `estado` (ABIERTO/PROVISIONAL/DEFINITIVO/FISCALIZADO/BLOQUEADO/ANULADO/REPARADO), numeración `(ejercicio, numero_asiento)` única, y trazabilidad (`evento_contable`, `regla_contable`, `origen_id`).
`AsientoLinea`	`asiento_lineas`	Línea con `cuenta_id`, `debe`, `haber`, `tercero_id`.

3.3 Facturas

Modelo	Tabla	Propósito
`Factura` / `FacturaLinea`	`facturas` / `factura_lineas`	Factura recibida. Estado, `fase_contable` (A/D/O/P), integración FACe (`face_id`, DIR3), retenciones, vínculo a propuesta (`ud_propuesta_id`) y a `compromiso_id`, `estado_tramitacion`.
`FacturaAsignacion`	`factura_asignaciones`	Responsable asignado para crear la propuesta cuando la factura llega sin ella.
`FacturaEmitida` / `FacturaEmitidaLinea`	`facturas_emitidas` / …	Factura emitida. Serie+numeración, estado (BORRADOR/EMITIDA/COBRADA/RECTIFICADA/ANULADA), rectificativas (`factura_origen_id`), vínculo a `DerechoAIngreso`.

3.4 Compromisos de gasto (ADOP)

Modelo	Tabla	Propósito
`CompromisoGasto`	`compromisos_gasto`	Seguimiento del gasto recurrente. `tipo` (PERIODICO/CERTIFICACIONES/ACUMULATIVO), `importe_adjudicado`, `importe_por_periodo`, `periodicidad`, `tolerancia_importe_pct`, estado.
`CompromisoAnualidad`	`compromisos_anualidades`	Importes por ejercicio: `importe_autorizado` (fase A), `importe_dispuesto` (fase D).
`CompromisoPeriodo`	`compromisos_periodos`	Calendario de pagos esperados (YYYY-MM).
`CompromisoFactura`	`compromisos_facturas`	Vínculo compromiso↔factura (tipo ORDINARIA/REGULARIZACION/COMPLEMENTARIA/FINAL, desviación).
`CompromisoHistorialImporte`	`compromisos_historial_importes`	Revisiones de precio con su aprobación.

3.5 Contratos de gasto

Modelo	Tabla	Propósito
`ContratoGasto`	`contratos_gasto`	Contrato 1:1 con una UD. Tipo, procedimiento de contratación, adjudicatario, importes, fechas, prórrogas, responsables, estado.
`ContratoPropuesta`	`contratos_propuestas`	Propuestas vinculadas (ORIGINAL/COMPLEMENTARIA/MODIFICATIVA).
`ContratoModificacion`	`contratos_modificaciones`	Modificación (REVISION_PRECIO/AMPLIACION_PLAZO/PRORROGA) con flujo de firmas y snapshots.
`ContratoHistoricoPrecio`	`contratos_historico_precios`	Línea temporal de precios por periodo.
`ContratoReajuste`	`contratos_reajustes`	Diferencia acumulada cuando una modificación retroactiva afecta a periodos ya facturados.
`ContratoAprobacionRegla` / `…Paso`	`contratos_aprobacion_reglas` / `…pasos`	Reglas de aprobación configurables (qué cargos firman según condiciones).

3.6 Motor contable (RCF)

Modelo	Tabla	Propósito
`ReglaContable`	`reglas_contables`	Regla: cuándo/para qué contabilizar. `es_sistema` la protege de borrado.
`TipoReglaContable`	`tipos_reglas_contables`	Categoría de regla.
`PlantillaAsiento` / `PlantillaAsientoLinea`	`plantillas_asiento` / …	Plantilla versionada con la `definicion` (JSON: líneas de debe/haber).
`CampoContable` / `TipoLineaContable`	`campos_contables` / `tipos_linea_contable`	Piezas para definir las líneas de plantilla (importe y origen de cuenta).
`AuditoriaContable` / `ContabilidadAuditoriaEvento`	`auditoria_contable` / `contabilidad_auditoria_evento`	Doble auditoría del motor (decisión + certificación).

3.7 Inmovilizado y derechos de ingreso

Modelo	Tabla	Propósito
`ActivoFijo` / `Amortizacion`	`activos_fijos` / `amortizaciones`	Inmovilizado y su amortización periódica.
`DerechoAIngreso`	`derechos_ingreso`	Derecho de cobro 1:1 con UD (arrendamiento, concesión…), con periodicidad y facturación automática/manual.
`DerechoIngresoPeriodo` / `…Anualidad`	`derecho_ingreso_periodos` / …	Vencimientos y distribución plurianual.

4. El motor contable (RCF)

Es el rasgo más distintivo del módulo: permite contabilizar sin programar, configurando reglas y plantillas.

flowchart TD
    EV["Evento de negocio<br/>(factura, fase ADOP, cobro/pago…)"] --> M["MotorContable.contabilizar_evento(regla_id, objeto, modo)"]
    M --> R["Resuelve ReglaContable + PlantillaAsiento (versión vigente)"]
    R --> C["Construye ContextoContable<br/>(importes y cuentas del objeto)"]
    C --> I["Interpreta la plantilla JSON → líneas lógicas (debe/haber)"]
    I --> A1["Auditoría del motor (siempre, incluso en 'simular')"]
    A1 --> P{modo}
    P -- simular --> FIN["No persiste"]
    P -- ejecutar --> SC["ServicioContable: valida debe=haber, numera, persiste Asiento"]
    SC --> A2["Auditoría contable (certifica el asiento)"]

Una regla define cuándo/para qué contabilizar; una plantilla (en JSON, versionada) define las líneas de debe/haber y de dónde sale cada cuenta (cuenta fija, clasificación económica, tercero, cuenta bancaria…) y cada importe (base, IVA, IRPF, total…).
El motor trabaja en dos capas: decisión (ServicioContabilizacion, en motor_contable.py) y persistencia (ServicioContable).
Importes negativos → invierte debe/haber (asientos correctivos).
Modos: ejecutar, simular (previsualiza sin grabar) y reprocesar.
Doble auditoría: contabilidad_auditoria_evento (la decisión, siempre) y auditoria_contable (el asiento creado), enlazadas entre sí.

Reglas del sistema

seed_reglas_sistema.py siembra ~29 reglas (recepción/conciliación/reversión de facturas, apertura/cierre/regularización presupuestaria, pagos a justificar, cobros/pagos, endoso, compensación, arqueos, recaudación, subvenciones…). Llevan es_sistema=True: pueden desactivarse y reversionarse, pero no borrarse. Algunos parámetros de control apuntan a ellas (p. ej. tesoreria.pj.regla_contable_pago → SYS-PJ-ENT).

Validaciones de importe

Tolerancia (validacion_tolerancia.py): comprueba que la factura encaja en la propuesta/contrato. En contratos FIJOS, desviar más del redondeo (0,01 €) es bloqueante.
Desviación (validacion_desviacion.py): escalado OK → WARNING → BLOQUEO → BLOQUEO_CRITICO (la factura agota el disponible y exige propuesta complementaria).

5. Endpoints REST

El módulo expone más de 250 rutas bajo /api/contabilidad/. Resumen por área:

Área	Rutas (ejemplos)	Permiso típico
Terceros	`/terceros`, `/terceros/<id>`, `/terceros/rapido`, anexos	`contabilidad:terceros:ver` / `:gestionar`
Plan de cuentas	`/plan-contable`, `/plan-contable/list`, `/cuentas-contables/<id>/movimientos`	`contabilidad:parametros:gestionar` / `:asientos:ver`
Asientos	`/asientos`, `/asientos/<id>/estado`, `/asientos/definitivizar-masivo`, `/libro-mayor`	`contabilidad:asientos:ver/crear/editar`
Periodos y cierre	`/periodos-contables`, `/periodos-contables/<id>/cerrar`, `/cierre/`, `/distribucion-resultado/`, `/amortizacion/*`	`contabilidad:periodo:cierre`
Facturas recibidas (RCF)	`/rcf`, `/rcf/upload`, `/rcf/<id>/cambiar-estado`, `/rcf/<id>/rechazar`, `/rcf/bandejas`	`contabilidad:facturas:ver/crear`
FACe	`/face/consultar`, `/face/pendientes`, `/face/procesar/<id>`, `/face/devolver/<id>`	`contabilidad:facturas:crear` / `:procesar_face`
Vinculación factura↔propuesta	`/facturas/<id>/vincular-propuesta`, `/vinculaciones-pendientes`, `/facturas/<id>/confirmar-conciliacion`	`contabilidad:facturas:crear`
Cuenta 413	`/413/resumen`, `/413/facturas`, `/413/<id>/devolver-proveedor`, `/413/<id>/vincular-y-conciliar`	`contabilidad:facturas:ver/crear`
Facturas emitidas	`/facturas-emitidas`, `/emitir`, `/anular`, `/marcar-cobrada`, `/rectificativa`, `/pdf`	`contabilidad:facturas:ver/crear`
Derechos de ingreso	`/derechos-ingreso`, `/generar-periodos`, `/facturar-periodo/<pid>`, `/prorrogar`	`contabilidad:facturas:ver/crear`
Compromisos	`/compromisos`, `/activar`, `/revision-precio`, `/vincular-factura`, `/timeline`	`contabilidad:facturas:ver/crear`
Contratos y modificaciones	`/contratos`, `/contratos/<id>/modificaciones`, `/enviar-aprobacion`, `/aprobar`, `/timeline`	`expediente:ver/crear`, `contabilidad:contratos:aprobar_modificaciones`
Reglas de aprobación	`/aprobacion-reglas` (CRUD)	`expediente:ver`, `admin:gestionar_usuarios`
Informes / estados	`/informes/sumas-y-saldos`, `/balance_situacion`, `/cuenta_resultados`, `/ecpn`, `/efe`, `/pmp`, `/memoria/*` (con export CSV/PDF)	`contabilidad:informes:ver`
Dashboard / stats	`/stats/dashboard-kpis`, `/stats/interventor-dashboard`, `/dashboard/departamento`	`contabilidad:informes:ver` / `:dashboard:departamento`
Configuración del motor	`/tablas/tipos_regla`, `/tablas/reglas`, `/tablas/plantillas`, `/tablas/tipos-linea`, `/tablas/campos`, `/auditoria/*`	`contabilidad:configuracion:gestionar`
IA	`/ia/explicar-balance`, `/ia/explicar-ecpn`, `/ia/explicar-efe`, `/memoria/seccion/<id>/generar-ia`	`contabilidad:informes:ver`

6. El ciclo del gasto (ADOP) y los contratos

flowchart LR
    PR["Propuesta de gasto (UD)"] -->|Autorización A| CO["Compromiso / Contrato"]
    CO -->|Disposición D| CO
    FA["Factura recibida"] -->|Obligación O| CO
    FA -->|Pago P| TES["Tesorería"]

Propuesta de gasto (UD del módulo Documental) → autoriza el gasto (A).
Compromiso / Contrato → dispone el crédito (D); al crear un compromiso activo se invoca ServicioPresupuestario.disponer_credito().
Factura vinculada → reconoce la obligación (O); su pago en Tesorería cierra la fase P.
Las modificaciones de contrato (revisión de precio, ampliación de plazo, prórroga) siguen un flujo de aprobación configurable por reglas (ContratoAprobacionRegla) que se materializa en el sistema genérico de firmas (resource_type='CONTRATO_MODIFICACION'). Al firmar el último paso, aplicar_aprobacion_completa() aplica los efectos (nuevo precio, nuevas fechas, reajustes retroactivos) y actualiza el histórico de precios.

Relación con Presupuesto

Cada evento contable tiene su contrapartida presupuestaria mediante MovimientoPresupuestario (fases A/D/O/P/DR/C), gestionada por ServicioPresupuestario. Ver el módulo Presupuesto (pendiente de documentar).

7. Permisos y roles

~27 permisos contabilidad:*. Principales:

Categoría	Permisos
Terceros	`contabilidad:terceros:ver`, `:gestionar` (y `admin:gestionar_terceros`).
Facturas	`contabilidad:facturas:ver`, `:crear`, `:procesar_face`.
Asientos	`contabilidad:asientos:ver`, `:crear`, `:editar`.
Periodos	`contabilidad:periodo:cierre`.
Compromisos / contratos	`contabilidad:compromisos:ver`, `contabilidad:contratos:aprobar_modificaciones`.
Informes / dashboard	`contabilidad:informes:ver`, `contabilidad:dashboard:departamento`.
Parámetros / motor	`contabilidad:parametros:gestionar`, `contabilidad:configuracion:gestionar`, `:auditoria:ver`.
Conciliación / reproceso	`contabilidad:conciliacion:ver`, `contabilidad:reprocesar`.

Roles base con peso contable: Interventor y Jefe de Contabilidad (reciben el grueso de los permisos operativos y de tablas del motor).

8. Integraciones

MOS — crons y acciones

Acción	Cuándo	Función
`contabilidad.sla_facturas_sin_propuesta`	diario	Escala facturas en cuenta 413 sin propuesta según umbral de días/importe.
`contabilidad.sla_facturas_retenidas`	diario	Escala facturas retenidas (avisa a Jefatura e Interventor).
`contabilidad.revisar_facturas_retenidas`	tras aprobar propuesta complementaria	Libera facturas retenidas si aumenta el disponible del compromiso.
`contabilidad.facturar_derechos`	programado	Genera borradores de factura emitida de los derechos de ingreso que vencen.

Además, eventos de auditoría en todas las operaciones relevantes (FACTURA_EMITIDA_*, DERECHO_INGRESO_*, COMPROMISO_*, CONTRATO_*…).

Otros módulos y sistemas externos

Documental: propuestas de gasto, contratos y derechos de ingreso son UDs; las modificaciones de contrato usan el sistema genérico de firmas.
Presupuesto: MovimientoPresupuestario y ServicioPresupuestario.
Tesorería: órdenes de pago y cobros enlazan con facturas.
FACe: recepción de facturas electrónicas (vía RedSARA, con DIR3).
Google Gemini: explicación de estados contables y generación de memoria.