# New Subscriber Application System - Complete Guide

## Overview
The new subscriber application system is a 6-step workflow for onboarding new water service customers. This system automates the entire process from initial application through installation and activation.

---

## System Architecture

### Models
- **Application** - Tracks the complete application lifecycle
- **Client** - Created after payment (Step 4)
- **Setting** - Company settings including setup fee configuration

### Workflow Status
1. `submitted` - Initial application submission
2. `approved` - Approved by company admin (Step 2)
3. `payment_pending` - Awaiting payment (Step 3)
4. `payment_completed` - Payment processed (Step 3)
5. `meter_assigned` - Meter assigned and client created (Step 4)
6. `installation_pending` - Installation scheduled (Step 5)
7. `installation_completed` - Installation completed by installer
8. `active` - Customer fully activated
9. `rejected` - Application rejected

---

## Step-by-Step Implementation

### **STEP 1: Customer Data Encoding**
**Route:** `GET /applications/create`
**Controller Method:** `ApplicationController@create`

**What Happens:**
- New subscriber fills out application form
- Captures: Name, Email, Phone, Complete Address, Meter Location, Property Description
- Application status: `submitted`
- Activity Log: Created with "New subscriber application submitted"

**Form Fields:**
- First Name, Last Name (required)
- Email, Phone (required)
- Street Address, Barangay, City, Province, Zip Code (required)
- Meter Location, Property Description (optional)

**Validation:**
- All required fields must be filled
- Email must be valid
- Phone must be 20 characters max

---

### **STEP 2: Approval Process**
**Route:** `GET|POST /applications/{application}/approve`
**Controller Methods:** `showApproval`, `approve`

**Permissions:**
- Only Company Admin and Super Admin can approve
- Company Admin can only approve for their company

**What Happens:**
- Company admin reviews applicant information
- Can add approval notes
- Can override setup fee (or use company default)
- Application status: `submitted` → `payment_pending`
- Activity Log: "Application approved for {name}"

**Form Fields:**
- Approval Notes (optional)
- Setup Fee (optional - defaults to company setting)

**Company Settings:**
- Setup fee configured in Company Settings → Billing Settings → New Connection Setup Fee
- Default fee applies if not specified during approval
- Can be overridden per application

---

### **STEP 3: Payment Processing**
**Route:** `GET|POST /applications/{application}/payment`
**Controller Methods:** `showPayment`, `processPayment`

