# Admin Payment Summary Dashboard - Wireframe Notes

## Overview
Comprehensive payment analytics dashboard for POS and Online transactions with KPIs, charts, filters, and drill-down transaction table.

## URL
`/admin/reports/payments`

## Layout Structure

### 1. Header Section
- **Title**: "Payment Summary Dashboard"
- **Subtitle**: "Comprehensive payment analytics for POS and Online transactions"
- **Action Button**: "Export CSV" (top-right, primary button with download icon)
  - Exports filtered transaction data to CSV

### 2. Filters Section (Card)
**Layout**: Single row with responsive grid (Bootstrap columns)

**Filter Fields** (left to right):
1. **Start Date** (col-md-3)
   - Input type: date
   - Default: 30 days ago
   
2. **End Date** (col-md-3)
   - Input type: date
   - Default: today
   
3. **Payment Method** (col-md-2)
   - Select dropdown
   - Options: All Methods, Online, COD, Cash, Card, Digital Wallet
   
4. **Transaction Type** (col-md-2)
   - Select dropdown
   - Options: All, POS, Online
   
5. **Status** (col-md-2)
   - Select dropdown
   - Options: All, Paid, Pending, Failed, Refunded
   
6. **Order ID** (col-md-2)
   - Text input
   - Placeholder: "Order ID"
   
7. **Transaction ID** (col-md-2)
   - Text input
   - Placeholder: "Transaction ID"
   
8. **Action Buttons** (col-md-2)
   - "Apply Filters" (primary button, full width)
   - "Reset" (secondary button, icon only)

**Behavior**:
- Form submission triggers AJAX data refresh
- Filters persist in URL parameters
- Reset button clears all filters and reloads default view

### 3. KPI Cards Section
**Layout**: Responsive grid (7 cards, col-md-3 col-lg-2 each)

**Card 1: Total Received** (stat-success)
- Icon: Currency Rupee (₹)
- Label: "Total Received"
- Value: ₹X,XXX.XX (formatted Indian currency)
- Color: Green theme

**Card 2: Failed** (stat-danger)
- Icon: X Circle
- Label: "Failed"
- Value: X (count)
- Color: Red theme

**Card 3: Pending** (stat-warning)
- Icon: Clock
- Label: "Pending"
- Value: X (count)
- Color: Yellow/Orange theme

**Card 4: POS Total** (stat-info)
- Icon: Cash Register
- Label: "POS Total"
- Value: ₹X,XXX.XX
- Color: Blue theme

**Card 5: Online Total** (stat-primary)
- Icon: Globe
- Label: "Online Total"
- Value: ₹X,XXX.XX
- Color: Primary blue theme

**Card 6: Refunds** (stat-secondary)
- Icon: Counterclockwise Arrow
- Label: "Refunds"
- Value: ₹X,XXX.XX
- Color: Gray theme

**Card 7: Success Rate** (stat-success)
- Icon: Graph Up Arrow
- Label: "Success Rate"
- Value: XX.XX%
- Color: Green theme

**Card Styling**:
- Minimum height: 120px
- Stat value font size: 1.5rem (1.25rem on mobile)
- Icon on left, content on right
- Hover effect for better UX

### 4. Charts Section
**Layout**: Responsive grid (row g-4)

#### Chart 1: Payment Trend (col-md-8)
- **Type**: Multi-line chart (Chart.js)
- **Title**: "Payment Trend"
- **X-Axis**: Dates (formatted as "MMM DD")
- **Y-Axis**: Amount (₹ formatted)
- **Lines**:
  - Paid (Green, filled area)
  - Failed (Red, filled area)
  - Pending (Yellow, filled area)
  - Refunded (Gray, filled area)
- **Height**: 300px max
- **Features**:
  - Tooltip on hover showing all values
  - Responsive design
  - Legend at top

#### Chart 2: POS vs Online (col-md-4)
- **Type**: Doughnut chart (Chart.js)
- **Title**: "POS vs Online"
- **Segments**:
  - POS (Blue)
  - Online (Green)
- **Tooltip**: Shows amount, percentage, and transaction count
- **Height**: 250px max
- **Legend**: Bottom position

#### Chart 3: Payment Method Distribution (col-md-4)
- **Type**: Pie chart (Chart.js)
- **Title**: "Payment Method Distribution"
- **Segments**: Dynamic based on payment methods
  - Colors: Blue, Green, Yellow, Red, Purple, Pink
- **Tooltip**: Shows method name, amount, percentage, transaction count
- **Height**: 250px max
- **Legend**: Bottom position
- **Empty State**: Shows "No payment method data available" message

**Chart Container Styling**:
- White card background
- Card header with title
- Responsive canvas elements
- Maintain aspect ratio

### 5. Transaction Table Section
**Layout**: Full-width card

**Header**:
- Title: "Transactions" (left)
- Refresh button (right, outline primary, small)

