# Sales Module Analysis

## Module Overview
The Sales module is a comprehensive customer relationship and order management system that handles customer management, quotations, sales orders, invoices, and recurring subscriptions. It integrates with the Inventory module for delivery order tracking and fulfillment.

## Module Structure

```
Modules/Sales/
├── Actions/
│   ├── GenerateCustomerCodeAction.php
│   ├── GenerateProductCodeAction.php
│   ├── DeleteSalesOrder.php
│   ├── DeleteSubscription.php
│   ├── StoreOrUpdateSubscriptionAction.php
│   ├── StoreSalesOrderAction.php
│   ├── UpdateSalesOrderAction.php
│   ├── Invoice/
│   └── Quotation/
├── Constants/
│   └── InvoiceStatus.php
├── Entities/
│   ├── Customer.php
│   ├── Quotation.php
│   ├── QuotationItem.php
│   ├── QuotationAdjust.php
│   ├── SalesOrder.php
│   ├── SalesOrderDetail.php
│   ├── SalesOrderLog.php
│   ├── Invoice.php
│   ├── InvoiceDetail.php
│   ├── InvoiceAdjust.php
│   ├── InvoicePayment.php
│   ├── InvoiceLog.php
│   ├── Subscription.php
│   ├── SubscriptionDetail.php
│   ├── Product.php
│   └── Service.php
├── Http/
│   ├── Controllers/
│   │   ├── SalesController.php
│   │   ├── CustomerController.php
│   │   ├── ProductController.php
│   │   ├── QuotationController.php
│   │   ├── SalesOrderController.php
│   │   ├── InvoiceController.php
│   │   ├── SubscriptionController.php
│   │   └── API/
│   ├── Requests/V1/
│   └── Resources/V1/
├── Transformers/
│   ├── SalesOrderResource.php
│   ├── QuotationResource.php
│   ├── SubscriptionResource.php
│   └── MarketingResource.php
├── Routes/
│   ├── web.php
│   ├── api.php
│   ├── mobile.php
│   └── public.php
├── Database/
│   └── Migrations/
├── Tests/
├── Providers/
│   ├── RouteServiceProvider.php
│   └── SalesServiceProvider.php
└── Config/config.php
```

## Entity Relationships Diagram

```mermaid
erDiagram
    CUSTOMER ||--o{ QUOTATION : requests
    CUSTOMER ||--o{ SALES-ORDER : places
    CUSTOMER ||--o{ SUBSCRIPTION : subscribes
    CUSTOMER ||--o{ INVOICE : receives
    CUSTOMER }o--|| PROVINCE : "billing_province"
    CUSTOMER }o--|| CITY : "billing_city"
    CUSTOMER }o--|| PROVINCE : "shipping_province"
    CUSTOMER }o--|| CITY : "shipping_city"

    QUOTATION ||--o{ QUOTATION-ITEM : contains
    QUOTATION ||--o{ QUOTATION-ADJUST : adjustments
    QUOTATION }o--|| CUSTOMER : "from"

    SALES-ORDER ||--o{ SALES-ORDER-DETAIL : contains
    SALES-ORDER }o--|| QUOTATION : "references"
    SALES-ORDER }o--|| CUSTOMER : "to"
    SALES-ORDER }o--|| STATUS : "status_id"
    SALES-ORDER }o--|| TAX : "tax_id"
    SALES-ORDER ||--o{ INVOICE : "so_number"
    SALES-ORDER ||--o{ DELIVERY-ORDER : "sales_order_id"
    SALES-ORDER ||--o{ SALES-ORDER-LOG : logs

    SALES-ORDER-DETAIL }o--|| SALES-ORDER : "in"
    SALES-ORDER-DETAIL }o--|| PRODUCT : "product_id"

    INVOICE ||--o{ INVOICE-DETAIL : contains
    INVOICE ||--o{ INVOICE-ADJUST : adjustments
    INVOICE ||--o{ INVOICE-PAYMENT : payments
    INVOICE ||--o{ INVOICE-LOG : logs
    INVOICE }o--|| CUSTOMER : "from"
    INVOICE }o--|| SALES-ORDER : "so_number"
    INVOICE }o--|| SUBSCRIPTION : "subscription_id"
    INVOICE }o--|| STATUS : "status_id"

    INVOICE-DETAIL }o--|| INVOICE : "in"
    INVOICE-DETAIL }o--|| PRODUCT : "product_id"

    INVOICE-PAYMENT }o--|| INVOICE : "in"

    SUBSCRIPTION ||--o{ SUBSCRIPTION-DETAIL : contains
    SUBSCRIPTION }o--|| CUSTOMER : "customer_id"
    SUBSCRIPTION }o--|| SERVICE : "service_id"
    SUBSCRIPTION ||--o{ INVOICE : "generates"

    SUBSCRIPTION-DETAIL }o--|| SUBSCRIPTION : "in"
    SUBSCRIPTION-DETAIL }o--|| SERVICE : "service_id"

    QUOTATION-ITEM }o--|| QUOTATION : "in"
    QUOTATION-ITEM }o--|| PRODUCT : "product_id"

    QUOTATION-ADJUST }o--|| QUOTATION : "in"

    INVOICE-ADJUST }o--|| INVOICE : "in"

    DELIVERY-ORDER }o--|| SALES-ORDER : "from"
    DELIVERY-ORDER }o--|| CUSTOMER : "to"

    PRODUCT }o--|| SERVICE : "from"
    SERVICE }o--|| CUSTOMER : "to"

    SALES-ORDER-LOG }o--|| SALES-ORDER : "logs"
    INVOICE-LOG }o--|| INVOICE : "logs"
```

