# Deploy — Virtual Wallet, Wallet History, ID Card & Certificate, Earning Report

## 1. NEW files to upload

| File | Purpose |
|---|---|
| `includes/wallet.php` | **Dual wallet engine.** Main + Virtual balances, virtual-first spending, full ledger, earning queries |
| `includes/credentials.php` | ID card + seller certificate renderer, PNG download / print |
| `includes/earning_view.php` | Shared Earning Report renderer (cards, chart, sources, table, CSV) |
| `admin/wallet_history.php` | **Admin → Wallet Management → Wallet History** |
| `earning_report.php` | Member panel → Earning Report |
| `seller/earning_report.php` | Seller panel → Earning Report |
| `newmigration.php` | The migration — run once, then delete |

## 2. MODIFIED files to upload

| File | What changed |
|---|---|
| `includes/functions.php` | 3-level referral commission now credits the **virtual** wallet |
| `includes/shares.php` | Seller share → main wallet; referral share → virtual wallet |
| `includes/theme.php` | Menus: My ID Card, Main/Virtual Wallet, Earning Report |
| `category.php` | Virtual-first checkout, dual balance in the payment modal, **premium government portal cards** |
| `wallet.php` | Dual wallet summary + Virtual Wallet tab; deposits go through the ledger |
| `seller/wallet.php` | Same as above, seller side |
| `subscription.php` | New **Pay from Wallet** option (virtual first) |
| `profile.php` | Live **ID Card** and **Certificate** tabs |
| `seller/profile.php` | Same as above, seller side |
| `admin/sellers.php` | Issues the certificate + notifies the seller the moment a request is approved |
| `admin/wallet.php`, `admin/orders.php`, `admin/user_list.php`, `seller/index.php`, `seller/orders.php`, `add_money.php` | All money movements now go through the wallet engine so nothing bypasses the ledger |
| 17 × `admin/*.php` | Sidebar link to the new Wallet History page |

## 3. Run the migration

```
https://yourdomain.com/newmigration.php
```

**Delete the file afterwards.**

### New columns on `users`

| Column | Type | Purpose |
|---|---|---|
| `bonus_wallet` | `DECIMAL(10,2) NOT NULL DEFAULT 0.00` | **The virtual wallet balance** |
| `is_subscribed` | `TINYINT(1) NOT NULL DEFAULT 0` | Subscription flag |
| `referred_by` | `INT NULL` | Referrer's user id |
| `pincode` | `VARCHAR(20) NULL` | Used by the service-area gate |

Plus index `idx_users_referred (referred_by)`.

### New table `wallet_ledger`

Every rupee that moves in either wallet.

| Column | Type |
|---|---|
| `id` | `INT AUTO_INCREMENT PK` |
| `user_id` | `INT NOT NULL` |
| `wallet` | `VARCHAR(10)` — `main` \| `virtual` |
| `direction` | `VARCHAR(10)` — `credit` \| `debit` |
| `amount` | `DECIMAL(10,2)` |
| `balance_after` | `DECIMAL(10,2)` |
| `category` | `VARCHAR(40)` — `deposit`, `withdrawal`, `purchase`, `referral`, `seller_share`, `staff_share`, `subscription`, `refund`, `admin`, `bonus` |
| `description` | `VARCHAR(255)` |
| `reference_type` / `reference_id` | link to an order, service, subscription or transaction |
| `counterparty_id` | the other user involved (e.g. the buyer who generated your commission) |
| `created_by` | admin who made a manual adjustment |
| `created_at` | `TIMESTAMP` |

Indexes: `(user_id, created_at)`, `(wallet)`, `(category)`.

### New table `member_certificates`

| Column | Type |
|---|---|
| `id` | `INT AUTO_INCREMENT PK` |
| `user_id` | `INT NOT NULL` |
| `cert_no` | `VARCHAR(40) UNIQUE` — e.g. `WBMCZ/SLR/2026/00032` |
| `cert_type` | `VARCHAR(20)` — `seller` \| `member` |
| `holder_name`, `business_name` | text |
| `issued_on`, `valid_till` | `DATE` |
| `status` | `TINYINT(1)` |

