Skip to content

Report Migration: Next Phases Checklist

Goal

Move from legacy report storage to canonical report storage safely:

  • canonical: users/{uid}/reports/{sid}
  • legacy projection: users/{uid}/strategies/{sid} (+ positions/position)

Current State (done)

  • FinLab client writes canonical payload (report + execution) to reports/{sid}.
  • Web clients (new_website, backtestWebsite) support fallback to canonical docs.
  • Canary script exists: scripts/report_web_canary.py.

Phase 1: Deploy And Stabilize

Actions

  1. Deploy report_projection Cloud Function.
  2. Deploy new FinLab package.
  3. Deploy both website updates (dual-read mode).
  4. Run canary on sampled real strategies.

Canary command

uv run python scripts/report_web_canary.py \
  --uid <uid> \
  --sid <sid1> \
  --sid <sid2> \
  --check-legacy

Use FINLAB_ID_TOKEN env var or pass --id-token.

Exit criteria

  • No spike in strategy page failures.
  • Canary pass rate is high on production samples.
  • Legacy projection docs are present and fresh.

Phase 2: Canonical-First Reads

Actions

  1. Flip web read order:
  2. from: strategies first, reports fallback
  3. to: reports first, strategies fallback
  4. Keep same UI view model (no user-visible schema change).
  5. Continue canary + error monitoring.

Exit criteria

  • Canonical-first reads stable in production.
  • No functional regressions in strategy/performance/position pages.

Phase 3: Legacy Decommission

Actions

  1. Stop using legacy endpoint writes (write_database) for report payloads.
  2. Announce deprecation window for legacy read paths.
  3. Remove legacy fallback code from web clients after window.
  4. Remove projection trigger when no consumer depends on legacy docs.

Exit criteria

  • All active clients read canonical docs directly.
  • Legacy docs/endpoint no longer required by any production flow.

Rollback Plan

If Phase 1 or 2 has issues:

  1. Keep projection enabled.
  2. Keep frontend in dual-read mode.
  3. Revert canonical-first switch (if applied).
  4. Re-run canary on affected strategies before re-release.

Ownership

  • Backend/FinLab: canonical payload correctness + upload/read behavior.
  • Cloud Function: projection health + logs.
  • Frontend: render parity and fallback behavior.
  • Release: canary execution and rollout gate decisions.