lbyte-budget 0.1.1

data/db/migrate/20251129000003_create_budget_payments.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreateBudgetPayments < ActiveRecord::Migration[7.0]
+  def change
+    create_table :budget_payments do |t|
+      t.references :budget_quote, null: false, foreign_key: true, index: true
+      t.decimal :amount, precision: 10, scale: 2, null: false, default: 0.0
+      t.datetime :payment_date, null: false
+      t.string :payment_method, default: 'efectivo'
+      t.text :notes
+
+      t.timestamps
+    end
+
+    add_index :budget_payments, :payment_date
+    add_index :budget_payments, :payment_method
+  end
+end

data/examples/basic_usage.rb

@@ -0,0 +1,130 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# This example requires a Rails environment with the Budget engine loaded
+# Run from a Rails app that has the budget gem installed:
+#   rails runner examples/basic_usage.rb
+
+puts '=' * 70
+puts 'EJEMPLO DE USO DEL SISTEMA DE PRESUPUESTOS'
+puts '=' * 70
+puts
+
+# 1. Create a new quote for a customer
+puts '1. Creando un nuevo presupuesto para María González...'
+quote = Budget::Quote.create!(
+  customer_name: 'María González',
+  customer_contact: '555-1234',
+  notes: 'Prefiere montura liviana'
+)
+puts "✓ Presupuesto ##{quote.id} creado"
+puts
+
+# 2. Add line items (lentes, montura, tratamiento)
+puts '2. Agregando artículos al presupuesto...'
+
+# Add lenses
+quote.add_line_item(
+  description: 'Lentes progresivos alta gama',
+  price: 150.00,
+  category: 'lente'
+)
+puts '✓ Agregado: Lentes progresivos - $150.00'
+
+# Add frame
+quote.add_line_item(
+  description: 'Montura de titanio ligera',
+  price: 80.00,
+  category: 'montura'
+)
+puts '✓ Agregado: Montura de titanio - $80.00'
+
+# Add treatment
+quote.add_line_item(
+  description: 'Tratamiento anti-reflejante',
+  price: 35.00,
+  category: 'tratamiento'
+)
+puts '✓ Agregado: Tratamiento anti-reflejante - $35.00'
+
+# Add additional treatment
+quote.add_line_item(
+  description: 'Protección UV',
+  price: 25.00,
+  category: 'tratamiento'
+)
+puts '✓ Agregado: Protección UV - $25.00'
+
+# Add case
+quote.add_line_item(
+  description: 'Estuche premium',
+  price: 10.00,
+  category: 'other'
+)
+puts '✓ Agregado: Estuche premium - $10.00'
+puts
+
+# 3. Display quote
+puts '3. Presupuesto completo:'
+puts quote
+puts
+
+# 4. Add initial payment (adelanto)
+puts '4. Cliente realiza adelanto del 50%...'
+adelanto_amount = quote.total * 0.5
+quote.add_payment(
+  amount: adelanto_amount,
+  payment_method: 'efectivo',
+  notes: 'Adelanto inicial (50%)'
+)
+puts "✓ Adelanto de $#{format('%.2f', adelanto_amount)} registrado"
+puts "   Saldo pendiente: $#{format('%.2f', quote.remaining_balance)}"
+puts
+
+# 5. Display updated quote
+puts '5. Presupuesto actualizado:'
+puts quote
+puts
+
+# Simulate time passing and customer returning
+puts '=' * 70
+puts '... 2 semanas después ...'
+puts '=' * 70
+puts
+
+# 6. Customer returns to complete payment
+puts '6. Cliente regresa para completar el pago...'
+remaining = quote.remaining_balance
+quote.add_payment(
+  amount: remaining,
+  payment_method: 'tarjeta',
+  notes: 'Pago final - retira lentes'
+)
+puts "✓ Pago final de $#{format('%.2f', remaining)} registrado"
+puts "✓ Estado: #{quote.fully_paid? ? 'PAGADO COMPLETO ✓' : 'PENDIENTE'}"
+puts
+
+# 7. Display final quote
+puts '7. Presupuesto final:'
+puts quote
+puts
+
+# 8. Display summary
+puts '8. Resumen del presupuesto:'
+summary = quote.summary
+puts "   ID: #{summary[:id]}"
+puts "   Cliente: #{summary[:customer_name]}"
+puts "   Total: $#{format('%.2f', summary[:total])}"
+puts "   Pagado: $#{format('%.2f', summary[:total_paid])}"
+puts "   Pendiente: $#{format('%.2f', summary[:remaining_balance])}"
+puts "   Estado: #{summary[:fully_paid] ? 'COMPLETO' : 'PENDIENTE'}"
+puts
+puts '   Desglose por categoría:'
+summary[:category_breakdown].each do |category, amount|
+  puts "   - #{category}: $#{format('%.2f', amount)}"
+end
+puts
+
+puts '=' * 70
+puts 'EJEMPLO COMPLETADO'
+puts '=' * 70

