verifactu-rails 0.1.0.pre

data/lib/verifactu_rails/formato.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'date'
+require_relative 'error'
+
+module VerifactuRails
+  # Normalización canónica de los valores que aparecen a la vez en la cadena de la
+  # huella y en el XML.
+  #
+  # REGLA DE ORO, la misma que rige Importe: la AEAT recalcula la huella sobre lo
+  # que recibe en el XML. Si un valor se normaliza distinto en cada sitio, rechazo.
+  # Por eso fechas y marcas temporales viven aquí y no duplicadas en cada módulo.
+  #
+  # (El escapado XML es harina de otro costal y no rompe esta regla: la huella se
+  # calcula sobre el valor crudo y el XML lo escapa, pero la AEAT desescapa antes
+  # de recalcular. Una serie "A&B" va cruda a la huella y como "A&B" al XML.)
+  module Formato
+    module_function
+
+    # Espacios al inicio y al final: la spec NO es ambigua, dice recortarlos.
+    #
+    #   "Los valores de los campos deberán tener la misma información contenida
+    #    en el campo correspondiente del fichero XML, pero eliminando los
+    #    espacios al inicio y al final de cada valor"
+    #   (Especificaciones huella v0.1.2, ap. 3)
+    #
+    # Aquí rechazamos en vez de recortar, que es MÁS ESTRICTO que la norma: un
+    # valor con espacios al borde casi siempre es un defecto de los datos de
+    # origen, y recortar en silencio lo taparía. Los espacios interiores sí se
+    # respetan ("12345678 / G33" es un NumSerieFactura válido y así lo ejemplifica
+    # la propia AEAT).
+    def texto(valor, campo)
+      cadena = valor.to_s
+      raise ValidacionError, "#{campo} no puede estar vacío" if cadena.empty?
+
+      if cadena != cadena.strip
+        raise ValidacionError,
+              "#{campo} contiene espacios al inicio o final: #{cadena.inspect}. " \
+              'Normalízalo antes de generar el registro.'
+      end
+      cadena
+    end
+
+    # Tipo sf:fecha del XSD: exactamente dd-mm-yyyy.
+    def fecha(valor)
+      objeto = valor.is_a?(String) ? Date.strptime(valor, '%d-%m-%Y') : valor
+      # Guarda explícita, como en marca_temporal: sin ella, un nil se escapaba
+      # del contrato de errores del módulo con un NoMethodError en vez de un
+      # ValidacionError, porque el rescue de abajo no captura NoMethodError.
+      unless objeto.respond_to?(:strftime)
+        raise ValidacionError, "Fecha inválida (se espera Date o 'dd-mm-yyyy'): #{valor.inspect}"
+      end
+
+      objeto.strftime('%d-%m-%Y')
+    rescue ArgumentError, TypeError
+      raise ValidacionError, "Fecha inválida (se espera Date o 'dd-mm-yyyy'): #{valor.inspect}"
+    end
+
+    # ISO 8601 con offset explícito. OJO: Ruby serializa UTC como "Z" mientras
+    # que la referencia usa "+00:00"; forzamos siempre ±HH:MM para que la huella
+    # coincida con la de otras implementaciones y con el XML.
+    def marca_temporal(valor)
+      tiempo = valor.is_a?(String) ? Time.iso8601(valor) : valor
+      raise ValidacionError, 'fecha_hora_gen debe ser Time o String ISO 8601' unless tiempo.respond_to?(:strftime)
+
+      tiempo.strftime('%Y-%m-%dT%H:%M:%S%:z')
+    rescue ArgumentError => e
+      raise ValidacionError, "fecha_hora_gen inválida: #{valor.inspect} (#{e.message})"
+    end
+
+    # Longitud fija de 9 según sf:NIFType. El XSD no valida el dígito de control,
+    # y nosotros tampoco: rechazar un NIF válido por una tabla desactualizada
+    # sería peor que dejar que la AEAT lo rechace.
+    # Se normaliza a MAYÚSCULAS, y esto sí es una excepción deliberada a la regla
+    # de "rechazar en vez de arreglar" que rige `texto`.
+    #
+    # Motivo, comprobado contra preproducción: un NIF con la letra en minúscula
+    # ("89890001k") supera la validación de FORMATO de la AEAT (no da 4116) pero
+    # falla la búsqueda en el censo, que sí distingue mayúsculas, y devuelve un
+    # 4104 "no está identificado" que apunta al sitio equivocado: parece que el
+    # NIF no existe cuando lo único que pasa es que va en minúscula.
+    #
+    # La diferencia con los espacios al borde es que ahí el valor original podía
+    # significar algo (un campo de ancho fijo mal recortado, por ejemplo) y
+    # recortar lo taparía. Aquí no: la forma canónica de un NIF es en mayúsculas
+    # y "c" y "C" denotan la misma letra de control. No se pierde información.
+    def nif(valor, campo = 'NIF')
+      cadena = texto(valor, campo).upcase
+      unless cadena.length == 9
+        raise ValidacionError, "#{campo} debe tener 9 caracteres: #{cadena.inspect}"
+      end
+
+      cadena
+    end
+
+    # NumSerieFactura solo admite ASCII imprimible (32-126) y prohíbe además
+    # cinco caracteres concretos (Validaciones v1.2.2, ap. 3.1.3.1).
+    #
+    # Ojo a la asimetría: "&" SÍ está permitido, y es justo el que obliga a
+    # escapar en el XML mientras la huella lo usa crudo. Los que romperían el
+    # XML de verdad (< > ") están prohibidos de entrada por la AEAT.
+    PROHIBIDOS_SERIE = ['"', "'", '<', '>', '='].freeze
+
+    def num_serie(valor, campo = 'NumSerieFactura')
+      cadena = limitar(valor, campo, 60)
+
+      malos = cadena.chars.reject { |c| c.ord.between?(32, 126) }.uniq
+      unless malos.empty?
+        raise ValidacionError,
+              "#{campo} solo admite ASCII imprimible (32-126); sobran: " \
+              "#{malos.map(&:inspect).join(', ')}"
+      end
+
+      encontrados = PROHIBIDOS_SERIE.select { |c| cadena.include?(c) }
+      unless encontrados.empty?
+        raise ValidacionError,
+              "#{campo} no admite los caracteres #{encontrados.map(&:inspect).join(', ')}: " \
+              "#{cadena.inspect}"
+      end
+
+      cadena
+    end
+
+    def limitar(valor, campo, maximo)
+      cadena = texto(valor, campo)
+      if cadena.length > maximo
+        raise ValidacionError,
+              "#{campo} excede #{maximo} caracteres (#{cadena.length}): #{cadena.inspect}"
+      end
+
+      cadena
+    end
+
+    # Campos sf:SiNoType. Acepta el booleano de Ruby y también la letra de la
+    # AEAT, porque quien lee la documentación escribe 'S'/'N' de forma natural.
+    #
+    # Lo que NO puede pasar es tratarlo como valor de verdad a secas: 'N' es
+    # truthy en Ruby, así que `multi_ot ? 'S' : 'N'` emitía 'S' cuando el usuario
+    # había pedido 'N', invirtiendo la declaración en silencio.
+    def si_no(valor, campo)
+      case valor
+      when nil       then nil
+      when true, 'S' then 'S'
+      when false, 'N' then 'N'
+      else
+        raise ValidacionError,
+              "#{campo} debe ser true/false o 'S'/'N' (recibido: #{valor.inspect})"
+      end
+    end
+
+    # Colección homogénea de objetos de valor.
+    #
+    # No basta con Array(): Array(hash) devuelve los PARES del hash, así que un
+    # `destinatarios: {nombre_razon: 'X', nif: '...'}` se convertía en dos
+    # "destinatarios" que pasaban las validaciones de conteo y solo reventaban
+    # al serializar, con un NoMethodError sobre un Array. Aquí el criterio es el
+    # mismo que en el resto de la gema: si el objeto se construye, es emitible.
+    def coleccion(valor, campo, clase, maximo: nil)
+      lista = valor.nil? ? [] : Array(valor)
+
+      if valor.is_a?(Hash) || (valor && !valor.is_a?(Array) && !valor.is_a?(clase))
+        raise ValidacionError,
+              "#{campo} debe ser un #{clase} o un array de #{clase} " \
+              "(recibido: #{valor.class})"
+      end
+      lista = [valor] if valor.is_a?(clase)
+
+      intrusos = lista.reject { |e| e.is_a?(clase) }.map(&:class).uniq
+      unless intrusos.empty?
+        raise ValidacionError,
+              "#{campo} solo admite #{clase} (encontrados: #{intrusos.join(', ')})"
+      end
+      if maximo && lista.size > maximo
+        raise ValidacionError,
+              "#{campo} admite como mucho #{maximo} elementos (recibidos #{lista.size})"
+      end
+
+      lista
+    end
+
+    # Colaborador obligatorio de una clase concreta.
+    def objeto(valor, campo, clase)
+      return valor if valor.is_a?(clase)
+
+      raise ValidacionError, "#{campo} debe ser un #{clase} (recibido: #{valor.class})"
+    end
+
+    def enumerado(valor, campo, admitidos)
+      cadena = texto(valor, campo)
+      unless admitidos.include?(cadena)
+        raise ValidacionError,
+              "#{campo} inválido: #{cadena.inspect}. Admitidos: #{admitidos.join(', ')}"
+      end
+
+      cadena
+    end
+  end
+end

