nfcom 0.1.2

data/lib/nfcom/models/endereco.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Nfcom
+  module Models
+    # Representa o endereço do emitente ou destinatário da NF-COM
+    #
+    # Esta classe é utilizada tanto pelo emitente quanto pelo destinatário
+    # para armazenar as informações completas de endereço.
+    #
+    # @example Criar endereço completo
+    #   endereco = Nfcom::Models::Endereco.new(
+    #     logradouro: 'Rua das Flores',
+    #     numero: '123',
+    #     complemento: 'Sala 101',
+    #     bairro: 'Centro',
+    #     municipio: 'Recife',
+    #     codigo_municipio: '2611606',
+    #     uf: 'PE',
+    #     cep: '50000-000',
+    #     telefone: '(81) 3333-4444'
+    #   )
+    #
+    # @example Validar endereço
+    #   if endereco.valido?
+    #     puts "Endereço válido"
+    #   else
+    #     puts "Erros: #{endereco.erros.join(', ')}"
+    #   end
+    #
+    # Atributos obrigatórios:
+    # - logradouro (rua, avenida, etc) - 2-60 caracteres (ER47)
+    # - numero (número do imóvel) - 1-60 caracteres (ER47)
+    # - bairro (bairro/distrito) - 2-60 caracteres (ER47)
+    # - municipio (nome do município) - 2-60 caracteres (ER47)
+    # - codigo_municipio (código IBGE do município - 7 dígitos) (ER2)
+    # - uf (sigla do estado - 2 letras) (D5)
+    # - cep (8 dígitos) (ER67)
+    #
+    # Atributos opcionais:
+    # - complemento (apartamento, sala, bloco, etc) - 1-60 caracteres (ER47)
+    # - codigo_pais (padrão: 1058 para Brasil)
+    # - pais (padrão: 'Brasil')
+    # - telefone (7-12 dígitos) (ER61)
+    # - email (ER72)
+    #
+    # @note O código do município (IBGE) pode ser consultado em:
+    #   https://www.ibge.gov.br/explica/codigos-dos-municipios.php
+    class Endereco
+      include Utils::Helpers
+
+      attr_accessor :logradouro, :numero, :complemento, :bairro,
+                    :codigo_municipio, :municipio, :uf, :cep,
+                    :codigo_pais, :pais, :telefone, :email
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          send("#{key}=", value) if respond_to?("#{key}=")
+        end
+      end
+
+      def valido?
+        erros.empty?
+      end
+
+      def erros # rubocop:disable Metrics/MethodLength
+        errors = []
+
+        # Validações de campos obrigatórios
+        errors << 'Logradouro é obrigatório' if logradouro.to_s.strip.empty?
+        errors << 'Número é obrigatório' if numero.to_s.strip.empty?
+        errors << 'Bairro é obrigatório' if bairro.to_s.strip.empty?
+        errors << 'Município é obrigatório' if municipio.to_s.strip.empty?
+        errors << 'Código do município é obrigatório' if codigo_municipio.to_s.strip.empty?
+        errors << 'UF é obrigatório' if uf.to_s.strip.empty?
+        errors << 'CEP é obrigatório' if cep.to_s.strip.empty?
+
+        # Validações declarativas de formato/schema
+        campos = {}
+
+        # Campos obrigatórios - validar formato apenas se não estiverem vazios
+        unless logradouro.to_s.strip.empty?
+          campos[:logradouro] = { valor: logradouro, validador: :er47, nome: 'Logradouro', max: 60 }
+        end
+
+        campos[:numero] = { valor: numero, validador: :er47, nome: 'Número', max: 60 } unless numero.to_s.strip.empty?
+
+        campos[:bairro] = { valor: bairro, validador: :er47, nome: 'Bairro', max: 60 } unless bairro.to_s.strip.empty?
+
+        unless municipio.to_s.strip.empty?
+          campos[:municipio] = { valor: municipio, validador: :er47, nome: 'Município', max: 60 }
+        end
+
+        unless codigo_municipio.to_s.strip.empty?
+          campos[:codigo_municipio] = { valor: codigo_municipio, validador: :er2, nome: 'Código do município' }
+        end
+
+        campos[:uf] = { valor: uf, validador: :d5, nome: 'UF' } unless uf.to_s.strip.empty?
+
+        unless cep.to_s.strip.empty?
+          cep_limpo = apenas_numeros(cep)
+          campos[:cep] = { valor: cep_limpo, validador: :er67, nome: 'CEP' }
+        end
+
+        # Campos opcionais - validar formato apenas se informados
+        if complemento && !complemento.to_s.strip.empty?
+          campos[:complemento] = { valor: complemento, validador: :er47, nome: 'Complemento', max: 60 }
+        end
+
+        if telefone && !telefone.to_s.strip.empty?
+          telefone_limpo = apenas_numeros(telefone)
+          campos[:telefone] = { valor: telefone_limpo, validador: :er61, nome: 'Telefone' }
+        end
+
+        campos[:email] = { valor: email, validador: :er72, nome: 'Email' } if email && !email.to_s.strip.empty?
+
+        # Executar validações declarativas
+        errors.concat(Validators::SchemaValidator.validar_campos(campos))
+
+        errors
+      end
+    end
+  end
+end

