# Water Billing System - Quick Start Guide

## Initial Setup Instructions

### Step 1: Database Configuration
Edit `.env` file with your database credentials:
```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=water_billing
DB_USERNAME=root
DB_PASSWORD=
```

### Step 2: Run Migrations
```bash
cd /var/www/html/billing.happyimart.com
php artisan migrate
```

### Step 3: Create Admin User
```bash
php artisan tinker
```

Then in the tinker shell:
```php
App\Models\User::create([
    'name' => 'Admin',
    'email' => 'admin@example.com',
    'password' => Hash::make('password'),
    'tenant_id' => 1,
]);
```

### Step 4: Create Tenant
```php
$tenant = App\Models\Tenant::create([
    'name' => 'Your Property/Company Name',
    'slug' => 'your-property',
    'domain' => 'billing.happyimart.com',
]);

App\Models\Setting::create([
    'tenant_id' => $tenant->id,
    'app_name' => 'Your Property Name',
    'app_email' => 'billing@your-property.com',
    'app_phone' => '63-9XX-XXX-XXXX',
    'app_address' => 'Your Address',
    'currency' => 'PHP',
    'timezone' => 'Asia/Manila',
]);
```

### Step 5: Create Pricing Tiers
```php
$tenant = App\Models\Tenant::first();

// Tier 1: 0-10 cu.m @ 50/unit
$tenant->tiers()->create([
    'name' => 'Basic (0-10 cu.m)',
    'price_per_unit' => 50.00,
    'min_units' => 0,
    'max_units' => 10,
    'order' => 1,
    'is_active' => true,
]);

// Tier 2: 11-20 cu.m @ 60/unit
$tenant->tiers()->create([
    'name' => 'Standard (11-20 cu.m)',
    'price_per_unit' => 60.00,
    'min_units' => 11,
    'max_units' => 20,
    'order' => 2,
    'is_active' => true,
]);

// Tier 3: 21+ cu.m @ 75/unit
$tenant->tiers()->create([
    'name' => 'Premium (21+ cu.m)',
    'price_per_unit' => 75.00,
    'min_units' => 21,
    'max_units' => null,
    'order' => 3,
    'is_active' => true,
]);
```

## User Interface Walkthrough

### Dashboard
- Overview of key metrics
- Recent activities
- Quick actions

### Clients Management
1. **Add Client**: Click "Add New Client" to create a new water subscriber
2. **View Clients**: See all clients with their outstanding balances
3. **Edit Client**: Update client information
4. **Client Details**: View client's billing and payment history

### Meter Readings
1. **Record Reading**: Submit new water meter readings
2. **Review Readings**: See pending, approved, and rejected readings
3. **Approve Reading**: Review and approve readings to auto-generate billings
4. **View Details**: See calculation details for each reading

### Billings
1. **View Billings**: See all billing statements
2. **Edit Billing**: Adjust taxes, charges, and penalties
3. **Print PDF**: Generate standard PDF billing statement
4. **Print Thermal**: Generate thermal printer format for POS
5. **Send Billing**: Mark billing as sent to customer
6. **Track Payments**: View payment history for each billing

### Settings
1. **Application Settings**: Set company name, email, phone
2. **SMS Gateway**: Configure Twilio or Nexmo for notifications
3. **Payment Gateway**: Setup Stripe or PayPal integration
4. **Currency & Timezone**: Configure locale settings

## Workflow Example

1. **Add a Client**
   - Go to Clients > Add New Client
   - Fill in customer details
   - System generates Account Number and Meter Number fields

2. **Record Meter Reading**
   - Go to Meter Readings > Record Reading
   - Select client
   - Enter current meter reading
   - Submit

3. **Approve Reading & Generate Billing**
   - Go to Meter Readings
   - Find the submitted reading
   - Click View Details
   - Review the reading
   - Click "Approve & Generate Billing"

4. **Billing Generated**
   - Billing automatically created based on pricing tiers
   - All calculations done automatically
   - View in Billings section

5. **Print or Send Billing**
   - Go to Billings
   - Click on billing to view details
   - Print PDF for normal paper
   - Print Thermal for POS thermal printer
   - Use SMS/Email integration to send to customer (future feature)

6. **Record Payment**
   - Track payments against billings
   - Update outstanding balance automatically

## API Usage for Mobile App

### Get Client Info
```bash
curl -X POST https://billing.happyimart.com/api/v1/meter-reading/client-details \
  -H "X-Tenant: your-property" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your-api-key",
    "account_number": "ACC-1-000001"
  }'
```

### Submit Meter Reading
```bash
curl -X POST https://billing.happyimart.com/api/v1/meter-reading/submit \
  -H "X-Tenant: your-property" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your-api-key",
    "account_number": "ACC-1-000001",
    "reading_value": 1234.56,
    "recorded_by": "John Doe"
  }'
```

### Get Billing History
```bash
curl -X GET "https://billing.happyimart.com/api/v1/billings?api_key=xxx&account_number=ACC-1-000001" \
  -H "X-Tenant: your-property"
```

## Important Notes

- **Backups**: Regularly backup your database
- **Security**: Always use HTTPS in production
- **API Keys**: Keep API keys secure, never expose in frontend
- **Passwords**: Use strong passwords for admin accounts
- **Updates**: Keep Laravel and dependencies updated

## Support & Troubleshooting

### Common Issues

**Migrations Failed**
```bash
php artisan migrate:reset
php artisan migrate
```

**Permission Errors**
```bash
chmod -R 775 storage bootstrap/cache
```

**Assets Not Loading**
```bash
npm install
npm run build
```

**Clear Cache**
```bash
php artisan cache:clear
php artisan config:clear
php artisan view:clear
```

## Default Ports

- Web Application: http://localhost:8000
- MySQL: localhost:3306

## File Locations

- Views: `resources/views/`
- Controllers: `app/Http/Controllers/`
- Models: `app/Models/`
- Database: `database/migrations/`
- Configuration: `config/`
- Routes: `routes/web.php` and `routes/api.php`

---

For more details, see `SYSTEM_DOCUMENTATION.md`