feat: add expense payment export, auto-populate payment details, and comprehensive filtering system

docs/features/expenses/EXPENSE_API.md

@@ -0,0 +1,198 @@
+# Expense Management API
+
+**Base:** `/api/v1/ticket-expenses`
+
+---
+
+## PM Endpoints
+
+### 1. List All Expenses
+`GET /ticket-expenses`
+
+**Filters:**
+```
+?is_approved=false              // Pending approval
+?ready_for_payment=true         // Ready to pay
+?date_range=this_week           // today|yesterday|this_week|last_week|this_month|last_month
+?category=transport,materials   // Comma-separated
+?project_id=uuid
+?user_id=uuid
+?search=taxi
+```
+
+**Response:**
+```json
+{
+  "expenses": [{
+    "id": "uuid",
+    "ticket_reference": "TKT-123",
+    "incurred_by_user_name": "John Doe",
+    "category": "transport",
+    "description": "Taxi to site",
+    "expense_date": "2024-12-08",
+    "total_cost": 500.00,
+    "is_approved": false,
+    "is_paid": false,
+    "location_verified": true,
+    "payment_method": "send_money",
+    "payment_details": {"phone_number": "+254712345678", "recipient_name": "John Doe"}
+  }],
+  "total": 25,
+  "page": 1,
+  "page_size": 50,
+  "pages": 1
+}
+```
+
+### 2. Approve/Reject
+`POST /ticket-expenses/{id}/approve`
+
+**Request:**
+```json
+// Approve
+{"is_approved": true}
+
+// Reject
+{"is_approved": false, "rejection_reason": "Receipt unclear"}
+```
+
+### 3. Export for Payment (CSV)
+`POST /ticket-expenses/export-for-payment?from_date=2024-12-01&to_date=2024-12-08`
+
+**Returns:** CSV file
+
+**CSV Columns:** `technician_name, phone_number, account_name, total_amount, expense_count, date, tickets_summary, categories_summary, expense_ids`
+
+**⚠️ Side Effect:** Marks all expenses as paid (irreversible!)
+
+### 4. Get Statistics
+`GET /ticket-expenses/stats/summary?from_date=2024-12-01&to_date=2024-12-08`
+
+**Response:**
+```json
+{
+  "total_expenses": 25,
+  "total_amount": 12500.00,
+  "pending_count": 3,
+  "pending_amount": 1500.00,
+  "approved_count": 20,
+  "approved_amount": 10000.00,
+  "paid_count": 15,
+  "paid_amount": 7500.00,
+  "by_category": {"transport": 5000.00, "materials": 4000.00}
+}
+```
+
+---
+
+## Field Agent Endpoints
+
+### 1. Create Expense
+`POST /ticket-expenses`
+
+**Request:**
+```json
+{
+  "ticket_assignment_id": "uuid",
+  "category": "transport",
+  "description": "Taxi to customer site",
+  "total_cost": 500.00,
+  "expense_date": "2024-12-08",
+  "notes": "Shared with team"
+}
+```
+
+**Categories:** `transport`, `materials`, `meals`, `accommodation`, `other`
+
+**Note:** Payment details auto-populated from financial account
+
+### 2. My Expenses
+`GET /ticket-expenses/my-expenses`
+
+**Filters:** Same as PM list (is_approved, is_paid, date_range, category, search)
+
+### 3. My Stats
+`GET /ticket-expenses/my-stats`
+
+**Response:** Same as PM stats but for current user only
+
+### 4. Update Expense
+`PUT /ticket-expenses/{id}`
+
+**Only before approval!**
+
+### 5. Delete Expense
+`DELETE /ticket-expenses/{id}`
+
+**Only before approval!**
+
+---
+
+## Quick Filters
+
+```typescript
+const FILTERS = {
+  pendingApproval: '?is_approved=false',
+  readyForPayment: '?ready_for_payment=true',
+  today: '?date_range=today',
+  thisWeek: '?date_range=this_week',
+  unpaid: '?is_approved=true&is_paid=false',
+};
+```
+
+---
+
+## Data Types
+
+```typescript
+interface CreateExpense {
+  ticket_assignment_id: string;
+  category: 'transport' | 'materials' | 'meals' | 'accommodation' | 'other';
+  description: string;
+  total_cost: number;
+  expense_date?: string;  // ISO date, defaults to today
+  notes?: string;
+}
+
+interface Expense {
+  id: string;
+  ticket_reference: string;
+  incurred_by_user_name: string;
+  category: string;
+  description: string;
+  expense_date: string;
+  total_cost: number;
+  is_approved: boolean;
+  is_paid: boolean;
+  location_verified: boolean;
+  payment_method?: string;
+  payment_details?: object;
+  rejection_reason?: string;
+}
+```
+
+---
+
+## UI Components Needed
+
+**PM:**
+- Expense list with filters
+- Approve/Reject buttons
+- Export dialog (date range picker)
+- Stats dashboard cards
+
+**Field Agent:**
+- Add expense form (in ticket detail)
+- My expenses list
+- Status badges (Pending/Approved/Rejected/Paid)
+- Stats cards
+
+---
+
+## Important Rules
+
+1. **Export = Payment** - CSV export marks expenses as paid automatically
+2. **No editing after approval** - Locked once approved
+3. **Location verified** - System checks GPS automatically
+4. **Payment auto-populated** - From financial account
+5. **Same-day rule** - Can add expenses on completion day only

