# Personal Dashboard Rollout

## Table: `user_tag_dashboards`

Purpose: capture per-user widget selections and configuration for upcoming personal dashboards. One row represents a single widget/tag on a personal page.

| Column | Type | Notes |
| --- | --- | --- |
| `id` | INT UNSIGNED PK | Auto-increment identifier. |
| `user_id` | INT | References `members.member_id`; cascades on delete/update. |
| `dashboard_key` | VARCHAR(64) | Allows multiple saved pages per user (e.g., `default`, `boilers`, `lab`). |
| `widget_type` | VARCHAR(32) | `trend`, `stat`, `gauge`, etc. Defaults to `trend`. |
| `panel_size` | VARCHAR(16) | Layout hint (`full`, `half`, `card`). |
| `position_index` | SMALLINT UNSIGNED | Zero-based ordering for rendering widgets. |
| `tag_name` | VARCHAR(255) | Historian/OPC tag identifier. |
| `display_label` | VARCHAR(255) | Optional friendly label shown on the UI. |
| `series_color` | VARCHAR(32) | Optional color override (hex/RGB). |
| `preferred_axis` | VARCHAR(16) | Left/right axis preference for trend widgets. |
| `update_interval_ms` | INT UNSIGNED | Polling cadence in milliseconds (default 5000). |
| `time_window_minutes` | SMALLINT UNSIGNED | Historical span for trend charts (default 180). |
| `rollup_function` | VARCHAR(16) | Server-side aggregation hint (`raw`, `avg`, `min`, `max`, `sum`, `delta`). |
| `scale_min` / `scale_max` | DECIMAL(14,4) | Optional manual bounds for chart scaling. |
| `threshold_low` / `threshold_high` | DECIMAL(14,4) | Alert thresholds for future highlighting. |
| `is_active` | TINYINT(1) | Soft delete flag; inactive rows stay archived. |
| `config_json` | LONGTEXT | Free-form JSON for extended configuration (annotations, alert styles, etc.). |
| `last_viewed_at` | DATETIME | Updated when a user loads the dashboard. |
| `created_at` / `updated_at` | TIMESTAMP | Audit columns managed by MySQL. |

### Indexing
- `uniq_user_dashboard_tag` ensures each user/dashboard/widget/tag combo is unique.
- `idx_user_dashboard` supports fast lookups while rendering the personal page.

> **FK note:** the `user_id` column is left signed (no `UNSIGNED`) so it matches the existing `members.member_id` definition in production. MySQL requires the parent and child column types to be identical (size and sign) for foreign keys to succeed.

### Seed Checklist
1. Run `sql/create_user_tag_dashboards.sql` in the LASUCA MySQL schema.
2. Insert starter rows for the pilot account (use your `members.member_id`).
3. Verify `SELECT * FROM user_tag_dashboards WHERE user_id = ?;` returns the seeded tags.

### Implemented
- Read endpoint: `data/personal/get_user_tags.php` returns active rows for the authenticated user and accepts an optional `dashboard` query parameter (defaults to `default`).
- Prototype personal page: `personal/dashboard.php` renders saved widgets, surfaces metadata, and links out to the live trend view.

## Table: `dashboard_row_catalog`

Purpose: master reference of displayable rows (friendly labels, units, rendering hints) that users can pin to their personal dashboard.

| Column | Type | Notes |
| --- | --- | --- |
| `id` | INT UNSIGNED PK | Auto-increment identifier. |
| `row_key` | VARCHAR(64) | Stable identifier used by code/user selections. Unique. |
| `friendly_name` | VARCHAR(255) | Picker label shown to users. |
| `source_type` | VARCHAR(32) | Data origin (`historian`, `mysql`, `computed`, etc.). |
| `source_id` | VARCHAR(128) | Identifier consumed by the source system (historian ID, OPC tag, etc.). |
| `unit` | VARCHAR(32) | Unit of measure (psi, %, °F, rpm, etc.). |
| `is_level_indicator` | TINYINT(1) | `1` = render with a level indicator/UI instead of plain numeric output. |
| `value_precision` | TINYINT UNSIGNED | Optional decimal precision hint. |
| `display_template` | VARCHAR(128) | Optional PHP include or template key for rendering the row. |
| `requires_include` | VARCHAR(128) | Name of prerequisite include (e.g., `items.php`). |
| `sort_order` | SMALLINT UNSIGNED | Default order when listing catalog entries. |
| `metadata_json` | LONGTEXT | Extra configuration (thresholds, grouping, color hints). |
| `created_at` / `updated_at` | TIMESTAMP | Audit columns managed by MySQL. |

Seed checklist mirrors the prior pattern:
1. Run `sql/create_dashboard_row_catalog.sql` in the LASUCA MySQL schema.
2. Insert catalog rows for each displayable metric (include unit/level flag).
3. Verify lookups via `SELECT * FROM dashboard_row_catalog ORDER BY sort_order, friendly_name;`.

### Next Steps
- Prototype a personal dashboard page that hydrates from the endpoint and renders the tags in slot order.
- Build write endpoints/UI for managing selections, expose threshold alerts, and support multiple dashboards via `dashboard_key`.