data/lib/verifactu_rails/huella.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative 'importe'
+require_relative 'formato'
+require_relative 'error'
+
+module VerifactuRails
+  # Cálculo de la huella (hash) de los registros de facturación.
+  #
+  # Referencia normativa: RD 1007/2023 art. 7, Orden HAC/1177/2024, y el documento
+  # "Detalle de las especificaciones técnicas para la generación de la huella o hash
+  # de los registros" publicado en la web de desarrolladores de la AEAT.
+  #
+  # La cadena se construye como pares "Campo=valor" unidos por "&", SIN escapado
+  # de los valores, y se le aplica SHA-256 devuelto en hexadecimal MAYÚSCULAS.
+  module Huella
+    PATRON_HUELLA = /\A[0-9A-F]{64}\z/
+    CAMPOS_ALTA = %w[
+      IDEmisorFactura NumSerieFactura FechaExpedicionFactura
+      TipoFactura CuotaTotal ImporteTotal Huella FechaHoraHusoGenRegistro
+    ].freeze
+    CAMPOS_ANULACION = %w[
+      IDEmisorFacturaAnulada NumSerieFacturaAnulada FechaExpedicionFacturaAnulada
+      Huella FechaHoraHusoGenRegistro
+    ].freeze
+
+    module_function
+
+    # Huella de un registro de facturación de ALTA.
+    #
+    # @param huella_anterior [String, nil] huella del registro previo de la cadena.
+    #   nil o "" únicamente para el PRIMER registro de ese SIF y NIF obligado.
+    #   Ojo: la cadena es una sola por SIF+NIF, NO una por serie de facturación.
+    def alta(**datos)
+      digerir(cadena_alta(**datos))
+    end
+
+    # Cadena exacta sobre la que se calcula la huella de un ALTA.
+    #
+    # Es pública a propósito y por dos motivos. Uno: cuando la AEAT rechaza por
+    # huella, lo primero que hay que comparar es ESTE string, no el digest. Dos:
+    # que los tests puedan afirmar sobre la cadena sin reconstruirla por su
+    # cuenta, que es como se quedan ciegos ante un cambio de normalizador.
+    def cadena_alta(id_emisor:, num_serie:, fecha_expedicion:, tipo_factura:,
+                    cuota_total:, importe_total:, fecha_hora_gen:, huella_anterior: nil)
+      pares = {
+        'IDEmisorFactura'          => texto(id_emisor, 'IDEmisorFactura'),
+        'NumSerieFactura'          => texto(num_serie, 'NumSerieFactura'),
+        'FechaExpedicionFactura'   => fecha(fecha_expedicion),
+        'TipoFactura'              => texto(tipo_factura, 'TipoFactura'),
+        'CuotaTotal'               => Importe.formatear(cuota_total),
+        'ImporteTotal'             => Importe.formatear(importe_total),
+        'Huella'                   => encadenamiento(huella_anterior),
+        'FechaHoraHusoGenRegistro' => marca_temporal(fecha_hora_gen)
+      }
+      serializar(pares, CAMPOS_ALTA)
+    end
+
+    # Huella de un registro de facturación de ANULACIÓN.
+    # Aquí huella_anterior es SIEMPRE obligatoria: una anulación nunca puede ser
+    # el primer registro de la cadena.
+    def anulacion(**datos)
+      digerir(cadena_anulacion(**datos))
+    end
+
+    # Cadena exacta sobre la que se calcula la huella de una ANULACIÓN.
+    def cadena_anulacion(id_emisor:, num_serie:, fecha_expedicion:,
+                         fecha_hora_gen:, huella_anterior:)
+      if huella_anterior.nil? || huella_anterior.to_s.empty?
+        raise ValidacionError,
+              'Un registro de anulación exige huella_anterior: no puede iniciar cadena'
+      end
+
+      pares = {
+        'IDEmisorFacturaAnulada'        => texto(id_emisor, 'IDEmisorFacturaAnulada'),
+        'NumSerieFacturaAnulada'        => texto(num_serie, 'NumSerieFacturaAnulada'),
+        'FechaExpedicionFacturaAnulada' => fecha(fecha_expedicion),
+        'Huella'                        => encadenamiento(huella_anterior),
+        'FechaHoraHusoGenRegistro'      => marca_temporal(fecha_hora_gen)
+      }
+      serializar(pares, CAMPOS_ANULACION)
+    end
+
+    # Expone la cadena previa al hash. Imprescindible para depurar: cuando la AEAT
+    # rechaza por huella, lo primero es comparar ESTE string, no el digest.
+    def serializar(pares, orden)
+      orden.map { |campo| "#{campo}=#{pares.fetch(campo)}" }.join('&')
+    end
+
+    def digerir(cadena)
+      Digest::SHA256.hexdigest(cadena.encode(Encoding::UTF_8)).upcase
+    end
+
+    # --- normalizadores -------------------------------------------------------
+    #
+    # texto, fecha y marca_temporal viven en Formato porque el generador de XML
+    # necesita exactamente los mismos: si divergieran, la huella que calculamos
+    # dejaría de corresponder al XML que enviamos.
+    #
+    # DELIBERADO: aquí se usa Formato.texto y NO Formato.num_serie, que es el que
+    # aplica las restricciones de la AEAT al NumSerieFactura (ASCII 32-126, sin
+    # " ' < > =). Este módulo es una primitiva de hash, no la capa de reglas de
+    # negocio: debe poder recalcular la huella de CUALQUIER registro, incluido uno
+    # que no generamos nosotros. Eso es justo lo que necesitas al depurar un
+    # rechazo de la AEAT o al migrar desde otro sistema.
+    #
+    # Quien construye registros nuevos pasa por RegistroAlta / RegistroAnulacion,
+    # y ahí sí se aplican todas las restricciones.
+
+    def texto(valor, campo) = Formato.texto(valor, campo)
+
+    def fecha(valor) = Formato.fecha(valor)
+
+    def marca_temporal(valor) = Formato.marca_temporal(valor)
+
+    def encadenamiento(valor)
+      return '' if valor.nil? || valor.to_s.empty?
+
+      cadena = valor.to_s
+      unless cadena.match?(PATRON_HUELLA)
+        raise ValidacionError,
+              "huella_anterior debe ser SHA-256 hex en MAYÚSCULAS (64 chars): #{cadena.inspect}"
+      end
+      cadena
+    end
+
+    private_class_method :texto, :fecha, :encadenamiento, :marca_temporal
+  end
+end

