# Total Amount Till Today API - How It Works

## Endpoint
```
GET /collection_details
```

## Authentication
Requires collection agent authentication via Bearer token.

---

## What is `total_amount_till_today`?

`total_amount_till_today` is a calculated field that represents **the total amount that should have been collected from the loan start date up to today** (inclusive).

### Calculation Logic

```javascript
// For daily loans:
// 1. Start date = next_due_date (or loan_date if next_due_date is not set)
// 2. End date = today
// 3. Calculate days from start date to today (inclusive)
// 4. total_amount_till_today = days × per_due_amount
```

### Formula
```
total_amount_till_today = days_from_start_to_today × per_due_amount
remaining_amount_till_today = total_amount_till_today - total_of_all_receipts
```

Where:
- `days_from_start_to_today` = Number of days from `next_due_date` (or `loan_date`) to today (inclusive)
- `per_due_amount` = Amount per due payment (from `loan_entry.per_due_amt`)
- `total_of_all_receipts` = Sum of all receipts based on `loan_id` and `customer_id` (only receipts up to today, excludes future-dated receipts)

**Important**: Receipts are SUBTRACTED from `total_amount_till_today` to calculate `remaining_amount_till_today`. Receipts represent payments made, so they reduce the amount due.

---

## cURL Example

```bash
curl -X GET "http://192.168.1.3:3000/collection_details" \
  -H "Authorization: Bearer YOUR_AGENT_JWT_TOKEN" \
  -H "Accept: application/json"
```

### With Area Filter
```bash
curl -X GET "http://192.168.1.3:3000/collection_details?area=Erode" \
  -H "Authorization: Bearer YOUR_AGENT_JWT_TOKEN" \
  -H "Accept: application/json"
```

---

## Response Format

```json
{
  "status": "success",
  "message": "Collection details retrieved successfully",
  "data": {
    "customers": [
      {
        "loan_id": "DL2025001",
        "customer_name": "John Doe",
        "customer_mobile": "9876543210",
        "next_due_date": "2025-01-10",
        "per_due_amount": 100.00,
        "collection_details": {
          "previous_unpaid_amount": 0.00,
          "today_expected_amount": 100.00,
          "total_collection_amount": 100.00,
          "total_amount_till_today": 1200.00,
          "total_collected_amount": 800.00,
          "collected_today_amount": 100.00,
          "remaining_amount_till_today": 400.00,
          "total_pending_amount": 0.00,
          "remaining_pending": 0.00,
          "collection_status": "FULLY_PAID",
          "payment_type": "FULL_PAID"
        }
      }
    ],
    "summary": {
      "total_customers": 50,
      "total_collection_amount": 5000.00,
      "total_amount_till_today": 60000.00,
      "total_collected_amount": 45000.00,
      "collected_today_amount": 5000.00,
      "remaining_amount_till_today": 15000.00,
      "total_pending_amount": 0.00,
      "remaining_pending": 0.00
    }
  }
}
```

---

## Field Explanation

### `total_amount_till_today`
- **Type**: Decimal (amount in currency)
- **Description**: Total amount that should have been collected from loan start to today (BASE amount, before subtracting receipts)
- **Calculation**: `days from start to today × per_due_amount`
- **Example**: 
  - If loan started 12 days ago and per_due_amount is ₹100
  - Then `total_amount_till_today = 12 × 100 = ₹1200`
  - This is the target amount that should be collected (receipts are subtracted from this to get remaining)

### Related Fields

1. **`total_collected_amount`**
   - Total amount actually collected from all receipts (from loan start to today)
   - Only counts receipts up to today (excludes future-dated receipts)

2. **`remaining_amount_till_today`**
   - Remaining amount that should have been collected but hasn't
   - Formula: `total_amount_till_today - total_collected_amount`
   - Example: If `total_amount_till_today = ₹1200` and `total_collected_amount = ₹800`, then `remaining_amount_till_today = ₹400`

3. **`total_collection_amount`**
   - Total amount needed to collect TODAY (different from `total_amount_till_today`)
   - Formula: `previous_unpaid_amount + today_expected_amount`
   - This is what the agent needs to collect today, not the cumulative total

---

## Example Scenarios

