Client Paid Debt Sell Bills Controller Documentation

File: /controllers/clientPayedDeptSellBillsController.php

Purpose: Manages debt payment tracking for sales bills and return sales bills with comprehensive payment analysis

Last Updated: December 20, 2024

Total Functions: 8 main actions + print functionality

Lines of Code: ~649

---

📋 Overview

The Client Paid Debt Sell Bills Controller is a specialized payment tracking system for sales transactions. It handles both regular sales bills (sellbill) and return sales bills (returnsellbill), providing detailed debt management, payment history, and receipt printing capabilities.

Primary Functions

• ✅ Sales bill debt tracking and payment monitoring
• ✅ Return sales bill payment tracking (credit/refund management)
• ✅ Outstanding debt calculation for sales transactions
• ✅ Comprehensive payment history with drill-down details
• ✅ Date range filtering and client-specific analysis
• ✅ Receipt printing for payment confirmations
• ✅ Dual operation support (sales and returns in single interface)
• ✅ Arabic text conversion for printed amounts

Related Controllers

• • sellbillController.php - Sales bill creation and management
• • returnsellbillController.php - Return sales bill management
• • clientReportsController.php - Comprehensive client reports
• • clientPayedDeptController.php - General debt payment processing

---

🗄️ Database Tables

Primary Tables (Direct Operations)

🔑 Key Functions

1. Default Action (empty $do) - Outstanding Sales Bills

Location: Lines 115-207

Purpose: Display sales bills with outstanding debt balances

Function Signature:

// Parameters: client, from, to, bill_no, obgyBillType
$client = $_POST['client'];
$bill_no = $_REQUEST['bill_no'];
$start_date = $_REQUEST['from'];
$end_date = $_REQUEST['to'];
$obgyBillType = (int) $_POST['obgyBillType'];

Process Flow:

1. Build dynamic SQL query with filters

2. Query sellbill table with conditions = 0 (active bills)

3. Batch load related data (users, clients, payments)

4. Calculate outstanding debt per bill

5. Filter bills with waitvalue > 0

Key SQL Query:

SELECT sellbillid,sellbilldate,pricetype,sellbilltotalpayed,sellbillfinalbill,
       sellbillaftertotalbill,conditions,userid,sellbillclientid
FROM sellbill WHERE conditions = 0 AND [filters]
ORDER BY sellbilldate DESC, sellbillid DESC

Debt Calculation:

$waitvalue = $value['sellbillfinalbill'] - $client_dept_change_amount;
if ($waitvalue > 0) {
    // Include in outstanding bills
}

---

2. show - Paid Sales Bills Summary

Location: Lines 208-290

Purpose: Show summary of sales bills that have received payments

Process Flow:

1. Query clientdebtchange for bills with payments

2. Filter by tablename = "clientPayedDeptSellBillsController.php"

3. Load corresponding bill details

4. Calculate totals across all paid bills

Payment Aggregation:

SELECT billid, sum(clientdebtchangeamount) as clientdebtchangeamount 
FROM clientdebtchange 
WHERE billid IN([bill_ids]) AND tablename = 'clientPayedDeptSellBillsController.php'
GROUP BY billid

---

3. show_details / editprint / details - Payment History Details

Location: Lines 291-355

Purpose: Detailed payment breakdown for a specific sales bill

Features:

• • Complete payment timeline with dates
• • Running balance calculations
• • User information for each payment
• • Daily entry ID tracking for audit trails
• • Payment type classification

Running Balance Logic:

if ($x == 1) {
    $wait_before = $waitvalue;
    $wait_aftre = $wait_before - $clientdebtchangeamount;
} else {
    $wait_before = $wait_aftre;
    $wait_aftre = $wait_before - $clientdebtchangeamount;
}

---

4. ret - Outstanding Return Bills

Location: Lines 358-449

Purpose: Track return sales bills with outstanding credit/refund amounts

Key Differences from Sales Bills:

• • Uses returnsellbill table
• • Debt calculation: waitvalue + payment_amount (credits increase debt)
• • Filter by tablename = "clientPayedDeptReturnSellBillsController.php"
• • Different business logic for credit management

---

5. showret - Paid Return Bills Summary

Location: Lines 450-534

Purpose: Summary of return bills with processed payments/credits

---

6. show_details_ret / editprintret / detailsret - Return Payment Details

Location: Lines 535-599

Purpose: Detailed payment/credit history for return bills

