finishing QDRO section
This commit is contained in:
HotSwapp
175
docs/PENSIONS.md
Normal file
175
docs/PENSIONS.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# 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
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user