Validate model version during model load

[mengChengxi]

Linked issue

• Closes [Enhancement] Enforce modelVersion validation during model load to prevent schema mismatch #172
• Related [Enhancement] Implement incremental model schema migration framework #173

Existing related work reviewed

• Issues/PRs reviewed: [Enhancement] Enforce modelVersion validation during model load to prevent schema mismatch #172, [Enhancement] Implement incremental model schema migration framework #173
• If none found, write: None found after search

Overlap assessment

• Classification: Related follow-up, not duplicate
• Overlapping items:
  • [Enhancement] Enforce modelVersion validation during model load to prevent schema mismatch #172 enforces schema version validation during model load
  • [Enhancement] Implement incremental model schema migration framework #173 is a broader schema migration framework for legacy models
• Why this is not duplicate/superseded:
  • This PR adds fail-fast validation and version stamping for current models
  • It does not implement automatic migration of legacy schemas
  • Legacy update/migration work can still build on top of this contract later

Why this PR should proceed

• It establishes a centralized schema-version contract in the backend instead of relying on scattered checks
• It prevents legacy or malformed cases from reaching run/view workflows and failing later in less clear ways
• It preserves the existing “select old model, then update it from configuration” workflow instead of blocking case selection entirely
• It improves user feedback by surfacing the backend version-mismatch message in the frontend

Summary

• What changed:
  • Added a centralized model version helper in API/Classes/Base/ModelVersionClass.py
  • Added structured version_mismatch errors for missing or incompatible schema versions
  • Enabled the existing CustomException JSON error handler in API/app.py
  • Validated schema version when loading model data in OsemosysClass
  • Stamped modelVersion alongside osy-version when saving new/current models and importing templates
  • Backfilled modelVersion for uploaded 5.0 archives without changing the legacy upload/update flow
  • Updated frontend error handling to consistently surface backend messages
  • Added a Home-page warning for older schema versions using modelVersion || osy-version
• Why:
  • To enforce model-version compatibility at the point where run/view workflows actually depend on the schema
  • To give users a clear upgrade path instead of allowing incompatible models to fail deeper in the workflow

Validation

• Tests added/updated (or not applicable)
• Validation steps documented
• Evidence attached (logs/screenshots/output as relevant)

Validation performed:

• python3 -m py_compile on all changed Python files
• Helper smoke tests for:
  • current version acceptance
  • legacy version rejection
  • missing version metadata rejection
• Flask test client smoke test confirming viewData returns 409 with version_mismatch
• Playwright smoke tests confirming:
  • current-schema case selection does not show legacy warning
  • legacy-schema case selection shows the warning
  • ViewData displays the backend version-mismatch message
• Upload smoke test confirming a 5.0 archive missing modelVersion is backfilled on restore

Documentation

• Docs updated in this PR (or not applicable)
• Any setup/workflow changes reflected in repo docs

Scope check

• No unrelated refactors
• Implemented from a feature branch
• Change is deliverable without upstream OSeMOSYS/MUIO dependency
• Base repo/branch is EAPD-DRB/MUIOGO:main (not upstream)

Exception rationale