### Scenario 1: New Loan (12 Days Old, No Receipts)
```
Loan Start Date: 2025-01-01
Today: 2025-01-13
Next Due Date: 2025-01-02
Per Due Amount: ₹100
Total Receipts: ₹0

Calculation:
- Days from start to today: 12 days (Jan 2 to Jan 13, inclusive)
- total_amount_till_today = 12 × ₹100 = ₹1,200 (base amount)
- total_collected_amount = ₹0 (no receipts)
- remaining_amount_till_today = ₹1,200 - ₹0 = ₹1,200
```

### Scenario 2: Loan with Collections
```
Loan Start Date: 2025-01-01
Today: 2025-01-13
Next Due Date: 2025-01-02
Per Due Amount: ₹100
Total Receipts Collected: ₹800 (from 8 receipts)

Calculation:
- Days from start to today: 12 days (Jan 2 to Jan 13, inclusive)
- total_amount_till_today = 12 × ₹100 = ₹1,200 (base amount - what should be due)
- total_collected_amount = ₹800 (from receipts - payments made)
- remaining_amount_till_today = ₹1,200 - ₹800 = ₹400 (what's still pending)
```

### Scenario 3: Fully Paid Loan
```
Loan Start Date: 2025-01-01
Today: 2025-01-13
Next Due Date: 2025-01-02
Per Due Amount: ₹100
Total Receipts Collected: ₹1,200 (from 12 receipts)

Calculation:
- Days from start to today: 12 days (Jan 2 to Jan 13, inclusive)
- total_amount_till_today = 12 × ₹100 = ₹1,200 (base amount - what should be due)
- total_collected_amount = ₹1,200 (from receipts - payments made)
- remaining_amount_till_today = ₹1,200 - ₹1,200 = ₹0 (fully paid, nothing pending)
```

---

## Key Points

1. **Cumulative Calculation**: `total_amount_till_today` is a cumulative amount from loan start to today
2. **Fixed Target**: This value represents what should have been collected by today (doesn't change based on payments)
3. **Daily Basis**: Calculated based on number of days × per_due_amount
4. **Inclusive Dates**: Includes both start date and today in the calculation
5. **Comparison**: Compare with `total_collected_amount` to see how much is still pending

---

## Summary Statistics

The API also provides summary statistics:

```json
{
  "summary": {
    "total_amount_till_today": 60000.00,  // Sum of all customers' total_amount_till_today
    "total_collected_amount": 45000.00,   // Sum of all customers' total_collected_amount
    "remaining_amount_till_today": 15000.00, // Sum of all customers' remaining_amount_till_today
    "total_collection_amount": 5000.00,   // Total needed TODAY (different from total_amount_till_today)
    "collected_today_amount": 5000.00     // Total collected TODAY
  }
}
```

---

## Use Cases

1. **Collection Tracking**: See how much should have been collected vs. how much was actually collected
2. **Performance Analysis**: Compare `total_amount_till_today` with `total_collected_amount` to measure collection efficiency
3. **Outstanding Balance**: Use `remaining_amount_till_today` to identify customers with outstanding amounts
4. **Daily Reports**: Track daily collection progress against cumulative targets

---

## Notes

- `total_amount_till_today` is calculated based on the `next_due_date` or `loan_date` as the start point
- Only counts days up to today (excludes future dates)
- Uses `per_due_amount` from the loan entry
- This is a cumulative value, not a daily value
- The value remains constant for a given day (doesn't change when payments are made)

---

## Difference Between Fields

| Field | Description | Example |
|-------|-------------|---------|
| `total_amount_till_today` | Cumulative amount due from loan start to today | ₹1,200 (12 days × ₹100) |
| `total_collection_amount` | Amount needed to collect TODAY only | ₹100 (today's due) |
| `total_collected_amount` | Total actually collected (all time) | ₹800 (from all receipts) |
| `collected_today_amount` | Amount collected TODAY | ₹100 (from today's receipt) |
| `remaining_amount_till_today` | Remaining from cumulative total | ₹400 (₹1,200 - ₹800) |

---

## Testing

### Test the API
```bash
curl -X GET "http://192.168.1.3:3000/collection_details" \
  -H "Authorization: Bearer YOUR_AGENT_JWT_TOKEN" \
  -H "Accept: application/json" | python3 -m json.tool
```

### Check a Specific Customer
```bash
curl -X GET "http://192.168.1.3:3000/collection_details?area=Erode" \
  -H "Authorization: Bearer YOUR_AGENT_JWT_TOKEN" \
  -H "Accept: application/json" | python3 -m json.tool | grep -A 20 "total_amount_till_today"
```