# Invoice Form Enhancements
## Overview
The Invoice form has been completely redesigned with a modern tabbed interface to accommodate all the new enhanced fields from the database migration.
## Form Structure
### Tab 1: Basic Information
**Purpose:** Core invoice identification and relationships
#### Invoice Details Section
- **Invoice Number** - Auto-generated (INV-YYYYMMDD-XXXXXX), read-only
- **Invoice Type** - Dropdown: Proforma, Final, Credit Note, Debit Note
- **Status** - Dropdown: Draft, Pending, Sent, Viewed, Approved, Cancelled
- **Invoice Date** - Date picker (default: today)
- **Due Date** - Date picker (default: 30 days from today)
#### Related Records Section
- **Booking** - Searchable dropdown, auto-fills client info when selected
- **Client** - Required, searchable dropdown, auto-fills name/phone/address
- **Company** - Required, defaults to session company
- **Workspace** - Optional, defaults to session workspace
- **Reservation (Legacy)** - For backward compatibility
#### Client Information Section
- **Client Name** - Required, auto-filled from booking/client
- **Phone** - Tel input, auto-filled
- **Address** - Textarea, auto-filled
### Tab 2: Invoice Items
**Purpose:** Line items with full category support
#### Line Items Repeater
Each item includes:
- **Category** - Dropdown: Accommodation, Spot, Service, Package, Product, Fee, Tax, Discount, Other
- **Item Name** - Required text input
- **Description** - Textarea for details
- **Quantity** - Numeric, default 1, live calculation
- **Unit Price** - Numeric with € prefix, live calculation
- **Duration Type** - Visible for accommodation/spot/service: Night, Day, Hour, Session, Unit
- **Duration Value** - Numeric, visible for time-based items
- **Start Date** - DateTime picker, visible for time-based items
- **End Date** - DateTime picker, visible for time-based items
- **Discount (%)** - Percentage discount, live calculation
- **Tax Rate (%)** - Default 20%, live calculation
- **Total** - Auto-calculated, read-only
- **Is Free** - Toggle for complimentary items
**Features:**
- Live calculation of totals
- Conditional fields based on category
- Reorderable with buttons
- Collapsible items
- Cloneable for quick duplication
- Add unlimited items
### Tab 3: Payment & Totals
**Purpose:** Financial summary and payment tracking
#### Pricing Summary Section
- **Subtotal** - Auto-calculated from items, read-only
- **Tax Amount** - Auto-calculated from items, read-only
- **Service Fee** - Manual entry for platform fees
- **Discount Amount** - Manual entry for invoice-level discounts
- **Discount Type** - Percentage or Fixed Amount
- **Total Amount** - Final total, read-only, bold display
- **Amount Paid** - Track payments received
- **Currency** - Required, searchable dropdown
#### Payment Details Section
- **Payment Status** - Dropdown: Unpaid, Partially Paid, Paid, Refunded, Cancelled
- **Payment Method** - Dropdown: Cash, Card, Bank Transfer, Check, PayPal, Stripe, Other
- **Payment Date** - DateTime picker
- **Paid At** - Auto-filled timestamp, read-only
### Tab 4: Fiscal & Additional
**Purpose:** Fiscal compliance and extra information
#### Fiscal Receipt Information Section
- **Fiscal Receipt Number** - Text input for fiscal printer number
- **Fiscal Status** - Dropdown: Pending, Printed, Failed, Cancelled
- **Fiscal Printed At** - Auto-filled timestamp, read-only
#### Additional Information Section
- **Internal Notes** - Textarea for staff notes
- **Activated** - Toggle, default true
- **Is Offer/Quote** - Toggle for proforma/quotes
- **Send Email to Client** - Toggle for email notification
#### Cancellation Section
- **Cancelled At** - Auto-filled timestamp, read-only
- **Cancellation Reason** - Textarea
- **Visibility** - Only shown if invoice is cancelled
## Smart Features
### 1. Auto-Fill from Booking
When a booking is selected:
- Client ID is auto-filled
- Company ID is auto-filled
- Workspace ID is auto-filled
- Client name is auto-filled
- Phone is auto-filled
- Address is auto-filled
### 2. Auto-Fill from Client
When a client is selected:
- Name is auto-filled
- Phone is auto-filled
- Address is auto-filled
### 3. Live Calculations
Item totals are calculated in real-time:
```
Subtotal = Quantity × Unit Price
Discount Amount = Subtotal × (Discount % / 100)
Subtotal After Discount = Subtotal - Discount Amount
Tax Amount = Subtotal After Discount × (Tax Rate / 100)
Total = Subtotal After Discount + Tax Amount
```
### 4. Conditional Fields
Duration fields (type, value, start/end dates) only appear for:
- Accommodation items
- Spot items
- Service items
### 5. Session Defaults
- Company defaults to `session('selected_company')`
- Workspace defaults to `session('selected_workspace')`
## Field Mapping
### Database → Form Field Mapping
| Database Column | Form Field | Tab | Section |
|----------------|------------|-----|---------|
| `invoice_number` | Invoice Number | 1 | Invoice Details |
| `invoice_type` | Invoice Type | 1 | Invoice Details |
| `status` | Status | 1 | Invoice Details |
| `date` | Invoice Date | 1 | Invoice Details |
| `due_date` | Due Date | 1 | Invoice Details |
| `booking_id` | Booking | 1 | Related Records |
| `client_id` | Client | 1 | Related Records |
| `company_id` | Company | 1 | Related Records |
| `workspace_id` | Workspace | 1 | Related Records |
| `reservation_id` | Reservation | 1 | Related Records |
| `name` | Client Name | 1 | Client Information |
| `phone` | Phone | 1 | Client Information |
| `address` | Address | 1 | Client Information |
| `invoiceItems` | Line Items | 2 | Line Items |
| `subtotal` | Subtotal | 3 | Pricing Summary |
| `tax_amount` | Tax Amount | 3 | Pricing Summary |
| `service_fee` | Service Fee | 3 | Pricing Summary |
| `discount_amount` | Discount Amount | 3 | Pricing Summary |
| `discount_type` | Discount Type | 3 | Pricing Summary |
| `total` | Total Amount | 3 | Pricing Summary |
| `paid` | Amount Paid | 3 | Pricing Summary |
| `currency_id` | Currency | 3 | Pricing Summary |
| `payment_status` | Payment Status | 3 | Payment Details |
| `payment_method` | Payment Method | 3 | Payment Details |
| `payment_date` | Payment Date | 3 | Payment Details |
| `paid_at` | Paid At | 3 | Payment Details |
| `fiscal_receipt_number` | Fiscal Receipt Number | 4 | Fiscal Receipt |
| `fiscal_status` | Fiscal Status | 4 | Fiscal Receipt |
| `fiscal_printed_at` | Fiscal Printed At | 4 | Fiscal Receipt |
| `notes` | Internal Notes | 4 | Additional Info |
| `is_activated` | Activated | 4 | Additional Info |
| `is_offer` | Is Offer/Quote | 4 | Additional Info |
| `send_email` | Send Email | 4 | Additional Info |
| `cancelled_at` | Cancelled At | 4 | Cancellation |
| `cancellation_reason` | Cancellation Reason | 4 | Cancellation |
### Invoice Items Fields
| Database Column | Form Field | Notes |
|----------------|------------|-------|
| `category` | Category | Dropdown with 9 options |
| `item` | Item Name | Required |
| `description` | Description | Textarea |
| `qty` | Quantity | Numeric, live calc |
| `unit_price` | Unit Price | Numeric, live calc |
| `duration_type` | Duration Type | Conditional visibility |
| `duration_value` | Duration | Conditional visibility |
| `start_date` | Start Date | Conditional visibility |
| `end_date` | End Date | Conditional visibility |
| `discount` | Discount (%) | Live calculation |
| `tax_rate` | Tax Rate (%) | Live calculation |
| `total` | Total | Auto-calculated |
| `is_free` | Free Item | Toggle |
## Usage Examples
### Creating an Invoice from Scratch
1. **Navigate to Invoices → Create**
2. **Tab 1: Basic Information**
- Invoice number is auto-generated
- Select invoice type (usually "Final Invoice")
- Select client (or create new)
- Company/workspace auto-filled from session
- Dates auto-filled (adjust if needed)
3. **Tab 2: Invoice Items**
- Click "Add Item"
- Select category (e.g., "Product" for minibar)
- Enter item name and description
- Set quantity and unit price
- Total calculates automatically
- Add more items as needed
4. **Tab 3: Payment & Totals**
- Review auto-calculated subtotal and tax
- Add service fee if applicable
- Add discount if applicable
- Select currency
- Set payment status
- Enter payment method if paid
5. **Tab 4: Fiscal & Additional**
- Add internal notes if needed
- Configure fiscal settings if using fiscal printer
- Toggle email notification if needed
6. **Save**
### Creating an Invoice from a Booking
1. **Navigate to Invoices → Create**
2. **Tab 1: Basic Information**
- Select the booking from dropdown
- All client info auto-fills
- Company/workspace auto-fill from booking
3. **Tab 2: Invoice Items**
- Manually add items OR
- Use InvoiceService to auto-populate from booking
4. **Continue with tabs 3-4 as above**
### Adding Different Item Types
#### Accommodation Item
```
Category: Accommodation
Item Name: Deluxe Ocean View Room
Description: 3 nights, 2 guests
Quantity: 1
Unit Price: 180.00
Duration Type: Night
Duration Value: 3
Start Date: 2025-01-23 14:00
End Date: 2025-01-26 11:00
Tax Rate: 20%
```
#### Product Item (Minibar)
```
Category: Product
Item Name: Minibar Consumption
Description: Various drinks and snacks
Quantity: 1
Unit Price: 45.00
Tax Rate: 20%
```
#### Fee Item
```
Category: Fee
Item Name: Cleaning Fee
Description: Final cleaning service
Quantity: 1
Unit Price: 30.00
Tax Rate: 20%
```
#### Discount Item
```
Category: Discount
Item Name: Early Booking Discount
Description: 10% off for booking 30 days in advance
Quantity: 1
Unit Price: -50.00
Tax Rate: 0%
```
## Validation Rules
- **Invoice Number** - Required, auto-generated
- **Invoice Type** - Required
- **Status** - Required
- **Invoice Date** - Required
- **Due Date** - Required
- **Client** - Required
- **Company** - Required
- **Currency** - Required
- **Item Name** - Required for each item
- **Quantity** - Required, numeric, minimum 1
- **Unit Price** - Required, numeric
## Best Practices
### 1. Always Link to Booking
When creating invoices for bookings, always select the booking first to auto-fill all related information.
### 2. Use Correct Categories
Choose the appropriate category for each item:
- **Accommodation** - Rooms, houses, apartments
- **Spot** - Beach spots, parking spots
- **Service** - Medical, legal, beauty services
- **Package** - Service bundles
- **Product** - Minibar, insurance, damage fees
- **Fee** - Cleaning, late checkout, service fees
- **Discount** - Any discounts (use negative amounts)
### 3. Set Duration for Time-Based Items
For accommodations, spots, and services, always fill in:
- Duration type
- Duration value
- Start and end dates
### 4. Use Live Calculations
Let the form calculate totals automatically:
- Enter quantity and unit price
- Set discount percentage if applicable
- Set tax rate (defaults to 20%)
- Total updates in real-time
### 5. Track Payments Properly
- Set payment status correctly
- Enter payment method
- Record payment date
- Update "Amount Paid" field
### 6. Use Fiscal Fields
If using fiscal printers:
- Enter fiscal receipt number after printing
- Update fiscal status
- System records fiscal_printed_at automatically
## Troubleshooting
### Issue: Totals Not Calculating
**Solution:** Ensure quantity and unit_price are numeric values. The calculation is triggered on field change.
### Issue: Duration Fields Not Showing
**Solution:** Duration fields only appear when category is "accommodation", "spot", or "service".
### Issue: Booking Not Auto-Filling
**Solution:** Ensure the booking has associated client, company, and workspace records.
### Issue: Invoice Number Not Generating
**Solution:** The `generateInvoiceNumber()` method in the Invoice model must be accessible. Check model boot method.
## Future Enhancements
Potential improvements:
1. **Auto-populate items from booking** - Add button to automatically add all booking items
2. **Product search** - Quick search for products to add as items
3. **Templates** - Save and reuse common invoice configurations
4. **Bulk actions** - Add multiple items at once
5. **PDF preview** - Preview invoice before saving
6. **Email preview** - Preview email before sending
7. **Payment recording** - Quick payment entry modal
8. **Credit note wizard** - Guided credit note creation from original invoice
## Summary
The enhanced invoice form provides:
- ✅ **4 organized tabs** for logical data entry
- ✅ **Auto-fill functionality** from bookings and clients
- ✅ **Live calculations** for item totals
- ✅ **Conditional fields** based on item category
- ✅ **Full category support** for all booking types
- ✅ **Duration tracking** for time-based items
- ✅ **Payment tracking** with status and method
- ✅ **Fiscal integration** fields ready
- ✅ **Flexible item management** with repeater
- ✅ **Professional layout** with sections and descriptions