ReturnSellBill Documentation

Return Sell Bill Controller Documentation

File: /controllers/returnSellBillController.php

Purpose: Manages sales return operations, customer refunds, and inventory restoration for returned goods

Last Updated: December 19, 2024

Total Functions: 47

Lines of Code: 2,994

---

📋 Overview

The Return Sell Bill Controller handles all operations related to customers returning sold goods. It manages:

Primary Functions

Related Controllers

---

🗄️ Database Tables

Primary Tables (Direct Operations)

Table NamePurposeKey Columns
**returnsellbill**Main return billsreturnsellbillid, returnsellbillserial, returnsellbilldate, returnsellbilltotalbill, returnsellbillclientid, returnsellbillstoreid
**returnsellbilldetail**Return bill line itemsreturnsellbilldetailid, returnsellbillid, returnsellbilldetailproductid, returnsellbilldetailquantity, returnsellbilldetailprice
**returnsellbillcurr**Multi-currency returnsreturnsellbillcurrid, returnsellbillid, returnsellbillcurrencyid, returnsellbillexchangerate
### Inventory Tables (Updated)

Table NamePurposeRelationship
**storedetail**Stock quantities by storeIncreased on returns
**sizecolorstoredetail**Stock by size/color variantsFor variant products
**storereport**Stock movement historyAudit trail for returns
**buypriceshistorybook**Purchase cost trackingCost recalculation
**productserial**Serial number trackingFor serialized returns
### Financial Tables

Table NamePurposeRelationship
**client**Client master datareturnsellbill.returnsellbillclientid
**clientdebtchange**Client debt changesCredit adjustment tracking
**save**Cash registers/safesreturnsellbill.returnsellbillsaveid
**savedaily**Daily cash movementsFinancial reconciliation
**dailyentry**Accounting journal entriesAuto-generated from returns
### Reference Tables

Table NamePurposeRelationship
**product**Product master dataForeign key in details
**productunit**Units of measurementreturnsellbilldetail.productunitid
**store**Warehouses/storesreturnsellbill.returnsellbillstoreid
**billname**Bill templates/typesreturnsellbill.billnameid
**billsettings**Bill configurationPer bill type settings
**user**Sales representativesreturnsellbill.userid
---

🔧 Key Functions

1. editprint()

Purpose: Main entry point for creating/editing sales return bills

Called By: Form submission with ?do=editprint

Line: 400

Parameters (via $_POST):

Database Operations:

Business Logic Flow:

┌─────────────────┐
User submits
return form
└─────────┬───────┘
▼
┌─────────────────┐
Validate data
& permissions
└─────────┬───────┘
▼
┌─────────────────┐
Process profit
calculations
└─────────┬───────┘
▼
┌─────────────────┐
Save return
bill header
└─────────┬───────┘
▼
┌─────────────────┐
Process each
returned item
└─────────┬───────┘
▼
┌─────────────────┐
Update client
debt (increase)
└─────────┬───────┘
▼
┌─────────────────┐
Restore store
inventory
└─────────┬───────┘
▼
┌─────────────────┐
Create daily
└─────────────────┘

2. showDetail($returnsellbillId)

Purpose: Display detailed view of a specific sales return bill

Parameters: $returnsellbillId - Return bill ID

Line: 742

Returns: Formatted HTML view with:

3. delete($returnsellbillid, $savePaymentDateWithBillDate)

Purpose: Delete a sales return bill and reverse all its effects

Called By: Form with ?do=delete

Line: 1242

Parameters:

Database Operations:

4. showallajax()

Purpose: Ajax endpoint for DataTables to display returns list

Called By: Ajax request with ?do=showallajax

Line: 2493

Returns: JSON formatted data for DataTables with:

5. increaseProductQuantity($storedetailId, $productquantityBefore, $productChangeAmount, $sizeColorStoreDetailId, $sizeId, $colorId)

Purpose: Increase inventory when products are returned

Line: 1764

Database Operations:

6. quickProfitRow($myproduct, $finalQuantity, $isreturn, $isadd, $prototal, $billDiscountVal, $billTotalBeforeDiscount, $storeId)

Purpose: Calculate profit adjustments for returned items

Line: 2117

Parameters:

Business Logic: Handles complex profit recalculation based on:

7. updateClientDebt($clientid, $clientdebtAfter)

Purpose: Adjust client debt when goods are returned

Line: 1966

Parameters:

8. insertClientdebtchange($clientid, $clientdebtchangebefore, $clientdebtchangeamount, $clientdebtchangetype, $processname, $clientdebtchangemodelid, $clientdebtchangeafter, $tablename, $comment, $totalOperationCost, $dailyentryid, $visa, $visaAccount, $cash)

