# Admin Portal Backend — Manual Testing Guide

## Prerequisites

1. Docker stack running: `cd hubwallet-api && docker-compose up --build`
2. Migration applied: `docker-compose exec web alembic upgrade head`
3. A superuser account must exist in the `users` table with `is_superuser=true`

## Creating a Superuser

Run directly against the DB or via psql:
```sql
-- After hashing the password using bcrypt
INSERT INTO users (email, username, hashed_password, is_superuser, is_active, is_verified)
VALUES ('superadmin@hubwallet.com', 'superadmin', '<bcrypt_hash>', true, true, true);
```

Or use the existing `/api/v1/auth/register` endpoint then update `is_superuser` in the DB.

## Step-by-Step Tests

### 1. Get a superuser JWT token
```
POST /api/v1/auth/login
{ "email": "superadmin@hubwallet.com", "password": "yourpassword" }
```
Copy the `access_token` from the response. Use it as `Bearer <token>` in all subsequent requests.

### 2. Dashboard Stats
```
GET /api/v1/admin/dashboard/stats
Authorization: Bearer <token>
```
Expected: 200 with `total_merchants`, `merchants_by_status`, `transaction_counts`, `transaction_volume`, `new_merchants_this_month`.

### 3. List Merchants
```
GET /api/v1/admin/merchants?page=1&per_page=10
Authorization: Bearer <token>
```
Expected: 200 with `items` array and `meta` pagination object.

### 4. Filter Merchants by Status
```
GET /api/v1/admin/merchants?status=active
Authorization: Bearer <token>
```
Expected: Only merchants with `status=active`.

### 5. Activate a Merchant
```
POST /api/v1/admin/merchants/{id}/activate
Authorization: Bearer <token>
```
Expected: 200 `{"activated": true, "status": "pending_approval"}`.
Verify: `is_active=true`, `approved_by=<admin_user_id>`, `approved_at` set in DB.
Verify: Audit log row with `action="merchant.activate"`.

### 6. Deactivate a Merchant
```
POST /api/v1/admin/merchants/{id}/deactivate
Authorization: Bearer <token>
```
Expected: 200 `{"deactivated": true}`.
Verify: `is_active=false` in DB, audit log entry added.

### 7. Merchant Impersonation
```
POST /api/v1/admin/merchants/{id}/impersonate
Authorization: Bearer <token>
```
Expected: 200 with `access_token`, `expires_in=14400`, `impersonated_merchant_id`.
Use returned `access_token` to call merchant-scoped endpoints — they should behave as if you are that merchant.

### 8. End Impersonation
```
DELETE /api/v1/admin/merchants/{id}/impersonate
Authorization: Bearer <token>
```
Expected: 200 `{"revoked": true}`. Impersonation session marked revoked in DB.

### 9. Create Admin User
```
POST /api/v1/admin/users
Authorization: Bearer <token>
{ "email": "newadmin@hubwallet.com", "first_name": "New", "last_name": "Admin", "password": "SecurePass123" }
```
Expected: 201/200 with `id` and `email`. User created with `is_superuser=true`.

### 10. Audit Log
```
GET /api/v1/admin/audit-log?page=1&per_page=20
Authorization: Bearer <token>
```
Expected: All audit actions recorded from previous steps appear here.

### 11. Non-superuser Blocked
```
GET /api/v1/admin/dashboard/stats
Authorization: Bearer <non_superuser_token>
```
Expected: 403 Forbidden.