data/lib/verifactu_rails/importe.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require 'bigdecimal/util'
+require_relative 'error'
+
+module VerifactuRails
+  # Formateo canónico de importes monetarios.
+  #
+  # REGLA DE ORO: el string que produce este módulo es el que debe ir TANTO en la
+  # cadena de la huella COMO en el XML. Si divergen aunque sea en un decimal, la
+  # AEAT recalcula la huella sobre lo que recibe en el XML y rechaza el registro.
+  # Por eso el formateo vive aquí y en un solo sitio.
+  module Importe
+    PATRON = /\A-?\d{1,12}\.\d{2}\z/
+
+    module_function
+
+    # Normaliza a string con exactamente 2 decimales y punto como separador.
+    # Acepta BigDecimal, Integer, Rational o String; rechaza Float por
+    # imprecisión binaria (0.1 + 0.2 no es 0.3 y aquí eso es un rechazo AEAT).
+    def formatear(valor)
+      case valor
+      when Float
+        raise ValidacionError,
+              'No se admiten Float en importes: usa BigDecimal, Integer o String ' \
+              "(recibido: #{valor.inspect})"
+      when BigDecimal then decimal = valor
+      when Integer    then decimal = valor.to_d
+      when Rational   then decimal = valor.to_d(20)
+      when String     then decimal = parsear_string(valor)
+      when nil        then raise ValidacionError, 'Importe requerido'
+      else
+        raise ValidacionError, "Tipo de importe no admitido: #{valor.class}"
+      end
+
+      # ROUND_HALF_UP explícito, y NO porque Ruby traiga otro por defecto: el
+      # suyo ya es HALF_UP, tanto en BigDecimal.mode como en Float#round. El
+      # motivo es que BigDecimal.mode es estado GLOBAL del proceso: cualquier
+      # gema de la aplicación puede cambiarlo, y entonces todos los importes
+      # redondearían distinto y con ellos las huellas, sin que nadie relacionara
+      # una cosa con la otra. Pasándolo en la llamada, da igual lo que haga el
+      # resto. HALF_UP es además el que aplica la normativa fiscal española.
+      resultado = decimal.round(2, BigDecimal::ROUND_HALF_UP).to_s('F')
+      resultado = format('%.2f', resultado.to_d) # asegura los 2 decimales
+
+      unless resultado.match?(PATRON)
+        raise ValidacionError, "Importe fuera de rango o mal formado: #{resultado}"
+      end
+
+      # -0.00 no existe fiscalmente y rompería la comparación de huellas
+      resultado == '-0.00' ? '0.00' : resultado
+    end
+
+    # sf:Tipo2.2Type, para los porcentajes: patrón \d{1,3}(\.\d{0,2})? — SIN
+    # signo y con tres dígitos enteros como mucho. Es un tipo distinto de
+    # sf:ImporteSgn12.2Type, así que formatear con `formatear` a secas dejaba
+    # pasar un -21.00 o un 1000.00 que luego rechaza el esquema.
+    def porcentaje(valor, campo)
+      cadena = formatear(valor)
+      unless cadena.match?(/\A\d{1,3}\.\d{2}\z/)
+        raise ValidacionError,
+              "#{campo} debe ser un porcentaje sin signo y de hasta 3 dígitos " \
+              "enteros (recibido: #{cadena})"
+      end
+
+      cadena
+    end
+
+    def parsear_string(cadena)
+      texto = cadena.strip
+      unless texto.match?(/\A-?\d+([.,]\d+)?\z/)
+        raise ValidacionError, "Importe no numérico: #{cadena.inspect}"
+      end
+
+      texto.tr(',', '.').to_d
+    end
+    private_class_method :parsear_string
+  end
+end