data/examples/test_examples.rb

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Quick Test Examples - Shows what the test suite validates
+# Run from a Rails app that has the budget gem installed:
+#   rails runner examples/test_examples.rb
+
+puts '=' * 70
+puts 'BUDGET GEM - TEST EXAMPLES'
+puts '=' * 70
+puts
+
+# Example 1: LineItem validation
+puts '1. LineItem - Category Validation'
+puts '-' * 70
+quote = Budget::Quote.create!(customer_name: 'Test Customer')
+item1 = quote.line_items.create!(description: 'Lente', price: 100, category: 'lente')
+item2 = quote.line_items.build(description: 'Invalid', price: 50, category: 'invalid_cat')
+item2.valid? # This will fail validation
+puts "Valid category ('lente'): #{item1.category}"
+puts "Invalid category validation: #{item2.errors[:category].join(', ')}" if item2.errors[:category].any?
+puts
+
+# Example 2: Payment method validation
+puts '2. Payment - Method Validation'
+puts '-' * 70
+payment1 = quote.payments.create!(amount: 100, payment_method: 'tarjeta')
+payment2 = quote.payments.create!(amount: 50, payment_method: 'efectivo')
+puts "tarjeta → #{payment1.payment_method}"
+puts "efectivo → #{payment2.payment_method}"
+puts
+
+# Example 3: Quote calculations
+puts '3. Quote - Total Calculations'
+puts '-' * 70
+calc_quote = Budget::Quote.create!(customer_name: 'Test Customer')
+calc_quote.add_line_item(description: 'Lente', price: 150.0, category: 'lente')
+calc_quote.add_line_item(description: 'Montura', price: 80.0, category: 'montura')
+calc_quote.add_line_item(description: 'Tratamiento', price: 35.0, category: 'tratamiento', quantity: 2)
+puts 'Items: Lente ($150) + Montura ($80) + Tratamiento ($35 x 2)'
+puts "Total: $#{calc_quote.total}"
+puts "Category breakdown: #{calc_quote.category_breakdown}"
+puts
+
+# Example 4: Payment tracking
+puts '4. Quote - Payment Tracking'
+puts '-' * 70
+calc_quote.add_payment(amount: 150.0, notes: 'Adelanto (50%)')
+puts "After adelanto: Paid=$#{calc_quote.total_paid}, Remaining=$#{calc_quote.remaining_balance}"
+calc_quote.add_payment(amount: calc_quote.remaining_balance, notes: 'Final payment')
+puts "After final payment: Paid=$#{calc_quote.total_paid}, Remaining=$#{calc_quote.remaining_balance}"
+puts "Fully paid? #{quote.fully_paid?}"
+puts
+
+# Example 5: Type conversions
+puts '5. Type Conversions'
+puts '-' * 70
+item = Budget::LineItem.new(description: 'Test', price: '99.99', quantity: '3')
+puts "String price '99.99' → #{item.price.class}: #{item.price}"
+puts "String quantity '3' → #{item.quantity.class}: #{item.quantity}"
+puts "Subtotal: $#{item.subtotal}"
+puts
+
+# Example 6: Edge cases
+puts '6. Edge Cases'
+puts '-' * 70
+edge_quote = Budget.create_quote(customer_name: 'Edge Test')
+edge_quote.add_line_item(description: 'Item', price: 100.0)
+edge_quote.add_payment(amount: 150.0) # Overpayment
+puts 'Total: $100, Paid: $150'
+puts "Remaining balance (overpayment): $#{edge_quote.remaining_balance}"
+puts "Fully paid? #{edge_quote.fully_paid?}"
+puts
+
+# Example 7: Spanish formatting
+puts '7. Spanish Translations'
+puts '-' * 70
+categories = %i[lente montura tratamiento other]
+categories.each do |cat|
+  item = Budget::LineItem.new(description: 'Test', price: 50, category: cat)
+  puts "#{cat} → #{item.category_name}"
+end
+puts
+payment_methods = %w[efectivo tarjeta transferencia cheque other]
+payment_methods.each do |method|
+  payment = Budget::Payment.new(amount: 50, payment_method: method)
+  puts "#{method} → #{payment.payment_method_name}"
+end
+puts
+
+# Example 8: Complete workflow
+puts '8. Complete Workflow (Integration Test)'
+puts '-' * 70
+complete_quote = Budget.create_quote(
+  customer_name: 'María González',
+  customer_contact: '555-1234'
+)
+complete_quote.add_line_item(description: 'Lentes progresivos', price: 150.0, category: :lente)
+complete_quote.add_line_item(description: 'Montura titanio', price: 80.0, category: :montura)
+complete_quote.add_line_item(description: 'Anti-reflejante', price: 35.0, category: :tratamiento)
+
+puts "Total: $#{complete_quote.total}"
+adelanto = complete_quote.total * 0.5
+complete_quote.add_payment(amount: adelanto, notes: 'Adelanto 50%')
+puts "After 50% adelanto: Remaining=$#{complete_quote.remaining_balance}"
+complete_quote.add_payment(amount: complete_quote.remaining_balance, notes: 'Pago final')
+puts "After final payment: Status=#{complete_quote.fully_paid? ? 'COMPLETO' : 'PENDIENTE'}"
+puts
+
+puts '=' * 70
+puts 'All examples demonstrate test coverage scenarios'
+puts "Run 'bundle exec rspec' to execute the full test suite"
+puts '=' * 70

