zipdatev 0.1.0

data/lib/zipdatev/package.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "zip"
+require "fileutils"
+
+module ZipDatev
+  # Main entry point for creating DATEV-compliant ZIP packages.
+  #
+  # A package collects multiple documents (invoices with attachments)
+  # and generates a ZIP file containing document.xml and ledger XML files.
+  #
+  # @example Creating a package with invoices
+  #   package = ZipDatev::Package.new(
+  #     generator_info: "MyCompany",
+  #     generating_system: "MyApp"
+  #   )
+  #
+  #   package.add_document(
+  #     invoice: invoice,
+  #     attachments: ["/path/to/invoice.pdf"],
+  #     invoice_month: "2023-01",
+  #     folder_name: "Eingangsrechnungen"
+  #   )
+  #
+  #   package.build("/path/to/output.zip")
+  class Package
+    # Size limits as specified in DATEV documentation
+    MAX_PACKAGE_SIZE = 465 * 1024 * 1024  # 465 MB
+    MAX_FILE_SIZE = 20 * 1024 * 1024      # 20 MB
+    MAX_DOCUMENTS = 5000
+
+    # Pattern for valid ASCII filenames (no special characters that cause issues)
+    ASCII_FILENAME_PATTERN = /\A[\x20-\x7E]+\z/
+
+    attr_reader :generator_info, :generating_system, :documents
+
+    def initialize(generator_info:, generating_system:)
+      @generator_info = generator_info
+      @generating_system = generating_system
+      @documents = []
+    end
+
+    # Add a document to the package.
+    #
+    # @param invoice [Invoice] The invoice data
+    # @param attachments [Array<String>] Paths to attachment files
+    # @param invoice_month [String] Invoice month in "YYYY-MM" format
+    # @param folder_name [String] Folder name for filing
+    # @param repository [Repository, nil] Optional repository structure
+    # @return [Document] The created document
+    def add_document(invoice:, attachments: [], invoice_month: nil, folder_name: nil, repository: nil)
+      document = Document.new(
+        invoice: invoice,
+        attachments: attachments,
+        invoice_month: invoice_month,
+        folder_name: folder_name,
+        repository: repository
+      )
+      @documents << document
+      document
+    end
+
+    # Build the ZIP package.
+    #
+    # @param output_path [String] Path for the output ZIP file
+    # @raise [PackageError] If package creation fails
+    # @raise [ValidationError] If validation fails
+    # @raise [SchemaValidationError] If XSD validation fails
+    # @return [String] The output path
+    def build(output_path)
+      raise PackageError, "No documents added to package" if @documents.empty?
+      raise PackageError, "Too many documents (max #{MAX_DOCUMENTS})" if @documents.size > MAX_DOCUMENTS
+
+      # 1. Validate all documents
+      validate_documents!
+
+      # 2. Generate XMLs and validate against XSD schemas
+      document_xml = generate_and_validate_document_xml
+      ledger_xmls = generate_and_validate_ledger_xmls
+
+      # 3. Validate attachment files
+      validate_attachments!
+
+      # 4. Create ZIP archive
+      create_zip(output_path, document_xml, ledger_xmls)
+
+      output_path
+    end
+
+    private
+
+    # Validate all documents in the package
+    #
+    # @raise [ValidationError] If any document validation fails
+    def validate_documents!
+      validation_errors = []
+
+      @documents.each_with_index do |document, index|
+        next if document.valid?
+
+        document.errors.full_messages.each do |message|
+          validation_errors << "Document #{index + 1}: #{message}"
+        end
+      end
+
+      return if validation_errors.empty?
+
+      raise ValidationError.new("Document validation failed", errors: validation_errors)
+    end
+
+    # Generate document.xml and validate against XSD schema
+    #
+    # @return [Nokogiri::XML::Document] The generated document.xml
+    # @raise [SchemaValidationError] If XSD validation fails
+    def generate_and_validate_document_xml
+      generator = Generators::DocumentXml.new(package: self)
+      doc = generator.generate
+
+      SchemaValidator.validate_document_xml(doc)
+
+      doc
+    end
+
+    # Generate ledger XML files for each document and validate against XSD schema
+    #
+    # @return [Array<Hash>] Array of {filename:, doc:} hashes
+    # @raise [SchemaValidationError] If XSD validation fails
+    def generate_and_validate_ledger_xmls
+      @documents.map do |document|
+        generator = Generators::LedgerXml.new(
+          invoice: document.invoice,
+          generator_info: @generator_info,
+          generating_system: @generating_system
+        )
+        doc = generator.generate
+        filename = generator.filename
+
+        SchemaValidator.validate_ledger_xml(doc)
+
+        { filename: filename, doc: doc }
+      end
+    end
+
+    # Validate all attachment files
+    #
+    # @raise [PackageError] If any attachment fails validation
+    def validate_attachments!
+      @documents.each do |document|
+        document.attachments.each do |path|
+          validate_attachment_file!(path)
+        end
+      end
+    end
+
+    # Validate a single attachment file
+    #
+    # @param path [String] Path to the attachment file
+    # @raise [PackageError] If validation fails
+    def validate_attachment_file!(path)
+      filename = File.basename(path)
+
+      # Check ASCII filename
+      unless filename.match?(ASCII_FILENAME_PATTERN)
+        raise PackageError, "Attachment filename contains non-ASCII characters: #{filename}"
+      end
+
+      # Check file size
+      file_size = File.size(path)
+      return unless file_size > MAX_FILE_SIZE
+
+      raise PackageError,
+            "Attachment file too large (#{file_size} bytes, max #{MAX_FILE_SIZE}): #{filename}"
+    end
+
+    # Create the ZIP archive
+    #
+    # @param output_path [String] Path for the output ZIP file
+    # @param document_xml [Nokogiri::XML::Document] The document.xml content
+    # @param ledger_xmls [Array<Hash>] Array of {filename:, doc:} hashes
+    # @raise [PackageError] If ZIP creation fails or package is too large
+    def create_zip(output_path, document_xml, ledger_xmls)
+      # Ensure output directory exists
+      FileUtils.mkdir_p(File.dirname(output_path))
+
+      # Track filenames to detect duplicates
+      used_filenames = Set.new
+
+      begin
+        Zip::File.open(output_path, create: true) do |zipfile|
+          # Add document.xml
+          add_xml_to_zip(zipfile, "document.xml", document_xml, used_filenames)
+
+          # Add ledger XML files
+          ledger_xmls.each do |ledger|
+            add_xml_to_zip(zipfile, ledger[:filename], ledger[:doc], used_filenames)
+          end
+
+          # Add attachment files
+          @documents.each do |document|
+            document.attachments.each do |path|
+              add_attachment_to_zip(zipfile, path, used_filenames)
+            end
+          end
+        end
+
+        # Validate final package size
+        package_size = File.size(output_path)
+        if package_size > MAX_PACKAGE_SIZE
+          File.delete(output_path)
+          raise PackageError,
+                "Package too large (#{package_size} bytes, max #{MAX_PACKAGE_SIZE})"
+        end
+      rescue Zip::Error => e
+        # Clean up partial file on error
+        FileUtils.rm_f(output_path)
+        raise PackageError, "Failed to create ZIP archive: #{e.message}"
+      end
+    end
+
+    # Add an XML document to the ZIP file
+    #
+    # @param zipfile [Zip::File] The ZIP file being created
+    # @param filename [String] The filename within the ZIP
+    # @param xml_doc [Nokogiri::XML::Document] The XML document
+    # @param used_filenames [Set] Set of already used filenames
+    # @raise [PackageError] If filename is duplicate
+    def add_xml_to_zip(zipfile, filename, xml_doc, used_filenames)
+      check_duplicate_filename!(filename, used_filenames)
+
+      xml_string = xml_doc.to_xml(encoding: "UTF-8")
+
+      # Validate XML string size
+      if xml_string.bytesize > MAX_FILE_SIZE
+        raise PackageError,
+              "Generated XML too large (#{xml_string.bytesize} bytes, max #{MAX_FILE_SIZE}): #{filename}"
+      end
+
+      zipfile.get_output_stream(filename) do |stream|
+        stream.write(xml_string)
+      end
+    end
+
+    # Add an attachment file to the ZIP
+    #
+    # @param zipfile [Zip::File] The ZIP file being created
+    # @param path [String] Path to the attachment file
+    # @param used_filenames [Set] Set of already used filenames
+    # @raise [PackageError] If filename is duplicate
+    def add_attachment_to_zip(zipfile, path, used_filenames)
+      filename = File.basename(path)
+      check_duplicate_filename!(filename, used_filenames)
+
+      zipfile.add(filename, path)
+    end
+
+    # Check for duplicate filenames
+    #
+    # @param filename [String] The filename to check
+    # @param used_filenames [Set] Set of already used filenames
+    # @raise [PackageError] If filename is duplicate
+    def check_duplicate_filename!(filename, used_filenames)
+      raise PackageError, "Duplicate filename in package: #{filename}" if used_filenames.include?(filename)
+
+      used_filenames.add(filename)
+    end
+  end
+end

