docs: add monitoring retention plan

docs/superpowers/specs/2026-04-28-monitoring-retention-storage-design.md

@@ -0,0 +1,74 @@
+# Monitoring Retention And Storage Display Design
+
+## Goal
+
+Add an administrator-facing configuration for monitoring data retention and display the current database storage usage in the configuration page.
+
+## Scope
+
+- Add a single config key: `monitor_retention_days`.
+- Default retention is `7` days.
+- Apply the retention window uniformly to:
+  - `node_metric`
+  - `tunnel_metric`
+  - `service_monitor_result`
+  - `tunnel_quality`
+- Show database usage on the config page as a read-only operational value.
+
+## Non-Goals
+
+- No per-table retention settings.
+- No manual purge button.
+- No database vacuum/compaction action.
+- No frontend test framework changes.
+
+## Backend Design
+
+### Retention Config
+
+- Store `monitor_retention_days` in `vite_config`, consistent with existing site settings.
+- Accept integer values from `1` through `3650`.
+- Missing or invalid stored values fall back to `7` days.
+- `normalizeAndValidateConfigValue` rejects invalid user-submitted values so bad config does not get saved through the API.
+
+### Cleanup Flow
+
+- `metrics.IngestionService.pruneMetrics()` reads `monitor_retention_days` from the repository each hourly cleanup cycle.
+- The computed cutoff is used for `node_metric`, `tunnel_metric`, and `service_monitor_result`.
+- `tunnel_quality` uses the same retention config.
+- `tunnel_quality` cleanup must run even when real-time tunnel quality probing is disabled; disabling probing should stop new probe writes, not stop cleanup.
+
+### Database Storage API
+
+- Add an admin-only API endpoint for storage summary, for example `/api/v1/system/storage`.
+- Response fields:
+  - `dbType`: `sqlite` or `postgres`
+  - `databaseSizeBytes`: raw byte count
+  - `databaseSizeText`: human-readable formatted size
+- SQLite implementation reports the DB file size and includes `-wal` and `-shm` sidecar files when present.
+- PostgreSQL implementation uses `pg_database_size(current_database())`.
+- If size cannot be determined, return an API error rather than a misleading zero.
+
+## Frontend Design
+
+- Add `monitor_retention_days` to the config page.
+- Label: `监控数据保留天数`.
+- Description: `统一清理节点指标、隧道流量、服务监控结果和隧道质量历史；默认 7 天。`
+- Use a regular numeric input through the existing config rendering path.
+- Fetch database storage summary when the config page loads.
+- Display a read-only card/row named `数据库占用` with `databaseSizeText`.
+- If fetching fails, show `获取失败` and keep config editing usable.
+
+## Error Handling
+
+- Invalid retention values return a validation error on save.
+- Cleanup logs individual prune failures and continues with other tables, matching existing monitoring cleanup behavior.
+- Storage summary failures are non-blocking in the frontend.
+
+## Testing
+
+- Backend unit tests for retention config parsing and validation.
+- Backend tests proving custom retention is used by monitoring cleanup.
+- Backend API/repository test for SQLite storage size returning a non-negative byte count and formatted text.
+- Run `go test ./...` in `go-backend`.
+- Run `pnpm run build` in `vite-frontend`.