data/lib/nfcom/models/fatura/codigo_de_barras/formato_44.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Nfcom
+  module Models
+    class Fatura
+      class CodigoDeBarras
+        class Formato44
+          def initialize(valor)
+            @valor = valor
+            validar!
+          end
+
+          def linha_digitavel
+            [
+              campo(@valor[0, 4] + @valor[19, 5]),
+              campo(@valor[24, 10]),
+              campo(@valor[34, 10]),
+              @valor[4],
+              @valor[5, 14]
+            ].join(' ')
+          end
+
+          private
+
+          def campo(valor)
+            "#{valor[0, 5]}.#{valor[5, 5]}#{modulo10(valor)}"
+          end
+
+          def modulo10(numero)
+            soma = 0
+            multiplicador = 2
+
+            numero.reverse.each_char do |char|
+              v = char.to_i * multiplicador
+              v -= 9 if v > 9
+              soma += v
+              multiplicador = multiplicador == 2 ? 1 : 2
+            end
+
+            (10 - (soma % 10)) % 10
+          end
+
+          def validar!
+            return if @valor.match?(/\A\d{44}\z/)
+
+            raise ArgumentError, 'Código de barras (44) inválido'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nfcom/models/fatura/codigo_de_barras.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Nfcom
+  module Models
+    class Fatura
+      class CodigoDeBarras
+        attr_reader :valor
+
+        def initialize(valor)
+          @valor = valor.to_s.gsub(/\D/, '')
+          validar!
+        end
+
+        def tamanho
+          valor.length
+        end
+
+        def formato
+          case tamanho
+          when 44 then :formato_44
+          when 48 then :formato_48
+          else :desconhecido
+          end
+        end
+
+        def linha_digitavel
+          handler.linha_digitavel
+        end
+
+        def valido?
+          true
+        rescue ArgumentError
+          false
+        end
+
+        private
+
+        def handler
+          @handler ||= case formato
+                       when :formato_44
+                         CodigoDeBarras::Formato44.new(valor)
+                       when :formato_48
+                         CodigoDeBarras::Formato48.new(valor)
+                       else
+                         raise ArgumentError, 'Formato de código de barras não suportado'
+                       end
+        end
+
+        def validar!
+          return if valor.match?(/\A\d+\z/)
+
+          raise ArgumentError, 'Código de barras deve conter apenas números'
+        end
+      end
+    end
+  end
+end

