feat(backend): add calculatedAt metric freshness indicator (Closes #1240)

[Banx17]

Description

Adds a visible stale/cached indicator to the admin metrics dashboard by including a calculatedAt ISO-8601 timestamp in the GET /v1/admin/metrics response. The timestamp reflects when the underlying aggregation actually ran (when the metrics payload was stored in the in-process cache), not when the HTTP response is serialized. This lets operators/dashboards tell whether the numbers reflect the last few seconds or up to the full cache TTL (60s) ago.

Type of Change

• ✨ New feature (non-breaking change which adds functionality)
• 🧪 Test addition or update

Related Issues

Closes #1240

Changes Made

The metrics cache (MemoryCache, backend/src/lib/redis.ts) already records the timestamp at which each cache entry was populated (createdAt, exposed via cache.getMetadata()). No new caching pattern was invented — this reuses the same convention already used by claimable.service.ts (cachedAt).

Changed files:

• backend/src/routes/v1/admin.routes.ts
  • Added withCalculatedAt() helper that reads cache.getMetadata(ADMIN_METRICS_CACHE_KEY).createdAt and attaches a calculatedAt field (falling back to the current time only if metadata is unavailable).
  • Applied it on both the cache-HIT path (behind withLiveIndexerCounters) and the cache-MISS path.
• backend/tests/integration/admin-metrics.test.ts
  • Added a test asserting calculatedAt is present in valid ISO 8601 format.
  • Added a test asserting calculatedAt reflects the aggregation time and is stable across multiple responses served from the same cache entry (does not drift to "now" on every call).

Acceptance Criterion

"The /v1/admin/metrics response includes a timestamp field reflecting when the underlying aggregation ran."

Met as follows:

• On a cache MISS, buildAdminMetrics() runs and the result is stored via cache.set(ADMIN_METRICS_CACHE_KEY, payload, 60). The cache entry's createdAt is that store time, i.e. when the aggregation actually ran. calculatedAt is derived from it.
• On a cache HIT, the cached payload is served and calculatedAt is still derived from the same cache entry's createdAt, so two consecutive requests within the 60s TTL return the same calculatedAt — proven by the new stability test. It is never recomputed as "now" at response-serialization time on a cache hit.

Testing

Test Coverage

• Integration tests added/updated
• Manual testing performed (local CI-equivalent checks)

Commands & Real Results

Backend has no lint script (backend/package.json has no lint); .github/workflows/ci.yml runs npm run build + npx vitest run --coverage --reporter=basic for the backend. Frontend lint also runs in CI but no frontend files are touched here.

npm run build (backend — includes tsc type-check):

> backend@1.0.0 prebuild
> prisma generate
✔ Generated Prisma Client (v7.4.1) to .\src\generated\prisma

> backend@1.0.0 build
> tsc
EXIT=0

Targeted test file:

✓ tests/integration/admin-metrics.test.ts (20 tests) 1791ms
Test Files  1 passed (1)
     Tests  20 passed (20)

Full backend suite (CI-equivalent: npx vitest run --coverage --reporter=basic; real-Postgres integration tests self-skip locally because Docker/DATABASE_URL are unavailable — they run in CI):

Test Files  51 passed (51)
     Tests  381 passed | 16 skipped (397)
All files  | 66.39 | 74.52 | 70.83 | 66.39
  backend/src/routes/v1/admin.routes.ts | 90.72 | 75.86 | 100 | 90.72

Coverage thresholds (60%) all pass. The only uncleanness in the local run is a pre-existing unhandled rejection in tests/workers.index.test.ts (stream-runway-worker logger mock, default.error is not a function) that also reproduces on the clean base branch with these changes stashed; it does not fail any test.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have checked for breaking changes and documented them if applicable