CostPrediction/docs/superpowers/plans/2026-04-25-ml-algorithm-demo.md

ML Algorithm Demo Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a modern demo page that compares common machine learning algorithms using a local data file instead of MySQL.

Architecture: Add an isolated backend demo service that reads data/demo_equipment_costs.csv, trains selected regressors in memory, and returns metrics, prediction points, feature importance, and a sample prediction. Add a Vue route that calls the demo API and renders algorithm switching, charts, metrics, and data preview. Existing database-backed pages remain unchanged.

Tech Stack: Flask, pandas, scikit-learn, optional xgboost/lightgbm, Vue 3, Element Plus, ECharts.

---

Task 1: Backend Demo Service

Files:

• Create: tests/test_demo_service.py

• Create: src/demo_service.py

• Create: data/demo_equipment_costs.csv

• Write failing tests for data loading, algorithm availability, and training payload shape.

• Run python -m pytest tests/test_demo_service.py -q and verify it fails because src.demo_service is missing.

• Implement DemoModelService with local CSV loading, selected algorithm training, metric calculation, top feature importance, and fallback algorithms when optional libraries are unavailable.

• Run python -m pytest tests/test_demo_service.py -q and verify it passes.

Task 2: Demo API

Files:

• Modify: src/routes.py

• Test: tests/test_demo_routes.py

• Write Flask route tests for GET /api/demo/algorithms, GET /api/demo/dataset, and POST /api/demo/run.

• Run python -m pytest tests/test_demo_routes.py -q and verify missing routes fail.

• Add demo routes that call DemoModelService and do not access MySQL.

• Run the route tests and demo service tests.

Task 3: Vue Demo Page

Files:

• Create: frontend/src/views/AlgorithmDemoPage.vue

• Modify: frontend/src/router/index.js

• Modify: frontend/src/App.vue

• Modify: frontend/src/api/index.js

• Modify: frontend/src/views/HomePage.vue

• Add API helpers for demo algorithms, dataset, and run.

• Add /algorithm-demo route and navigation label 算法演示.

• Build a modern dashboard-style page with algorithm toggles, metric cards, comparison chart, predicted-vs-actual chart, feature importance chart, sample prediction panel, and data preview table.

• Add a home page entry that links to the demo.

Task 4: Verification

Files:

• No new files.

• Run python -m pytest tests/test_demo_service.py tests/test_demo_routes.py -q.

• Run npm run build in frontend.

• Start the app if feasible and confirm the new route is available.