## Core Workflows

### 1. Quotation Workflow
```
Customer Inquiry → Create Quotation → Add Quote Items → Add Adjustments → 
Customize Terms → Send to Customer → Customer Review → Convert to SO
```

### 2. Sales Order Workflow
```
Create SO (from Quotation or Manual) → Add SO Details → Customize Terms/Notes → 
Submit → Approve → Create DO → Delivery → Create Invoice
```

### 3. Invoice Workflow
```
SO Created → Generate Invoice (Auto or Manual) → Add Invoice Details → 
Add Adjustments (if needed) → Submit → Approve → Payment Processing
```

### 4. Subscription Workflow
```
Customer Request → Create Subscription → Add Services → Setup Schedule → 
Auto-generate Invoices on Schedule → Track Payments → Renewal Management
```

### 5. Delivery Order Workflow
```
SO Approved → Create Delivery Order → Pick/Pack Items → 
Ship to Customer → Delivery Confirmed → Trigger Invoice Creation
```

## Key Entities Description

| Entity | Purpose | Key Fields |
|--------|---------|-----------|
| **Customer** | Customer information & accounts | customer_code, name, email, contact, address |
| **Quotation** | Sales proposal to customer | quotation_number, quotation_date, customer_id, total |
| **QuotationItem** | Line items in quotation | product_id, quantity, unit_price, discount |
| **SalesOrder** | Confirmed sales order | so_number, so_date, etd_date, customer_id, total |
| **SalesOrderDetail** | Line items in sales order | product_id, quantity, unit_price, tax |
| **Invoice** | Customer invoice/bill | invoice_number, invoice_date, due_date, total_amount |
| **InvoiceDetail** | Line items in invoice | product_id, quantity, unit_price |
| **InvoicePayment** | Payment records | payment_date, amount, payment_method |
| **Subscription** | Recurring service agreement | subscription_code, service_id, start_date, end_date |
| **SubscriptionDetail** | Service items in subscription | service_id, quantity, billing_frequency |
| **DeliveryOrder** | Shipment records | sales_order_id, delivery_date, status |
| **Product** | Sellable products | product_code, name, price, category |
| **Service** | Billable services | service_code, name, base_price |

## Controllers

| Controller | Responsibilities |
|------------|------------------|
| **SalesController** | Main sales module entry point |
| **CustomerController** | Customer management, profiles, contact info |
| **ProductController** | Product catalog management |
| **QuotationController** | Quotation creation, editing, conversion to SO |
| **SalesOrderController** | SO creation, approval, modification, document generation |
| **InvoiceController** | Invoice management, payment tracking, adjustments |
| **SubscriptionController** | Subscription management, renewal, billing automation |

