Migration Plan

Phase 1 - Specification And Contracts ✅

Document current routes and workflows.
Document API calls and response shapes.
Identify backend gaps that block a clean Vue client.
Confirm JavaScript-only implementation.
Decide exact gnexus-ui-kit installation method.

Deliverable:

Complete docs in webclient-vue/docs/.

Phase 2 - Project Scaffold ✅

Create Vue app under webclient-vue/.
Configure build tooling.
Add gnexus-ui-kit.
Add router.
Add API client wrapper.
Add app shell, layout, navigation, toast, modal, and error state primitives.

Deliverable:

New client opens locally and can call GET /api/v1/areas/list.

Phase 2.1 - Minimal Vertical Slice ✅

Build the smallest complete app slice:

App shell.
Hash router.
API client.
Areas API module.
Favorites localStorage store with key sh_fav_areas.
/areas/favorites page.
Loading, empty, and error state components.

Acceptance criteria:

Running the dev server opens the Vue client.
/ redirects to /areas/favorites.
/areas/favorites calls the backend areas list endpoint.
Existing favorite ids from localStorage are respected.
Empty favorites state is rendered correctly.
No old webclient/src/js code is imported.
UI-kit access is isolated behind local adapter components, even if adapters are initially minimal.

Phase 3 - Read-Only Screens ✅

Implement without mutations first:

Areas favorites.
Areas tree.
Devices list.
Devices scanning list.
Scripts actions list.
Scripts regular list.
Scripts scopes list.

Deliverable:

New client can display the same operational data as the current client.

Phase 4 - Mutations And Modals ✅

Implement user actions:

Run action script.
Enable/disable regular scripts.
Enable/disable scopes.
Device details.
Device reboot.
Device setup.
Area details.
Area create/edit.
Area devices modal.
Area actions modal.

Deliverable:

New client covers daily operational workflows.

Phase 5 - Hardening ✅

Add concurrency limits to device live-state loading.
Add request cancellation on route leave/modal close.
Add normalized error handling.
Add stale data and retry states.
Add smoke checklist.

Deliverable:

New client is safe to use as primary UI.

Phase 5.5 - Test Infrastructure & Unit Tests

Install and configure testing stack for Vite + Vue:

Vitest — test runner (native Vite integration, replaces Jest).
@vue/test-utils — mount and interact with Vue components.
jsdom — DOM environment for component tests.
@vitest/coverage-v8 — code coverage reports.

Unit test targets (no DOM, fast, isolated):

Target	What to test
`api/client.js`	`apiRequest` success path, error path, network failure, abort
`api/http.js`	`requestHttp` URL building, proxy wrapping, timeout abort, JSON parse
`api/mappers.js`	`unifyDeviceFields` normalizes snake_case → camelCase
`stores/favorites.js`	localStorage read/write, toggle, add, remove
`stores/areas.js`	`buildAreaTree` handles roots, children, self-reference, cycles
`stores/devices.js`	`makeDeviceStatePatch`, `normalizeStatusSuccess`, `normalizeStatusError`

Deliverable:

npm test runs unit tests.
Coverage report generated in coverage/.

Phase 5.6 - Component Tests

Test Vue components in isolation with mocked dependencies:

Component	What to test
`AppEmptyState`	renders title and message, slots work
`AppErrorState`	renders title/message, retry button fires event
`AppLoadingState`	renders label
`AppShell`	renders nav items, brand, content slot
`AreaTreeNode`	toggles expand, emits rename/remove/unassign, cycle detection
`DeviceConnectionBadge`	maps status → correct variant
`DeviceStateCell`	maps state → correct badge/loader
`AreaFavoritesPage`	loads areas, filters favorites, handles empty
`DevicesListPage`	loads devices + states, renders table rows, stale badge
`ScriptsActionsPage`	loads actions, run button triggers API, shows alert

Mock strategy:

Pinia stores via createTestingPinia().
API calls via vi.mock() or MSW (mock service worker).

Deliverable:

Component tests cover all feature components and pages.

Phase 5.7 - Integration Tests ✅

End-to-end user flows with mocked backend:

Flow	Steps
Area lifecycle	Load areas → Create area → Rename → Remove
Device discovery	Scan network → Select device → Setup → Appears in list
Script execution	Load actions → Run script → See result alert
Navigation	Visit each route → Assert correct page renders

Use MSW (Mock Service Worker) to intercept fetch and return fixture data.

Deliverable:

Integration tests verify complete user workflows.

Phase 6 - Switch-Over

Keep old webclient/ available as fallback.
Serve new client on the chosen route/domain.
Monitor backend logs and user-reported issues.
Remove or archive old client only after a stable period.

Open Decisions

Vue state library: Pinia or lightweight composables only.
Router mode: hash mode for compatibility or history mode with server config.
How to consume gnexus-ui-kit as an updatable dependency: package/git dependency preferred, submodule only if necessary.
Whether to keep proxy.php or use direct backend API from the new dev server.

Current Recommendations

Use JavaScript.
Use Pinia.
Use hash router for the first production-capable version.
Keep proxy.php compatibility in the API client, but allow direct backend URL through environment variables.
Integrate gnexus-ui-kit through local adapter components, not direct imports across feature code.