# Hardware Store Software (Laravel 12) - Phase 1

Branches, users and roles, products with units, per-branch stock and transfers,
sales/POS with khata, purchases with supplier ledger. Urdu and English throughout.

## Install (about 5 minutes)

1. Start from a fresh Laravel 12 project (the one you already downloaded).
   Do this on a new project, because the files below replace a few default ones.
2. Copy everything from this zip into the project folder and choose "replace" when asked.
   Files that replace Laravel defaults:
   - `bootstrap/app.php`
   - `routes/web.php`
   - `app/Models/User.php`
   - `app/Providers/AppServiceProvider.php`
   - `database/seeders/DatabaseSeeder.php`
   - `resources/views/layouts/app.blade.php`, `resources/views/dashboard.blade.php`, `resources/views/auth/login.blade.php`
3. Open `.env` and set:

   ```
   APP_LOCALE=ur
   APP_FALLBACK_LOCALE=en
   APP_TIMEZONE=Asia/Karachi

   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=hardware_store
   DB_USERNAME=root
   DB_PASSWORD=
   ```

   Create an empty database called `hardware_store` first.
4. Run:

   ```
   php artisan migrate --seed
   php artisan serve
   ```
5. Open http://127.0.0.1:8000 and log in:

   - Email: `owner@store.test`
   - Password: `password`

   Change this password straight away (Users > Edit).

`migrate --seed` creates 2 sample branches, units (kg, ton, bori, foot...), a few categories,
3 sample products and 1 sample customer and supplier so the screens are not empty.
Delete them when you are ready to enter real data.

## How it works

- Every product has a base unit (for example kg). Stock is always counted in the base unit.
  Other units are conversions: 1 Bori = 50 Kg, 1 Ton = 1000 Kg. You can sell or buy in any of them.
- Stock is kept per branch. The owner switches branch from the top bar. Everyone else is locked to their own branch.
- A branch transfer takes stock out of the branch you are working in and adds it to the other one.
  Vehicle, transport and loader charges are saved on the transfer.
- A sale to a walk-in customer must be paid in full. Choose a customer to leave udhaar. Their khata
  (bills, payments, running balance) is on the customer page, where you also receive payments.
- Roles: owner (everything), manager (own branch, catalogue and stock), munshi (sales, purchases, khata,
  transfers), salesman (sales and stock view only).

## Updating from the previous zip

Copy this zip over your project (replace), then run `php artisan migrate`. Your data stays. The migrations
add price history, the carrier (transport/loader) tables, and a "settled" amount on bills. Old payments are
applied to old bills (oldest first) by the migration itself.

## Payments and advance

- A payment from a customer (or to a supplier) is applied to the oldest unpaid bill first, then the next one.
  The opening balance counts as the oldest bill. Invoice "Due" in Sales shows what is really left.
- If the payment is more than everything owed, the extra is kept as **Advance** on the khata and is used on
  the next bill automatically.

## Transport and loaders

- Menu > Transport & loaders: add vehicle owners and loaders. Each has a khata (what you owe them).
- On a sale (and a branch transfer) pick who did the delivery / loading next to the charge. The charge on the
  bill is added to that person's khata. "Not tracked" leaves it out.
- Pay them from their page; the balance drops.
- Purchase bills do not use this yet (the transport charge there stays on the supplier's bill).

## Cost and selling prices

- Cost is the weighted average of your purchases. It is set only through purchases (the product form asks
  for an opening cost once, when you create the product; after that it is read-only).
  Example: 100 bori at 1,000 in stock + 100 bori bought at 1,100 = cost 1,050.
- The purchase screen shows the new average cost, the old cost, and the profit your current selling price
  leaves. Change the selling price right there if needed; only changed prices are saved.
- Every change to cost or selling price is recorded (Products > clock icon): old value, new value, where it
  came from, who did it. Prices there are per base unit.
- Selling below cost: owner and manager see a red warning and must confirm. Munshi and salesman are blocked
  (they never see cost prices).
- Old bills keep the cost they were sold at, so changing prices never rewrites past profit.

## Accounts, partners and settlement

- Owner menu > Accounts: one account per partner (with profit share %, e.g. 50 / 50), plus Shop cash,
  Bank and Mobile wallet. Opening balance = money already there when you start.
- Every time money moves you choose the account, there is no default: sale paid amount ("Received into"),
  purchase paid amount ("Paid from"), customer payment, supplier payment, transport/loader payment.
  So if Partner-1 makes the invoice and the cash goes to Partner-1's pocket, pick Partner-1's account.
- Each account page is its own khata (in, out, balance). There you can also add an expense, a partner
  withdrawal, other income, or move money to another account (partner hands cash to the other, deposit to bank).
- Owner menu > Partner settlement: who should receive / hand over how much so each partner ends up with
  their profit share of all the money (withdrawals already taken are counted). Money only; udhaar is not counted.
- Sales older than this update have no account; put that money in the account's opening balance.

## Partner capital and settlement by date

- On a partner account, "Capital already invested" is what that partner had put in before the software.
  Later investments or capital taken back are entered on any account page > "Expense / withdrawal / other"
  (types: Capital invested, Capital taken back, Partner withdrawal = profit already taken).
- Settlement: each partner should end up with their capital plus their profit share of (all money minus all capital).
  Choose From / To to see, for that period, every account's opening, money in, money out and closing,
  where the money came from, and the partner position as of the "To" date.

## Reports

Menu > Reports (owner and manager). All reports have From/To, Print and Export CSV (opens in Excel).
Sales, Daily summary, Product/category sales, Customer-wise sales, Profit and loss, Customers owing us (aging),
Suppliers we owe (aging), Purchases, Stock value, Transport and loaders.
Owner only: Cash book (every rupee with account and who entered it), Expenses, Who did what, Branch summary.
Sales and Purchases reports can be filtered by customer/supplier, user and account.

## Cancelling a bill

Owner or manager: open the invoice or purchase > "Cancel this bill". Stock goes back, the money is reversed in
its account, transport/loader charges are removed, and the bill stops counting everywhere. Payments the party made
later are kept and applied to their other bills. Cancelling a purchase needs the goods to still be in stock;
the average cost is not rolled back.

## Backups

Back up the database every day. For MySQL: `mysqldump -u root hardware_store > backup-$(date +%F).sql`
(schedule it with Windows Task Scheduler or cron) and keep a copy on another disk or a USB drive.

## Good to know

- Bootstrap, icons and fonts are bundled in `public/vendor`, so the software works without internet.
  The look is in `public/css/app.css` (colours are the variables at the top).
- Validation messages are translated for the common rules only; the rest fall back to English.
- Printing: sale page > "Print A4" or "Print receipt". For a 58 mm roll printer change the two `80mm`
  values at the top of `resources/views/sales/print_thermal.blade.php` to `58mm`.

## Not in Phase 1 yet

Expense book, transport/loader payment ledger (charges are recorded on bills and transfers but not
yet tracked as their own account), sale/purchase returns, profit and day-end reports, editing or
cancelling a saved bill.