## Integration Points

- **Inventory Module**: DeliveryOrder for shipment tracking and fulfillment
- **Accounting Module**: Invoice entries linked to accounting via Account references
- **Core App**: User, Status, Tax, Location (Province, City), Service
- **Marketing Module**: Campaign tracking and marketing resource references

## Action Classes

- **GenerateCustomerCodeAction**: Auto-generates unique customer codes
- **GenerateProductCodeAction**: Auto-generates product codes
- **StoreSalesOrderAction**: Creates new sales orders with validation
- **UpdateSalesOrderAction**: Updates SO with business logic
- **DeleteSalesOrder**: Soft delete with cascading actions
- **StoreOrUpdateSubscriptionAction**: Creates/updates subscriptions
- **DeleteSubscription**: Handles subscription deletion
- **Invoice/Actions**: Invoice operations (create, duplicate, email, etc.)
- **Quotation/Actions**: Quotation operations (convert to SO, etc.)

## Resource Transformers

- **SalesOrderResource**: Formats SO data for API responses
- **QuotationResource**: Formats quotation data for API responses
- **SubscriptionResource**: Formats subscription data for API responses
- **MarketingResource**: Marketing campaign/tracking data

## Status Flow

```
Quotation: Draft → Sent → Approved → Rejected → Converted to SO
Sales Order: Draft → Submitted → Approved → Ready to Deliver → Delivered → Invoiced → Closed
Invoice: Draft → Submitted → Approved → Partially Paid → Paid → Archived
Subscription: Draft → Active → Paused → Renewing → Ended → Archived
Delivery Order: Draft → Shipped → In Transit → Delivered
```

## Key Features

1. **Multi-stage Sales Process**: Quotation → SO → Delivery → Invoice
2. **Customer Management**: Complete customer database with multi-location support
3. **Flexible Quotations**: Customizable quotes with items and adjustments
4. **Automated Order Processing**: Convert quotes to orders, auto-generate invoices
5. **Invoice Management**: Payment tracking, adjustments, and payment history
6. **Recurring Billing**: Subscription support with automatic invoice generation
7. **Delivery Tracking**: Integration with inventory for order fulfillment
8. **Document Generation**: PDF export for Quotations, Sales Orders, and Invoices
9. **Audit Trail**: Logging of all transaction changes and approvals
10. **Flexible Pricing**: Support for discounts, adjustments, and tax calculations
11. **Tax Management**: Multiple tax rates and formats
12. **Multi-location Customers**: Billing and shipping address support

## Data Flow

```
Customer → Quotation → SalesOrder → DeliveryOrder → Invoice → Payment
                 ↓
         (Auto-convert)
```

## Business Rules

1. **Quotation Conversion**: Can be converted to a single or multiple Sales Orders
2. **Sales Order to Invoice**: One SO can generate one or more invoices
3. **Subscription Billing**: Automatically generates invoices on configured schedule
4. **Payment Tracking**: Multiple payments can be recorded per invoice
5. **Tax Calculation**: Applied at line item and document level
6. **Discount Handling**: Support for percentage and fixed amount discounts
7. **Order Status Progression**: Validates status transitions (prevents invalid state changes)
8. **Soft Deletes**: All transactions support soft delete for audit compliance

## API Endpoints

- **Customers**: CRUD operations, search, bulk operations
- **Quotations**: Create, list, show, update, delete, convert to SO
- **Sales Orders**: CRUD, approve, modify, generate PDF, shipment tracking
- **Invoices**: Create, list, show, update, payment recording, adjustments
- **Subscriptions**: CRUD, renewal, billing schedule management
- **Delivery Orders**: Track shipments, confirm delivery

## Performance Considerations

- Invoice number generation uses sequence optimization
- Relationships use eager loading where appropriate
- Soft deletes maintain data integrity
- Indexed foreign keys for fast lookups
- Tax and discount calculations cached at invoice level