health-records

# health-records

Log detailed health events per animal with follow-up dates, cost tracking, and exportable history.

## When to Use

- Recording a vet visit with diagnosis notes and cost
- Logging a treatment with dosage and follow-up date
- Adding an injury or observation note to an animal's history
- Viewing all health events for a specific animal in date order
- Filtering events across the herd by type or date range
- Exporting health event history to CSV for record-keeping

## Health Event Types

| Type | When to Use |
|---|---|
| vaccination | Any vaccine administered (also creates a vaccination record) |
| treatment | Medication, wound care, foot bath, spraying |
| vet_visit | Scheduled or emergency veterinary examination |
| injury | Wound, fracture, bite, or other physical injury |
| observation | Routine note with no intervention (weight check, behavioral note) |

## API Reference

```bash
# List all health events (newest first)
curl http://localhost:3002/api/health-events

# Filter by animal
curl "http://localhost:3002/api/health-events?animal_id={id}"

# Filter by event type
curl "http://localhost:3002/api/health-events?event_type=vet_visit"

# Filter by date range
curl "http://localhost:3002/api/health-events?from=2025-01-01&to=2025-04-30"

# Create a health event
curl -X POST http://localhost:3002/api/health-events \
  -H "Content-Type: application/json" \
  -d '{
    "animal_id": "...",
    "event_type": "vet_visit",
    "event_date": "2025-04-12",
    "title": "Pre-calving vet check",
    "description": "Checked position of calf. Normal presentation. Estimated delivery in 14-18 days.",
    "administered_by": "Dr. Carter",
    "cost_usd": 65.00,
    "follow_up_date": "2025-04-25"
  }'

# Update a health event
curl -X PUT http://localhost:3002/api/health-events/{id} \
  -H "Content-Type: application/json" \
  -d '{"description":"Updated notes after follow-up."}'

# Delete a health event
curl -X DELETE http://localhost:3002/api/health-events/{id}

# Get animal timeline (all event types merged)
curl http://localhost:3002/api/animals/{id}/timeline
```

## Follow-up Dates

When `follow_up_date` is set on a health event, the daily cron job creates a `follow_up_due` notification when the date is within the reminder window.

To set a follow-up:
```json
{
  "follow_up_date": "2025-04-21"
}
```

The notification will appear as: "Patches #S003 - Follow-up due: Foot rot treatment check"

## Cost Tracking

`cost_usd` stores the cost of each event as a decimal. The Reports page aggregates:
- Total vet cost per animal (YTD)
- Total vet cost by event type
- Overall vet spending across the herd

If cost is zero (observation, routine check), pass `0` or omit the field.

## Export

The Health Events page provides a "Export CSV" button that downloads all visible events with columns: Date, Animal, Tag, Event Type, Title, Administered By, Cost, Follow-up Date.

Using the API directly:
```bash
# All events as JSON
curl "http://localhost:3002/api/health-events?limit=9999" > health-export.json
```

## Timeline vs Health Events List

The `GET /api/animals/{id}/timeline` endpoint merges:
- Health events
- Vaccination records
- Weight records
- Breeding events

All sorted by date descending. This is the data source for the Animal Detail page timeline view.

The `GET /api/health-events` endpoint returns only health events (not weights or vaccinations) and supports cross-animal filtering.

## Troubleshooting

### Follow-up notification not appearing

1. Confirm `follow_up_date` is set on the event: `GET /api/health-events/{id}`
2. Confirm `follow_up_date` is within the next `REMINDER_DAYS_AHEAD` days (default 7)
3. The cron job runs at 06:00 daily - check logs for `follow_up_due` processing output
4. Check notifications: `GET /api/notifications` - the item may be present but already dismissed

### Event cost not appearing in reports

Cost must be set at event creation or via PUT update. Zero values display correctly. Null values are excluded from cost totals in the Reports page.

### Timeline missing events

The timeline endpoint queries four tables. If a specific event type is missing, verify the record exists in its own endpoint: `GET /api/vaccinations?animal_id=...` or `GET /api/weights?animal_id=...`.