harvest-logger

# harvest-logger

Record and analyze crop harvest yields with quality grading, field tracking, and storage destination logging.

## When to Use

- Recording a new harvest entry (crop, field, date, quantity, grade, storage)
- Checking total yield for a specific crop over a date range
- Filtering harvest history by grade (Grade A only, reject entries)
- Viewing yield trend charts in the Analytics page
- Comparing season-over-season performance
- Exporting harvest data to CSV

## Key Concepts

### Harvest Entry

Each entry records:
- **Crop**: what was picked (Tomatoes, Beans, Lettuce, etc.)
- **Field**: where it came from (North Field, Greenhouse 1, etc.)
- **Date**: harvest date
- **Quantity + Unit**: amount in kg, lb, bushel, lug, or count
- **Grade**: A (premium), B (standard), C (substandard), Reject, Ungraded
- **Storage**: where it was taken (Cooler 1, Barn Storage, Farmers Market, etc.)
- **Labor hours**: optional time tracking
- **Notes**: optional observations

### Grade Scale

| Grade | Meaning |
|---|---|
| A | Premium - meets full market standards |
| B | Standard - minor defects, still marketable |
| C | Substandard - significant defects, reduced price |
| Reject | Not marketable, discarded or composted |
| Ungraded | No quality assessment performed |

### Analytics

The Analytics page uses Chart.js to show:
- Yield trend (daily or weekly totals per crop)
- Grade breakdown per crop (stacked bar chart)
- Field performance comparison (horizontal bar chart)
- Top crops by total volume

All analytics support date range filtering.

## API Quick Reference

```bash
# Log a harvest
curl -X POST http://localhost:3003/api/harvests \
  -H "Content-Type: application/json" \
  -d '{
    "crop_id": "...",
    "field_id": "...",
    "harvest_date": "2025-04-18",
    "quantity": 142,
    "unit": "kg",
    "grade": "A",
    "storage_id": "...",
    "labor_hours": 2.5,
    "notes": "Good color, early morning harvest"
  }'

# List harvests (filtered)
curl "http://localhost:3003/api/harvests?crop_id=...&from=2025-04-01&to=2025-04-30"

# Filter by grade
curl "http://localhost:3003/api/harvests?grade=reject"

# Get yield by crop (analytics)
curl "http://localhost:3003/api/analytics/yield-by-crop?from=2025-04-01&to=2025-04-30"

# Get yield trend for a crop
curl "http://localhost:3003/api/analytics/yield-trend?crop_id=...&granularity=week"

# Get grade breakdown
curl "http://localhost:3003/api/analytics/grade-breakdown?from=2025-04-01"

# List crops
curl http://localhost:3003/api/crops

# List fields
curl http://localhost:3003/api/fields

# List storage locations
curl http://localhost:3003/api/storage
```

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| PORT | HTTP port | 3003 |
| DATA_DIR | SQLite directory | ./data |
| AUTH_PASSWORD | Optional login password | (empty) |
| NODE_ENV | development or production | development |
| SESSION_SECRET | Required in production | (required) |
| DEFAULT_TIMEZONE | Initial timezone for settings | America/Chicago |

## Troubleshooting

### Analytics shows 0 for a crop

Verify harvests exist for the date range and crop: `GET /api/harvests?crop_id=...`. Analytics endpoints require at least one harvest record within the requested date range.

### Grade breakdown percentages do not add up

Ungraded entries are included in the total but shown separately. If you want 100% from A/B/C/Reject only, filter out ungraded entries in the frontend or exclude `grade=ungraded` from your query.

### Export CSV returns wrong date range

The CSV export on the Harvests page respects the active filters. Set the date range filter before clicking Export CSV.