data/lib/verifactu_rails/libro/autochequeo.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module VerifactuRails
+  module Libro
+    # Las comprobaciones que el art. 7.i) de la Orden HAC/1177/2024 obliga a hacer
+    # ANTES de generar cada registro:
+    #
+    #   1.º El último registro de facturación generado está correctamente
+    #       encadenado.
+    #   2.º La fecha y hora de generación del último registro no es superior en
+    #       más de un minuto a la fecha y hora actuales.
+    #
+    # DEVUELVE una lista de anomalías; no levanta excepciones. Es deliberado: las
+    # FAQs dicen que "será preciso generar el siguiente RF, ya que la facturación
+    # por este motivo NUNCA debe interrumpirse". Bloquear la caja por un problema
+    # de trazabilidad es peor remedio que la enfermedad.
+    class Autochequeo
+      # El minuto del art. 7.i).2.º.
+      MARGEN_RELOJ = 60
+
+      def initialize(anterior)
+        @anterior = anterior
+      end
+
+      # @param ahora [Time] la hora con la que se va a fechar el nuevo registro
+      # @return [Array<Symbol>] vacío si todo cuadra
+      def anomalias(ahora:)
+        return [] if anterior.nil? # "salvo cuando se trate del primer registro"
+
+        fallos = []
+        fallos << :encadenamiento_roto unless eslabon_cuadra?
+        fallos << :huella_alterada unless anterior.huella_cuadra?
+        fallos << :reloj_hacia_atras if reloj_atrasado?(ahora)
+        fallos
+      end
+
+      private
+
+      attr_reader :anterior
+
+      # Lo que pide literalmente la Orden: que la huella que el RF n-1 guarda de
+      # su predecesor se corresponda con la huella del RF n-2. Un eslabón atrás,
+      # no la cadena entera.
+      def eslabon_cuadra?
+        return anterior.cadena.registros.where(huella_anterior: '').count == 1 if anterior.primero?
+
+        anterior.cadena.registros.exists?(huella: anterior.huella_anterior)
+      end
+
+      # Esto va MÁS ALLÁ de lo que exige la Orden: recalcula la huella del
+      # anterior desde sus columnas y la compara con la almacenada. Es un
+      # SHA-256, y es lo único que detecta que alguien haya editado la fila en la
+      # base de datos. Ser más estricto aquí no tiene el riesgo habitual porque
+      # no bloquea nada: solo anota.
+      #
+      # (La comprobación vive en Registro#huella_cuadra?)
+
+      # OJO al sentido, que es el que confunde: que pasen horas entre registros es
+      # lo normal y no es anomalía. Lo que no se admite es fechar el nuevo
+      # registro MÁS DE UN MINUTO ANTES que el anterior, o sea que el reloj haya
+      # ido hacia atrás.
+      def reloj_atrasado?(ahora)
+        ahora < anterior.momento - MARGEN_RELOJ
+      end
+    end
+  end
+end

