# Agent Management

## Purpose
Agent Management handles CRUD operations for external agents who manage merchants on the platform. Agents are intermediaries that can manage multiple merchants, earn commissions, and have their own KYC status tracking. This page provides agent creation, editing, commission configuration, and account management.

## Components
- Page header with icon and title
- Statistics cards (6 metrics)
- Action bar with Create, Delete, Export, Refresh buttons
- Search input
- Search & Filter section
- Agent list data table
- Business Rules section
- Create/Edit Agent modal
- View Agent modal
- Reset Agent Password modal

## Header
- **Title**: "Agent Management"
- **Subtitle**: "Create, edit, and manage all registered agents"
- **Page Icon**: Purple background with users icon

### Statistics Cards
| Card | ID | Description |
|------|-----|-------------|
| Total Agents | `totalAgents` | All registered agents |
| Active Agents | `activeAgents` | Currently active agents |
| Inactive Agents | `inactiveAgents` | Inactive accounts |
| Total Commission Paid | `totalCommission` | Total commissions earned by agents |
| Avg Commission Rate | `avgCommission` | Average commission percentage |
| Total Transactions | `totalTransactions` | Transactions processed through agents |

## Filters
| Filter | ID | Type | Options |
|--------|-----|------|---------|
| Agent ID | `filterId` | text | — |
| Agent Name | `filterName` | text | — |
| Status | `filterStatus` | select | All Status, Active, Inactive |
| Commission | `filterCommission` | select | All Rates, Low (0-4%), Medium (4-6%), High (6%+) |
| Date From | `filterDateFrom` | date | — |
| Date To | `filterDateTo` | date | — |

## Search
- **Input ID**: `searchInput`
- **Placeholder**: "Search agents..."
- **Searches**: Name, email, username, ID

## Buttons
| Button | Action | Location |
|--------|--------|----------|
| Create Agent | Opens create modal | Action bar |
| Delete Agent | Deletes selected agents | Action bar |
| Export | Exports agent list to CSV | Action bar |
| Refresh | Reloads agent list | Action bar |
| Clear Filters | Resets all filters | Filter section |

## Forms

### Create/Edit Agent Modal (`agentModal`)
| Field | ID | Type | Required | Notes |
|-------|-----|------|----------|-------|
| Agent ID | `agentId` | text | No (auto) | Auto-generated, hidden |
| Agent Name | `agentName` | text | Yes | — |
| Username | `agentUsername` | text | Yes | — |
| Password | `agentPassword` | password | Yes | Hidden when editing |
| Email | `agentEmail` | email | Yes | — |
| Phone | `agentPhone` | tel | Yes | — |
| Commission Rate (%) | `agentCommission` | number | Yes | min=0, max=100, step=0.5 |
| Status | `agentStatus` | select | No | Active, Inactive |

**Hint**: "Leave blank to keep current password when editing"
**Buttons**: Cancel, Save Agent

### View Agent Modal (`viewModal`)
**Title**: "Agent Details"
**Displayed Fields**: Agent ID, Agent Name, Username, Email, Phone, Commission Rate, Status, Created, Transactions, Total Volume, Earned Commission
**Button**: Close

### Reset Agent Password Modal (`resetModal`)
**Title**: "Reset Agent Password"
| Field | ID | Type | Required |
|-------|-----|------|----------|
| New Password | `newPassword` | password | Yes |
| Confirm Password | `confirmPassword` | password | Yes |

**Dynamic Text**: "Enter a new password for agent **{name}**"
**Buttons**: Cancel, Reset Password

## Tables

### Agent List Table
| Column | Description |
|--------|-------------|
| Checkbox | Select all/individual |
| Agent ID | Unique identifier |
| Agent Name | Business name |
| Username | Login username |
| Email | Contact email |
| Phone | Contact phone |
| Commission Rate | Commission percentage |
| Status | Account status (Active, Inactive) |
| Created Date | Registration date |
| Actions | Action buttons |

## Action Buttons

### Row Actions
| Button | Function | Icon |
|--------|----------|------|
| View | View agent details | Eye |
| Edit | Edit agent information | Pencil |
| Reset Password | Reset agent password | Key |
| Disable/Enable | Toggle account status | Toggle |
| Delete | Delete agent account | Trash |

## Workflow
1. Admin navigates to Agent Management page
2. Views statistics cards showing agent counts and commission data
3. Uses search/filters to find specific agents
4. Clicks "Create Agent" to open creation modal
5. Fills in required fields (name, username, email, phone, commission rate)
6. Saves new agent
7. Can edit existing agents via row action
8. Can view detailed agent information including transaction volume
9. Can reset agent passwords
10. Can enable/disable agent accounts
11. Can export agent list to CSV
12. Can delete selected agents (with confirmation)

## Translation Requirements
| Key | English | Description |
|-----|---------|-------------|
| `agent_management` | Agent Management | Page title |
| `create_edit_manage_registered_agents` | Create, edit, and manage all registered agents | Subtitle |
| `create_agent` | Create Agent | Button text |
| `delete_agent` | Delete Agent | Button text |
| `export` | Export | Button text |
| `refresh` | Refresh | Button text |
| `clear_filters` | Clear Filters | Button text |
| `search_agents` | Search agents... | Placeholder |
| `total_agents` | Total Agents | Stat label |
| `active_agents` | Active Agents | Stat label |
| `inactive_agents` | Inactive Agents | Stat label |
| `total_commission_paid` | Total Commission Paid | Stat label |
| `avg_commission_rate` | Avg Commission Rate | Stat label |
| `total_transactions` | Total Transactions | Stat label |
| `agent_id` | Agent ID | Column/filter |
| `agent_name` | Agent Name | Column/filter |
| `username` | Username | Column |
| `email` | Email | Column |
| `phone` | Phone | Column |
| `commission_rate` | Commission Rate | Column/filter |
| `status` | Status | Column/filter |
| `created_date` | Created Date | Column |
| `actions` | Actions | Column |
| `active` | Active | Status |
| `inactive` | Inactive | Status |
| `view` | View | Action |
| `edit` | Edit | Action |
| `reset_password` | Reset Password | Action |
| `disable` | Disable | Action |
| `enable` | Enable | Action |
| `save` | Save | Button |
| `cancel` | Cancel | Button |
| `agent_hierarchy` | Agent Hierarchy | Rule title |
| `agent_hierarchy_desc` | Agents can manage Merchants but not other Agents | Rule |
| `commission_rates` | Commission Rates | Rule title |
| `commission_rates_desc` | Each agent has a unique commission rate configuration | Rule |
| `multiple_merchants` | Multiple Merchants | Rule title |
| `multiple_merchants_desc` | One agent can manage multiple merchants simultaneously | Rule |

## Responsive Requirements

### Desktop (≥1024px)
- 6-column statistics grid
- Horizontal filter bar
- Full-width data table

### Tablet (768px–1023px)
- 3-column statistics grid
- Stacked filter fields
- Horizontally scrollable table

### Mobile (<768px)
- 2-column statistics grid
- Full-width stacked filters
- Horizontally scrollable table

## API Dependency
- **Agents API**: GET `/api/agents` — List all agents
- **Create Agent**: POST `/api/agents` — Create new agent
- **Update Agent**: PUT `/api/agents/:id` — Update agent
- **Delete Agent**: DELETE `/api/agents/:id` — Delete agent
- **Reset Password**: POST `/api/agents/:id/reset-password` — Reset password
- **Agent Stats**: GET `/api/agents/stats` — Agent statistics
- **Export Agents**: GET `/api/agents/export` — CSV export