egg/DashBoard
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
main
DashBoard/openspec/changes/archive/2026-02-12-modernization-hardening-follow-up/proposal.md
egg 7cb0985b12 feat(modernization): full architecture blueprint with hardening follow-up 
Implement phased modernization infrastructure for transitioning from
multi-page legacy routing to SPA portal-shell architecture, plus
post-delivery hardening fixes for policy loading, fallback consistency,
and governance drift detection.

Key changes:
- Add route contract enrichment with scope/visibility/compatibility policies
- Canonical 302 redirects from legacy direct-entry to /portal-shell/ routes
- Asset readiness enforcement and runtime fallback retirement for in-scope routes
- Shared feature-flag helpers (env > config > default) replacing duplicated _to_bool
- Defensive copy for lru_cached policy payloads preventing mutation corruption
- Unified retired-fallback response helper across app and blueprint routes
- Frontend/backend route-contract cross-validation in governance gates
- Shell CSS token fallback values for routes rendered outside shell scope
- Local-safe .env.example defaults with production recommendation comments
- Legacy contract fallback warning logging and single-hop redirect optimization

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 11:26:02 +08:00

2.7 KiB
Raw Permalink Blame History

Why

Recent code review on the Phase 1 modernization delivery found several high-risk consistency gaps: mutable cached policy payloads, inconsistent fallback-retirement error behavior, aggressive .env.example defaults, and route-governance drift risks between backend JSON and frontend contract definitions. These issues can cause environment-dependent startup failures, silent policy drift, and hard-to-debug runtime behavior.

What Changes

  • Harden modernization policy loaders to prevent shared mutable cache corruption and make refresh semantics explicit/documented.
  • Unify in-scope fallback-retirement response behavior across app-level routes and blueprint routes.
  • Make .env.example safe for local onboarding while still documenting production-recommended hardening values.
  • Consolidate feature-flag boolean resolution (env > config > default) into a shared helper and remove duplicated _to_bool implementations.
  • Add route-contract cross-validation between backend contract artifacts and frontend routeContracts.js inventory.
  • Add explicit warning telemetry when legacy shell-contract artifact fallback is used.
  • Document and test intentional canonical-redirect scope asymmetry (report routes vs admin external targets).
  • Reduce avoidable redirect chain length for /hold-detail missing-reason flow in SPA mode.
  • Add shell-token fallback values for QC-GATE page CSS variables to prevent rendering degradation outside shell context.

Capabilities

New Capabilities

  • None.

Modified Capabilities

  • asset-readiness-and-fallback-retirement: unify fallback-retirement failure surfaces and safe local defaults for readiness-related flags.
  • frontend-platform-modernization-governance: add governance requirements for contract-source consistency and legacy artifact fallback observability.
  • spa-shell-navigation: document and enforce canonical redirect scope rules, including missing-reason redirect behavior.
  • unified-shell-route-coverage: require frontend/backend route-contract set consistency checks.
  • style-isolation-and-token-enforcement: require token fallback behavior for route-local styles that may render outside shell variable scope.
  • maintainability-type-and-constant-hygiene: require shared feature-flag and boolean parsing helpers for policy/runtime modules.

Impact

  • Affected backend modules: src/mes_dashboard/core/modernization_policy.py, src/mes_dashboard/core/runtime_contract.py, src/mes_dashboard/app.py, hold-related routes.
  • Affected frontend modules: frontend/src/portal-shell/routeContracts.js, frontend/src/qc-gate/style.css.
  • Affected governance and tests: modernization gate script/tests, route-contract consistency tests, redirect/fallback behavior tests, .env.example documentation.