data/lib/budget/engine.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Budget
+  # Rails Engine for Budget gem
+  # Provides mountable engine functionality with isolated namespace
+  class Engine < ::Rails::Engine
+    isolate_namespace Budget
+
+    # Ensure app directory is in autoload paths
+    config.autoload_paths += %W[
+      #{root}/app/models
+      #{root}/app/controllers
+    ]
+
+    # Add views path for JBuilder templates
+    config.paths['app/views'] ||= []
+    config.paths['app/views'] << File.expand_path('../../app/views', __dir__)
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.fixture_replacement :factory_bot
+      g.factory_bot dir: 'spec/factories'
+    end
+  end
+end

data/lib/budget/line_item.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Budget
+  # Represents a single line item in a quote
+  # Examples: lente (lens), montura (frame), tratamiento (treatment)
+  class LineItem
+    attr_accessor :description, :price, :category, :quantity
+
+    CATEGORIES = %w[lente montura tratamiento accesorio servicio other].freeze
+
+    def initialize(description:, price:, category: 'other', quantity: 1)
+      @description = description
+      @price = price.to_f
+      @category = validate_category(category)
+      @quantity = quantity.to_i
+    end
+
+    # Calculate subtotal (price * quantity)
+    # @return [Float] Subtotal
+    def subtotal
+      @price * @quantity
+    end
+
+    # Get category in Spanish
+    # @return [String] Category name in Spanish
+    def category_name
+      {
+        'lente' => 'Lente',
+        'montura' => 'Montura',
+        'tratamiento' => 'Tratamiento',
+        'accesorio' => 'Accesorio',
+        'servicio' => 'Servicio',
+        'other' => 'Otro'
+      }[@category] || @category.capitalize
+    end
+
+    # Format line item for display
+    # @return [String] Formatted line item
+    def to_s
+      if @quantity > 1
+        "#{category_name} - #{@description} (#{@quantity} x $#{format('%.2f', @price)}) = $#{format('%.2f', subtotal)}"
+      else
+        "#{category_name} - #{@description}: $#{format('%.2f', @price)}"
+      end
+    end
+
+    # Convert to hash
+    # @return [Hash] Line item as hash
+    def to_h
+      {
+        description: @description,
+        price: @price,
+        category: @category,
+        quantity: @quantity,
+        subtotal: subtotal
+      }
+    end
+
+    private
+
+    def validate_category(category)
+      category = category.to_s
+      CATEGORIES.include?(category) ? category : 'other'
+    end
+  end
+end