data/lib/zipdatev/repository.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ZipDatev
+  # Represents a 3-level filing structure for DATEV documents.
+  #
+  # The repository structure defines how documents are organized in
+  # DATEV Unternehmen online. It consists of three levels:
+  # - Level 1: Category (e.g., "Software Name")
+  # - Level 2: Folder (e.g., "Belege")
+  # - Level 3: Register (e.g., "2023/01")
+  #
+  # If no repository is specified, DATEV uses a default structure:
+  # "Buchhaltung/IMPORT YYYY RE/MM Monatsname"
+  #
+  # @example Creating a repository structure
+  #   repository = ZipDatev::Repository.new(
+  #     level1: "MyApp",
+  #     level2: "Eingangsrechnungen",
+  #     level3: "2023/01"
+  #   )
+  class Repository
+    # @return [String, nil] Level 1 - Category name
+    attr_reader :level1
+
+    # @return [String, nil] Level 2 - Folder name
+    attr_reader :level2
+
+    # @return [String, nil] Level 3 - Register name
+    attr_reader :level3
+
+    # Initialize a new repository structure.
+    #
+    # @param level1 [String, nil] Category name
+    # @param level2 [String, nil] Folder name
+    # @param level3 [String, nil] Register name
+    def initialize(level1: nil, level2: nil, level3: nil)
+      @level1 = level1
+      @level2 = level2
+      @level3 = level3
+    end
+  end
+end