src/app/api/v1/ticket_expenses.py

@@ -19,7 +19,7 @@ from fastapi import APIRouter, Depends, status, Query
 from sqlalchemy.orm import Session
 from typing import Optional, List
 from uuid import UUID
-from datetime import date
+from datetime import date, datetime, timedelta
 
 from app.api.deps import get_db, get_current_user
 from app.models.user import User
@@ -34,10 +34,111 @@ from app.schemas.ticket_expense import (
     TicketExpenseListResponse,
     TicketExpenseStats,
 )
+from app.schemas.filters import ExpenseFilters
 
 router = APIRouter()
 
 
+# ============================================
+# FILTER PARSING
+# ============================================
+
+def parse_expense_filters(
+    ticket_id: Optional[UUID] = Query(None),
+    assignment_id: Optional[UUID] = Query(None),
+    user_id: Optional[UUID] = Query(None),
+    project_id: Optional[UUID] = Query(None),
+    category: Optional[str] = Query(None),
+    payment_method: Optional[str] = Query(None),
+    payment_recipient_type: Optional[str] = Query(None),
+    expense_date: Optional[date] = Query(None),
+    expense_date_from: Optional[date] = Query(None),
+    expense_date_to: Optional[date] = Query(None),
+    is_approved: Optional[bool] = Query(None),
+    is_paid: Optional[bool] = Query(None),
+    location_verified: Optional[bool] = Query(None),
+    has_receipt: Optional[bool] = Query(None),
+    has_payment_details: Optional[bool] = Query(None),
+    ready_for_payment: Optional[bool] = Query(None),
+    date_range: Optional[str] = Query(None),
+    search: Optional[str] = Query(None),
+    sort_by: Optional[str] = Query(None),
+    sort_order: str = Query("desc"),
+    page: int = Query(1, ge=1),
+    page_size: int = Query(50, ge=1, le=100),
+    from_date: Optional[date] = Query(None),
+    to_date: Optional[date] = Query(None),
+) -> ExpenseFilters:
+    """Parse and convert query parameters to ExpenseFilters"""
+    # Parse comma-separated multi-value filters
+    def parse_csv(value: Optional[str]) -> Optional[List[str]]:
+        if value is None:
+            return None
+        return [item.strip() for item in value.split(',') if item.strip()]
+    
+    # Handle quick date range filters
+    if date_range:
+        today = date.today()
+        if date_range == "today":
+            expense_date_from = today
+            expense_date_to = today
+        elif date_range == "yesterday":
+            yesterday = today - timedelta(days=1)
+            expense_date_from = yesterday
+            expense_date_to = yesterday
+        elif date_range == "this_week":
+            # Monday to Sunday
+            start_of_week = today - timedelta(days=today.weekday())
+            expense_date_from = start_of_week
+            expense_date_to = today
+        elif date_range == "last_week":
+            start_of_last_week = today - timedelta(days=today.weekday() + 7)
+            end_of_last_week = start_of_last_week + timedelta(days=6)
+            expense_date_from = start_of_last_week
+            expense_date_to = end_of_last_week
+        elif date_range == "this_month":
+            expense_date_from = today.replace(day=1)
+            expense_date_to = today
+        elif date_range == "last_month":
+            first_of_this_month = today.replace(day=1)
+            last_day_of_last_month = first_of_this_month - timedelta(days=1)
+            expense_date_from = last_day_of_last_month.replace(day=1)
+            expense_date_to = last_day_of_last_month
+    
+    # Support legacy from_date/to_date parameters
+    if from_date and not expense_date_from:
+        expense_date_from = from_date
+    if to_date and not expense_date_to:
+        expense_date_to = to_date
+    
+    return ExpenseFilters(
+        ticket_id=ticket_id,
+        assignment_id=assignment_id,
+        user_id=user_id,
+        project_id=project_id,
+        category=parse_csv(category),
+        payment_method=parse_csv(payment_method),
+        payment_recipient_type=parse_csv(payment_recipient_type),
+        expense_date=expense_date,
+        expense_date_from=expense_date_from,
+        expense_date_to=expense_date_to,
+        is_approved=is_approved,
+        is_paid=is_paid,
+        location_verified=location_verified,
+        has_receipt=has_receipt,
+        has_payment_details=has_payment_details,
+        ready_for_payment=ready_for_payment,
+        date_range=date_range,
+        search=search,
+        sort_by=sort_by,
+        sort_order=sort_order,
+        page=page,
+        page_size=page_size,
+        from_date=expense_date_from,
+        to_date=expense_date_to,
+    )
+
+
 # ============================================
 # CREATE EXPENSE
 # ============================================