data/lib/verifactu_rails/libro/cadena.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module VerifactuRails
+  module Libro
+    # Una cadena de registros: un "SIF virtual" identificado por su
+    # NumeroInstalacion, con su obligado tributario.
+    #
+    # Las FAQs (v1.3) exigen que cada facturación distinta -sean de distintos
+    # obligados o del mismo obligado en centros independientes, como tiendas-
+    # lleve su propio nº de instalación, "porque se consideran SIF
+    # independientes, como si fueran SIF virtuales".
+    class Cadena < ActiveRecord::Base
+      self.table_name = 'verifactu_cadenas'
+
+      has_many :registros, class_name: 'VerifactuRails::Libro::Registro',
+                           foreign_key: :cadena_id, inverse_of: :cadena, dependent: :restrict_with_error
+      belongs_to :ultimo_registro, class_name: 'VerifactuRails::Libro::Registro',
+                                   optional: true
+
+      validates :numero_instalacion, :nif_obligado, :nombre_obligado, presence: true
+
+      # Abre una cadena. El número de instalación se EXIGE explícito y no se
+      # genera nunca aquí: ni con un default, ni con un find_or_create_by, ni
+      # "por comodidad".
+      #
+      # No es celo: si la gema lo autogenerase, un contenedor que se recrea en
+      # cada despliegue acabaría abriendo una instalación por despliegue, y en el
+      # límite una por factura, que es exactamente el patrón que vacía de sentido
+      # el encadenamiento. Abrir una instalación es un acto deliberado de quien
+      # despliega y tiene que constar como tal.
+      #
+      # Las FAQs recomiendan como valor un timestamp de instalación o un
+      # secuencial propio del obligado. No puede repetirse NUNCA, ni al reinstalar
+      # el mismo software en la misma máquina.
+      def self.abrir!(numero_instalacion:, nif_obligado:, nombre_obligado:)
+        if numero_instalacion.to_s.strip.empty?
+          raise ValidacionError,
+                'numero_instalacion es obligatorio y no se genera solo. Usa un ' \
+                'timestamp de instalación o un secuencial propio del obligado, y ' \
+                'no lo reutilices jamás (FAQs Desarrolladores v1.3).'
+        end
+
+        create!(numero_instalacion: numero_instalacion,
+                nif_obligado: Formato.nif(nif_obligado, 'NIF del obligado'),
+                nombre_obligado: Formato.limitar(nombre_obligado, 'NombreRazon del obligado', 120))
+      end
+
+      # Anota un alta y la encadena. Síncrono y bajo lock: el encadenamiento no
+      # se puede diferir, aunque el ENVÍO sí.
+      def anotar_alta!(**datos)
+        anotar!(RegistroAlta, 'alta', **datos)
+      end
+
+      def anotar_anulacion!(**datos)
+        anotar!(RegistroAnulacion, 'anulacion', **datos)
+      end
+
+      def sistema_informatico = Libro.configuracion.sistema_para(self)
+
+      private
+
+      def anotar!(clase, tipo, **datos)
+        with_lock do # SELECT ... FOR UPDATE sobre esta fila
+          previo = ultimo_registro
+
+          # Art. 7.i) de la OM. NO levanta excepción a propósito: ante una
+          # anomalía de trazabilidad "la facturación NUNCA debe interrumpirse".
+          anomalias = Autochequeo.new(previo).anomalias(ahora: Time.now)
+
+          # Esto SÍ puede levantar: con datos inválidos no hay registro que
+          # generar, y tampoco hay factura que emitir.
+          registro = clase.new(**datos, sistema_informatico: sistema_informatico)
+
+          anterior = previo&.a_registro_anterior
+          fila = registros.create!(
+            **columnas(registro, tipo),
+            huella: registro.huella(anterior: anterior),
+            huella_anterior: previo&.huella || '',
+            payload: Libro.fragmento_xml(registro, anterior),
+            qr_url: qr_de(registro, tipo),
+            anomalias: anomalias.any? ? JSON.generate(anomalias) : nil
+          )
+          update!(ultimo_registro_id: fila.id)
+          Libro.avisar_de(anomalias, fila) if anomalias.any?
+          fila
+        end
+      end
+
+      def columnas(registro, tipo)
+        comunes = { tipo: tipo, id_emisor: registro.id_emisor,
+                    num_serie: registro.num_serie,
+                    fecha_expedicion: registro.fecha_expedicion,
+                    fecha_hora_gen: registro.fecha_hora_gen }
+        return comunes if tipo == 'anulacion'
+
+        comunes.merge(tipo_factura: registro.tipo_factura,
+                      cuota_total: registro.cuota_total,
+                      importe_total: registro.importe_total)
+      end
+
+      # Una anulación no lleva QR propio: el QR va en la factura, y una anulación
+      # no expide factura. Se guarda vacío para no dejar la columna nula.
+      def qr_de(registro, tipo)
+        return '' if tipo == 'anulacion'
+
+        QR.url(registro, entorno: Libro.configuracion.entorno)
+      end
+    end
+  end
+end

