DashBoard/openspec/changes/archive/2026-02-11-portal-no-iframe-navigation/tasks.md

0. Implementation Kickoff (Apply Session Day-1)

• 0.1 Generate and commit migration baseline snapshots (drawer visibility, route/query contracts, critical API payload key/type).
• 0.2 Create parity checklist artifacts mapped to the functional parity matrix routes.
• 0.3 Define and verify cutover control mechanism (feature flag / env toggle) before any breaking navigation change.
• 0.4 Record rollback rehearsal plan with target recovery SLO and responsible operator steps.

1. Drawer Baseline and Governance Contract

• 1.1 Capture the current production drawer baseline from data/page_status.json (id/name/order/admin_only/pages) as migration reference data.
• 1.2 Define canonical drawer responsibilities: IA grouping, ordering, and permission visibility only (no iframe/frame loading semantics).
• 1.3 Define a drawer-route consistency contract (route exists, drawer exists, order is valid, admin_only behavior is deterministic).
• 1.4 Add validation checks/tests for admin and non-admin drawer visibility against the current baseline configuration.
• 1.5 Define frame_id/tool_src deprecation policy and transition checkpoints.

2. SPA Shell and Router Foundation

• 2.1 Create a SPA shell entry for portal navigation using Vue 3 + Vue Router.
• 2.2 Build router records from drawer/page route contracts while preserving existing URL compatibility.
• 2.3 Implement router-aware sidebar active state and breadcrumb/title metadata handling.
• 2.4 Align auth/permission checks between backend route guard and frontend navigation guard behavior.
• 2.5 Keep health-status widget behavior available in shell without iframe coupling.

3. Portal Iframe Decommission

• 3.1 Refactor portal.html to remove iframe panel DOM and switch sidebar metadata to route-driven navigation.
• 3.2 Refactor frontend/src/portal/main.js to remove frame activation/lazy-load/unload logic.
• 3.3 Replace iframe-specific UI states with route-transition states and loading indicators.
• 3.4 Remove portal CSS rules that target iframe layout while preserving current visual structure.
• 3.5 Verify non-admin/admin navigation outcomes for all current drawers under direct routing.

4. Tailwind Design System Bootstrap

• 4.1 Introduce Tailwind CSS + PostCSS configuration into the frontend build pipeline.
• 4.2 Define design tokens (color, spacing, typography, radius, elevation, z-index) mapped to existing UI language.
• 4.3 Establish global base/component/utility layers and migration-safe style ordering.
• 4.4 Define style governance rules to prevent new large page-local CSS during migration.
• 4.5 Publish migration guide for converting existing CSS modules/pages to Tailwind patterns.

5. Shared UI and Composable Consolidation

• 5.1 Inventory duplicated UI patterns across WIP/Resource/Hold/QC pages (filter bar, KPI cards, tables, pagination, badges, banners).
• 5.2 Create shared UI component layer and normalize props/events/slot contracts.
• 5.3 Consolidate cross-page composables (auto-refresh, autocomplete, query state, pagination state) under shared modules.
• 5.4 Migrate existing pages to shared components incrementally with visual parity checks.
• 5.5 Remove obsolete duplicated component/style artifacts after each migration batch.

6. Legacy Page Wrapper Phase (Confirmed Decision)

• 6.1 Implement wrapper integration for job-query inside the new router/shell flow.
• 6.2 Implement wrapper integration for excel-query inside the new router/shell flow.
• 6.3 Implement wrapper integration for query-tool inside the new router/shell flow.
• 6.4 Implement wrapper integration for tmtt-defect inside the new router/shell flow.
• 6.5 Define wrapper-level telemetry (load success, error, latency) and fallback behavior.
• 6.6 Document hard exit criteria that determine when each wrapped page can be considered rewrite-ready.

7. Legacy Rewrite Execution (Post-Wrapper)

• Reference checklist: docs/migration/portal-no-iframe/legacy_rewrite_smoke_checklists.md
• Reference exemplar: docs/migration/portal-no-iframe/tmtt_rewrite_exemplar.md
• Reference playbook: docs/migration/portal-no-iframe/legacy_rewrite_playbook.md
• Reference decommission record: docs/migration/portal-no-iframe/wrapper_decommission_report.md
• 7.1 Prioritize rewrite order among wrapped pages using usage/complexity/risk scoring.
• 7.2 Rewrite first legacy page as canonical migration exemplar with shared UI + Tailwind.
• 7.3 Rewrite remaining three legacy pages with reusable migration playbook and acceptance criteria.
• 7.4 Decommission wrappers after rewrite completion and parity validation.

8. Interaction and Motion System

• 8.1 Define baseline motion guidelines using Vue Transition (route transitions, panel changes, loading states).
• 8.2 Implement reduced-motion accessibility behavior and fallback styles.
• 8.3 Add key interaction transitions for filter apply, chart/table refresh, and drawer navigation.
• 8.4 Define an escalation rule for when GSAP (or equivalent) is allowed beyond baseline transitions.

9. Testing, Quality Gates, and Performance

• 9.1 Update unit/template tests from iframe assumptions to router/drawer contract assertions.
• 9.2 Update E2E and stress suites to validate route navigation stability instead of iframe switching.
• 9.3 Add regression tests for drawer ordering, admin_only filtering, and mixed release/dev visibility.
• 9.4 Add contract tests for legacy wrapper routing and fallback behavior.
• 9.5 Establish performance baselines (first paint, route switch latency, memory footprint) and compare pre/post migration.

10. Rollout, Cleanup, and Spec Closure

• 10.1 Define phased rollout plan with canary scope and success/error thresholds.
• 10.2 Define rollback strategy for shell/router cutover and wrapper failures.
• 10.3 Remove frame_id/tool_src from runtime navigation payload after wrapper-to-rewrite milestones are complete.
• 10.4 Sync changed requirements into main specs and prepare archive criteria for this migration change.

11. Cutover Gate Enforcement (Measurable)

• 11.1 Enforce G1 route availability gate: P0 routes return 2xx/3xx at 100% pass rate in release validation.
• 11.2 Enforce G2 drawer parity gate: admin/non-admin visible route sets must match pre-migration baseline exactly (delta = 0).
• 11.3 Enforce G3 workflow parity gate: one critical smoke flow per route in parity matrix must pass at 100%.
• 11.4 Enforce G4 client stability gate: zero unhandled JavaScript runtime errors on critical E2E paths.
• 11.5 Enforce G5 data contract gate: required payload key/type parity checks must pass for all critical APIs.
• 11.6 Enforce G7 rollback readiness gate: rollback rehearsal must recover stable navigation within target SLO (e.g., <= 15 minutes).