Return Balance Calculation:

// For returns, payments increase the debt (credits to customer)
$wait_aftre = $wait_before + $clientdebtchangeamount;

---

7. print - Payment Receipt Printing

Location: Lines 603-644

Purpose: Generate printable payment receipts

Features:

• • Arabic number-to-text conversion for amounts
• • Support for both sales (type=0) and return (type=1) bills
• • Special handling for cash customers (laterNakdiClientId)
• • Currency formatting from program settings

Arabic Text Conversion:

$ar_number = new convert_ar($totalpaid, "male");
$totalWritten = $ar_number->convert_number();
$totalWritten .= ' ' . $Programsettingdata->currancy . ' فقط لاغير';

---

🔄 Workflows

Workflow 1: Outstanding Sales Bills Analysis

---

🌐 URL Routes & Actions

Outstanding Sales Bills (default):

• • client - Customer ID (optional, -1 for all)
• • from - Start date (YYYY-MM-DD, optional)
• • to - End date (YYYY-MM-DD, optional)
• • bill_no - Bill ID for exact match (optional)
• • obgyBillType - Bill type filter (optional)

Payment Receipt (do=print):

• • bill - Bill ID (required)
• • type - Bill type (0=sales, 1=return, required)
• • m - Payment amount (required)

---

🧮 Calculation Methods

Outstanding Debt for Sales Bills

// Final bill amount minus total payments made
$waitvalue = $sellbillfinalbill - $client_dept_change_amount;

// Total payments = bill payments + additional debt payments  
$total_payed = $sellbilltotalpayed + $client_dept_change_amount;

Outstanding Credit for Return Bills

// For returns, payments increase the outstanding amount (credit owed)
$waitvalue = $sellbillfinalbill + $client_dept_change_amount;

Payment Receipt Totals

// Convert numeric amount to Arabic text
$ar_number = new convert_ar($totalpaid, "male");
$totalWritten = $ar_number->convert_number() . ' ' . $currency . ' فقط لاغير';

---

🔒 Security & Permissions

Authentication

• • All actions require authentication via include_once("../public/authentication.php")
• • Session validation before database operations

Payment Tracking Security

• • Payments linked by tablename to prevent cross-controller contamination
• • Daily entry ID tracking for audit trails
• • User ID logging for payment accountability

---

📊 Performance Considerations

Optimized Query Strategy

1. Batch Loading: Single queries for users, clients, and payments instead of N+1 queries

2. Indexed Filtering: Efficient WHERE clauses with proper indexing

3. Array Optimization: Custom indexing functions (customArrayIndexOne)

Required Indexes:

• • sellbill(sellbillclientid, sellbilldate, conditions)
• • returnsellbill(returnsellbillclientid, returnsellbilldate, conditions)
• • clientdebtchange(billid, tablename)

---

🐛 Common Issues & Troubleshooting

1. Incorrect Payment Totals

Issue: Payment amounts don't match expected values

Cause: Mixed tablename values in clientdebtchange

Fix: Ensure proper tablename filtering:

-- Check payments for specific controller
SELECT * FROM clientdebtchange 
WHERE billid = [BILL_ID] 
AND tablename = 'clientPayedDeptSellBillsController.php';

2. Missing Bills in Outstanding Report

Issue: Bills with debt not appearing

Cause: conditions flag not properly filtered

Debug:

-- Check bill conditions
SELECT sellbillid, conditions, sellbillfinalbill 
FROM sellbill 
WHERE sellbillid = [BILL_ID];

---

🧪 Testing Scenarios

Test Case 1: Outstanding Debt Accuracy

1. Create sales bill with partial payment
2. Verify correct outstanding amount calculation  
3. Make additional payment via debt system
4. Confirm updated outstanding balance
5. Check bill removal when fully paid

Test Case 2: Return Bill Credit Tracking

1. Create return bill with partial refund
2. Verify credit amount calculation (addition logic)
3. Process additional credit payment
4. Confirm updated credit balance

Test Case 3: Receipt Printing

1. Select bill with payment
2. Generate receipt with Arabic text conversion
3. Verify currency formatting
4. Check client name handling for cash customers

---

📚 Related Documentation

• • CLAUDE.md - PHP 8.2 migration guide
• • sellbillController.md - Sales bill management
• • clientReportsController.md - Client reporting system

---

Documented By: AI Assistant

Review Status: ✅ Complete

Next Review: When major changes occur