# Facturacion y contabilidad analitica El modulo `Facturacion` de AnimalCharlie. gestiona facturas, cobros, catalogo facturable, planes recurrentes, gastos imputables y analitica de margen. Esta pensado para operar el ERP diario sin salir del modulo, usando subvistas internas en vez de una pagina larga apilada. La entrada `Control` ocupa el primer pantallazo con cartera, vencimientos, documentos sin enviar, presupuestos, gastos y calidad de datos; `Facturas` conserva la edicion completa cuando se abre un documento. ## Que incluye - Facturas ordinarias, de anticipo, simplificadas, rectificativas, presupuestos (almacenados como `proforma`) y abonos. - Mesa ERP `Control` como entrada predeterminada: prioridades ordenadas por urgencia y registro tabular permanecen visibles; `Indicadores` abre en el popup común los seis filtros accionables, tesoreria a 7/30 dias y controles de calidad contable. Cada fila abre directamente la factura, el cobro, el gasto, el plan recurrente, la analitica o el cierre correspondiente. - `Control` evita accesos redundantes: Prioridades usa la accion concreta de cada tarea y `Ultimas facturas` abre el documento al pulsar cualquier punto de la fila, tambien con `Enter` o espacio. No repite botones `Ver facturas`, `Abrir registro completo` ni `Abrir` por documento cuando la pestaña `Facturas` y la propia fila ya cubren esas rutas. - La tesoreria de `Control` presenta cobrar, pagar, neto y cartera en una rejilla 2 x 2 dentro de `#billingControlOverviewPopup`; no desplaza el registro diario cuando no se consulta. - Los indicadores del popup abren colas reales y lo repliegan al navegar: vencidas, por cobrar, borradores, emitidas sin enviar, presupuestos y gastos por pagar. No son tarjetas informativas sin salida ni ejecutan escrituras automaticamente. - Altas rapidas desde la mesa de control para presupuesto, lectura inteligente de gasto y plan recurrente; `Nueva factura` permanece como accion primaria de cabecera. - En `Gastos`, la accion primaria de cabecera sigue el pane real: `Nuevo gasto` mientras se consulta el indice, `Guardar gasto` al abrir un alta y `Guardar cambios` al editar un movimiento. El indice no repite otro boton `Nuevo`; volver desde la ficha restaura la misma accion sin perder ni guardar datos implicitamente. - Registro de facturas con numero, cliente, emision, vencimiento, estado, total, cobrado y pendiente en una tabla densa adaptada a PC, Galaxy Tab A9+ e iPad Air. En iPad vertical se retiran columnas redundantes, no funciones ni acciones. - Ciclo de vida rapido en la ficha: solo muestra las acciones validas para el estado actual; `Finalizar factura`, `Enviar al cliente`, registrar aceptacion, convertir un presupuesto o `Registrar cobro` quedan a mano y duplicar, abonar o anular viven en `Mas acciones`. - Presupuestos con numero comercial, aceptacion trazable (`accepted_at`, `accepted_by`, `acceptance_reference`) y conversion en un clic a factura ordinaria; el presupuesto aceptado queda bloqueado como historico y la factura conserva `source_type=proforma` y `source_id`. - Facturas de anticipo con tipo y serie propia `ANT`, documento rotulado y el mismo circuito de emision, entrega, cobro y cumplimiento que una factura ordinaria. - Preparacion de duplicados y abonos desde una factura guardada, manteniendo cliente, lineas e imputacion analitica en un borrador nuevo. - Cola de trabajo en el indice de facturas: todas, por cobrar, vencidas y borradores con contadores. - Seleccion inicial operativa: abre `Vencidas` si hay alguna, despues `Por cobrar`, despues `Borradores` y usa `Todas` cuando no existe trabajo pendiente, tambien cuando todavia no hay facturas. La cola activa siempre queda identificada. - Resumen de una linea con los indicadores completos dentro de `Ver todos los indicadores`, cerrado por defecto. - Navegacion primaria `Facturas`, `Gastos` y `Recurrentes`; `Catalogo`, `Analitica`, `Libro` y `Cierre` siguen accesibles en `Mas vistas`. - Busqueda y cola siempre visibles; estado y tipo quedan en `Filtros` con contador de filtros activos. - Una factura nueva usa todo el ancho para cliente, vencimiento, forma de pago y conceptos, sin asistente ni pasos numerados. Mientras todavia no existe una factura guardada, no muestra PDF, envio, cobros ni IA, porque esas acciones aun no se pueden completar. - Ficha de factura por divulgacion progresiva: solo cliente, vencimiento y forma de pago quedan visibles; tipo de documento, emision, explotacion, proyecto, serie, numero, estado, rectificacion y notas se conservan en `Opciones avanzadas`. - Conceptos con alta rapida desde descripcion, cantidad y precio unitario. Catalogo, tipo, IVA, IRPF, descuento, centro y categoria siguen disponibles en `Catalogo y opciones`, sin retirar edicion, copia ni borrado por fila. - Relleno rapido de imputacion analitica: `Imputar lineas` completa centro y/o categoria en las lineas que todavia esten vacias sin sobrescribir las ya revisadas. - Tabla de lineas compacta: muestra concepto, cantidad, precio, total y acciones; cada concepto conserva debajo sus etiquetas operativas de tipo, IVA, IRPF, descuento, centro y categoria, por lo que no se pierde informacion ni se fuerza una tabla de nueve columnas. - Una vez guardada, `Ver PDF`, `Enviar`, `Cobrar` y `Revisar` comparten una sola zona con pestañas. Solo se monta la superficie activa para conservar espacio de conceptos y cliente. - En PC, Galaxy Tab A9+ e iPad Air, una factura nueva conserva el mismo recorrido de una columna. Tras guardarla, Galaxy Tab A9+ e iPad Air apaisado mantienen conceptos y zona lateral en paralelo; en iPad Air vertical se apilan dentro del scroll del workbench. `.billing-section-grid` no recorta los paneles secundarios y solo muestra la pestaña activa. No se diseña una vista de telefono. - Imputacion por centro analitico y categoria en cada linea facturable. - Pagos por factura con importe, fecha, metodo, referencia, cuenta, identificador de movimiento, estado de conciliacion y control de saldo pendiente. - Edicion directa de cobros guardados para completar referencia bancaria, metodo o notas sin borrar el pago ni alterar el historico de la factura. - Entrega trazable por correo, descarga, portal, en mano u otro canal. `Preparar correo` abre el cliente de correo con asunto y texto; `Registrar entrega` guarda destinatario, resultado, fecha, referencia del proveedor y notas. Descargar PDF registra una entrega de tipo `downloaded`. - Asistente IA con revision local reproducible de errores fiscales/operativos, borrador de recordatorio ajustado a vencimiento y cobro parcial, y acceso a Charlie con la factura activa como entidad. - Documento profesional de factura dentro del editor compartido: emisor y cliente completos, fechas, pago, referencias de explotacion/proyecto, lineas, descuentos, desglose fiscal, IRPF, total, saldo, rectificacion, marca y paginacion. `Preparar PDF` abre el estudio global y `Descargar` genera el fichero sin abandonar la ficha. - Datos fiscales, lineas e importes bloqueados dentro del documento. Solo el bloque `Contenido para el cliente` se puede editar con formato, tablas, imagenes e IA mientras la factura sea borrador; se guarda con la factura y se reutiliza al reabrirla. - Separacion estricta entre informacion externa e interna: las notas internas de factura, centros analiticos y categorias de imputacion no aparecen en la vista del cliente ni en el PDF. - Planes recurrentes con indicador de vencidos, vista previa comun y generacion por lote de borradores. La accion confirma cliente, fecha e importe antes de escribir, conserva la generacion individual y agrupa los vencidos en una sola prioridad de `Control` para no saturar la mesa. - Imputacion analitica de planes recurrentes por centro y categoria. - Catalogo de servicios y productos con precio, IVA, coste y stock. - Centros analiticos con codigo, tipo, presupuesto mensual y notas. - Configuracion fiscal del emisor en `Catalogo`: razon social, NIF, direccion, ciudad, provincia, CP, pais, telefono, email, cuenta bancaria, notas de pie y logotipo PNG/JPG/WebP de hasta 2 MB, incrustado sin recursos remotos. `Desde biblioteca` usa `AnimalCharlieAssetLibrary.mountFileInput(...)` y conserva la misma validacion, vista previa y persistencia del emisor. - Series configurables por tipo (`FAC`, `PRE`/serie historica `PRO`, `ANT`, `REC`, `SIM`, `CRE`) con contador correlativo anual. Los borradores fiscales no consumen numero: se asigna dentro de la transaccion de emision o entrega, evitando huecos por borradores descartados y comprobando duplicados. - Tipos de IVA, IGIC y recargo de equivalencia precargados (`tax_rates`) para desglose legal y futuras integraciones fiscales. - Bloqueo de edicion en facturas ya emitidas: solo borradores permiten modificar lineas, cliente o importes; para corregir una factura emitida se debe usar una rectificativa. - Desglose de IVA por tipo impositivo en el documento de factura con base y cuota separadas. - Factura rectificativa completa con seleccion de factura original, tipo (por diferencias o por sustitucion) y motivo obligatorio; validacion backend de que la original existe, no esta cancelada y no es proforma/abono/rectificativa. - Factura simplificada con validacion de importe maximo (400 €) y documento que oculta datos completos del receptor. - Formas de pago estandar españolas codificadas (01 Efectivo, 02 Cheque, 03 Transferencia, 04 Tarjeta, 05 Domiciliacion, 06 Bizum) en factura y gastos. - IRPF profesional en lineas de factura con campo `irpfRate`, calculo de retencion en totales y desglose en el documento cuando aplica. - Gastos imputables a centro analitico, cliente, explotacion y proyecto con vencimiento de pago a proveedor. - Los gastos pueden guardarse temporalmente sin centro analitico; el backend lo conserva como `NULL` y el cierre lo señala como imputacion pendiente. - Gastos pagados con metodo, referencia y notas para poder conciliarlos contra banco/caja. - Control diario de gastos con resumen de importe por pagar, vencidos, coste del mes y registros pendientes de clasificar. - Alta asistida desde `Leer factura o ticket`: reutiliza `AnimalCharlieAssetLibrary`, acepta PNG, JPG, WebP y PDF privados, y el agente `hermes-module-billing` del Hermes local usa GPT para preparar proveedor, concepto, base, IVA, total, fechas, pago, referencia, categoría, notas e imputación. Esta capacidad no llama al cliente auxiliar Kimi del backend. Si el proveedor no existe, queda en azul con `Aceptar alta automática`: un popup editable separa datos de factura, contraste oficial VIES y coincidencias del maestro. Charlie nunca guarda el gasto ni crea el proveedor silenciosamente; el usuario revisa ambas fichas y confirma antes de continuar. - Lista de gastos con busqueda por proveedor, concepto o referencia y filtros `Todos`, `Por pagar`, `Vencidos` y `Pagados`; cada fila abre la ficha completa y conserva el pago rapido `Pagar`. - Alta sencilla con concepto, proveedor, base, IVA, total calculado, fechas y estado visibles. Imputacion, relacion con cliente/explotacion/proyecto, conciliacion y notas permanecen visibles en la misma ficha sin retirar ningun campo. - Estado de gasto mediante un unico selector `Pendiente de pago`, `Pago programado` o `Pagado`, sin franja de pasos ni acciones redundantes. Duplicar y anular viven en `Mas acciones` solo cuando existe un gasto guardado. - Edicion directa de gastos, centros, planes, servicios y productos desde sus listas auxiliares. - Resumen de ingresos, gastos, margen, pendiente y vencido. - Resumen fiscal de IVA repercutido, IVA soportado, IVA a liquidar y caja cobrada. - Tesoreria prevista en `Analitica`: cobros, pagos y neto operativo a 7 y 30 dias con acceso directo a cartera y cuentas a pagar. - Calidad de cobro dentro de `Tesoreria prevista`: tasa de cobro, plazo medio, vencido abierto y clientes en riesgo. - Rentabilidad por concepto en `Analitica`: ingresos, coste directo, margen y margen porcentual por servicio, producto, cuota o linea manual; tambien se puede elegir `Conceptos` en la tabla principal y exportarlo por CSV. - Control presupuestario por centro analitico con uso, margen y acceso directo al centro. - Cartera de cobro por tramos de vencimiento con acceso directo a la factura. - Aging de cartera exigible por antigüedad de saldo y cliente, con acceso directo al extracto. - Plan de cobros operativo que prioriza facturas vencidas o proximas, abre el cobro y copia recordatorios sin pasar por la lista general. - Cuentas a pagar por tramos de vencimiento proveedor, apertura directa del gasto y CSV propio. - Extracto de cliente con cuenta corriente, debe, haber, saldo, usuarios cliente de portal, apertura directa de factura y CSV propio. - `Gastos` separa `Control de gastos` y `Centros analiticos`; `Catalogo` separa `Servicios`, `Productos` y `Emisor`; `Analitica` separa `Resumen`, `Cobros y pagos`, `Margen y fiscalidad` y `Extractos`. Todas las funciones siguen en el mismo modulo, pero una sola superficie densa queda visible cada vez. - Analitica y cierre usan scroll interno de panel para mantener cabecera, exportacion y controles dentro del workspace sin alargar la pantalla. - Periodo contable con fechas `Desde` y `Hasta` y atajos `Mes`, `Trim.`, `Año` y `Todo` para cerrar analitica, KPIs, fiscalidad y CSV sin mezclar historicos. - Libro contable con asientos derivados de facturas, abonos, gastos y cobros, balance por cuenta y filtro operativo por cuenta contable. - Conciliacion de cobros y pagos pagados: detecta movimientos sin metodo, referencia, identificador bancario o confirmacion de conciliacion y abre el cobro o gasto exacto para corregirlo. - Trazabilidad de facturacion en `Cierre`, alimentada por `GET /api/activity?module=billing`, con actor, accion, fecha y apertura directa de la ficha cuando existe. - Zona segura en `Cierre` para que el boton flotante de Charlie no tape acciones de imputacion o apertura. - Checklist de cierre por periodo con controles accionables antes de exportar. - Exportacion CSV de la analitica agrupada. - Exportacion CSV del libro contable y del checklist de cierre del periodo. - Vista `Gestoria y legal` con control de preparacion, huella SHA-256 encadenada para registros VERI*FACTU preparados, XML Facturae 3.2.2 exportable y paquete ZIP con manifiesto, facturas, lineas, cobros, entregas, XML y copias HTML documentales. Ninguna accion se marca como presentada ante AEAT, FACe o proveedor externo si no hay integracion y certificado configurados. ## Base Fiscal Y Series El backend prepara una base fiscal comun para que Facturacion no dependa de valores sueltos en la UI: - `company_settings` guarda datos fiscales de la empresa emisora, como razon social, NIF/CIF, direccion, contacto, cuenta bancaria, logo y notas de pie. `logo_url` solo admite una imagen raster `data:image` PNG, JPEG o WebP validada y limitada a 2 MB; cualquier URL remota o contenido no valido se descarta. - `billing_series` mantiene series activas por tipo de factura. Las instalaciones nuevas incluyen `FAC` ordinaria, `PRE` presupuesto, `ANT` anticipo, `REC` rectificativa, `SIM` simplificada y `CRE` abono; bases historicas conservan el prefijo comercial ya utilizado para no romper continuidad. `billing_number()` reinicia contador por año, comprueba colisiones y solo reserva numeracion fiscal al emitir. - `tax_rates` registra tipos de IVA, IGIC y recargo de equivalencia iniciales para futuras pantallas fiscales sin hardcodear porcentajes en cada modulo. - `billing_invoices` ya reserva `series_id`, `rectified_invoice_id`, `rectification_type`, `rectification_reason` y `document_notes_html`; otros modulos deben consumir estas columnas a traves de las rutas de Facturacion y no escribirlas directamente. En la UI, al elegir `Rectificativa` aparecen factura original, tipo de rectificacion (`differences`/`substitution`) y motivo; el backend exige factura original valida y limpia esos campos en facturas no rectificativas. `document_notes_html` guarda solo el contenido destinado al cliente y pasa por el saneador HTML de informes compartido. - Cada borrador recurrente guarda `recurrence_plan_id` y `recurrence_due_date`. El indice unico parcial sobre ambas columnas impide dos facturas para el mismo vencimiento incluso con doble clic, reintento o concurrencia; editar despues el borrador conserva esos metadatos internos aunque el navegador no los reenvie. - `billing_recurring_plans.anchor_day` conserva el dia original de los planes mensuales, trimestrales y anuales: un plan del dia 31 usa el ultimo dia disponible en febrero y recupera el 31 en marzo en vez de derivar al 28 para siempre. La migracion recupera ese ancla desde `start_date` y, si falta, desde `next_run_date` para los planes existentes. - `billing_invoice_lines` y `billing_recurring_plan_lines` guardan `irpf_rate`; el total de factura calcula `base + IVA - IRPF`. Las facturas simplificadas se validan con limite de 400 euros y las formas de pago se guardan con codigos estandar (`01` a `06`) desde el selector de factura. - `billing_invoice_deliveries` conserva cada preparacion, envio, entrega o descarga sin confundir abrir un correo con una entrega confirmada. - `billing_payments` añade `bank_account`, `bank_transaction_reference`, `reconciliation_status`, `reconciled_at` y `reconciled_by` para relacionar cobros parciales o totales con el banco. - `billing_compliance_records` conserva tipo, estado local, huella, huella anterior, referencia externa y fechas. El estado inicial es siempre `prepared`; `submitted` o `accepted` quedan reservados para una integracion oficial futura. - `customers.tax_id` queda disponible como identificador fiscal unificado de clientes y busquedas. ## Uso operativo 1. Abrir `Facturacion` desde la barra lateral o desde la ficha de cliente. La entrada operativa es `#facturacion/control`. 2. Revisar Prioridades y Últimas facturas en la mesa. Abrir `Indicadores` solo cuando se necesiten cartera, tesoreria o calidad; usar la navegacion diaria para `Facturas`, `Gastos` y `Recurrentes`, y `Mas vistas` para `Catalogo`, `Analitica`, `Libro`, `Cierre` y `Gestoria y legal`. Ninguna subvista se ha retirado. 3. Pulsar `Nueva factura`, elegir cliente y escribir concepto, cantidad y precio antes de usar `Añadir concepto` y guardar el borrador. Vencimiento y forma de pago permanecen a la vista; `Opciones avanzadas` conserva tipo, emision, explotacion, proyecto, numeracion, rectificacion, estado y notas. 4. La cola elige automaticamente la primera prioridad no vacia: `Vencidas`, `Por cobrar`, `Borradores` y, cuando no hay pendientes, `Todas`. Se puede cambiar manualmente en cualquier momento. 5. Usar la accion principal disponible: `Finalizar factura`, `Enviar al cliente`, `Registrar aceptacion`, `Convertir en factura` o `Registrar cobro`. En presupuestos, primero se registra la aceptacion y despues `Convertir en factura` genera un borrador ordinario enlazado; el numero `FAC` se reserva al finalizar ese borrador. `Enviar al cliente` abre la preparacion y trazabilidad de entrega, no cambia el estado silenciosamente. Abrir `Mas acciones` para `Duplicar`, `Abonar` o `Anular`. 6. Para usar un servicio o producto guardado, cambiar impuestos o imputar el concepto, abrir `Catalogo y opciones`. La tabla resume esos datos bajo el concepto para mantenerlos consultables. `Imputar lineas` aplica el centro y/o categoria del editor solo a las lineas que aun no lo tengan. Si un concepto necesita correccion, usar `Editar` para cargarlo en el editor —las opciones avanzadas se abren automaticamente—, `Actualizar concepto` para aplicar el cambio, `Copiar` para repetirlo o `Cancelar edicion` para volver al alta. 7. Guardar el borrador antes de preparar el documento, enviarlo o cobrarlo. El backend calcula base, IVA y total; la ficha cambia de la preparacion guiada a la vista de trabajo de la factura guardada. 8. Alternar `Ver PDF`, `Enviar`, `Cobrar` y `Revisar`. `Ver PDF` monta `AnimalCharlieDocumentEditor` con perfil `report`; `Enviar` prepara correo y registra trazabilidad; `Cobrar` registra pagos y conciliacion; `Revisar` detecta errores, prepara recordatorios y abre Charlie sobre la factura activa. El panel `Cobros y vencimientos` precarga solo el saldo pendiente; si la factura ya esta cobrada, bloquea el alta de nuevos cobros para evitar duplicados, pero permite `Editar` un cobro existente y actualizar importe, fecha, metodo, referencia o notas. `Cancelar edicion` vuelve al alta normal. `Copiar recordatorio` genera un texto listo para WhatsApp o email con cliente, numero, vencimiento, saldo y forma de pago prevista; no envia nada automaticamente y se desactiva en borradores, facturas cobradas o canceladas. 9. En `Gastos`, usar `Control de gastos` para registrar y consultar compras y costes, y `Centros analiticos` para mantener codigos y presupuestos. `Nuevo` limpia la ficha y deja a la vista proveedor obligatorio, documento, tipo de compra, concepto, importes, fechas, imputacion, pago, referencia y notas. Las líneas admiten mercancía, servicios, activos y gasto general; para mercancía o activos se elige si entra en inventario. `Leer factura o ticket` abre la biblioteca privada de Facturación; al subir o elegir una foto/PDF, Charlie rellena cabecera y líneas, contrasta el catálogo y muestra qué artículo reutilizaría o crearía. Si el proveedor ya existe se vincula su ID; si no, aparece en azul y `Aceptar alta automática` abre el popup sin pasos para corregir la ficha, aplicar datos oficiales de VIES, usar una coincidencia existente o confirmar `Crear de todas formas`. El servidor vuelve a comprobar duplicados al aceptar. Si la ficha de gasto ya contiene datos, pide confirmación antes de sustituir campos. Nada se persiste ni mueve stock hasta pulsar `Guardar gasto`. La columna izquierda permite buscar, filtrar y abrir cualquier movimiento; `Pagar` cierra rapidamente un proveedor pendiente. En PC se mantienen lista y ficha simultaneas; en Galaxy Tab A9+ e iPad Air la lista ocupa el ancho al entrar y, al elegir o crear un gasto, la ficha usa todo el espacio disponible con `Volver a gastos` como retorno directo. Clasificación, líneas, tesorería y seguimiento siguen visibles sin desplegables. Al guardar se mantiene la ficha seleccionada para poder revisar o corregir sin buscarla de nuevo. 10. En `Recurrentes`, mantener planes periodicos y su imputacion. Si hay vencidos, pulsar `Generar vencidas`, revisar el popup y confirmar una sola vez; se crea como maximo una ocurrencia por plan en cada lote para evitar recuperar meses atrasados sin revision. El resultado avisa si queda otro periodo pendiente y permite abrir cada factura creada. La accion `Generar` de cada fila sigue disponible para casos individuales. 11. En `Catalogo`, alternar `Servicios`, `Productos` y `Emisor`; el boton primario de la cabecera guarda la superficie activa. 12. En `Analitica`, ajustar `Periodo` con fechas manuales o con `Mes`, `Trim.`, `Año` y `Todo`. Usar `Resumen`, `Cobros y pagos`, `Margen y fiscalidad` y `Extractos` para revisar una familia de datos cada vez; `Extractos` conserva el extracto de cliente y la tabla agrupada, y todas las aperturas a facturas, gastos, clientes, productos o centros se mantienen. 13. En `Libro`, revisar el balance por cuenta contable, filtrar una cuenta concreta si se esta cuadrando banco, clientes, IVA o proveedores, y exportar el libro contable del periodo para contraste con asesoria o contabilidad externa. 14. En `Cierre`, revisar conciliacion, ultimos movimientos de facturacion, descuadres, borradores, vencidos, imputaciones incompletas, gastos pendientes, recurrentes vencidos e IVA estimado antes de dar por cerrado el periodo. 15. En `Gestoria y legal`, corregir incidencias, preparar huella VERI*FACTU o descargar Facturae de una factura lista y exportar el paquete del periodo. La vista indica siempre que preparar o exportar no equivale a presentar oficialmente. ## Subvistas y hash Cada subvista tiene hash propio para que se pueda compartir o restaurar: - `#facturacion/facturas`: indice, formulario de factura, lineas y pagos. - `#facturacion/gastos`: alta y listado de gastos imputables. - `#facturacion/recurrentes`: planes de facturacion periodica. - `#facturacion/catalogo`: servicios y productos facturables. - `#facturacion/analitica`: resumen, agrupaciones y centros analiticos. - `#facturacion/libro`: libro contable derivado de facturas, cobros y gastos. - `#facturacion/cierre`: checklist de cierre del periodo con accesos directos a la incidencia. - `#facturacion/gestoria-legal`: preparacion VERI*FACTU, Facturae y paquete para gestoria. El boton primario de la cabecera cambia segun la subvista activa y tambien sigue la pestaña interna de `Gastos` o `Catalogo`: guardar factura, gasto, centro, plan, servicio, producto o emisor; exportar CSV de analitica, libro o cierre. La navegacion enfocada usa `Facturas / Factura`: el indice ocupa el workspace al entrar y seleccionar o crear abre la ficha completa. En las vistas sin indice propio se enfoca directamente el workbench y se oculta esa navegacion local para no mostrar `Factura` mientras se trabaja en Analitica, Libro o Cierre. La cola de trabajo del indice filtra sin cambiar de subvista: `Por cobrar` y `Vencidas` excluyen presupuestos y borradores, mientras `Borradores` localiza documentos pendientes de emitir. `Emitir` llama al endpoint de estado y reserva numero; `Enviar` abre la subvista de entrega; `Registrar aceptacion` llama a `POST /api/billing/invoices/{id}/accept`; `Crear factura` llama a `POST /api/billing/invoices/{id}/convert` solo cuando el presupuesto tiene aceptacion trazable; `Cobrar` abre la pestaña de cobros. `Duplicar`, `Abonar` y `Anular` conservan su comportamiento previo. El panel `Documento` de `Facturas` compone la factura desde el formulario actual y las lineas cargadas. Antes de exportar comprueba cliente, al menos una linea, razon social, NIF/CIF y direccion del emisor; avisa tambien si faltan numero definitivo, NIF/direccion del cliente o forma de pago. Muestra emisor y receptor, explotacion/REGA/proyecto, emision, vencimiento, forma de pago, base por linea, descuentos, IVA por tipo, IRPF, total, saldo y datos de rectificacion. Las facturas en borrador o proformas muestran una marca de agua y las simplificadas omiten los datos completos del receptor. El documento se monta con `AnimalCharlieDocumentEditor.mount(...)`, perfil `report` y `editableSelector: "[data-billing-document-notes-body]"`. Solo ese bloque admite texto, formato, listas, tablas, imagenes e IA; al guardar se persiste en `billing_invoices.document_notes_html`, saneado en backend. Las notas internas (`billing_invoices.notes`), centros analiticos y categorias de las lineas se mantienen en el ERP pero no se interpolan en el HTML del cliente. Al emitir o salir de borrador, incluso ese bloque queda en modo lectura. `Preparar PDF` abre `AnimalCharliePdfEngine` para revisar pagina, orientacion, margenes y escala. `Descargar` usa `POST /api/pdf/render` con el preset `invoice`, pie repetible y numeracion de paginas; ambos parten del mismo HTML que se ve en Documento y eliminan antes los atributos editables. Si el contenido para el cliente esta vacio, su seccion no ocupa espacio en el PDF. El nombre del fichero deriva del numero y el cliente. El logotipo del emisor se incrusta cuando existe; si no existe y la razon social contiene Herba, se usa el lockup vectorial corporativo incluido en la aplicacion, sin dependencias de red. El bloque `Fiscalidad` de `Analitica` calcula IVA repercutido desde `revenueTotal - revenueNet`, IVA soportado desde `expensesTotal - expensesNet`, IVA a liquidar como diferencia y caja cobrada desde `paid`. Es una estimacion operativa para control interno; el cierre fiscal formal debe contrastarse con la asesoria y los libros oficiales. El bloque `Tesoreria prevista` combina la cartera de cobro y las cuentas a pagar del periodo. Muestra entradas previstas a 7 dias, salidas previstas a 7 dias, neto operativo a 7 y 30 dias, caja cobrada y riesgo dominante (`pagos vencidos`, `cobros vencidos`, `salida neta 7d` o `caja controlada`). La franja `Calidad de cobro` añade tasa de cobro sobre facturas emitidas en el periodo, plazo medio de facturas cerradas, porcentaje vencido sobre cartera abierta y clientes con riesgo, usando solo facturas, cobros y vencimientos ya cargados. Los accesos `Cartera` y `Pagos` no crean datos: desplazan al usuario al bloque operativo correspondiente para abrir la factura o gasto original. En esos bloques, los buckets de vencimiento son filtros accionables; pulsar el bucket activo una segunda vez recupera la lista completa. El bloque `Rentabilidad por concepto` agrupa las lineas facturadas del periodo por servicio, producto, cuota o concepto manual. Es el mismo dato que `GET /api/billing` publica en `analytics.byConcept`, por lo que el selector `Conceptos` lo muestra tambien en la tabla principal de margen y `Exportar CSV` genera `animalcharlie-analitica-byConcept.csv`. Para productos de catalogo usa el campo `Coste` del producto como coste directo por unidad, incluso si el producto ya no esta activo; en servicios, cuotas y manuales deja el coste directo a cero salvo que se impute como gasto analitico en el modulo. Cada fila muestra ingresos, coste directo, margen y margen porcentual. Si el concepto viene del catalogo, la fila abre `Catalogo` y carga el servicio o producto para ajustar precio, coste, categoria o notas sin perder el contexto analitico. El bloque `Presupuesto` usa `analytics.byCostCenter` para mostrar centros con presupuesto, gastos, ingresos o margen. Cada fila indica gasto imputado, presupuesto mensual, margen y porcentaje de uso. Al hacer clic en un centro se abre `Gastos > Centros analiticos` con el presupuesto listo para revisar. La exportacion CSV incluye las columnas `Presupuesto` y `Uso presupuesto %`. La cartera de cobro de `Analitica` separa el saldo pendiente en `+30 vencido`, `1-30 vencido`, `0-7 dias`, `8-30 dias` y `+30 dias`. Cada bucket filtra la lista inferior por tramo de vencimiento y muestra el tramo activo en la cabecera del panel. Cada fila se comporta como un boton de trabajo: abre la factura en `Facturas` y deja preparado el formulario de cobro para registrar el pago. El bloque `Aging de cartera` toma solo facturas exigibles, excluyendo borradores, proformas, pagadas y canceladas. Agrupa el saldo por `Al dia`, `1-30`, `31-60` y `+60` dias vencidos, y lista clientes con desglose por antigüedad para priorizar seguimiento contable. Cada bucket filtra la lista de clientes; cada cliente abre el `Extracto cliente` para revisar movimientos y saltar a la factura original. El bloque `Cartera por cliente` agrupa esa cartera pendiente por cliente, mostrando saldo vencido, saldo pendiente y riesgo operativo (`vencido`, `proximo` o `controlado`). Cada fila abre el `Extracto cliente` del mismo cliente, de modo que contabilidad puede pasar de la alerta de cobro a la cuenta corriente y desde ahi a la factura original sin cambiar de modulo. El bloque `Plan de cobros` convierte la cartera pendiente en una cola diaria de trabajo. Excluye borradores, proformas, facturas pagadas y canceladas; prioriza por vencimiento (`reclamar`, `hoy`, `confirmar`, `preparar` o `seguir`) y muestra saldo pendiente, cliente, documento y accion. `Cobrar` abre la factura original en `Facturas`, prepara el importe pendiente y enfoca el registro de pago. `Recordatorio` copia el mismo texto firmado que usa el panel de `Pagos`, sin enviar nada automaticamente ni cambiar de subvista. El bloque `Cuentas a pagar` de `Analitica` separa gastos pendientes o programados por vencimiento de proveedor: vencidos, hoy, 0-7 dias, 8-30 dias y +30 dias. Cada bucket filtra los pagos inferiores por tramo y deja el bucket activo marcado con el acento de la vista. Cada fila abre el gasto original en `Gastos` con el campo `Vence el` enfocado, para completar fecha, metodo, referencia o cambiar el estado a `Pagado`. Desde la lista de `Control de gastos`, `Pagar` carga el gasto y persiste el pago rapido con fecha de hoy y transferencia por defecto si el metodo estaba vacio. `Exportar pagos` descarga `animalcharlie-cuentas-a-pagar.csv` con proveedor, concepto, vencimiento, estado, referencia, centro e importe. El bloque `Extracto cliente` de `Analitica` genera una cuenta corriente por cliente a partir de las facturas y cobros cargados por `GET /api/billing`. El selector muestra los clientes ordenados por saldo pendiente; la tabla lista movimientos del periodo con `Debe`, `Haber` y `Saldo`, y cada fila abre la factura original para revisar o registrar cobros. Si el cliente tiene ficha CRM, el panel consulta `GET /api/clients/{id}/users` y muestra `Usuarios cliente` con `clientUsersSummary`, estado de credenciales, permisos de portal, WhatsApp y botones `Histórico`/`Abrir` para operadores con `users.manage`; si el perfil no tiene `clients.read` o `users.manage`, la zona queda en lectura restringida y el extracto contable sigue funcionando. `Exportar extracto` descarga `animalcharlie-extracto-cliente.csv` con cliente, fecha, tipo, documento, detalle, debe, haber y saldo. La barra `Periodo` filtra `GET /api/billing` con `dateFrom` y `dateTo`. `Mes`, `Trim.` y `Año` rellenan las fechas del periodo actual de trabajo y `Todo` limpia ambos campos; las fechas manuales siguen siendo posibles para cierres irregulares. El backend aplica esas fechas sobre `issue_date` en facturas y `expense_date` en gastos; si el campo esta vacio usa la fecha de creacion. El resultado recalcula KPIs, listas, fiscalidad, presupuesto, cartera y exportacion CSV sobre el mismo periodo. La subvista `Libro` no guarda una tabla nueva: compone el libro desde los datos operativos cargados por `GET /api/billing`. Las facturas ordinarias generan debe en `430 Clientes` y haber en `700 Ingresos veterinarios` / `477 IVA repercutido`; los abonos invierten el asiento; los cobros generan banco/caja contra clientes; los gastos generan `62x Gasto operativo`, `472 IVA soportado` y proveedor o banco/caja segun estado. La cabecera muestra debe, haber, descuadre y una franja de cuentas; cada cuenta resume lineas, importe dominante y saldo deudor o acreedor. Al pulsar una cuenta se filtra la lista inferior y `Exportar libro` descarga solo la vista filtrada; al pulsarla de nuevo o usar `Todas`, vuelve el libro completo. Cada fila conserva fecha, asiento, cuenta, concepto, centro analitico, categoria, origen y estado, y permite abrir la factura o gasto original. La subvista `Cierre` usa el mismo periodo y no crea datos nuevos. Calcula controles sobre las facturas, gastos, planes, libro y fiscalidad ya cargados: - Libro cuadrado: compara debe y haber del libro derivado. - Conciliacion bancaria: revisa cobros y gastos pagados sin metodo o referencia. - Facturas sin emitir: detecta borradores dentro del periodo. - Cartera vencida: suma saldos pendientes con vencimiento anterior a hoy. - Facturas o gastos sin imputacion: localiza registros sin centro analitico o categoria. - Gastos pendientes: lista costes pendientes o programados que afectan tesoreria. - Recurrentes vencidos: detecta planes activos cuya proxima factura ya deberia generarse y abre directamente la vista previa agrupada. - IVA estimado: muestra el saldo operativo de IVA repercutido menos soportado. Cada fila del checklist abre la factura, gasto, plan, libro, cartera o bloque fiscal correspondiente. `Exportar cierre` descarga `animalcharlie-cierre-contable.csv` con estado, items, importe, detalle y accion recomendada. El bloque `Conciliacion` de `Cierre` resume cobros registrados, gastos pagados, movimientos sin metodo y movimientos sin referencia. Cada incidencia abre su factura o gasto original para completar el dato sin abandonar el flujo de cierre. En facturas conserva el identificador del cobro, carga ese pago directamente en modo `Actualizar pago` y enfoca `Metodo` o `Referencia` segun la alerta; el usuario solo completa el dato pendiente y guarda sin borrar el movimiento. En gastos se enfocan los campos `Metodo` o `Referencia` de la ficha original. Estos datos no sustituyen a la conciliacion bancaria oficial, pero dejan el ERP preparado para contrastar banco/caja con el libro derivado. Las filas de `Control de gastos` abren directamente la ficha sin repetir un boton `Abrir`; las listas de `Recurrentes`, `Catalogo` y `Centros analiticos` conservan sus acciones auxiliares. Al guardar con un registro abierto se actualiza el elemento existente mediante su endpoint `PUT`; al guardar sin registro abierto se crea uno nuevo. En gastos, la ficha guardada permanece seleccionada y `Duplicar gasto` prepara una copia pendiente con fecha de hoy sin modificar el original. Los planes recurrentes guardan `costCenterId` y `analyticCategory` en sus lineas. Al generar una factura desde el plan, todas las lineas, IVA, IRPF, descuentos e imputacion se copian a `billing_invoice_lines`, por lo que la cuota periodica entra directamente en `Analitica`, `Presupuesto` y la exportacion CSV sin correcciones manuales posteriores. Editar desde el formulario compacto actualiza la primera linea visible y conserva las lineas adicionales existentes. `GET /api/billing/plans/due-preview?asOf=AAAA-MM-DD` es de solo lectura y devuelve planes listos, ya generados o bloqueados. `POST /api/billing/plans/generate-due` recibe las ocurrencias exactas confirmadas (`planId` y `dueDate`), vuelve a comprobar fecha, estado y fin del plan y usa un savepoint por elemento: un plan defectuoso no revierte los borradores correctos. El lote genera una ocurrencia por plan, actualiza su siguiente fecha y devuelve `remainingDue` cuando todavia queda atrasado. Repetir la misma ocurrencia responde `already_generated` y no vuelve a avanzar el plan. `POST /api/billing/payments` rechaza importes cero, negativos o superiores al saldo pendiente. Si se manda `id`, actualiza el cobro existente y permite reutilizar su importe dentro del saldo editable para corregir referencia, metodo, fecha, importe o notas. `PUT /api/billing/payments/{id}` expone el mismo contrato de actualizacion usando el identificador en la URL. La UI replica esa regla antes de llamar al backend: muestra un `status-pill` con el saldo pendiente o editable, desactiva el alta si no hay saldo y corrige el importe cuando supera el saldo abierto. `Copiar recordatorio` no crea datos ni llama al backend. El recordatorio de cobro usa la factura seleccionada en memoria, exige factura guardada con saldo pendiente y estado distinto de `draft`, `paid` o `cancelled`, y copia al portapapeles un mensaje firmado como `AnimalCharlie. · desarrollado por Herba` para pegarlo en WhatsApp o email. La factura visual mantiene el wordmark de AnimalCharlie como producto y muestra el lockup corporativo de Herba únicamente en la atribución. Cuando se registra, actualiza o borra un cobro, el backend recalcula el estado de la factura desde el saldo real. Una factura queda `paid` solo si el saldo es cero; si al borrar o reducir un pago vuelve a quedar saldo abierto, recupera `sent` u `overdue` segun su vencimiento. ## API interna La vista principal consume `GET /api/billing`, que requiere rol legacy de lectura (`admin`, `technician` o `reviewer`) o permiso global `billing.read` / `billing.write`, y devuelve: - `invoices`: facturas con lineas, pagos, entregas, registros de cumplimiento, saldo, estado operativo y datos de cliente/proyecto. - `services` y `products`: catalogos activos. - `plans`: planes recurrentes. - `costCenters`: centros analiticos activos e historicos. - `expenses`: gastos no anulados. - `analytics`: totales y agrupaciones por centro, cliente, proyecto, explotacion, concepto y categoria. Endpoints especificos: - `POST /api/billing/invoices` - `POST /api/billing/invoices/{id}/convert` - `POST /api/billing/invoices/{id}/accept` - `POST /api/billing/invoices/{id}/deliveries` - `POST /api/billing/invoices/{id}/compliance` - `POST /api/billing/payments` - `PUT /api/billing/payments/{id}` - `POST /api/billing/services` - `POST /api/billing/products` - `POST /api/billing/plans` - `GET /api/billing/plans/due-preview` - `POST /api/billing/plans/generate-due` - `POST /api/billing/plans/{id}/generate` - `POST /api/billing/cost-centers` - `POST /api/billing/expenses` - `GET /api/billing/analytics` - `GET /api/billing/company-settings` - `POST /api/billing/company-settings` - `GET /api/billing/series` - `POST /api/billing/series` - `GET /api/billing/tax-rates` - `GET /api/billing/compliance` - `GET /api/billing/compliance/export` Las escrituras requieren rol legacy `admin`/`technician` o permiso global `billing.write`. Esto permite que `Usuarios` habilite perfiles de facturacion sin convertirlos en administradores ni tecnicos completos. En Recurrentes, los perfiles de solo lectura conservan la revision de planes pero no ven las acciones `Generar`, `Generar vencidas`, `Archivar` ni la confirmacion del lote. El resultado del lote conserva en memoria las facturas creadas para poder abrirlas aunque el periodo activo excluya la fecha de hoy. La auditoria UI read-only de `tools/verify_billing_readonly_ui.py` cubre PC 1920x1080, PC 1280x800, Galaxy Tab A9+, iPad Air horizontal e iPad Air vertical. Comprueba las nueve vistas, busqueda y colas, filas de Control por raton/teclado, primaria contextual de Gastos, borradores sin guardar, errores simulados de guardado, targets tactiles, overflow y ausencia de escrituras reales. `tools/verify_billing_recurring.py` valida en SQLite aislado que la vista previa no escriba, que se copien planes multilínea, que editar conserve el enlace, que los reintentos sean idempotentes, que una previsualizacion obsoleta se rechace, que los errores parciales no reviertan los exitos, que el dia ancla sobreviva a febrero y que la migracion recupere el ancla de planes antiguos. `GET /api/billing` y `GET /api/billing/analytics` aceptan filtros de periodo: - `dateFrom=AAAA-MM-DD`: incluye facturas/gastos desde esa fecha. - `dateTo=AAAA-MM-DD`: incluye facturas/gastos hasta esa fecha. El libro contable usa el mismo periodo visible. Para pagos, la UI aplica tambien el rango a `payment_date` cuando hay fechas activas, de modo que el CSV de libro no mezcla cobros fuera del cierre elegido. El checklist de cierre usa exactamente ese mismo periodo. Si se cambia `Desde` o `Hasta`, se recalculan a la vez analitica, libro, cartera y cierre. ## Modelo analitico Los ingresos salen de `billing_invoice_lines`, usando `cost_center_id`, `analytic_category` y `item_id` para construir `analytics.byConcept`. Los costes salen de `billing_expenses`, con estos campos principales: - `supplier_id`: vínculo obligatorio al guardar con la ficha maestra de `Proveedores`; los registros históricos sin ID siguen siendo legibles. - `cost_center_id` - `customer_id` - `project_id` - `expense_date` - `due_date` - `supplier` - `category` - `concept` - `amount`, `tax_rate`, `tax_total`, `total` - `payment_status` - `payment_method`, `reference`, `notes` - `document_type`: factura, ticket, albarán, recibo u otro. - `purchase_type`: mercancía, servicios, activos, gasto general o compra mixta. - `inventory_status`: no aplicable, aplicado, pendiente de revisión o revertido. - `source_asset_id`: justificante privado en `shared_assets`, vinculado al gasto definitivo al guardar. - `source_extraction_json`: confianza, avisos, campos detectados, agente y proveedor usados, propuesta de proveedor, procedencia de sus datos y resolución creada/existente para poder auditar el borrador. El selector de proveedor en Gastos consulta `GET /api/suppliers`. Cuando se elige una ficha existente, la compra conserva `supplier_id` y copia el nombre visible en `supplier` como instantánea compatible con los registros antiguos. También propone categoría, forma de pago, IVA y vencimiento de la ficha al crear un gasto. Si un nombre escrito manualmente no coincide con el maestro, `Alta proveedor` abre Proveedores con la razón social ya escrita. Cuando el nombre procede del análisis documental, la UI lo resalta en azul y usa `Aceptar alta automática`: la revisión muestra todos los datos detectados en la factura, el resultado de VIES y proveedores exactos o similares antes de crear. La compra no puede guardarse hasta seleccionar una ficha activa. Si cambia el texto de un proveedor seleccionado, la UI limpia el ID para no enlazarlo con la empresa equivocada. La ficha del proveedor muestra después esas compras mediante el mismo endpoint filtrado. Las líneas se guardan en `billing_purchase_lines`. Para las que tengan `inventory_action='increase'`, el backend contrasta `billing_products` y `billing_product_supplier_refs` por referencia del proveedor, código de barras, SKU, nombre normalizado y similitud. Una coincidencia fiable reutiliza el artículo existente aunque la propuesta de IA indicase otro ID. Solo cuando no hay coincidencia se confirma el alta de un producto nuevo. Las entradas quedan en `billing_inventory_movements`; editar recalcula los movimientos de la compra de forma idempotente y anularla revierte el stock. `billing_products` añade código de barras, unidad, stock mínimo, control de existencias, último coste, proveedor y fecha de compra, y sigue siendo el único maestro de artículos. `POST /api/billing/expenses/analyze-document` recibe `assetId` y el contexto actual de la ficha, ejecuta la misma capacidad `billing_expense_from_document` publicada en el MCP de Facturación y devuelve solo un borrador. AnimalCharlie entrega el documento por el puente interno al Hermes local, que selecciona `hermes-module-billing` y el modelo GPT configurado específicamente para compras y gastos. El agente recibe proveedores, productos y referencias reales, extrae las líneas y propone coincidencias, pero el backend vuelve a validarlas al guardar. También devuelve `supplierProposal` con datos editables, fuentes, resultado público y coincidencias; `POST /api/suppliers/assisted-preview` actualiza ese contraste y `POST /api/suppliers/assisted-create` repite la deduplicación justo antes del alta. La consulta pública usa VIES de la Comisión Europea y solo transmite país y NIF-IVA; nunca envía el PDF, la imagen ni el texto de la factura. Los PDF con texto se procesan además con extracción local; fotos y documentos escaneados se preparan como imágenes acotadas para la lectura multimodal. Si Hermes, GPT o VIES no están disponibles, el parser local y la revisión manual conservan una degradación útil. El contenido del justificante no se incluye en auditoría ni se expone por URL pública. El margen general se calcula como `ingresos base - gastos base`. Solo entran como ingreso las facturas fiscales emitidas; borradores, presupuestos, aceptados y cancelados no inflan analitica, libro ni fiscalidad. En `analytics.byConcept`, el coste directo de productos se toma de `billing_products.cost * quantity` para que la rentabilidad por producto pueda auditarse aunque no exista un gasto imputado. El IVA queda separado para no mezclar caja fiscal con rentabilidad operativa. Cuando `cost_center_id` se deja vacio desde la UI, el backend guarda `NULL` en lugar de una cadena vacia para respetar la clave foranea de `billing_cost_centers`. La analitica lo agrupa como `Sin centro` y el checklist de cierre lo mantiene como gasto pendiente de imputacion.