# StudyTrack Pro Features — Setup Guide

This adds a full **Pro subscription system** on top of StudyTrack: PayHere payments,
a free-tier daily AI quota, an Upgrade page, and an admin panel to manage subscriptions.

## 1. Run the database migration

Import `database_pro_features.sql` via phpMyAdmin (or `mysql -u user -p db < database_pro_features.sql`).
It's additive/safe — adds columns to `users` and creates 3 new tables. Run it once, after your existing `database.sql` / `database_full.sql` / `database_new_features.sql`.

## 2. Configure PayHere

Sign up at **https://www.payhere.lk** (Sri Lankan payment gateway — cards, bank, mobile wallets).
While testing, use a **sandbox** account at https://sandbox.payhere.lk.

Edit `includes/config.php`:
```php
define('PAYHERE_MODE', 'sandbox');              // switch to 'live' when ready
define('PAYHERE_MERCHANT_ID', 'your_merchant_id');
define('PAYHERE_MERCHANT_SECRET', 'your_merchant_secret');
```
Merchant ID/Secret are in your PayHere dashboard → **Integrations**.

**Important:** PayHere calls `payhere-notify.php` directly (server-to-server) to confirm
payments — that's what actually activates Pro. Your site must be publicly reachable at
`SITE_URL . '/payhere-notify.php'` for this to work (won't work on `localhost`).

## 3. Adjust pricing / free-tier limit (optional)

Defaults: LKR 500/month, LKR 5000/year, 3 free AI requests/day. Change these anytime from
**Admin Panel → Pro Subscriptions** (no code edit needed) — it writes to the `site_settings` table.

## 4. What's Pro-gated

Only the AI features are behind Pro, per your earlier answer:
- **AI Study Tips** (`ai-tips.php`) — tips generator + AI chat widget
- **AI Analysis** (`ai-analysis.php`) — deep analysis tabs

Free users get **3 AI requests/day combined** across both pages (configurable). Once the
limit is hit, they see an upgrade prompt instead of a raw error. Pro users get unlimited access.

I did **not** gate `chat.php` — that's the user-to-user messaging/social chat feature, not AI,
and `ai.php` — an old unlinked test page not in the nav.

## 5. Security fix included

The original code called Groq's API **directly from the browser** with the API key embedded
in the page source — meaning anyone could open dev tools and call Groq for free, unlimited,
bypassing any quota entirely. I moved those calls behind a server-side proxy
(`action=ai_chat` / `ai_generate_tips` / `ai_generate` POST endpoints), so:
- `GROQ_API_KEY` never reaches the browser anymore
- the daily quota is enforced server-side, where it can't be bypassed

## 6. New/changed files

| File | Purpose |
|---|---|
| `database_pro_features.sql` | Migration: Pro columns, payments table, AI usage log, site_settings |
| `upgrade.php` | Pricing page + PayHere checkout |
| `payhere-notify.php` | PayHere webhook — verifies payment, activates Pro |
| `payhere-return.php` / `payhere-cancel.php` | Post-checkout landing pages |
| `admin/pro-subscriptions.php` | Admin: view/search users, manually grant/revoke Pro, view payments, edit pricing |
| `includes/functions.php` | Added: `isProUser()`, `activatePro()`, `checkAiQuota()`, `callGroqServer()`, PayHere hash helpers |
| `includes/config.php` | Added PayHere + pricing constants |
| `includes/header.php` | Added "Upgrade to Pro" sidebar link + Pro badge |
| `admin/includes/header.php` | Added "Pro Subscriptions" admin sidebar link |
| `ai-tips.php`, `ai-analysis.php` | Quota banners, server-side AI proxy, upgrade CTAs |

## 7. Testing the payment flow (sandbox)

1. Set `PAYHERE_MODE` to `sandbox` and put in your **sandbox** merchant ID/secret.
2. Go to `/upgrade`, click a plan — you'll be redirected to PayHere's sandbox checkout.
3. Use PayHere's test card numbers (see their sandbox docs) to simulate a payment.
4. PayHere calls `payhere-notify.php` in the background, which activates Pro and you'll
   land on `payhere-return.php` showing your new Pro status.
5. Check **Admin → Pro Subscriptions** to see the payment logged.

## 8. Manually granting Pro (no payment)

Admin Panel → **Pro Subscriptions** → find the user → pick `+30 days`, `+365 days`, or
`Lifetime` → **Grant**. Useful for comps, refunds-as-credit, or beta testers.
