# 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 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.