Porting All features from RKNN to Jetson

API.md

@@ -0,0 +1,220 @@
+# counter_dashboard.py — API Documentation
+
+## Page
+
+### `GET /`
+Renders the main dashboard HTML page (`dashboard.html`).
+
+---
+
+## API Endpoints
+
+### `GET /api/live-video`
+MJPEG streaming endpoint. Serves live frames from the path configured in `LIVE_STREAM_FRAME_PATH` (default `/dev/shm/jetson-counter/live_frame.jpg`) as `multipart/x-mixed-replace`.
+
+**Response:** JPEG stream with `--frame` boundary delimiters.
+
+---
+
+### `GET /api/current-batch`
+Returns the currently active batch's data read from `current_batch.json`.
+
+**Success response:**
+```json
+{
+  "success": true,
+  "counting_date": "2024-01-01",
+  "batch_number": 12,
+  "count": 342,
+  "start_time": "2024-01-01T14:30:00",
+  "last_detection_time": "2024-01-01T14:35:00"
+}
+```
+
+**Error response (no active batch, 200):**
+```json
+{
+  "success": false,
+  "error": "No active batch",
+  "count": 0,
+  "batch_number": null,
+  "counting_date": null
+}
+```
+
+---
+
+### `GET /api/previous-batch`
+Returns the most recently completed batch from the `batches` database table, with computed `duration_minutes`.
+
+**Success response:**
+```json
+{
+  "success": true,
+  "date": "2024-01-01",
+  "batch_number": 11,
+  "count": 287,
+  "start_time": "2024-01-01T14:00:00",
+  "end_time": "2024-01-01T14:27:00",
+  "duration_minutes": 27.0
+}
+```
+
+---
+
+### `GET /api/summary`
+Returns today, yesterday, and all-time aggregate statistics plus average per day and best day.
+
+**Success response:**
+```json
+{
+  "today": {
+    "date": "2024-01-01",
+    "total_count": 1500,
+    "total_batches": 8
+  },
+  "yesterday": {
+    "date": "2023-12-31",
+    "total_count": 1342,
+    "total_batches": 7
+  },
+  "all_time": {
+    "grand_total": 50000,
+    "grand_batches": 260,
+    "total_days": 45
+  },
+  "average_per_day": 1111.1,
+  "best_day": {
+    "date": "2023-12-15",
+    "count": 2100
+  }
+}
+```
+
+---
+
+### `GET /api/daily-data`
+Returns daily summary rows for charting.
+
+**Query params:**
+| Param  | Type | Default | Description                     |
+|--------|------|---------|---------------------------------|
+| `days` | int  | 30      | Number of days to look back     |
+
+**Response:**
+```json
+[
+  {
+    "date": "2024-01-01",
+    "total_count": 1500,
+    "total_batches": 8,
+    "avg_per_batch": 187.5
+  }
+]
+```
+
+---
+
+### `GET /api/day-detail/<date>`
+Returns all batch records for a specific `counting_date` along with summary totals.
+
+**Path params:**
+| Param  | Type   | Description            |
+|--------|--------|------------------------|
+| `date` | string | Date in `YYYY-MM-DD`   |
+
+**Success response:**
+```json
+{
+  "date": "2024-01-01",
+  "total_count": 1500,
+  "total_batches": 8,
+  "total_duration_minutes": 216.0,
+  "avg_duration_minutes": 27.0,
+  "batches": [
+    {
+      "batch_number": 1,
+      "count": 187,
+      "start_time": "2024-01-01T08:00:00",
+      "end_time": "2024-01-01T08:27:00",
+      "duration_minutes": 27.0
+    }
+  ]
+}
+```
+
+---
+
+### `GET /api/recent-batches`
+Returns the most recent batches with computed durations.
+
+**Query params:**
+| Param   | Type | Default | Description                     |
+|---------|------|---------|---------------------------------|
+| `limit` | int  | 10      | Max number of batches to return |
+
+**Response:**
+```json
+[
+  {
+    "date": "2024-01-01",
+    "batch_number": 8,
+    "count": 213,
+    "start_time": "2024-01-01T16:30:00",
+    "end_time": "2024-01-01T16:58:00",
+    "duration_minutes": 28.0
+  }
+]
+```
+
+---
+
+### `GET /api/available-dates`
+Returns all dates with data from the `daily_summaries` table, ordered by date descending.
+
+**Response:**
+```json
+[
+  {
+    "date": "2024-01-01",
+    "total_count": 1500,
+    "total_batches": 8
+  }
+]
+```
+
+---
+
+## Export Endpoints (XLSX)
+
+### `GET /api/export-daily-csv`
+Exports batch detail records for the last N days as an `.xlsx` file.
+
+**Query params:**
+| Param  | Type | Default | Description                 |
+|--------|------|---------|-----------------------------|
+| `days` | int  | 30      | Number of days to look back |
+
+**Response:** XLSX file download with columns: Date, Batch #, Count, Start Time, End Time, Duration (min).
+
+Filename format: `{SITE_NAME}_daily_records_{timestamp}.xlsx`
+
+---
+
+### `GET /api/export-day-csv/<date>`
+Exports all batch records for a single date as an `.xlsx` file.
+
+**Path params:**
+| Param  | Type   | Description          |
+|--------|--------|----------------------|
+| `date` | string | Date in `YYYY-MM-DD` |
+
+**Response:** XLSX file download with columns: Batch Number, Count, Start Time, End Time, Duration (min).
+
+Filename format: `{SITE_NAME}_day_detail_{date}.xlsx`
+
+---
+
+## Error Handling
+
+All endpoints return `{"success": false, "error": "<message>"}` with HTTP 500 on unexpected errors. Database-unavailable errors (`sqlite3.OperationalError`) return HTTP 200 with an empty/default data structure. The `/api/live-video` endpoint returns HTTP 503 if the frame file is not found.