**Table Structure**:
- Responsive table with horizontal scroll on mobile
- Columns:
  1. **Order ID**: #XXX (linked to order detail)
  2. **Transaction ID**: Code-styled text (monospace)
  3. **Date**: Formatted date-time (MMM DD, YYYY HH:MM)
  4. **Customer**: Name (with mobile number below if available)
  5. **Amount**: ₹X,XXX.XX (bold, formatted)
  6. **Payment Method**: Formatted method name
  7. **Source**: Badge (POS = info blue, Online = primary blue)
  8. **Status**: Badge (Paid = success, Pending = warning, Failed = danger, Refunded = secondary)
  9. **Actions**: View button (eye icon, outline primary, small)

**Pagination**:
- Centered below table
- Shows page numbers with ellipsis for large ranges
- Previous/Next buttons
- Active page highlighted
- Disabled state for first/last pages

**Loading State**:
- Spinner in table body during data fetch
- "No transactions found" message when empty
- Error message on failure

**Table Features**:
- Hover effect on rows
- Clickable order ID links to order detail page
- Real-time data refresh on filter changes
- Server-side pagination (15 items per page default)

## Color Scheme

### Status Colors
- **Success/Paid**: Green (#22c55e)
- **Warning/Pending**: Yellow/Orange (#fbbf24)
- **Danger/Failed**: Red (#ef4444)
- **Secondary/Refunded**: Gray (#6b7280)
- **Info/POS**: Blue (#3b82f6)
- **Primary/Online**: Blue (#2563eb)

### Card Themes
- stat-success: Green background with white text
- stat-danger: Red background with white text
- stat-warning: Yellow/Orange background with dark text
- stat-info: Blue background with white text
- stat-primary: Primary blue background with white text
- stat-secondary: Gray background with white text

## Responsive Behavior

### Desktop (≥992px)
- 7 KPI cards in single row (col-lg-2)
- Charts: 8-4-4 column layout
- Full filter form visible
- Table with all columns visible

### Tablet (768px - 991px)
- KPI cards: 3-3-1 or 2-2-2-1 layout
- Charts: Stack vertically or 2-column
- Filters: 2 rows
- Table: Horizontal scroll enabled

### Mobile (<768px)
- KPI cards: Stack vertically
- Charts: Full width, stack
- Filters: Stack all fields
- Table: Horizontal scroll with all columns
- Smaller font sizes for stat values

## Data Flow

### Initial Load
1. Page loads with default filters (last 30 days)
2. JavaScript fetches KPI and chart data via `/admin/reports/payments/api/summary`
3. JavaScript fetches transaction list via `/admin/reports/payments/api/transactions`
4. Charts render with Chart.js
5. Table populates with pagination

### Filter Change
1. User modifies filters and clicks "Apply Filters"
2. Form prevents default submission
3. JavaScript updates currentFilters object
4. AJAX calls to both API endpoints with new filters
5. KPIs, charts, and table update dynamically
6. URL parameters update (optional, for bookmarking)

### Export CSV
1. User clicks "Export CSV" button
2. Button href includes all current filter parameters
3. Server generates CSV with filtered data
4. Browser downloads file: `payment_report_YYYY-MM-DD_HH-MM-SS.csv`

## API Endpoints

### GET `/admin/reports/payments/api/summary`
**Query Parameters**:
- `start_date` (required)
- `end_date` (required)
- `payment_method` (optional)
- `transaction_type` (optional)
- `status` (optional)

**Response**:
```json
{
  "kpis": {
    "total_received": 123456.78,
    "failed": 5,
    "pending": 12,
    "pos_total": 50000.00,
    "online_total": 73456.78,
    "refunds": 1000.00,
    "success_rate": 95.5
  },
  "charts": {
    "trend_data": [...],
    "pos_vs_online": [...],
    "payment_method_pie": [...]
  }
}
```

### GET `/admin/reports/payments/api/transactions`
**Query Parameters**:
- `start_date` (required)
- `end_date` (required)
- `payment_method` (optional)
- `transaction_type` (optional)
- `status` (optional)
- `order_id` (optional)
- `tx_id` (optional)
- `page` (default: 1)
- `per_page` (default: 15)

**Response**:
```json
{
  "data": [...],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 67,
    "from": 1,
    "to": 15
  }
}
```

### GET `/admin/reports/payments/export-csv`
**Query Parameters**: Same as transactions API
**Response**: CSV file download

## Performance Considerations

1. **Database Indexes**:
   - Composite index on `(payment_status, source, created_at)`
   - Composite index on `(payment_method, payment_status, created_at)`
   - Index on `(razorpay_payment_id, razorpay_order_id)`

2. **Query Optimization**:
   - Single aggregated query for KPIs (reduces from 7+ queries to 1)
   - Eager loading relationships (user, staff) for transactions
   - Pagination limits data transfer

3. **Frontend Optimization**:
   - Chart.js lazy loading
   - Debounced filter changes (if implemented)
   - Cached filter state

## Accessibility

- Semantic HTML structure
- ARIA labels for interactive elements
- Keyboard navigation support
- Screen reader friendly status badges
- Color contrast compliance (WCAG AA)

## Browser Support

- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)

## Notes

- All monetary values displayed in Indian Rupees (₹)
- Date formats use Indian locale (DD-MM-YYYY)
- Charts use Chart.js 4.0.1 (CDN)
- Bootstrap 5 for responsive grid
- Bootstrap Icons for icons
- No page reload required for filter changes (AJAX)