# Admin Panel Modules

The Admin panel is reserved for users with the `role = 'admin'`. Controllers live in `app/modules/Admin/`.

**Environment:** like the company portal, admin pages rely on `helpers/AppUrls.php` and optional `LINKPROX_BASE_PATH` in `.env` so links and assets resolve on any host or subfolder.

## Views (`views/admin/`)
| View | Purpose |
|---|---|
| `dashboard.php` | Platform-wide stats (total companies, contracts, revenue) |
| `companies.php` | Full list of companies with status filter |
| `company_details.php` | Detailed company profile + document review |
| `categories.php` | Browse global catalog categories |
| `manage_categories.php` | Create / edit global catalog categories |
| `category_mappings.php` | Map categories to companies |
| `category_companies.php` | View companies per category |
| `company_category_items.php` | Items per company per category |
| `settings.php` | Platform-wide configuration |
| `security.php` | Admin credentials + 2FA |

---

## 1. Company Management (`AdminCompanyController.php`)

### Approval Workflow
Companies register and land in `status = 'pending_approval'`. Admin must review uploaded documents and approve or reject.

| Endpoint | Method | Description |
|---|---|---|
| `GET /api/v1/admin/companies` | GET | List all companies (with status filter) |
| `GET /api/v1/admin/companies/details?id=` | GET | Full company profile |
| `POST /api/v1/admin/companies/approve` | POST | `{ company_id }` → sets status = `approved` |
| `POST /api/v1/admin/companies/suspend` | POST | `{ company_id }` → sets status = `suspended` |
| `POST /api/v1/admin/companies/update-status` | POST | Generic status update + optional reason |
| `POST /api/v1/admin/companies/verify` | POST | `{ company_id, is_verified: true/false }` |

### Company Status Values
| Status | Meaning |
|---|---|
| `pending_approval` | Registered but awaiting admin review |
| `approved` | Can receive requests and sign contracts |
| `suspended` | Temporarily blocked |
| `rejected` | Documents failed review |
| `deactivation_requested` | Company asked to close account (pending admin action) |

---

## 2. Catalog Categories (`CategoryMappingController.php`)

- Categories are **global** (not company-scoped).
- Each category has a `type`: either `'product'` or `'service'`.
- Companies can be mapped to categories to indicate what they offer.

---

## 3. Platform Settings (`AdminSettingsController.php`)

- Manage urgency levels, pricing models, measurement units.
- Configure platform fee percentages or global caps.

---

## 4. App Content Management
Admin can manage mobile app specific content like dashboard sliders and featured items.

- **Banners/Sliders**: Managed via `app_banners` table.
- **Trusted Partners**: Verified companies marked as `verified = 1`.
- **Global Categories**: Icons for mobile dashboard categories.

## Admin Role Rules
- Only users with `role = 'admin'` can access any `/api/v1/admin/*` endpoint.
- `AuthMiddleware::requireRole($user, 'admin')` is called at the top of every admin controller method.
- Admin accounts are created directly in the database (no self-registration).