# CUSTOMER PRICING SYSTEM - IMPLEMENTATION GUIDE

## Overview
This document describes the implementation of a dual pricing system for store owners:
1. **Agent Pricing** (Range-based) - For sub-agents who place orders via dashboard/API
2. **Customer Pricing** (Package-specific) - For regular customers who buy from the store page

---

## What Was Implemented

### 1. Database Table
**File**: `create_store_customer_pricing_table.php`

Creates the `store_customer_pricing` table with:
- `store_id` - Foreign key to stores
- `network_type` - Network (mtn, etc.)
- `package_size_gb` - Package size in GB (e.g., 1.0, 2.0, 5.0)
- `package_label` - Display label (e.g., "1GB", "2GB")
- `price` - Fixed price for this specific package
- `is_active` - Active/inactive flag

**To create the table**, run:
```bash
php create_store_customer_pricing_table.php
```

### 2. Customer Pricing Manager Class
**File**: `app/classes/StoreCustomerPricingManager.php`

Key methods:
- `getStoreCustomerPricing()` - Get all customer pricing for a store
- `getPriceForPackage()` - Get price for a specific package (package-specific lookup)
- `setCustomerPricing()` - Add/update customer pricing
- `deleteCustomerPricing()` - Delete customer pricing
- `getMaxAdminPackageSize()` - Get maximum package size from admin rules

### 3. Customer Pricing Management Page
**File**: `pages/store_customer_pricing.php`

Features:
- View all customer pricing rules
- Add new package-specific prices
- Edit existing prices
- Activate/deactivate pricing
- Validation: Maximum package size based on admin rules

### 4. API Endpoints
- **`pages/add_store_customer_pricing.php`** - Add new customer pricing
- **`pages/update_store_customer_pricing.php`** - Update existing customer pricing

### 5. Updated Order Processing
**Files Updated**:
- `process_store_order.php` - Now uses customer pricing (for regular customers)
- `check_package_availability.php` - Now uses customer pricing (for store page validation)

---

## How It Works

### For Regular Customers (Store Page)
1. Customer visits store page (`store.php`)
2. Selects network and enters package size
3. System checks `store_customer_pricing` table for exact package match
4. Displays price to customer
5. When order is placed (`process_store_order.php`), uses customer pricing

### For Sub-Agents (Dashboard/API)
1. Agent places order via dashboard or API
2. System uses existing `store_pricing` table (range-based)
3. Uses `StorePricingManager::calculatePrice()` method
4. Works exactly as before - no changes needed

---

## Key Differences

| Feature | Agent Pricing | Customer Pricing |
|---------|--------------|------------------|
| **Table** | `store_pricing` | `store_customer_pricing` |
| **Method** | Range-based | Package-specific |
| **Example** | 0.5-2.99GB at GH₵3.50/GB | 1GB = GH₵5.00, 2GB = GH₵10.00 |
| **Manager Class** | `StorePricingManager` | `StoreCustomerPricingManager` |
| **Used By** | Dashboard, API orders | Store page, customer orders |
| **Constraints** | Must match admin ranges | Up to max admin size |

---

## Usage Instructions

### For Store Owners

1. **Set Agent Pricing** (Range-based):
   - Go to: `pages/store_pricing.php`
   - Set price per GB for each admin-defined range
   - Used by sub-agents when placing orders

2. **Set Customer Pricing** (Package-specific):
   - Go to: `pages/store_customer_pricing.php`
   - Add prices for specific packages (e.g., 1GB, 2GB, 5GB)
   - Can set different prices for each package size
   - Used by regular customers on store page

### Example Setup

**Agent Pricing** (Range-based):
- Range 0.5-2.99GB: GH₵3.50/GB
- Range 3-10GB: GH₵3.00/GB
- Range 11-50GB: GH₵2.50/GB

**Customer Pricing** (Package-specific):
- 1GB: GH₵5.00
- 2GB: GH₵10.00
- 5GB: GH₵45.00
- 10GB: GH₵85.00

---

## Files Modified/Created

### New Files
1. `create_store_customer_pricing_table.php` - Table creation script
2. `app/classes/StoreCustomerPricingManager.php` - Customer pricing manager
3. `pages/store_customer_pricing.php` - Customer pricing management UI
4. `pages/add_store_customer_pricing.php` - Add pricing API
5. `pages/update_store_customer_pricing.php` - Update pricing API

### Modified Files
1. `process_store_order.php` - Now uses customer pricing
2. `check_package_availability.php` - Now uses customer pricing
3. `pages/store_pricing.php` - Updated navigation and instructions

---

## Testing Checklist

- [ ] Run `create_store_customer_pricing_table.php` to create table
- [ ] Access customer pricing page as store owner
- [ ] Add customer pricing for different package sizes
- [ ] Edit existing customer pricing
- [ ] Test store page with customer pricing
- [ ] Verify customer orders use customer pricing
- [ ] Verify agent orders still use agent pricing (range-based)
- [ ] Test package availability check with customer pricing

---

## Important Notes

1. **Customer pricing is package-specific**: Each package size has its own price
2. **Agent pricing is range-based**: Price per GB within a range
3. **Maximum package size**: Customer pricing cannot exceed the highest admin-defined range
4. **No overlap**: Customer pricing and agent pricing are completely separate
5. **Store owners can set different prices**: Agents and customers can have different pricing structures

---

## Future Enhancements

Potential improvements:
- Bulk import customer pricing from CSV
- Copy customer pricing from another store
- Price history tracking
- Discount rules for customers
- Package bundles/promotions

---

## Support

If you encounter any issues:
1. Check database table exists: `store_customer_pricing`
2. Verify store owner has access to customer pricing page
3. Check that customer pricing is set for the package size being ordered
4. Verify `StoreCustomerPricingManager` class is loaded correctly