data/lib/verifactu_rails/libro/migracion.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module VerifactuRails
+  module Libro
+    # El esquema del libro registro, en una migración reutilizable: la usa el
+    # generador de Rails y también la suite de tests, para que lo que se prueba
+    # sea exactamente lo que se instala.
+    #
+    # ESTA CLASE ESTÁ CONGELADA. Es el esquema v1 y no se toca nunca más. La
+    # migración que `rails g verifactu:install` deja en la app no copia el
+    # esquema: hereda de aquí. Eso significa que cambiarlo mutaría el pasado —
+    # una app que ya migró se quedaría con el esquema viejo mientras una
+    # instalación nueva estrena el nuevo, las dos convencidas de estar al día.
+    # Los cambios de esquema van en migraciones NUEVAS y aparte.
+    #
+    # Portable a PostgreSQL y MySQL: nada de índices parciales, de jsonb ni de
+    # tipos propios de un motor. Lo único que se exige de la base de datos es que
+    # sepa bloquear filas (SELECT ... FOR UPDATE) y respetar índices únicos.
+    class Migracion < ActiveRecord::Migration[7.0]
+      def change
+        create_table :verifactu_cadenas do |t|
+          # Una cadena por "SIF virtual". No lleva valor por defecto NI se genera
+          # sola en ninguna parte: abrir una instalación es un acto deliberado de
+          # quien despliega (ver doc/FUENTES.md).
+          t.string :numero_instalacion, null: false, limit: 100
+          t.string :nif_obligado,       null: false, limit: 9
+          t.string :nombre_obligado,    null: false, limit: 120
+          t.bigint :ultimo_registro_id
+          t.datetime :no_enviar_antes_de
+          t.timestamps
+
+          t.index :numero_instalacion, unique: true
+        end
+
+        create_table :verifactu_registros do |t|
+          t.references :cadena, null: false, index: false,
+                                foreign_key: { to_table: :verifactu_cadenas }
+          t.string :tipo, null: false, limit: 10 # alta | anulacion
+
+          # Las ENTRADAS de la huella van como columnas, no enterradas en el
+          # payload: son lo que permite recalcularla años después sin parsear
+          # nada. Se guardan ya formateadas, con el mismo string que se serializó.
+          t.string :id_emisor,        null: false, limit: 9
+          t.string :num_serie,        null: false, limit: 60
+          t.string :fecha_expedicion, null: false, limit: 10 # dd-mm-yyyy, canónico
+          t.string :tipo_factura,     limit: 2   # null en las anulaciones
+          t.string :cuota_total,      limit: 20
+          t.string :importe_total,    limit: 20
+          t.string :huella,           null: false, limit: 64
+
+          # Centinela '' para el primer eslabón, NO null: en Postgres y en MySQL
+          # dos NULL no colisionan en un índice único, así que con null se podría
+          # colar más de un PrimerRegistro por cadena. Con '' no.
+          t.string :huella_anterior, null: false, limit: 64, default: ''
+
+          # El STRING exacto que entró en la huella, con su huso. Una columna
+          # datetime normaliza a UTC y pierde el offset, y entonces la huella ya
+          # no se puede recalcular.
+          t.string :fecha_hora_gen, null: false, limit: 25
+
+          # El fragmento XML del registro, ya construido y con su huella dentro.
+          # Se guarda hecho, y no los argumentos con que se construyó, para que
+          # lo que se envíe sea exactamente lo que se calculó: la huella y el XML
+          # no pueden divergir si nadie los vuelve a derivar.
+          t.text    :payload,         null: false
+          t.integer :payload_version, null: false, default: 1
+          t.text    :qr_url,          null: false
+          t.text    :anomalias # JSON con los fallos del art. 7.i, o null
+          t.string  :estado,          null: false, limit: 20, default: 'pendiente'
+          t.string  :csv,             limit: 20
+          t.integer :codigo_error
+          t.text    :descripcion_error
+          t.datetime :enviado_at
+          t.timestamps
+
+          # ESTE es el índice que impide bifurcar la cadena. Dos registros no
+          # pueden compartir predecesor, pase lo que pase con el lock. Está
+          # comprobado que la AEAT acepta una cadena bifurcada sin avisar, así
+          # que esta restricción es la única red que hay.
+          t.index %i[cadena_id huella_anterior], unique: true,
+                                                 name: 'idx_verifactu_sin_bifurcacion'
+          t.index %i[cadena_id huella], unique: true
+          t.index %i[cadena_id estado id]
+
+          # NO es único a propósito: una subsanación reutiliza el mismo IDFactura
+          # deliberadamente, y así lo acepta la AEAT (comprobado).
+          t.index %i[id_emisor num_serie fecha_expedicion], name: 'idx_verifactu_id_factura'
+        end
+      end
+    end
+  end
+end