lbyte-budget 0.1.1

data/README.md

@@ -0,0 +1,367 @@
+# Budget
+
+A Rails Engine for managing quotes/budgets for eyeglasses businesses (or any business with advance payments and installment tracking). Perfect for optical stores that need to track customer orders with deposits and remaining balances.
+
+## Features
+
+- 📋 Create detailed quotes with line items (lentes, montura, tratamiento, etc.)
+- 💰 Track multiple payments (adelanto/deposit and subsequent payments)
+- 🧮 Automatic calculation of totals, paid amounts, and remaining balances
+- 📊 Category breakdown for different product types
+- 📄 Formatted output for printing or display
+- ✅ Payment status tracking (fully paid vs. pending)
+- 🚂 **Rails Engine** - Automatically creates database migrations
+- 💾 **ActiveRecord Models** - Persist quotes, line items, and payments
+- 🔧 **Easy Installation** - One command to set up
+- 🌐 **REST JSON API** - Complete API with JBuilder views
+- 📱 **API-Ready** - Perfect for React, Vue, or mobile apps
+
+## Installation for Rails Projects
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lbyte-budget'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+### Generate Migrations
+
+Run the install generator to copy migrations:
+
+```bash
+rails generate budget:install
+```
+
+This will create three migrations:
+- `create_budget_quotes` - For storing quotes
+- `create_budget_line_items` - For storing line items
+- `create_budget_payments` - For storing payments
+
+Then run the migrations:
+
+```bash
+rails db:migrate
+```
+
+### Mount the Engine (For API Access)
+
+Add to your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount Budget::Engine => "/budget"
+  # Your other routes...
+end
+```
+
+Now you have access to all budget API endpoints at `/budget/*`.
+
+## JSON API Quick Start
+
+### Fetch All Quotes
+
+```bash
+curl http://localhost:3000/budget/quotes
+```
+
+```json
+[
+  {
+    "id": 1,
+    "customer_name": "María González",
+    "customer_contact": "555-1234",
+    "line_items_count": 2,
+    "payments_count": 1,
+    "total": "230.00",
+    "total_paid": "115.00",
+    "remaining_balance": "115.00",
+    "fully_paid": false
+  }
+]
+```
+
+### Create a Quote with JavaScript
+
+```javascript
+const response = await fetch('http://localhost:3000/budget/quotes', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    quote: {
+      customer_name: "María González",
+      customer_contact: "555-1234"
+    }
+  })
+});
+
+const quote = await response.json();
+console.log(quote.id); // => 1
+```
+
+### Add Line Items and Payments
+
+```javascript
+// Add line item
+await fetch(`http://localhost:3000/budget/quotes/${quoteId}/line_items`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    line_item: {
+      description: "Lentes progresivos",
+      price: 150.00,
+      category: "lente",
+      quantity: 1
+    }
+  })
+});
+
+// Record payment
+await fetch(`http://localhost:3000/budget/quotes/${quoteId}/payments`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    payment: {
+      amount: 75.00,
+      payment_method: "tarjeta"
+    }
+  })
+});
+```
+
+📖 **See [API_DOCUMENTATION.md](API_DOCUMENTATION.md) for complete endpoint reference.**
+
+## Usage in Rails
+
+### Creating a Quote with ActiveRecord
+
+```ruby
+# 1. Create a new quote (persisted to database)
+quote = Budget::Quote.create!(
+  customer_name: "María González",
+  customer_contact: "555-1234",
+  notes: "Prefiere montura liviana"
+)
+
+# 2. Add line items
+quote.add_line_item(
+  description: "Lentes progresivos alta gama",
+  price: 150.00,
+  category: "lente"
+)
+
+quote.add_line_item(
+  description: "Montura de titanio",
+  price: 80.00,
+  category: "montura"
+)
+
+quote.add_line_item(
+  description: "Tratamiento anti-reflejante",
+  price: 35.00,
+  category: "tratamiento"
+)
+
+# 3. Add initial payment (adelanto)
+adelanto = quote.total * 0.5
+quote.add_payment(
+  amount: adelanto,
+  payment_method: "efectivo",
+  notes: "Adelanto inicial (50%)"
+)
+
+# 4. Check status
+puts "Total: $#{quote.total}"
+puts "Pagado: $#{quote.total_paid}"
+puts "Pendiente: $#{quote.remaining_balance}"
+puts "Estado: #{quote.fully_paid? ? 'COMPLETO' : 'PENDIENTE'}"
+
+# 5. Later, customer returns to complete payment
+quote.add_payment(
+  amount: quote.remaining_balance,
+  payment_method: "tarjeta",
+  notes: "Pago final - retira lentes"
+)
+
+# 6. Print formatted quote
+puts quote
+```
+
+## Database Schema
+
+The gem creates three tables:
+
+### budget_quotes
+- `customer_name` (string, required)
+- `customer_contact` (string)
+- `notes` (text)
+- `quote_date` (datetime)
+- timestamps
+
+### budget_line_items
+- `budget_quote_id` (foreign key)
+- `description` (string, required)
+- `price` (decimal, required)
+- `category` (string) - lente, montura, tratamiento, other
+- `quantity` (integer, default: 1)
+- timestamps
+
+### budget_payments
+- `budget_quote_id` (foreign key)
+- `amount` (decimal, required)
+- `payment_date` (datetime, required)
+- `payment_method` (string) - efectivo, tarjeta, transferencia, cheque, other
+- `notes` (text)
+- timestamps
+
+## Documentation
+
+- 📘 **[Rails Integration Guide](RAILS_USAGE.md)** - Detailed Rails/ActiveRecord usage
+- 🌐 **[API Documentation](API_DOCUMENTATION.md)** - Complete REST API reference with examples
+- 🧹 **[Cleanup Guide](CLEANUP.md)** - Understanding the codebase structure
+
+## Model Methods
+
+### Available Categories
+
+- `lente` - Lenses
+- `montura` - Frame
+- `tratamiento` - Treatment (anti-reflective, UV protection, etc.)
+- `accesorio` - Accessories
+- `servicio` - Services
+- `other` - Other items
+
+### Available Payment Methods
+
+- `efectivo` - Cash
+- `tarjeta` - Card
+- `transferencia` - Bank transfer
+- `cheque` - Check
+- `other` - Other methods
+
+### Core Methods
+
+#### Quote
+
+```ruby
+# Create a quote
+quote = Budget::Quote.create!(customer_name: "John Doe")
+
+# Add line items
+quote.add_line_item(description: "Product", price: 100.0, category: 'lente', quantity: 1)
+
+# Add payments
+quote.add_payment(amount: 50.0, payment_method: "efectivo")
+
+# Calculations
+quote.total              # Total price of all items
+quote.total_paid         # Total amount paid
+quote.remaining_balance  # Amount still owed
+quote.fully_paid?        # true if remaining_balance <= 0
+
+# Get breakdown
+quote.category_breakdown # Hash of totals by category
+quote.summary           # Complete summary hash
+
+# Access payments
+quote.initial_payment   # First payment (adelanto)
+quote.payments          # All payments array
+```
+
+### Running the Example
+
+See the complete example in action:
+
+```bash
+ruby examples/basic_usage.rb
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+### Running Tests
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Or use the test script for a nicer output with coverage:
+
+```bash
+bundle exec rspec
+```
+
+Run specific test suites:
+
+```bash
+# ActiveRecord model tests
+bundle exec rspec spec/models/
+
+# Controller/API tests
+bundle exec rspec spec/controllers/
+
+# Engine tests
+bundle exec rspec spec/lib/
+
+# Module tests
+bundle exec rspec spec/budget_spec.rb
+```
+
+View the coverage report:
+
+```bash
+bundle exec rspec
+open coverage/index.html
+```
+
+The gem has **100% test coverage** across all modules:
+- ✅ 145 ActiveRecord model tests
+- ✅ 80 controller/API tests
+- ✅ 8 engine configuration tests
+- ✅ 4 module tests
+- **Total: 237+ test examples**
+
+See [TESTING.md](TESTING.md) for detailed testing documentation.
+
+### Interactive Console
+
+Run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Installation
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Testing
+
+The Budget gem includes comprehensive test coverage:
+
+- **LineItem tests**: 20+ test cases covering initialization, calculations, formatting, and edge cases
+- **Payment tests**: 20+ test cases covering payment methods, validation, and formatting
+- **Quote tests**: 40+ test cases covering the complete workflow including line items, payments, calculations, and integration scenarios
+- **100% code coverage** as verified by SimpleCov
+
+Run tests with:
+
+```bash
+bundle exec rspec --format documentation
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rubenpazch/lbyte-budget. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/rubenpazch/lbyte-budget/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Budget project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/rubenpazch/lbyte-budget/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc 'Run tests and open coverage report'
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['spec'].invoke
+  `open coverage/index.html` if RUBY_PLATFORM =~ /darwin/
+end

data/TESTING.md

@@ -0,0 +1,243 @@
+# Test Coverage Summary
+
+## Overview
+The Budget gem has **100% test coverage** across all ActiveRecord models, controllers, and engine configuration.
+
+## Test Structure
+
+```
+spec/
+├── rails_helper.rb             # Rails/RSpec configuration
+├── budget_spec.rb              # Module tests
+├── support/
+│   └── database_cleaner.rb     # Database cleanup between tests
+├── dummy/                      # Dummy Rails app for testing the engine
+│   ├── config/
+│   │   ├── database.yml
+│   │   ├── environment.rb
+│   │   └── routes.rb
+│   └── db/
+│       └── schema.rb
+├── models/budget/              # ActiveRecord model tests (145 examples)
+│   ├── quote_spec.rb
+│   ├── line_item_spec.rb
+│   └── payment_spec.rb
+├── controllers/budget/         # Controller tests (80 examples)
+│   ├── quotes_controller_spec.rb
+│   ├── line_items_controller_spec.rb
+│   └── payments_controller_spec.rb
+└── lib/budget/
+    └── engine_spec.rb          # Engine configuration tests (8 examples)
+```
+
+## Running Tests
+
+### Install Dependencies
+
+```bash
+bundle install
+```
+
+### Run All Tests
+
+```bash
+bundle exec rspec
+```
+
+### Run Specific Test Suites
+
+```bash
+# ActiveRecord model tests
+bundle exec rspec spec/models/
+
+# Controller tests
+bundle exec rspec spec/controllers/
+
+# Engine tests
+bundle exec rspec spec/lib/
+
+# Module tests
+bundle exec rspec spec/budget_spec.rb
+```
+
+### View Coverage Report
+
+```bash
+bundle exec rspec
+open coverage/index.html
+```
+
+## Test Files
+
+### 1. `spec/budget_spec.rb` - Main Module Tests
+- ✅ Version number verification
+- ✅ Error class definition
+- **4 test cases**
+
+### 2. `spec/budget/line_item_spec.rb` - LineItem Class Tests
+- ✅ Initialization with various parameter combinations
+- ✅ Price and quantity type conversion
+- ✅ Category validation (lente, montura, tratamiento, other)
+- ✅ Subtotal calculations
+- ✅ Category name translations (Spanish)
+- ✅ String formatting for display
+- ✅ Hash conversion
+- ✅ Attribute setters
+- **24 test cases**
+
+### 3. `spec/budget/payment_spec.rb` - Payment Class Tests
+- ✅ Initialization with various parameters
+- ✅ Amount type conversion
+- ✅ Payment date defaulting
+- ✅ Payment method validation (efectivo, tarjeta, transferencia, cheque, other)
+- ✅ Payment method name translations (Spanish)
+- ✅ String formatting for display
+- ✅ Hash conversion
+- ✅ Attribute setters
+- **24 test cases**
+
+### 4. `spec/budget/quote_spec.rb` - Quote Class Tests
+- ✅ Initialization with auto-generated IDs
+- ✅ Adding and removing line items
+- ✅ Adding payments
+- ✅ Total calculation from line items
+- ✅ Total paid calculation
+- ✅ Remaining balance calculation
+- ✅ Fully paid status checking
+- ✅ Initial payment retrieval
+- ✅ Category breakdown generation
+- ✅ Summary hash generation
+- ✅ Formatted string output for printing
+- ✅ Attribute setters
+- ✅ Integration scenarios (complete workflows)
+- **46 test cases**
+
+## NEW: Rails Engine Tests
+
+### 5. `spec/models/budget/quote_spec.rb` - ActiveRecord Quote Model
+- ✅ Association tests (has_many line_items, has_many payments, dependent destroy)
+- ✅ Validation tests (customer_name, quote_date required)
+- ✅ Callback tests (auto-set quote_date)
+- ✅ Scope tests (recent, by_customer, pending)
+- ✅ Calculation methods (total, total_paid, remaining_balance, fully_paid?)
+- ✅ Helper methods (initial_payment, category_breakdown, summary)
+- ✅ String formatting (to_s with PAGADO/PENDIENTE status)
+- ✅ Convenience methods (add_line_item, add_payment)
+- ✅ Table name configuration
+- **80+ test cases**
+
+### 6. `spec/models/budget/line_item_spec.rb` - ActiveRecord LineItem Model
+- ✅ Association tests (belongs_to quote)
+- ✅ Validation tests (description, price > 0, category, quantity > 0)
+- ✅ Callback tests (default quantity, default category)
+- ✅ CATEGORIES constant definition
+- ✅ Subtotal calculation
+- ✅ Category name translation (Spanish)
+- ✅ String formatting
+- ✅ Table name configuration
+- **35+ test cases**
+
+### 7. `spec/models/budget/payment_spec.rb` - ActiveRecord Payment Model
+- ✅ Association tests (belongs_to quote)
+- ✅ Validation tests (amount > 0, payment_date, payment_method)
+- ✅ Callback tests (default payment_date, default payment_method)
+- ✅ PAYMENT_METHODS constant definition
+- ✅ Payment method name translation (Spanish)
+- ✅ String formatting
+- ✅ Table name configuration
+- **30+ test cases**
+
+### 8. `spec/controllers/budget/quotes_controller_spec.rb` - REST API
+- ✅ GET #index - List all quotes with summary
+- ✅ GET #show - Full quote with line_items, payments, totals
+- ✅ POST #create - Create quote with validations
+- ✅ PATCH #update - Update quote with error handling
+- ✅ DELETE #destroy - Remove quote
+- ✅ GET #summary - Quote summary endpoint
+- ✅ JSON response validation
+- ✅ 404 error handling
+- **30+ test cases**
+
+### 9. `spec/controllers/budget/line_items_controller_spec.rb` - Nested API
+- ✅ All CRUD actions (index, show, create, update, destroy)
+- ✅ Nested resource validation
+- ✅ Quote association verification
+- ✅ 404 handling for wrong quote
+- **25+ test cases**
+
+### 10. `spec/controllers/budget/payments_controller_spec.rb` - Nested API
+- ✅ All CRUD actions with payment-specific logic
+- ✅ Auto-set payment_date to today
+- ✅ Custom payment_date support
+- ✅ Nested resource validation
+- **25+ test cases**
+
+### 11. `spec/lib/budget/engine_spec.rb` - Engine Configuration
+- ✅ Engine inheritance and isolation
+- ✅ Route definitions verification
+- **8+ test cases**
+
+## Total Coverage
+
+- **ActiveRecord Model Tests**: 145
+- **Controller/API Tests**: 80
+- **Engine Configuration Tests**: 8
+- **Module Tests**: 4
+- **Total Test Cases**: 237+
+- **Code Coverage**: 100%
+- **Files Tested**: All production code
+
+## Running Tests
+
+### Basic test run:
+```bash
+bundle exec rspec
+```
+
+### With documentation format:
+```bash
+bundle exec rspec --format documentation
+```
+
+### View coverage report:
+```bash
+open coverage/index.html
+```
+
+## Coverage Configuration
+
+SimpleCov is configured in `spec/rails_helper.rb` with:
+- Minimum coverage requirement: 100%
+- Minimum coverage per file: 90%
+- Filters: `/spec/`, `/examples/`, `/db/`, `/config/`
+- Groups: ActiveRecord Models, Controllers, Views, Engine, Main
+
+## Test Quality Features
+
+### Edge Cases Covered
+- ✅ Type conversions (string to float, string to integer)
+- ✅ Invalid input validation
+- ✅ Nil/empty value handling
+- ✅ Negative balances (overpayment)
+- ✅ Zero values
+- ✅ Multiple payment installments
+- ✅ Complete purchase workflows
+
+### Integration Tests
+- ✅ Full eyeglasses purchase workflow
+- ✅ Partial payment scenarios
+- ✅ Multiple payment installments
+- ✅ Category breakdown with mixed items
+
+### Formatting Tests
+- ✅ Currency formatting
+- ✅ Date formatting
+- ✅ Spanish translations
+- ✅ Conditional output (with/without optional fields)
+
+## Continuous Integration Ready
+
+The test suite is configured to work with CI environments:
+- SimpleCov uses SimpleFormatter in CI mode
+- All dependencies specified in Gemfile
+- `.gitignore` properly configured to exclude coverage reports