data/lib/nfcom/models/fatura.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Nfcom
+  module Models
+    # Representa as informações de faturamento da NF-COM (grupo gFat)
+    #
+    # Este grupo contém as informações sobre o período de faturamento,
+    # vencimento e valores da fatura.
+    #
+    # @example Criar fatura básica para ISP
+    #   fatura = Nfcom::Models::Fatura.new(
+    #     competencia: '2026-01',        # Aceita YYYY-MM ou AAAAMM
+    #     data_vencimento: '2026-02-15', # Data de vencimento
+    #     codigo_barras: '23793381286000000099901234567890123456789012',
+    #     valor_fatura: 99.90
+    #   )
+    #
+    # @example Fatura com período de uso
+    #   fatura = Nfcom::Models::Fatura.new(
+    #     competencia: '202601',
+    #     data_vencimento: '2026-02-15',
+    #     codigo_barras: '23793381286000000099901234567890123456789012',
+    #     periodo_uso_inicio: '2026-01-01',
+    #     periodo_uso_fim: '2026-01-31',
+    #     valor_fatura: 99.90
+    #   )
+    #
+    # Atributos obrigatórios:
+    # - competencia (formato AAAAMM, ex: '202601' ou aceita '2026-01')
+    # - data_vencimento (formato YYYY-MM-DD, ex: '2026-02-15')
+    # - codigo_barras (linha digitável do boleto, 1-48 caracteres)
+    # - valor_fatura (valor total da fatura)
+    #
+    # Atributos opcionais:
+    # - valor_liquido (valor líquido após descontos)
+    # - periodo_uso_inicio (início do período de uso - YYYY-MM-DD)
+    # - periodo_uso_fim (fim do período de uso - YYYY-MM-DD)
+    # - codigo_debito_automatico (código de autorização débito em conta)
+    # - codigo_banco (número do banco - se houver débito automático)
+    # - codigo_agencia (número da agência - se houver débito automático)
+    class Fatura
+      include Utils::Helpers
+
+      attr_accessor :data_vencimento,              # dVencFat - YYYY-MM-DD
+                    :codigo_barras,                # codBarras - OBRIGATÓRIO
+                    :valor_fatura,                 # vFat - Valor total
+                    :valor_liquido,                # vLiqFat - Valor líquido (opcional)
+                    :periodo_uso_inicio,           # dPerUsoIni (opcional)
+                    :periodo_uso_fim,              # dPerUsoFim (opcional)
+                    :codigo_debito_automatico,     # codDebAuto (opcional)
+                    :codigo_banco,                 # codBanco (opcional)
+                    :codigo_agencia                # codAgencia (opcional)
+
+      attr_reader :competencia                     # CompetFat - AAAAMM
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          send("#{key}=", value) if respond_to?("#{key}=")
+        end
+
+        # Se valor_liquido não foi informado, usa o mesmo da fatura
+        @valor_liquido ||= @valor_fatura
+      end
+
+      # Define a competência, aceitando tanto YYYY-MM quanto AAAAMM
+      # @param value [String] Competência no formato YYYY-MM ou AAAAMM
+      def competencia=(value)
+        return if value.nil?
+
+        # Se vier no formato YYYY-MM, converter para AAAAMM
+        @competencia = if value.to_s.include?('-')
+                         value.to_s.gsub('-', '')
+                       else
+                         value.to_s
+                       end
+      end
+
+      def valido?
+        erros.empty?
+      end
+
+      def erros # rubocop:disable Metrics/MethodLength
+        errors = []
+
+        # Validar competência
+        if competencia.to_s.strip.empty?
+          errors << 'Competência é obrigatória'
+        elsif !competencia_valida?
+          errors << 'Competência deve estar no formato AAAAMM (ex: 202601)'
+        end
+
+        # Validar data de vencimento
+        if data_vencimento.to_s.strip.empty?
+          errors << 'Data de vencimento é obrigatória'
+        elsif !data_vencimento_valida?
+          errors << 'Data de vencimento deve estar no formato YYYY-MM-DD (ex: 2026-02-15)'
+        end
+
+        # Validar código de barras (OBRIGATÓRIO)
+        if codigo_barras.to_s.strip.empty?
+          errors << 'Código de barras é obrigatório'
+        elsif codigo_barras.to_s.length > 48
+          errors << 'Código de barras deve ter no máximo 48 caracteres'
+        end
+
+        # Validar valor da fatura
+        if valor_fatura.nil?
+          errors << 'Valor da fatura é obrigatório'
+        elsif valor_fatura.to_f <= 0
+          errors << 'Valor da fatura deve ser maior que zero'
+        end
+
+        # Validar períodos de uso (se informados)
+        if periodo_uso_inicio && periodo_uso_fim
+          inicio = safe_to_date(periodo_uso_inicio)
+          fim = safe_to_date(periodo_uso_fim)
+
+          if inicio.nil? || fim.nil?
+            errors << 'Período de uso: datas inválidas'
+          elsif inicio > fim
+            errors << 'Período de uso: data inicial não pode ser posterior à data final'
+          end
+        elsif periodo_uso_inicio || periodo_uso_fim
+          errors << 'Período de uso: ambas as datas (início e fim) devem ser informadas'
+        end
+
+        # Validar débito automático (se informado)
+        if codigo_debito_automatico
+          errors << 'Código do banco é obrigatório quando há débito automático' if codigo_banco.to_s.strip.empty?
+          errors << 'Código da agência é obrigatório quando há débito automático' if codigo_agencia.to_s.strip.empty?
+        end
+
+        errors
+      end
+
+      def linha_digitavel
+        CodigoDeBarras.new(codigo_barras).linha_digitavel
+      rescue StandardError
+        ''
+      end
+
+      private
+
+      def competencia_valida?
+        return false unless competencia
+
+        # Formato: AAAAMM (6 dígitos)
+        return false unless competencia.to_s.match?(/^\d{6}$/)
+
+        # Validar se o mês é válido (01-12)
+        mes = competencia[-2..].to_i
+        mes.between?(1, 12)
+      end
+
+      def data_vencimento_valida?
+        return false unless data_vencimento
+
+        # Se já é um Date, valida diretamente
+        return true if data_vencimento.is_a?(Date)
+
+        # Se é String, valida formato YYYY-MM-DD
+        return false unless data_vencimento.to_s.match?(/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/)
+
+        # Tentar fazer parse para validar se é uma data real
+        Date.parse(data_vencimento.to_s)
+        true
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end