**What Happens:**
- Payment details recorded (method, reference #, date)
- Application status: `payment_pending` → `payment_completed`
- Activity Log: "Payment of ₱X.XX processed for {name}"

**Payment Methods:**
- Cash
- Check
- Bank Transfer
- Online Payment

**Form Fields:**
- Payment Method (required)
- Reference Number (optional - check #, transaction ID)
- Payment Date (required)

---

### **STEP 4: Meter Assignment & Tier Connection**
**Route:** `GET|POST /applications/{application}/meter`
**Controller Methods:** `showMeter`, `assignMeter`

**What Happens:**
1. Meter number is assigned (must be unique)
2. Service tier is selected
3. **Client account is automatically created** with:
   - Account Number (auto-generated: ACC-{company_id}-{sequence})
   - Applicant information
   - Assigned meter number
   - Service tier
   - Status: `active`
4. Application status: `payment_completed` → `meter_assigned`
5. Activity Log: "Meter #{meter_number} assigned and client created"

**Form Fields:**
- Meter Number (required, must be unique)
- Service Tier (required)

**Client Auto-Generation:**
- Account Number: `ACC-{company_id}-{00001}`
- Name: Full name from application
- Email, Phone: From application
- Address: Complete address from application
- Meter Number: Assigned in this step
- Tier Group: Selected service tier
- Status: `active`
- Registered Date: Current timestamp

---

### **STEP 5: Installation Scheduling**
**Route:** `GET|POST /applications/{application}/installation`
**Controller Methods:** `showInstallation`, `scheduleInstallation`

**What Happens:**
1. Installer assigned from company staff
2. Installation scheduled for future date
3. Application status: `meter_assigned` → `installation_pending`
4. Activity Log: "Installation scheduled for {name}"

**Form Fields:**
- Assigned Installer (required)
- Installation Scheduled Date (required)

**Installer List:**
- Only users with "installer" or "company_admin" roles
- From same company

---

### **STEP 5B: Installation Document Generation**
**Route:** `GET /applications/{application}/installation-document`
**Controller Method:** `generateInstallationDocument`

**What Happens:**
- PDF document generated with:
  - Customer information
  - Meter number
  - Property details
  - Installation checklist
  - Signature fields
- Saves document path in database
- Installer can print and take to site

**Document Includes:**
- Customer name, contact, address
- Account number
- Meter number and location
- Service tier
- Scheduled installation date
- Installer name
- Installation checklist (8 items)
- Signature section for installer and customer

---

### **STEP 6: Installation Completion Report**
**Route:** `POST /applications/{application}/complete-installation`
**Controller Method:** `completeInstallation`

**What Happens:**
1. Installer marks installation as completed/failed
2. Can add completion notes
3. Application status:
   - `installation_pending` → `active` (if completed)
   - `installation_pending` → `installation_completed` (if failed)
4. Activity Log: "Installation {completed/failed} for {name}"

**Form Fields:**
- Installation Status (required): completed or failed
- Installation Notes (optional)

---

## Dashboard Widgets

### Company Admin Dashboard
New widgets added for tracking new subscriber applications:

**KPI Cards:**
- Total Applications
- New Applications (submitted)
- Payment Pending Applications
- Installation Pending Applications

**Recent Applications Table:**
- Shows last 5 applications
- Displays: Applicant Name, Email/Phone, Status, Applied Date
- Quick action link to view details

**View All Link:**
- Button to navigate to applications list

---

## Routes Summary

```
GET     /applications                          - List all applications
GET     /applications/create                   - Create new application form
POST    /applications                          - Store new application
GET     /applications/{application}            - View application details
GET     /applications/{application}/approve    - Approval form
POST    /applications/{application}/approve    - Process approval
GET     /applications/{application}/payment    - Payment form
POST    /applications/{application}/payment    - Process payment
GET     /applications/{application}/meter      - Meter assignment form
POST    /applications/{application}/meter      - Assign meter & create client
GET     /applications/{application}/installation - Installation form
POST    /applications/{application}/schedule-installation - Schedule installation
GET     /applications/{application}/installation-document - Download PDF
POST    /applications/{application}/complete-installation - Report completion
```

---

## Setup Fee Configuration

### How to Set the Setup Fee

**For Company Admin:**
1. Go to Company Settings (left sidebar)
2. Click "Billing Settings" tab
3. Scroll to "New Connection Setup Fee" section
4. Enter the amount in Philippine Pesos (₱)
5. Click "Save Settings"

**This fee will:**
- Appear as default when approving applications
- Can be overridden per application during approval
- Be charged to customers during payment processing
- Be logged in activity logs

### Multiple Companies
Each company can have different setup fees configured independently in their own settings.

---

## Activity Logging

All application workflow events are automatically logged:

- Application submission
- Application approval
- Payment processing
- Meter assignment and client creation
- Installation scheduling
- Installation completion/failure

View logs at: Activity Logs page (Activity Logs menu item)

---

## Database Schema

### Applications Table
```
id - Primary key
company_id - Foreign key to companies
first_name, last_name - Applicant name
email, phone - Contact information
street_address, barangay, city, province, zip_code - Address
meter_location - Where meter will be placed
property_description - Type/description of property
status - Current workflow status (enum)
approved_by - User ID of approver
approved_at - Approval timestamp
approval_notes - Notes from approval
setup_fee - Fee amount for this application
payment_reference - Reference number for payment
payment_date - When payment was made
meter_number - Assigned meter number
tier_id - Foreign key to tiers
client_id - Foreign key to clients (created in step 4)
assigned_installer - User ID of assigned installer
installation_scheduled_date - Scheduled installation date
installation_completed_date - When installation was done
installation_status - pending|in_progress|completed|failed
installation_notes - Notes about installation
installation_document_path - Path to PDF document
created_at, updated_at - Timestamps
```

### Settings Table Addition
```
new_connection_setup_fee - Decimal field for setup fee (default: 0.00)
```

---

## Authorization & Permissions

### View Application
- Super Admin: Can view all applications
- Company Admin: Can view applications from their company only
- Other roles: Cannot access

### Approve Application
- Super Admin: Can approve any application
- Company Admin: Can only approve applications from their company
- Other roles: Cannot approve

### Full Workflow Access
- Super Admin: Full access to all steps
- Company Admin: Full access for their company
- Company Staff: Limited access (installers can view/report installation)

---

## Best Practices

1. **Set up default setup fee first** in company settings before approving applications
2. **Use unique meter numbers** - system prevents duplicate meter assignments
3. **Assign installers** with active accounts and proper roles
4. **Generate installation documents** before scheduling dates for consistency
5. **Keep installation notes** brief but informative for audit trail
6. **Review activity logs** regularly to track all changes

---

## Troubleshooting

### Application doesn't progress to next step
- Check application status in database
- Verify user has correct permissions
- Check for validation errors in form

### Meter number already exists
- Meter numbers must be unique per company
- Try with a different meter number format

### Setup fee not saving
- Ensure "New Connection Setup Fee" field has a numeric value
- Check that form submission includes all required fields

### PDF document not generating
- Verify DomPDF is installed and working
- Check file permissions for document storage

---

## Future Enhancements

Possible features to add:
- Bulk application imports from CSV
- Email notifications for status changes
- SMS alerts to customers
- Photo upload for property verification
- Geographic mapping for meter locations
- Scheduled batch processing of applications
- Automated email workflow at each step