data/lib/zipdatev/schema_validator.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module ZipDatev
+  # Validates XML documents against DATEV XSD schemas.
+  #
+  # This validator ensures that generated XML conforms to DATEV's
+  # XSD specifications before creating the ZIP package.
+  #
+  # @example Validate document.xml using class method
+  #   xml_string = "<archive>...</archive>"
+  #   ZipDatev::SchemaValidator.validate_document_xml(xml_string)
+  #
+  # @example Validate ledger XML using class method
+  #   xml_doc = generator.generate
+  #   ZipDatev::SchemaValidator.validate_ledger_xml(xml_doc)
+  #
+  # @example Using instance methods (reuses cached schemas)
+  #   validator = ZipDatev::SchemaValidator.new
+  #   validator.validate_document_xml(doc1)
+  #   validator.validate_ledger_xml(ledger1)
+  #   validator.validate_ledger_xml(ledger2)
+  class SchemaValidator
+    # Schema file paths relative to this file
+    SCHEMAS_DIR = File.join(__dir__, "schemas")
+    DOCUMENT_SCHEMA_PATH = File.join(SCHEMAS_DIR, "Document_v060.xsd")
+    LEDGER_SCHEMA_PATH = File.join(SCHEMAS_DIR, "Belegverwaltung_online_ledger_import_v060.xsd")
+
+    # Mutex for thread-safe schema loading (Dir.chdir affects entire process)
+    SCHEMA_LOAD_MUTEX = Thread::Mutex.new
+    private_constant :SCHEMA_LOAD_MUTEX
+
+    # Validate document.xml against Document_v060.xsd
+    #
+    # @param xml [String, Nokogiri::XML::Document] The XML to validate
+    # @raise [SchemaValidationError] If validation fails
+    # @return [true] If validation succeeds
+    def self.validate_document_xml(xml)
+      new.validate_document_xml(xml)
+    end
+
+    # Validate ledger XML against Belegverwaltung_online_ledger_import_v060.xsd
+    #
+    # @param xml [String, Nokogiri::XML::Document] The XML to validate
+    # @raise [SchemaValidationError] If validation fails
+    # @return [true] If validation succeeds
+    def self.validate_ledger_xml(xml)
+      new.validate_ledger_xml(xml)
+    end
+
+    # Validate document.xml against Document_v060.xsd
+    #
+    # @param xml [String, Nokogiri::XML::Document] The XML to validate
+    # @raise [SchemaValidationError] If validation fails
+    # @return [true] If validation succeeds
+    def validate_document_xml(xml)
+      validate(xml, document_schema, "Document XML")
+    end
+
+    # Validate ledger XML against Belegverwaltung_online_ledger_import_v060.xsd
+    #
+    # @param xml [String, Nokogiri::XML::Document] The XML to validate
+    # @raise [SchemaValidationError] If validation fails
+    # @return [true] If validation succeeds
+    def validate_ledger_xml(xml)
+      validate(xml, ledger_schema, "Ledger XML")
+    end
+
+    private
+
+    # Lazy-load document schema
+    def document_schema
+      @document_schema ||= load_schema(DOCUMENT_SCHEMA_PATH)
+    end
+
+    # Lazy-load ledger schema
+    def ledger_schema
+      @ledger_schema ||= load_schema(LEDGER_SCHEMA_PATH)
+    end
+
+    # Load XSD schema from file path
+    #
+    # Uses a mutex to ensure thread-safety when changing directories
+    # to resolve relative XSD imports.
+    #
+    # @param path [String] Path to the XSD schema file
+    # @return [Nokogiri::XML::Schema] Loaded schema
+    # @raise [PackageError] If schema file is not found
+    def load_schema(path)
+      raise PackageError, "Schema file not found: #{path}" unless File.exist?(path)
+
+      # Change to schema directory to resolve relative imports
+      # (XSD files use schemaLocation="Document_types_v060.xsd" etc.)
+      # Use mutex for thread safety since Dir.chdir affects entire process
+      SCHEMA_LOAD_MUTEX.synchronize do
+        Dir.chdir(SCHEMAS_DIR) do
+          Nokogiri::XML::Schema(File.read(path))
+        end
+      end
+    end
+
+    # Validate XML against schema
+    #
+    # @param xml [String, Nokogiri::XML::Document] The XML to validate
+    # @param schema [Nokogiri::XML::Schema] The schema to validate against
+    # @param context_name [String] Name for error messages (e.g., "Document XML")
+    # @raise [SchemaValidationError] If validation fails
+    # @return [true] If validation succeeds
+    def validate(xml, schema, context_name)
+      doc = parse_xml(xml)
+      errors = schema.validate(doc)
+
+      return true if errors.empty?
+
+      # Format error messages with line numbers
+      error_messages = errors.map do |error|
+        format_error(error)
+      end
+
+      raise SchemaValidationError.new(
+        "#{context_name} validation failed",
+        schema_errors: error_messages
+      )
+    end
+
+    # Parse XML input (string or document)
+    #
+    # @param xml [String, Nokogiri::XML::Document] The XML to parse
+    # @return [Nokogiri::XML::Document] Parsed XML document
+    def parse_xml(xml)
+      return xml if xml.is_a?(Nokogiri::XML::Document)
+
+      Nokogiri::XML(xml) do |config|
+        config.strict.nonet
+      end
+    end
+
+    # Format schema validation error with line number
+    #
+    # @param error [Nokogiri::XML::SyntaxError] The validation error
+    # @return [String] Formatted error message
+    def format_error(error)
+      if error.line&.positive?
+        "Line #{error.line}: #{error.message}"
+      else
+        error.message
+      end
+    end
+  end
+end