# Super Admin

## Access and safety

Super Admin pages are under `/superadmin` and require an authenticated user whose role is `super_admin`. Store owners receive HTTP 403 for Super Admin routes, including action routes, exports, invoice/proof downloads, and theme previews. The router applies CSRF validation to POST requests. Mutating actions write audit events; store impersonation has an explicit exit action and audit trail.

When maintenance mode is enabled, store-owner sign-in and dashboard access return an unavailable response. Super Admin sign-in and access remain enabled so maintenance can be turned off.

## Pages

| Route | Data and actions |
|---|---|
| `/superadmin` | Database-backed store counts, active paid-subscription MRR, paid revenue for the current month, pending manual payments, open support tickets, recent activity, and local Chart.js charts. |
| `/superadmin/stores` | Search, status/plan/date filters, sorting, and pagination. |
| `/superadmin/stores/{id}` | Plan and expiry, product usage versus the plan limit, domains, last login, and order count. Suspend/unsuspend, extend, change plan, impersonate, and typed-confirmation soft delete are audited. |
| `/superadmin/users` | Search users; enable/disable accounts and issue password-reset links. |
| `/superadmin/plans` | Edit monthly/yearly pricing, product limits, theme access, and feature flags. Updates are consumed by `PlanService`. |
| `/superadmin/payments` | Review pending manual payments, inspect private proof images, approve/reject with a reason, and download invoices or CSV exports. |
| `/superadmin/themes` | View database-backed themes and preview theme assets. |
| `/superadmin/support` | Review threaded owner tickets, reply, and change status; notifications are sent through the configured mailer. |
| `/superadmin/announcements` | Publish notices to all stores, a plan, or a store; configure active dates and dismissal. |
| `/superadmin/settings` | Site identity, support contacts, SMTP/test mail, payment methods, maintenance, trial duration, invoice settings, and terms/privacy text. At least one payment method must remain enabled. |
| `/superadmin/audit` | Search audit events by action, actor, IP, and date range; export filtered results. |
| `/superadmin/health` | PHP version, required extensions, writable folders, latest daily cron audit, disk availability, and database size. |

Chart.js is served from `public/assets/js/chart.umd.min.js`; the Super Admin dashboard does not depend on a runtime CDN.

## Setup notes

- Keep a stable `APP_KEY` configured as described in [BILLING.md](./BILLING.md); encrypted Razorpay and SMTP credentials depend on it.
- Configure a real SMTP server before relying on support notifications, password resets, or the test-mail action. Delivery failures are logged and surfaced in the mail log.
- Configure the daily cron task so the health page can report its last successful run.
- Seller tax identifiers and tax values are operator-configured placeholders; confirm the business details before issuing production invoices.

## Verification

Run the integration suite from the repository root with PHP, `pdo_mysql`, cURL, and a MySQL account that can create and drop a temporary database:

```powershell
C:\xampp\php\php.exe tests\superadmin_test.php
```

The test applies migrations to an isolated database, exercises database-backed service actions and owner-side support, runs a temporary HTTP server for role/CSRF/tenant checks, and drops the test database. Notification delivery in this test uses an injected mock transport while still verifying the `mail_log` records; it does not send real email.