Purpose: Record client debt change for audit trail

Line: 1981

Parameters include all financial tracking data for comprehensive audit

9. decreaseProductParcodeSerialQuantity($productId, $sizeId, $colorId, $requiredQuantity, $proSerials, $sellbillId, $sellbillclientId, $sellbilldetailid, $sellbilltype, $operation)

Purpose: Handle serial number tracking for returned products

Line: 2800

Business Logic: Complex serial number management including:

10. executeOperation()

Purpose: Execute the complete return operation workflow

Called By: Form with ?do=executeOperation

Line: 1593

Workflow: Orchestrates the entire return process including validation, calculations, and database updates

---

🔄 Business Logic Flow

Sales Return Workflow

┌─────────────────┐
Original
Sales Bill
└─────────┬───────┘
▼
┌─────────────────┐
Customer
Return Request
└─────────┬───────┘
▼
┌─────────────────┐
Select Products
to Return
└─────────┬───────┘
▼
┌─────────────────┐
Create Return
Bill Header
└─────────┬───────┘
▼
┌─────────────────┐
Add Return
Line Items
└─────────┬───────┘
▼
┌─────────────────┐
Calculate
Refund Amount
└─────────┬───────┘
▼
┌─────────────────┐
Update Client
Credit/Debt
└─────────┬───────┘
▼
┌─────────────────┐
Restore Store
Inventory
└─────────┬───────┘
▼
┌─────────────────┐
Handle Serial
Numbers Return
└─────────┬───────┘
▼
┌─────────────────┐
Process Cash
Refund
└─────────┬───────┘
▼
┌─────────────────┐
Create Daily
Entry Record
└─────────┬───────┘
▼
┌─────────────────┐
Generate
Return Receipt
└─────────────────┘

Ajax Data Loading Flow

┌─────────────────┐
User visits
returns page
└─────────┬───────┘
▼
┌─────────────────┐
DataTables
initialization
└─────────┬───────┘
▼
┌─────────────────┐
Ajax request to
showallajax()
└─────────┬───────┘
▼
┌─────────────────┐
Query database
with filters
└─────────┬───────┘
▼
┌─────────────────┐
Format JSON
response
└─────────┬───────┘
▼
┌─────────────────┐
Render table
with data
└─────────────────┘

Files Involved:

---

⚠️ Common Issues

Issue 1: Profit Calculation Complexity

Problem: Complex profit recalculations when returns affect inventory costs

Cause: Multiple inventory evaluation methods and discount allocations

Fix: Proper handling in quickProfitRow() function

Line: 2117

Issue 2: Serial Number Management

Problem: Tracking serial numbers across returns and re-sales

Cause: Complex barcode and serial number relationships

Fix: Comprehensive serial tracking in decreaseProductParcodeSerialQuantity()

Line: 2800

Issue 3: Multi-Currency Returns

Problem: Exchange rate fluctuations affecting return amounts

Cause: Currency conversion complexity

Fix: Proper exchange rate handling and currency table updates

Issue 4: Ajax DataTables Performance

Problem: Large datasets causing slow page loads

Cause: Unoptimized database queries

Fix: Proper indexing and query optimization in showallajax()

---

🔗 Dependencies

Includes 

include("../public/impOpreation.php");
include_once("../public/config.php");
include_once("dailyentryfun.php");
include("../public/include_dao.php");

Required DAOs

Related Views

JavaScript Files

---

🎯 URL Routes & Actions

Action (`?do=`)MethodDescriptionView Template
showGETDisplay returns listreturnsellbill_show.html
editprintPOSTCreate/edit return billreturnsellbill_add.html
showDetailGETShow return bill detailsreturnsellbill_details.html
deletePOSTDelete return bill-
executeOperationPOSTExecute return workflow-
showallajaxAJAXDataTables data sourceJSON response
delLaterNakdiPayedPOSTDelete later payments-
editsellBillGETEdit related sell billsellbill_edit.html
updateReservationPOSTUpdate reservations-
---

🔐 Permissions & Security

Required Permissions

Security Checks 

include_once("../public/authentication.php");
include_once("initiateStaticSessionCommingWithCurl.php");

CURL Protection 

if ($do != "showallajax" && (!isset($_POST['curlpost']) || empty($_POST['curlpost']))) {
    include("../public/impOpreation.php");
}

---

📝 Notes

Important Considerations

Future Improvements

---

📚 Related Documentation