DashBoard/openspec/changes/archive/2026-02-23-admin-performance-vue-spa/tasks.md

1. Backend — Cache Telemetry Infrastructure

• 1.1 Add stats() method to ProcessLevelCache in core/cache.py (returns entries/max_size/ttl_seconds with lock)
• 1.2 Add _PROCESS_CACHE_REGISTRY, register_process_cache(), and get_all_process_cache_stats() to core/cache.py
• 1.3 Register _wip_df_cache in core/cache.py
• 1.4 Add stats() + register_process_cache() to services/resource_cache.py
• 1.5 Add stats() + register_process_cache() to services/realtime_equipment_cache.py
• 1.6 Add register_process_cache() to services/reject_dataset_cache.py

2. Backend — Direct Connection Counter

• 2.1 Add _DIRECT_CONN_COUNTER, _DIRECT_CONN_LOCK, and get_direct_connection_count() to core/database.py
• 2.2 Increment counter in get_db_connection() and read_sql_df_slow() after successful connection creation

3. Backend — Performance Detail API

• 3.1 Add GET /admin/api/performance-detail endpoint in routes/admin_routes.py returning redis, process_caches, route_cache, db_pool, and direct_connections sections
• 3.2 Implement Redis INFO + SCAN namespace key distribution (data, route_cache, equipment_status, reject_dataset, meta, lock, scrap_exclusion) with graceful degradation when Redis is disabled

4. Frontend — Page Scaffolding

• 4.1 Create frontend/src/admin-performance/index.html and main.js (standard Vue SPA entry)
• 4.2 Register admin-performance entry in vite.config.js
• 4.3 Add cp command for admin-performance.html in package.json build script

5. Frontend — Reusable Components

• 5.1 Create GaugeBar.vue — horizontal gauge bar with label, value, max, and color threshold props
• 5.2 Create StatCard.vue — mini card with numeric value, label, and optional unit/icon
• 5.3 Create StatusDot.vue — colored dot indicator (healthy/degraded/error/disabled) with label

6. Frontend — App.vue Main Dashboard

• 6.1 Implement data fetching layer: loadSystemStatus(), loadMetrics(), loadPerformanceDetail(), loadLogs(), loadWorkerStatus() with Promise.all parallel fetch and useAutoRefresh (30s)
• 6.2 Build header section with gradient background, title, auto-refresh toggle, and manual refresh button
• 6.3 Build status cards section (Database / Redis / Circuit Breaker / Worker PID) using StatusDot
• 6.4 Build query performance panel with P50/P95/P99 stat cards and ECharts latency distribution chart
• 6.5 Build Redis cache detail panel with memory GaugeBar, hit rate, client count, peak memory, and namespace key distribution table
• 6.6 Build memory cache panel with ProcessLevelCache grid cards (entries/max gauge + TTL) and route cache telemetry (L1/L2 hit rate, miss rate, total reads)
• 6.7 Build connection pool panel with saturation GaugeBar and stat card grid (checked_out, checked_in, overflow, max_capacity, pool_size, pool_recycle, pool_timeout, direct connections)
• 6.8 Build worker control panel with PID/uptime/cooldown display, restart button, and confirmation modal
• 6.9 Build system logs panel with level filter, text search, pagination, and log clearing
• 6.10 Create style.css with all panel, grid, gauge, card, and responsive layout styles

7. Route Integration

• 7.1 Change /admin/performance route handler in admin_routes.py from render_template to send_from_directory serving the Vue SPA
• 7.2 Update routeContracts.js: change renderMode to 'native', rollbackStrategy to 'fallback_to_legacy_route', compatibilityPolicy to 'redirect_to_shell_when_spa_enabled'

8. Verification (Phase 1)

• 8.1 Run cd frontend && npx vite build — confirm no compilation errors and admin-performance.html is produced
• 8.2 Verify all dashboard panels render correctly with live data after service restart

9. Backend — Metrics History Store

• 9.1 Create core/metrics_history.py with MetricsHistoryStore class (SQLite schema, thread-local connections, write_lock, write_snapshot, query_snapshots, cleanup)
• 9.2 Add MetricsHistoryCollector class (daemon thread, configurable interval, collect pool/redis/route_cache/latency)
• 9.3 Add module-level get_metrics_history_store(), start_metrics_history(app), stop_metrics_history() functions

10. Backend — Lifecycle Integration

• 10.1 Call start_metrics_history(app) in app.py after other background services
• 10.2 Call stop_metrics_history() in _shutdown_runtime_resources() in app.py

11. Backend — Performance History API

• 11.1 Add GET /admin/api/performance-history endpoint in admin_routes.py (minutes param, clamped 1-180, returns snapshots array)

12. Frontend — Trend Charts

• 12.1 Create TrendChart.vue component using vue-echarts VChart (line/area chart, dual yAxis support, time labels, autoresize)
• 12.2 Add loadPerformanceHistory() fetch to App.vue and integrate into refreshAll()
• 12.3 Add 4 TrendChart panels to App.vue template (pool saturation, query latency, Redis memory, cache hit rates)
• 12.4 Add trend chart styles to style.css

13. Verification (Phase 2)

• 13.1 Run cd frontend && npm run build — confirm no compilation errors
• 13.2 Verify trend charts render with historical data after service restart + 60s collection