### What the migration also does

1. **Backfills** every existing row of `transactions` into `wallet_ledger` (as main wallet, category auto-detected from the description). Runs **only once** — if the ledger already has rows it skips, so re-running is safe.
2. **Issues a certificate** to every existing seller.
3. Prints a verification summary at the end.

## 4. How each feature works

### Virtual wallet

| Money in | Goes to | Withdrawable |
|---|---|---|
| Razorpay deposit / admin recharge | **Main** | Yes |
| Seller share on a sale | **Main** | Yes |
| Referral commission (all 3 levels) | **Virtual** | **No** |
| Bonus | **Virtual** | **No** |

**Spending:** virtual is used **first**, the remainder comes from main.

- Product ₹240, virtual ₹100, main ₹140 → ₹100 virtual + ₹140 main, receipt shows the split
- Virtual ₹300, main ₹0, product ₹240 → fully paid from virtual
- Not enough in total → nothing is deducted, the user is told exactly how much more is needed
- **Withdrawals never touch the virtual wallet** — `wallet_withdraw()` sets `allow_virtual = false`

Both panels get a **Virtual Wallet** tab (`wallet.php#virtual`) with balance, total earned, total spent and full history. Subscription can now be bought from the wallet too.

### Admin → Wallet History

Searchable user list on the left (name / mobile / email / ID, filter by type, sorted by balance), full detail on the right:

- Main / Virtual / Total balance cards with in-and-out totals
- Lifetime earnings by source
- Filters: wallet, direction, category, date range
- Full ledger table — date, wallet, category, description, amount, running balance
- **CSV export** and a manual **Adjust** tool (add/deduct on either wallet, always logged)
- Platform totals at the top, plus a one-click "Import old transactions" button if the ledger is empty

### ID card & certificate

- **ID card** — `profile.php#id_card`, dark navy + gold, photo, name, role, **Member ID (`WBMCZ-000032`)**, **User ID**, mobile, business name, member-since, and a QR code that links back to the account.
- **Certificate** — `profile.php#certificate`, A4-landscape gold-bordered design with corner ornaments, gold seal, certificate number, issue and validity dates. Generated automatically the moment a customer is approved as a seller (and backfilled for existing sellers by the migration).
- Both download as a **high-resolution PNG** (html2canvas, 3× scale) or print via **Print → Save as PDF**. No PHP library or `vendor/` folder needed.

### Earning report

Available at `earning_report.php` (member) and `seller/earning_report.php` (seller):

- Four headline cards — all time, this month, last 7 days, today
- Main vs Virtual wallet split
- 12-month bar chart with hover values
- Source breakdown — stacked bar + per-source cards with percentages
- Quick range chips (today / 7 / 30 days / this month) plus source and custom date filters
- Full entry table and **CSV export**
- Sellers additionally see completed order value, pending order value and total orders

### Government portal cards

Category 1 cards now use a dedicated premium style: tricolour top edge, glass icon tile with a rotating gold ring and a light sweep on hover, gradient-filled icons, a "Govt. Portal" shield badge, deeper lift shadow, and a gradient "Visit Website" button. Animations respect `prefers-reduced-motion`.

## 5. Post-deploy check

1. Run `newmigration.php` → the verification block at the bottom should list ledger rows, certificates and wallet totals.
2. Admin → **Wallet Management → Wallet History** → pick a user → history and balances load.
3. Use **Adjust** to add ₹100 to a test user's **virtual** wallet → a `referral`/`admin` row appears with the correct running balance.
4. As that user, buy something priced above ₹100 → the alert should read "₹100 from Virtual Wallet + ₹X from Main Wallet".
5. Try to buy something costing more than both wallets combined → blocked with the exact shortfall, and no order is created.
6. Profile → **My ID Card** → Download PNG works; the member ID and role are correct.
7. Approve a seller request → the success message shows the new certificate number; that seller sees it under Profile → Certificate.
8. Open **Earning Report** in both panels → cards, chart and table populate; **Export CSV** downloads.
9. Open a Government Portals category → cards show the new premium styling.