data/lib/budget/payment.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Budget
+  # Represents a payment made towards a quote
+  # Can be initial payment (adelanto) or subsequent payments
+  class Payment
+    attr_accessor :amount, :payment_date, :payment_method, :notes
+
+    PAYMENT_METHODS = %w[efectivo tarjeta transferencia cheque other].freeze
+
+    def initialize(amount:, payment_date: nil, payment_method: 'efectivo', notes: nil)
+      @amount = amount.to_f
+      @payment_date = payment_date || Time.now
+      @payment_method = validate_payment_method(payment_method)
+      @notes = notes
+    end
+
+    # Get payment method in Spanish
+    # @return [String] Payment method in Spanish
+    def payment_method_name
+      {
+        'efectivo' => 'Efectivo',
+        'tarjeta' => 'Tarjeta',
+        'transferencia' => 'Transferencia',
+        'cheque' => 'Cheque',
+        'other' => 'Otro'
+      }[@payment_method] || @payment_method.capitalize
+    end
+
+    # Format payment for display
+    # @return [String] Formatted payment
+    def to_s
+      output = "$#{format('%.2f', @amount)} - #{payment_method_name} (#{@payment_date.strftime('%d/%m/%Y')})"
+      output += " - #{@notes}" if @notes
+      output
+    end
+
+    # Convert to hash
+    # @return [Hash] Payment as hash
+    def to_h
+      {
+        amount: @amount,
+        payment_date: @payment_date,
+        payment_method: @payment_method,
+        notes: @notes
+      }
+    end
+
+    private
+
+    def validate_payment_method(method)
+      method = method.to_s.downcase
+      PAYMENT_METHODS.include?(method) ? method : 'other'
+    end
+  end
+end

data/lib/budget/quote.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Budget
+  # Represents a quote/budget for eyeglasses purchase
+  # Manages line items (lentes, montura, tratamiento) and payments
+  class Quote
+    attr_accessor :id, :customer_name, :customer_contact, :date, :notes
+    attr_reader :line_items, :payments
+
+    def initialize(customer_name:, id: nil, customer_contact: nil, date: nil, notes: nil)
+      @id = id || generate_id
+      @customer_name = customer_name
+      @customer_contact = customer_contact
+      @date = date || Time.now
+      @notes = notes
+      @line_items = []
+      @payments = []
+    end
+
+    # Add a line item to the quote
+    # @param description [String] Item description (e.g., "Lente progresivo", "Montura metal")
+    # @param price [Float] Item price
+    # @param category [Symbol] :lente, :montura, :tratamiento, :other
+    def add_line_item(description:, price:, category: :other, quantity: 1)
+      # Convert symbol to string for consistency
+      category = category.to_s if category.is_a?(Symbol)
+      line_item = LineItem.new(
+        description: description,
+        price: price,
+        category: category,
+        quantity: quantity
+      )
+      @line_items << line_item
+      line_item
+    end
+
+    # Remove a line item by index
+    def remove_line_item(index)
+      @line_items.delete_at(index)
+    end
+
+    # Add a payment (adelanto or subsequent payment)
+    # @param amount [Float] Payment amount
+    # @param payment_date [Time] When payment was made
+    # @param payment_method [String] How payment was made (efectivo, tarjeta, transferencia)
+    # @param notes [String] Additional notes about payment
+    def add_payment(amount:, payment_date: nil, payment_method: 'efectivo', notes: nil)
+      payment = Payment.new(
+        amount: amount,
+        payment_date: payment_date || Time.now,
+        payment_method: payment_method,
+        notes: notes
+      )
+      @payments << payment
+      payment
+    end
+
+    # Calculate total price of all line items
+    # @return [Float] Total price
+    def total
+      @line_items.sum(&:subtotal)
+    end
+
+    # Calculate total amount paid so far
+    # @return [Float] Total paid
+    def total_paid
+      @payments.sum(&:amount)
+    end
+
+    # Calculate remaining balance to be paid
+    # @return [Float] Remaining amount
+    def remaining_balance
+      total - total_paid
+    end
+
+    # Check if quote is fully paid
+    # @return [Boolean]
+    def fully_paid?
+      remaining_balance <= 0
+    end
+
+    # Get the initial payment (adelanto)
+    # @return [Payment, nil] First payment or nil if no payments
+    def initial_payment
+      @payments.first
+    end
+
+    # Get breakdown by category
+    # @return [Hash] Category totals
+    def category_breakdown
+      breakdown = Hash.new(0)
+      @line_items.each do |item|
+        breakdown[item.category] += item.subtotal
+      end
+      breakdown
+    end
+
+    # Generate a summary of the quote
+    # @return [Hash] Quote summary
+    def summary
+      {
+        id: @id,
+        customer_name: @customer_name,
+        customer_contact: @customer_contact,
+        date: @date,
+        line_items_count: @line_items.count,
+        total: total,
+        total_paid: total_paid,
+        remaining_balance: remaining_balance,
+        fully_paid: fully_paid?,
+        category_breakdown: category_breakdown,
+        payments_count: @payments.count
+      }
+    end
+
+    # Format quote for display
+    # @return [String] Formatted quote
+    def to_s
+      output = []
+      output << ('=' * 60)
+      output << "PRESUPUESTO ##{@id}"
+      output << ('=' * 60)
+      output << "Cliente: #{@customer_name}"
+      output << "Contacto: #{@customer_contact}" if @customer_contact
+      output << "Fecha: #{@date.strftime('%d/%m/%Y')}"
+      output << "Notas: #{@notes}" if @notes
+      output << ''
+      output << 'DETALLE:'
+      output << ('-' * 60)
+
+      @line_items.each_with_index do |item, index|
+        output << "#{index + 1}. #{item}"
+      end
+
+      output << ('-' * 60)
+      output << "TOTAL: $#{format('%.2f', total)}"
+      output << ''
+
+      if @payments.any?
+        output << 'PAGOS:'
+        output << ('-' * 60)
+        @payments.each_with_index do |payment, index|
+          output << "#{index + 1}. #{payment}"
+        end
+        output << ('-' * 60)
+        output << "Total Pagado: $#{format('%.2f', total_paid)}"
+      end
+
+      output << ''
+      output << "SALDO PENDIENTE: $#{format('%.2f', remaining_balance)}"
+      output << "Estado: #{fully_paid? ? 'PAGADO COMPLETO' : 'PENDIENTE'}"
+      output << ('=' * 60)
+
+      output.join("\n")
+    end
+
+    private
+
+    def generate_id
+      "Q#{Time.now.strftime('%Y%m%d%H%M%S')}"
+    end
+  end
+end