@@ -362,32 +463,46 @@ def delete_expense(
     summary="Get current user's expenses"
 )
 def get_my_expenses(
-    is_approved: Optional[bool] = Query(None, description="Filter by approval status"),
-    is_paid: Optional[bool] = Query(None, description="Filter by payment status"),
-    from_date: Optional[date] = Query(None, description="Filter from date"),
-    to_date: Optional[date] = Query(None, description="Filter to date"),
-    page: int = Query(1, ge=1, description="Page number"),
-    page_size: int = Query(100, ge=1, le=100, description="Items per page"),
+    filters: ExpenseFilters = Depends(parse_expense_filters),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
     """
-    Get all expenses for the current user.
+    Get all expenses for the current user with comprehensive filtering.
     
     **Purpose:** Field agents can see all their expenses in one place
     
+    **Supports all expense filters:**
+    - `is_approved`: Filter by approval status
+    - `is_paid`: Filter by payment status
+    - `category`: Filter by category (transport,materials,meals)
+    - `date_range`: Quick filter (today,yesterday,this_week,last_week,this_month,last_month)
+    - `expense_date_from/to`: Date range
+    - `has_receipt`: Filter expenses with receipts
+    - `search`: Search description and notes
+    - And more...
+    
+    **Examples:**
+    ```
+    # Pending approval
+    GET /ticket-expenses/my-expenses?is_approved=false
+    
+    # This week's expenses
+    GET /ticket-expenses/my-expenses?date_range=this_week
+    
+    # Transport expenses only
+    GET /ticket-expenses/my-expenses?category=transport
+    ```
+    
     **Returns:** List of user's expenses with full context (ticket info, approval/payment status)
     """
-    expenses, total = TicketExpenseService.list_expenses(
+    # Force filter to current user
+    filters.user_id = current_user.id
+    
+    expenses, total = TicketExpenseService.list_expenses_with_filters(
         db=db,
         current_user=current_user,
-        user_id=current_user.id,  # Force filter to current user
-        is_approved=is_approved,
-        is_paid=is_paid,
-        from_date=from_date,
-        to_date=to_date,
-        page=page,
-        page_size=page_size
+        filters=filters
     )
     
     # Build responses with contextual information
@@ -415,13 +530,13 @@ def get_my_expenses(
         
         expense_responses.append(response)
     
-    pages = (total + page_size - 1) // page_size
+    pages = (total + filters.page_size - 1) // filters.page_size
     
     return TicketExpenseListResponse(
         expenses=expense_responses,
         total=total,
-        page=page,
-        page_size=page_size,
+        page=filters.page,
+        page_size=filters.page_size,
         pages=pages
     )
 
@@ -517,21 +632,12 @@ def get_expense(
     summary="List expenses with filters"
 )
 def list_expenses(
-    ticket_id: Optional[UUID] = Query(None, description="Filter by ticket"),
-    assignment_id: Optional[UUID] = Query(None, description="Filter by assignment"),
-    user_id: Optional[UUID] = Query(None, description="Filter by user"),
-    category: Optional[str] = Query(None, description="Filter by category"),
-    is_approved: Optional[bool] = Query(None, description="Filter by approval status"),
-    is_paid: Optional[bool] = Query(None, description="Filter by payment status"),
-    from_date: Optional[date] = Query(None, description="Filter from date (inclusive)"),
-    to_date: Optional[date] = Query(None, description="Filter to date (inclusive)"),
-    page: int = Query(1, ge=1, description="Page number"),
-    page_size: int = Query(50, ge=1, le=100, description="Items per page"),
+    filters: ExpenseFilters = Depends(parse_expense_filters),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
     """
-    List expenses with filters and pagination.
+    List expenses with comprehensive filtering and pagination.
     
     **Authorization:**
     - Field agents: See only their own expenses
@@ -540,31 +646,44 @@ def list_expenses(
     **Filters:**
     - `ticket_id`: Filter by specific ticket
     - `assignment_id`: Filter by specific assignment
-    - `user_id`: Filter by user who incurred expense
-    - `category`: Filter by category (transport, materials, meals, etc.)
+    - `user_id`: Filter by technician who incurred expense
+    - `project_id`: Filter by project (via ticket)
+    - `category`: Filter by category (comma-separated: transport,materials,meals)
+    - `payment_method`: Filter by payment method (comma-separated)
+    - `payment_recipient_type`: Filter by recipient (agent,vendor)
     - `is_approved`: Filter by approval status
     - `is_paid`: Filter by payment status
-    - `from_date`: Filter from date (inclusive)
-    - `to_date`: Filter to date (inclusive)
-    
-    **Example:**
+    - `location_verified`: Filter by location verification
+    - `has_receipt`: Filter expenses with receipts
+    - `has_payment_details`: Filter expenses with payment details
+    - `ready_for_payment`: Filter expenses ready for payment (approved + unpaid + has payment details)
+    - `expense_date`: Filter by exact expense date
+    - `expense_date_from`: Filter from date (inclusive)
+    - `expense_date_to`: Filter to date (inclusive)
+    - `date_range`: Quick filter (today,yesterday,this_week,last_week,this_month,last_month)
+    - `search`: Search across description and notes
+    - `sort_by`: Field to sort by
+    - `sort_order`: asc or desc
+    
+    **Examples:**
     ```
-    GET /ticket-expenses?is_approved=false&category=transport&page=1&page_size=20
+    # Pending approval, transport only
+    GET /ticket-expenses?is_approved=false&category=transport
+    
+    # Ready for payment
+    GET /ticket-expenses?ready_for_payment=true
+    
+    # This week's expenses
+    GET /ticket-expenses?date_range=this_week
+    
+    # Multiple categories
+    GET /ticket-expenses?category=transport,materials&date_range=today
     ```
     """
-    expenses, total = TicketExpenseService.list_expenses(
+    expenses, total = TicketExpenseService.list_expenses_with_filters(
         db=db,
         current_user=current_user,
-        ticket_id=ticket_id,
-        assignment_id=assignment_id,
-        user_id=user_id,
-        category=category,
-        is_approved=is_approved,
-        is_paid=is_paid,
-        from_date=from_date,
-        to_date=to_date,
-        page=page,
-        page_size=page_size
+        filters=filters
     )
     
     # Build responses with user names and contextual information
@@ -592,13 +711,13 @@ def list_expenses(
         
         expense_responses.append(response)
     
-    pages = (total + page_size - 1) // page_size
+    pages = (total + filters.page_size - 1) // filters.page_size
     
     return TicketExpenseListResponse(
         expenses=expense_responses,
         total=total,
-        page=page,
-        page_size=page_size,
+        page=filters.page,
+        page_size=filters.page_size,
         pages=pages
     )
 
@@ -666,3 +785,118 @@ def get_expense_stats(
     )
     
     return stats
+
+
+# ============================================
+# EXPORT FOR PAYMENT
+# ============================================
+
+@router.post(
+    "/export-for-payment",
+    summary="Export expenses for payment (CSV)",
+    description="Export approved unpaid expenses as CSV and mark them as paid"
+)
+def export_expenses_for_payment(
+    from_date: date = Query(..., description="Start date (inclusive)"),
+    to_date: date = Query(..., description="End date (inclusive)"),
+    project_id: Optional[UUID] = Query(None, description="Filter by project"),
+    ticket_id: Optional[UUID] = Query(None, description="Filter by ticket"),
+    user_id: Optional[UUID] = Query(None, description="Filter by technician"),
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Export approved unpaid expenses for payment processing.
+    
+    **Authorization:** PM, Dispatcher, Platform Admin only
+    
+    **What it does:**
+    1. Fetches all approved + unpaid expenses in date range
+    2. Groups by user + date (one payment per user per day)
+    3. Generates CSV with payment details
+    4. **Marks all expenses as paid** (irreversible!)
+    
+    **CSV Columns:**
+    - Technician Name
+    - Phone Number
+    - Account Name
+    - Total Amount
+    - Expense Count
+    - Date
+    - Tickets Summary (detailed breakdown)
+    - Categories Summary (totals by category)
+    - Expense IDs (comma-separated UUIDs)
+    
+    **Grouping Logic:**
+    - Agent payments: Grouped by user + date
+    - Vendor payments: Separate row per expense
+    
+    **Side Effects:**
+    - All exported expenses marked as `is_paid = true`
+    - `paid_at` set to export timestamp
+    - `payment_reference` set to `CSV_EXPORT_{timestamp}_{pm_user_id}`
+    
+    **Re-export Behavior:**
+    - Safe to run multiple times
+    - Only exports newly approved expenses (already paid excluded)
+    
+    **Example:**
+    ```
+    POST /ticket-expenses/export-for-payment?from_date=2024-12-01&to_date=2024-12-08
+    ```
+    
+    **Returns:** CSV file download
+    """
+    from fastapi.responses import StreamingResponse
+    import io
+    import csv
+    
+    # Export expenses
+    csv_rows, warnings = TicketExpenseService.export_for_payment(
+        db=db,
+        from_date=from_date,
+        to_date=to_date,
+        current_user=current_user,
+        project_id=project_id,
+        ticket_id=ticket_id,
+        user_id=user_id
+    )
+    
+    # Generate CSV
+    output = io.StringIO()
+    if csv_rows:
+        fieldnames = [
+            "technician_name",
+            "phone_number",
+            "account_name",
+            "total_amount",
+            "expense_count",
+            "date",
+            "tickets_summary",
+            "categories_summary",
+            "expense_ids"
+        ]
+        
+        writer = csv.DictWriter(output, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(csv_rows)
+    
+    # Add warnings as comments at the end
+    if warnings:
+        output.write("\n# WARNINGS:\n")
+        for warning in warnings:
+            output.write(f"# {warning}\n")
+    
+    # Prepare response
+    output.seek(0)
+    filename = f"expense_payments_{from_date.isoformat()}_{to_date.isoformat()}_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}.csv"
+    
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={
+            "Content-Disposition": f"attachment; filename={filename}",
+            "X-Export-Count": str(len(csv_rows)),
+            "X-Warnings-Count": str(len(warnings))
+        }
+    )

src/app/schemas/filters.py

@@ -194,3 +194,33 @@ class InventoryFilters(BaseListFilters):
     is_active: Optional[bool] = Field(None, description="Filter active/inactive items")
     has_serial_numbers: Optional[bool] = Field(None, description="Filter items with serial numbers")
     is_fully_distributed: Optional[bool] = Field(None, description="Filter fully distributed items")
+
+
+class ExpenseFilters(BaseListFilters):
+    """Comprehensive expense filtering - ALL FIELDS VERIFIED"""
+    # UUID filters
+    ticket_id: Optional[UUID] = Field(None, description="Filter by ticket")
+    assignment_id: Optional[UUID] = Field(None, description="Filter by assignment")
+    user_id: Optional[UUID] = Field(None, description="Filter by technician who incurred expense")
+    project_id: Optional[UUID] = Field(None, description="Filter by project (via ticket)")
+    
+    # Multi-value filters
+    category: Optional[List[str]] = Field(None, description="Filter by category: transport,materials,meals,accommodation,other")
+    payment_method: Optional[List[str]] = Field(None, description="Filter by payment method: send_money,till_number,paybill,pochi_la_biashara,bank_transfer,cash")
+    payment_recipient_type: Optional[List[str]] = Field(None, description="Filter by recipient: agent,vendor")
+    
+    # Date filters
+    expense_date: Optional[date] = Field(None, description="Filter by exact expense date")
+    expense_date_from: Optional[date] = Field(None, description="Expense from date (inclusive)")
+    expense_date_to: Optional[date] = Field(None, description="Expense to date (inclusive)")
+    
+    # Boolean filters
+    is_approved: Optional[bool] = Field(None, description="Filter by approval status")
+    is_paid: Optional[bool] = Field(None, description="Filter by payment status")
+    location_verified: Optional[bool] = Field(None, description="Filter by location verification")
+    has_receipt: Optional[bool] = Field(None, description="Filter expenses with receipt documents")
+    has_payment_details: Optional[bool] = Field(None, description="Filter expenses with payment details set")
+    ready_for_payment: Optional[bool] = Field(None, description="Filter expenses ready for payment (approved + unpaid + has payment details)")
+    
+    # Quick date filters (convenience)
+    date_range: Optional[str] = Field(None, description="Quick date filter: today,yesterday,this_week,last_week,this_month,last_month")

src/app/schemas/ticket_expense.py

@@ -150,6 +150,11 @@ class TicketExpenseCreate(BaseModel):
     receipt_document_id: Optional[UUID] = Field(None, description="ID of receipt document")
     notes: Optional[str] = Field(None, max_length=2000, description="Additional notes")
     
+    # Payment routing (optional - defaults to agent's financial account if not provided)
+    payment_recipient_type: Optional[PaymentRecipientType] = Field(None, description="Who receives payment: agent (default) or vendor")
+    payment_method: Optional[PaymentMethod] = Field(None, description="Payment method (auto-populated from financial account if not provided)")
+    payment_details: Optional[dict] = Field(None, description="Payment details (auto-populated from financial account if not provided, or vendor details if paying vendor)")
+    
     @field_validator('category')
     @classmethod
     def validate_category(cls, v):

src/app/services/ticket_expense_service.py

@@ -178,6 +178,14 @@ class TicketExpenseService:
             notes=data.notes,
         )
         
+        # Auto-populate payment details
+        expense = TicketExpenseService._populate_payment_details(
+            db=db,
+            expense=expense,
+            data=data,
+            current_user=current_user
+        )
+        
         db.add(expense)
         db.commit()
         db.refresh(expense)
@@ -873,3 +881,514 @@ class TicketExpenseService:
         
         # No location verification found
         return False, f"Not verified: No GPS location found for {expense_date}. Manual review required."
+    
+    # ============================================
+    # PAYMENT DETAILS AUTO-POPULATION (PRIVATE)
+    # ============================================
+    
+    @staticmethod
+    def _populate_payment_details(
+        db: Session,
+        expense: TicketExpense,
+        data: TicketExpenseCreate,
+        current_user: User
+    ) -> TicketExpense:
+        """
+        Auto-populate payment details from user's financial account or use provided vendor details.
+        
+        Logic:
+        - If payment details provided (vendor payment): Use them as-is
+        - If not provided (agent payment): Auto-populate from user's primary financial account
+        - If no financial account: Leave null (PM will handle manually)
+        
+        Args:
+            db: Database session
+            expense: Expense object to populate
+            data: Creation data
+            current_user: User creating expense
+            
+        Returns:
+            Expense with payment details populated
+        """
+        from app.models.user_financial_account import UserFinancialAccount
+        
+        # If payment details provided from frontend (vendor payment), use them
+        if data.payment_recipient_type and data.payment_method and data.payment_details:
+            expense.payment_recipient_type = data.payment_recipient_type.value
+            expense.payment_method = data.payment_method.value
+            expense.payment_details = data.payment_details
+            logger.info(
+                f"Using provided payment details for expense: "
+                f"recipient_type={data.payment_recipient_type.value}, "
+                f"method={data.payment_method.value}"
+            )
+            return expense
+        
+        # Otherwise, auto-populate from user's financial account (agent payment)
+        financial_account = db.query(UserFinancialAccount).filter(
+            UserFinancialAccount.user_id == current_user.id,
+            UserFinancialAccount.is_primary == True,
+            UserFinancialAccount.is_active == True,
+            UserFinancialAccount.deleted_at.is_(None)
+        ).first()
+        
+        if not financial_account:
+            logger.warning(
+                f"No primary financial account found for user {current_user.id}. "
+                f"Expense created without payment details."
+            )
+            return expense
+        
+        # Set recipient type to agent
+        expense.payment_recipient_type = "agent"
+        
+        # Map payout method to payment method
+        if financial_account.payout_method == "mobile_money":
+            expense.payment_method = "send_money"
+            expense.payment_details = {
+                "phone_number": financial_account.mobile_money_phone,
+                "recipient_name": financial_account.mobile_money_account_name or current_user.name
+            }
+            logger.info(
+                f"Auto-populated mobile money payment details for user {current_user.id}: "
+                f"phone={financial_account.mobile_money_phone}"
+            )
+        
+        elif financial_account.payout_method == "bank_transfer":
+            expense.payment_method = "bank_transfer"
+            expense.payment_details = {
+                "bank_name": financial_account.bank_name,
+                "account_number": financial_account.bank_account_number,
+                "account_name": financial_account.bank_account_name,
+                "branch": financial_account.bank_branch
+            }
+            logger.info(
+                f"Auto-populated bank transfer payment details for user {current_user.id}: "
+                f"bank={financial_account.bank_name}"
+            )
+        
+        else:
+            # Unsupported payout method, leave null
+            logger.warning(
+                f"Unsupported payout method '{financial_account.payout_method}' "
+                f"for user {current_user.id}. Expense created without payment details."
+            )
+        
+        return expense
+
+    # ============================================
+    # CSV EXPORT FOR PAYMENT
+    # ============================================
+    
+    @staticmethod
+    def export_for_payment(
+        db: Session,
+        from_date: date,
+        to_date: date,
+        current_user: User,
+        project_id: Optional[UUID] = None,
+        ticket_id: Optional[UUID] = None,
+        user_id: Optional[UUID] = None
+    ) -> Tuple[List[dict], List[str]]:
+        """
+        Export approved unpaid expenses grouped by user+date for payment processing.
+        Marks all exported expenses as paid.
+        
+        Args:
+            db: Database session
+            from_date: Start date (inclusive)
+            to_date: End date (inclusive)
+            current_user: User performing export (PM/Dispatcher/Admin)
+            project_id: Optional project filter
+            ticket_id: Optional ticket filter
+            user_id: Optional user filter
+            
+        Returns:
+            Tuple of (csv_rows, warnings)
+            - csv_rows: List of dicts with payment data
+            - warnings: List of warning messages
+            
+        Raises:
+            HTTPException: If not authorized
+        """
+        from app.models.user_financial_account import UserFinancialAccount
+        from app.models.ticket import Ticket
+        from collections import defaultdict
+        
+        # Authorization: Only PM, dispatcher, or platform admin
+        if current_user.role not in [
+            AppRole.PLATFORM_ADMIN,
+            AppRole.PROJECT_MANAGER,
+            AppRole.DISPATCHER
+        ]:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Not authorized to export expenses for payment"
+            )
+        
+        # Fetch approved unpaid expenses
+        query = db.query(TicketExpense).options(
+            joinedload(TicketExpense.incurred_by_user),
+            joinedload(TicketExpense.ticket),
+            joinedload(TicketExpense.assignment)
+        ).filter(
+            TicketExpense.is_approved == True,
+            TicketExpense.is_paid == False,
+            TicketExpense.expense_date >= from_date,
+            TicketExpense.expense_date <= to_date,
+            TicketExpense.deleted_at.is_(None)
+        )
+        
+        # Apply optional filters
+        if project_id:
+            query = query.join(Ticket).filter(Ticket.project_id == project_id)
+        if ticket_id:
+            query = query.filter(TicketExpense.ticket_id == ticket_id)
+        if user_id:
+            query = query.filter(TicketExpense.incurred_by_user_id == user_id)
+        
+        expenses = query.all()
+        
+        if not expenses:
+            return [], ["No approved unpaid expenses found in the specified date range"]
+        
+        # Group expenses by user_id + expense_date
+        grouped = defaultdict(list)
+        for expense in expenses:
+            # For vendor payments, group separately (no user grouping)
+            if expense.payment_recipient_type == "vendor":
+                key = f"vendor_{expense.id}"
+            else:
+                key = (expense.incurred_by_user_id, expense.expense_date)
+            grouped[key].append(expense)
+        
+        # Build CSV rows
+        csv_rows = []
+        warnings = []
+        payment_reference = f"CSV_EXPORT_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}_{current_user.id}"
+        
+        for key, group_expenses in grouped.items():
+            # Skip if no expenses in group
+            if not group_expenses:
+                continue
+            
+            first_expense = group_expenses[0]
+            
+            # Handle vendor payments separately
+            if first_expense.payment_recipient_type == "vendor":
+                row = TicketExpenseService._build_vendor_payment_row(
+                    expense=first_expense,
+                    warnings=warnings
+                )
+                if row:
+                    csv_rows.append(row)
+                continue
+            
+            # Handle agent payments
+            user = first_expense.incurred_by_user
+            expense_date = first_expense.expense_date
+            
+            # Get payment details from first expense (should be same for all in group)
+            phone_number = None
+            account_name = None
+            
+            if first_expense.payment_details:
+                phone_number = first_expense.payment_details.get("phone_number") or \
+                              first_expense.payment_details.get("account_number")
+                account_name = first_expense.payment_details.get("recipient_name") or \
+                              first_expense.payment_details.get("account_name")
+            
+            # If no payment details, try to get from financial account
+            if not phone_number or not account_name:
+                financial_account = db.query(UserFinancialAccount).filter(
+                    UserFinancialAccount.user_id == user.id,
+                    UserFinancialAccount.is_primary == True,
+                    UserFinancialAccount.is_active == True,
+                    UserFinancialAccount.deleted_at.is_(None)
+                ).first()
+                
+                if financial_account:
+                    if financial_account.payout_method == "mobile_money":
+                        phone_number = financial_account.mobile_money_phone
+                        account_name = financial_account.mobile_money_account_name or user.name
+                    elif financial_account.payout_method == "bank_transfer":
+                        phone_number = financial_account.bank_account_number
+                        account_name = financial_account.bank_account_name
+            
+            # Skip if still no payment details
+            if not phone_number or not account_name:
+                warnings.append(
+                    f"Skipped {len(group_expenses)} expense(s) for {user.name} on {expense_date}: "
+                    f"No payment details found"
+                )
+                continue
+            
+            # Calculate totals
+            total_amount = sum(e.total_cost for e in group_expenses)
+            expense_count = len(group_expenses)
+            expense_ids = [str(e.id) for e in group_expenses]
+            
+            # Build tickets summary
+            tickets_summary = TicketExpenseService._build_tickets_summary(group_expenses)
+            
+            # Build categories summary
+            categories_summary = TicketExpenseService._build_categories_summary(group_expenses)
+            
+            # Build CSV row
+            csv_rows.append({
+                "technician_name": user.name,
+                "phone_number": phone_number,
+                "account_name": account_name,
+                "total_amount": float(total_amount),
+                "expense_count": expense_count,
+                "date": expense_date.isoformat(),
+                "tickets_summary": tickets_summary,
+                "categories_summary": categories_summary,
+                "expense_ids": ",".join(expense_ids)
+            })
+        
+        # Mark all expenses as paid (in transaction)
+        try:
+            for expense in expenses:
+                expense.is_paid = True
+                expense.paid_at = datetime.utcnow()
+                expense.paid_to_user_id = expense.incurred_by_user_id
+                expense.payment_reference = payment_reference
+            
+            db.commit()
+            
+            logger.info(
+                f"Exported {len(expenses)} expenses for payment by user {current_user.id}. "
+                f"Generated {len(csv_rows)} payment rows. Reference: {payment_reference}"
+            )
+        except Exception as e:
+            db.rollback()
+            logger.error(f"Failed to mark expenses as paid: {str(e)}")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Failed to mark expenses as paid"
+            )
+        
+        return csv_rows, warnings
+    
+    @staticmethod
+    def _build_vendor_payment_row(expense: TicketExpense, warnings: List[str]) -> Optional[dict]:
+        """Build CSV row for vendor payment"""
+        if not expense.payment_details:
+            warnings.append(
+                f"Skipped vendor expense {expense.id}: No payment details"
+            )
+            return None
+        
+        phone_number = expense.payment_details.get("phone_number") or \
+                      expense.payment_details.get("till_number") or \
+                      expense.payment_details.get("account_number")
+        account_name = expense.payment_details.get("recipient_name") or \
+                      expense.payment_details.get("business_name") or \
+                      expense.payment_details.get("account_name")
+        
+        if not phone_number or not account_name:
+            warnings.append(
+                f"Skipped vendor expense {expense.id}: Incomplete payment details"
+            )
+            return None
+        
+        # Build ticket summary for single expense
+        ticket_ref = expense.ticket.ticket_reference if expense.ticket else "Unknown"
+        tickets_summary = f"Ticket #{ticket_ref} (1 expense: {expense.category.title()} {float(expense.total_cost)} KES)"
+        
+        return {
+            "technician_name": f"VENDOR: {account_name}",
+            "phone_number": phone_number,
+            "account_name": account_name,
+            "total_amount": float(expense.total_cost),
+            "expense_count": 1,
+            "date": expense.expense_date.isoformat(),
+            "tickets_summary": tickets_summary,
+            "categories_summary": f"{expense.category.title()}: {float(expense.total_cost)} (1x)",
+            "expense_ids": str(expense.id)
+        }
+    
+    @staticmethod
+    def _build_tickets_summary(expenses: List[TicketExpense]) -> str:
+        """Build detailed tickets summary for CSV"""
+        from collections import defaultdict
+        
+        # Group by ticket
+        by_ticket = defaultdict(list)
+        for expense in expenses:
+            ticket_ref = expense.ticket.ticket_reference if expense.ticket else "Unknown"
+            by_ticket[ticket_ref].append(expense)
+        
+        # Build summary for each ticket
+        ticket_summaries = []
+        for ticket_ref, ticket_expenses in by_ticket.items():
+            expense_details = []
+            ticket_total = Decimal(0)
+            
+            for expense in ticket_expenses:
+                expense_details.append(
+                    f"{expense.category.title()} {float(expense.total_cost)}"
+                )
+                ticket_total += expense.total_cost
+            
+            summary = f"Ticket #{ticket_ref} ({len(ticket_expenses)} expenses: {', '.join(expense_details)} = {float(ticket_total)} KES)"
+            ticket_summaries.append(summary)
+        
+        return " | ".join(ticket_summaries)
+    
+    @staticmethod
+    def _build_categories_summary(expenses: List[TicketExpense]) -> str:
+        """Build categories summary for CSV"""
+        from collections import defaultdict
+        
+        # Group by category
+        by_category = defaultdict(list)
+        for expense in expenses:
+            by_category[expense.category].append(expense)
+        
+        # Build summary for each category
+        category_summaries = []
+        for category, cat_expenses in by_category.items():
+            total = sum(e.total_cost for e in cat_expenses)
+            count = len(cat_expenses)
+            category_summaries.append(
+                f"{category.title()}: {float(total)} ({count}x)"
+            )
+        
+        return " | ".join(category_summaries)
+
+    
+    @staticmethod
+    def list_expenses_with_filters(
+        db: Session,
+        current_user: User,
+        filters: 'ExpenseFilters'
+    ) -> Tuple[List[TicketExpense], int]:
+        """
+        List expenses with comprehensive filtering support.
+        
+        Args:
+            db: Database session
+            current_user: Current user
+            filters: ExpenseFilters object with all filter criteria
+            
+        Returns:
+            Tuple of (expenses, total_count)
+        """
+        from app.schemas.filters import ExpenseFilters
+        from app.models.ticket import Ticket
+        
+        query = db.query(TicketExpense).options(
+            joinedload(TicketExpense.incurred_by_user),
+            joinedload(TicketExpense.approved_by_user),
+            joinedload(TicketExpense.paid_to_user),
+            joinedload(TicketExpense.ticket),
+            joinedload(TicketExpense.assignment)
+        ).filter(
+            TicketExpense.deleted_at.is_(None)
+        )
+        
+        # Authorization filter
+        if current_user.role == AppRole.FIELD_AGENT:
+            # Field agents see only their own expenses
+            query = query.filter(TicketExpense.incurred_by_user_id == current_user.id)
+        
+        # UUID filters
+        if filters.ticket_id:
+            query = query.filter(TicketExpense.ticket_id == filters.ticket_id)
+        
+        if filters.assignment_id:
+            query = query.filter(TicketExpense.ticket_assignment_id == filters.assignment_id)
+        
+        if filters.user_id:
+            query = query.filter(TicketExpense.incurred_by_user_id == filters.user_id)
+        
+        if filters.project_id:
+            query = query.join(Ticket).filter(Ticket.project_id == filters.project_id)
+        
+        # Multi-value filters
+        if filters.category:
+            query = query.filter(TicketExpense.category.in_(filters.category))
+        
+        if filters.payment_method:
+            query = query.filter(TicketExpense.payment_method.in_(filters.payment_method))
+        
+        if filters.payment_recipient_type:
+            query = query.filter(TicketExpense.payment_recipient_type.in_(filters.payment_recipient_type))
+        
+        # Date filters
+        if filters.expense_date:
+            query = query.filter(TicketExpense.expense_date == filters.expense_date)
+        
+        if filters.expense_date_from:
+            query = query.filter(TicketExpense.expense_date >= filters.expense_date_from)
+        
+        if filters.expense_date_to:
+            query = query.filter(TicketExpense.expense_date <= filters.expense_date_to)
+        
+        # Boolean filters
+        if filters.is_approved is not None:
+            query = query.filter(TicketExpense.is_approved == filters.is_approved)
+        
+        if filters.is_paid is not None:
+            query = query.filter(TicketExpense.is_paid == filters.is_paid)
+        
+        if filters.location_verified is not None:
+            query = query.filter(TicketExpense.location_verified == filters.location_verified)
+        
+        if filters.has_receipt is not None:
+            if filters.has_receipt:
+                query = query.filter(TicketExpense.receipt_document_id.isnot(None))
+            else:
+                query = query.filter(TicketExpense.receipt_document_id.is_(None))
+        
+        if filters.has_payment_details is not None:
+            if filters.has_payment_details:
+                query = query.filter(TicketExpense.payment_details.isnot(None))
+            else:
+                query = query.filter(TicketExpense.payment_details.is_(None))
+        
+        if filters.ready_for_payment:
+            # Approved + unpaid + has payment details
+            query = query.filter(
+                and_(
+                    TicketExpense.is_approved == True,
+                    TicketExpense.is_paid == False,
+                    TicketExpense.payment_details.isnot(None)
+                )
+            )
+        
+        # Search filter
+        if filters.search:
+            search_term = f"%{filters.search}%"
+            query = query.filter(
+                or_(
+                    TicketExpense.description.ilike(search_term),
+                    TicketExpense.notes.ilike(search_term),
+                    TicketExpense.category.ilike(search_term)
+                )
+            )
+        
+        # Get total count
+        total = query.count()
+        
+        # Sorting
+        sort_column = TicketExpense.expense_date  # default
+        if filters.sort_by:
+            if hasattr(TicketExpense, filters.sort_by):
+                sort_column = getattr(TicketExpense, filters.sort_by)
+        
+        if filters.sort_order == "asc":
+            query = query.order_by(sort_column.asc())
+        else:
+            query = query.order_by(sort_column.desc())
+        
+        # Secondary sort by created_at
+        query = query.order_by(TicketExpense.created_at.desc())
+        
+        # Apply pagination
+        offset = (filters.page - 1) * filters.page_size
+        expenses = query.offset(offset).limit(filters.page_size).all()
+        
+        return expenses, total