delphi-database/docs/PENSIONS.md

# Pensions API Reference (Fields and Sorting)

This document summarizes key fields for pensions-related endpoints and the allowed sort fields for each list.

## Models (key fields)

- Pension
  - file_no (string), version (string), plan_id (string), plan_name (string)
  - title, first, last, birth, race, sex
  - info, valu, accrued, vested_per, start_age
  - cola, max_cola, withdrawal, pre_dr, post_dr, tax_rate

- PensionSchedule
  - id, file_no, version, vests_on (date), vests_at (number), frequency (string)

- MarriageHistory
  - id, file_no, version, spouse_name (string), notes (text)
  - married_from (date), married_to (date), married_years (number)
  - service_from (date), service_to (date), service_years (number)
  - marital_percent (number)

- DeathBenefit
  - id, file_no, version
  - beneficiary_name (string), benefit_type (string), notes (text)
  - lump1, lump2, growth1, growth2, disc1, disc2 (numbers)
  - created_at, updated_at (timestamps)

- SeparationAgreement
  - id, file_no, version, agreement_date (date), terms (text), notes (text)

## Allowed sort fields

- Schedules (`GET /api/pensions/schedules`)
  - id, file_no, version, vests_on, vests_at

- Marriages (`GET /api/pensions/marriages`)
  - id, file_no, version, married_from, married_to, marital_percent, service_from, service_to

- Death benefits (`GET /api/pensions/death-benefits`)
  - id, file_no, version, lump1, lump2, growth1, growth2, disc1, disc2, created

- Separations (`GET /api/pensions/separations`)
  - id, file_no, version, agreement_date

## Notes

- All list endpoints support `skip`, `limit`, `sort_by`, `sort_dir`, and `include_total`.
- Whitelisted fields only are accepted for sorting; unknown fields fall back to defaults.
- Tokenized search semantics: AND across tokens, OR across listed fields. Matching is case-insensitive and trims simple punctuation.
- Sorting behavior: for string columns, sorting is case-insensitive (performed on lowercased values) for stable ordering.
- Basic tokenized search is available per endpoint:
  - Schedules: version, frequency
  - Marriages: version, spouse_name, notes
  - Death benefits: version, beneficiary_name, benefit_type, notes
  - Separations: version, terms, notes

## Examples (curl)

Schedules with filters, sorting, include_total:
```bash
curl \
  "http://localhost:6920/api/pensions/schedules?file_no=F-1&version=02&vests_at_min=10&vests_at_max=50&sort_by=vests_on&sort_dir=asc&include_total=true"
```

Marriages with tokenized search and sorting:
```bash
curl \
  "http://localhost:6920/api/pensions/marriages?file_no=F-1&search=Gamma&sort_by=married_from&sort_dir=desc"
```

Death benefits with numeric ranges and sorting:
```bash
curl \
  "http://localhost:6920/api/pensions/death-benefits?file_no=F-1&lump1_min=150&lump1_max=250&growth1_min=1.5&growth1_max=2.5&disc1_min=0.55&disc1_max=0.65&sort_by=lump1&sort_dir=desc"
```

Separations with date range filter and sorting:
```bash
curl \
  "http://localhost:6920/api/pensions/separations?file_no=F-1&start=2024-01-01&end=2024-03-31&sort_by=agreement_date&sort_dir=asc"
```

Nested detail with independent paging/sorting per section:
```bash
curl \
  "http://localhost:6920/api/pensions/F-1/detail?s_sort_by=vests_on&s_limit=5&m_sort_by=married_from&d_sort_by=lump1&sep_sort_by=agreement_date"
```

## Example responses (shapes)

Schedules as a plain list (default):
```json
[
  {
    "id": 1,
    "file_no": "F-1",
    "version": "01",
    "vests_on": "2024-01-01",
    "vests_at": 10.0,
    "frequency": "Monthly"
  },
  {
    "id": 2,
    "file_no": "F-1",
    "version": "01",
    "vests_on": "2024-02-01",
    "vests_at": 20.0,
    "frequency": "Monthly"
  }
]
```

Schedules with include_total=true:
```json
{
  "items": [
    {
      "id": 1,
      "file_no": "F-1",
      "version": "01",
      "vests_on": "2024-01-01",
      "vests_at": 10.0,
      "frequency": "Monthly"
    }
  ],
  "total": 12
}
```

Pension detail with nested lists (trimmed):
```json
{
  "pension": {
    "id": 123,
    "file_no": "F-1",
    "version": "01",
    "plan_id": "PID1",
    "plan_name": "Plan A",
    "vested_per": 50.0,
    "tax_rate": 25.0
  },
  "schedules": { "items": [/* ... */], "total": 3 },
  "marriages": { "items": [/* ... */], "total": 1 },
  "death_benefits": { "items": [/* ... */], "total": 0 },
  "separations": { "items": [/* ... */], "total": 2 }
}
```

Sample Pension record (GET /api/pensions/{pension_id}):
```json
{
  "id": 123,
  "file_no": "F-1",
  "version": "01",
  "plan_id": "PID1",
  "plan_name": "Plan A",
  "title": "Mr.",
  "first": "John",
  "last": "Doe",
  "birth": "1970-05-01",
  "race": "W",
  "sex": "M",
  "info": "Notes...",
  "valu": 100000.0,
  "accrued": 50000.0,
  "vested_per": 50.0,
  "start_age": 65,
  "cola": 2.0,
  "max_cola": 3.0,
  "withdrawal": "ANNUITY",
  "pre_dr": 4.0,
  "post_dr": 3.0,
  "tax_rate": 25.0
}
```