enhance utilisation of postgres features

2026-04-20 10:19:27 +10:00
parent 98e92a8264
commit 8ccf5a7009
28 changed files with 2836 additions and 422 deletions
@@ -0,0 +1,100 @@
+# Phase 0 Baseline and Regression Snapshot
+
+Date captured: 2026-04-20 (Australia/Sydney)
+
+## Baseline metrics (local `db.sqlite3` + `reports/`)
+
+| Area | Metric | Baseline |
+| --- | --- | --- |
+| Hourly capture | `snapshot_registry` hourly entries | `930` |
+| Hourly capture | Hourly compatibility tables (`inventory_hourly_%`) | `930` |
+| Hourly capture | Canonical cache rows (`vm_hourly_stats`) | `489865` |
+| Hourly capture | Latest hourly snapshot row count (`snapshot_count`) | `52` |
+| Hourly capture | Latest hourly snapshot table | `inventory_hourly_1776635926` |
+| Daily aggregation | `snapshot_registry` daily entries | `39` |
+| Daily aggregation | Daily summary tables (`inventory_daily_summary_%`) | `40` |
+| Daily aggregation | Canonical daily rollup rows (`vm_daily_rollup`) | `1779` |
+| Daily aggregation | Latest daily summary table | `inventory_daily_summary_20260419` |
+| Daily aggregation | Latest daily snapshot row count (`snapshot_count`) | `52` |
+| Monthly aggregation | `snapshot_registry` monthly entries | `1` |
+| Monthly aggregation | Latest monthly summary table | `inventory_monthly_summary_202601` |
+| Monthly aggregation | Latest monthly snapshot row count (`snapshot_count`) | `62` |
+| Report generation | Files present in `reports/` | `10339` |
+| Report generation | Most recent files | `inventory_hourly_1776635926.xlsx`, `inventory_daily_summary_20260419.xlsx`, `inventory_hourly_1776635626.xlsx` |
+
+Notes:
+- `snapshot_runs` rows: `10254`, success distribution: `TRUE=10254`, attempts min/max/avg: `1/2/1.0001`.
+- Runtime histograms/counters for long-running jobs are emitted on `/metrics` and are not persisted in SQLite.
+  - Hourly per-vCenter duration: `vctp_vcenter_snapshot_duration_seconds`
+  - Daily duration: `vctp_daily_aggregation_duration_seconds`
+  - Monthly duration: `vctp_monthly_aggregation_duration_seconds`
+  - Reports available gauge: `vctp_reports_available`
+
+## API/endpoint contract regression snapshot
+
+Source of truth: `server/router/router.go`.
+
+Unauthenticated/public routes:
+- `/`
+- `/vm/trace`
+- `/vcenters`
+- `/vcenters/totals`
+- `/vcenters/totals/daily`
+- `/vcenters/totals/hourly`
+- `/snapshots/hourly`
+- `/snapshots/daily`
+- `/snapshots/monthly`
+- `/metrics`
+- `/api/auth/login`
+- `/assets/*`, `/favicon*`, `/reports/*`, `/swagger*`
+
+Viewer routes (Bearer auth, viewer/admin role):
+- `/api/report/inventory`
+- `/api/report/updates`
+- `/api/report/snapshot`
+- `/api/diagnostics/daily-creation`
+
+Admin routes (Bearer auth, admin role):
+- `/api/event/vm/create`
+- `/api/event/vm/modify`
+- `/api/event/vm/move`
+- `/api/event/vm/delete`
+- `/api/import/vm`
+- `/api/inventory/vm/delete`
+- `/api/inventory/vm/update`
+- `/api/cleanup/updates`
+- `/api/snapshots/aggregate`
+- `/api/snapshots/hourly/force`
+- `/api/snapshots/migrate`
+- `/api/snapshots/repair`
+- `/api/snapshots/repair/all`
+- `/api/snapshots/regenerate-hourly-reports`
+- `/api/vcenters/cache/rebuild`
+- `/api/encrypt`
+- `/debug/pprof/*` (only when enabled)
+
+`/api/auth/me` route:
+- Protected by auth middleware (`withAuth`) but no explicit role gate.
+
+## Report filename behavior regression snapshot
+
+Source of truth: `server/handler/reportDownload.go`, `server/handler/snapshots.go`, `internal/report/snapshots.go`.
+
+HTTP download endpoints:
+- `GET /api/report/inventory` -> `Content-Disposition: attachment; filename="inventory_report.xlsx"`
+- `GET /api/report/updates` -> `Content-Disposition: attachment; filename="updates_report.xlsx"`
+- `GET /api/report/snapshot?table=<tableName>` -> `Content-Disposition: attachment; filename="<tableName>.xlsx"`
+
+On-disk generated report filename:
+- `SaveTableReport(...)` writes `<reports_dir>/<tableName>.xlsx`
+- Snapshot list pages link to `/reports/<tableName>.xlsx`
+
+## Migration guardrails confirmation
+
+- No auth-model changes: route auth wrappers remain unchanged (`withAuth`, `withAuthRole` usage in router).
+- SQLite support retained:
+  - settings default driver remains sqlite (`src/vctp.yml`, `README.md`).
+  - hourly canonical write path still has SQLite transactional upsert path (`insertHourlyCache`, `insertHourlyBatch`).
+- Compatibility mode enabled by default:
+  - `settings.snapshot_table_compat_mode` default is `true` in settings defaults.
+  - runtime check falls back to enabled when unset (`snapshotTableCompatModeEnabled()`).