data/lib/budget/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Budget
+  VERSION = '0.1.1'
+end

data/lib/budget.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'budget/version'
+require_relative 'budget/engine'
+
+# Budget module provides quote/budget management functionality
+# Rails Engine for managing quotes with line items and payments
+module Budget
+  class Error < StandardError; end
+end

data/lib/generators/budget/INSTALL

@@ -0,0 +1,46 @@
+===============================================================================
+
+Budget Engine has been installed!
+
+Next steps:
+
+1. Run the migrations:
+
+   $ rails db:migrate
+
+2. Start using Budget in your Rails app:
+
+   # Create a new quote
+   quote = Budget::Quote.create!(
+     customer_name: "María González",
+     customer_contact: "555-1234"
+   )
+
+   # Add line items
+   quote.add_line_item(
+     description: "Lentes progresivos",
+     price: 150.00,
+     category: "lente"
+   )
+
+   # Add payment
+   quote.add_payment(
+     amount: 75.00,
+     payment_method: "efectivo",
+     notes: "Adelanto 50%"
+   )
+
+   # Check status
+   quote.total              # => 150.0
+   quote.total_paid         # => 75.0
+   quote.remaining_balance  # => 75.0
+   quote.fully_paid?        # => false
+
+3. View the quote:
+
+   puts quote  # Formatted output
+
+For more information, visit:
+https://github.com/rubenpazch/lbyte-budget
+
+===============================================================================

data/lib/generators/budget/install_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module Budget
+  module Generators
+    # Rails generator for installing Budget migrations
+    # Creates migrations for quotes, line items, and payments tables
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('../../../db/migrate', __dir__)
+
+      desc 'Generates Budget migrations for quotes, line items, and payments'
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migrations
+        migration_template '20251129000001_create_budget_quotes.rb', 'db/migrate/create_budget_quotes.rb'
+        migration_template '20251129000002_create_budget_line_items.rb', 'db/migrate/create_budget_line_items.rb'
+        migration_template '20251129000003_create_budget_payments.rb', 'db/migrate/create_budget_payments.rb'
+      end
+
+      def show_readme
+        readme 'INSTALL' if behavior == :invoke
+      end
+    end
+  end
+end

data/sig/budget.rbs

@@ -0,0 +1,4 @@
+module Budget
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end