vue-pult/plans/plan1.md

# План 1: Рефакторинг HomePage.vue (разделение UI/бизнес/сеть)

Документ описывает подробный план раскладывания `client/src/pages/HomePage.vue` (~1200 строк) на независимые компоненты и вынос бизнес‑логики/сетевых вызовов в composables. Цель — сохранить текущее поведение, повысить читаемость, переиспользуемость и упростить сопровождение.

## Текущее состояние и проблемы
- В одном файле смешаны: верстка, управление модалками, работа со сменами, сетевые вызовы WebSocket, вывод ошибок и индикаторы системного состояния.
- Повторяются вызовы `socket.sendMessage({ do: ... })`; протокол (`do`, `promise`) «просачивается» в UI.
- Сложно тестировать и вносить изменения — любая правка затрагивает большой файл.

## Целевая архитектура
Страница — тонкий контейнер, который собирает:
- Отдельные UI‑компоненты (layout, grid, модалки) через props/emit.
- Composables для состояния и бизнес‑логики.
- Тонкий слой WS‑API вместо прямых `sendMessage`.

### Новые компоненты (директории и обязанности)
- `components/layout/HeaderBar.vue`
  - Отвечает за кнопки: пауза, выключение, выход, переключатель темы.
  - Props: `isPaused: boolean`.
  - Emits: `toggle-pause`, `request-shutdown`, `request-logout`, `open-shift-modal`.
- `components/layout/FooterBar.vue`
  - Отображает индикаторы (ESP, link‑to‑server, sync) и счетчики.
  - Props: `indicators: { esp:boolean, ext:boolean, sync:string, ... }`.
  - Emits: по необходимости (`open-tech-shift`, и т.п.).
- `components/game/PortsGrid.vue`
  - Отрисовывает сетку портов.
  - Props: `ports: Array<{ id:number, active:boolean, occupied:boolean }>`.
  - Emits: `click-port(id:number)`.
- `components/modals/ConfirmDialog.vue`
  - Универсальная модалка подтверждения.
  - Props: `modelValue:boolean`, `title:string`, `text:string`, `confirmLabel?:string`, `cancelLabel?:string`, `severity?:'info'|'warn'|'danger'`.
  - Emits: `update:modelValue`, `confirm`, `cancel`.
- `components/modals/ShiftModal.vue`
  - Форма открытия обычной смены.
  - Props: `modelValue:boolean`, `form:any`.
  - Emits: `update:modelValue`, `submit(form)`.
- `components/modals/CloseShiftModal.vue`
  - Форма закрытия смены; валидация данных (касса/расходы/зарплаты).
  - Props/Emits аналогично.
- `components/modals/TechShiftModal.vue`
  - Открытие/закрытие тех. смены; простые поля + подтверждение.

### Новые composables
- `composables/useShift.js`
  - Держит состояние смен: `regularShift`, `techShift`, `isPaused` и т.п.
  - Методы: `openRegularShift`, `closeRegularShift(closedData)`, `openTechShift`, `closeTechShift`, `fetchShiftStatus`, `togglePause`.
  - Обрабатывает ошибки и повторную авторизацию (если требуется) через `useAuth`.
- `composables/usePorts.js`
  - Держит `gamePorts`, `selectedPort`, вычисления для сетки.
  - Методы: `loadInfo()`, `selectPort(id)`, `handlePortClick(id)`.
- `composables/useIndicators.js`
  - Держит индикаторы: `espConnected`, `extServerConnected`, `syncState`.
  - Подписка на системные сообщения из слоя WS (без `window.*`).
- `api/wsApi.js`
  - Единая обертка над WebSocket‑вызовами, скрывает `promise/do`.
  - Методы: `info()`, `smenaOpen()`, `smenaClose(closedData)`, `tehOpen()`, `tehClose(closeObj)`, `ping()`.

### Файловая структура (предлагаемая)
```
client/src/
  api/wsApi.js
  components/
    layout/HeaderBar.vue
    layout/FooterBar.vue
    game/PortsGrid.vue
    modals/ConfirmDialog.vue
    modals/ShiftModal.vue
    modals/CloseShiftModal.vue
    modals/TechShiftModal.vue
  composables/
    useShift.js
    usePorts.js
    useIndicators.js
```

## Детали реализации (ключевые моменты)
1) WS URL и поведение по умолчанию: читать `import.meta.env.VITE_WS_URL || 'ws://localhost:9000'` в низком слое (не в UI).
2) Убрать `window.systemMessageHandler`: организовать подписки внутри `useWebSocketGlobal` (или локальная шина событий) и передавать уведомления в `useIndicators`.
3) Ошибки: единый helper `notifyError(message)` (позже заменить на toast), без `alert` для прод.
4) Логи: в прод режиме (`import.meta.env.PROD`) минимизировать `console.log`.

## Пошаговый план (итерации с критерием готовности)
Итерация 0 — Подготовка
- Добавить `api/wsApi.js` с оберткой `request(do, payload, { timeout })` и методами `info/smenaOpen/smenaClose/tehOpen/tehClose/ping`.
- Критерий: все вызовы на странице можно заменить без изменения логики.

Итерация 1 — PortsGrid
- Вырезать сетку портов в `components/game/PortsGrid.vue`.
- Пробросить данные через props и клики через emit.
- В `HomePage.vue` слушать `click-port` и вызывать логику из страницы (временный мост).
- Критерий: визуально без изменений, клики работают как прежде.

Итерация 2 — Header/Footer
- Создать `layout/HeaderBar.vue`, `layout/FooterBar.vue`, перенести кнопки/индикаторы.
- Все действия экспонировать через emit, состояние — через props.
- Критерий: UI/поведение идентичны (пауза, выход/выключение, индикаторы).

Итерация 3 — Модалки
- Создать `ConfirmDialog.vue` и заменить подтверждения выхода/выключения.
- Создать `ShiftModal.vue`, `CloseShiftModal.vue`, `TechShiftModal.vue`.
- Критерий: открытие/закрытие модалок и сабмиты работают как прежде.

Итерация 4 — useShift
- Вынести всю логику смен (открыть/закрыть/тех) из страницы в `useShift` и перевести вызовы на `wsApi`.
- Критерий: HomePage не содержит прямых `sendMessage`; все операции смен — через `useShift`.

Итерация 5 — usePorts
- Перенести состояние и обработчики портов в `usePorts` (загрузка `info()`, выбор порта, computed состояния).
- Критерий: HomePage оперирует только вызовами `usePorts` и `PortsGrid`.

Итерация 6 — useIndicators
- Перенести индикаторы и подписки на системные сообщения в `useIndicators` (подключение к глобальному WS).
- Критерий: индикаторы меняются корректно, без глобальных хендлеров в `window`.

Итерация 7 — Уборка и полировка
- Привести строки к UTF‑8, убрать «битую» кодировку, разграничить `DEV/PROD`‑логи.
- Ограничить `HomePage.vue` до 150–200 строк `<script setup>`.
- Критерий: сборка `npm run build` успешна, консоль без новых ошибок.

## Спецификации props/emit (выдержки)
- HeaderBar.vue
  - Props: `{ isPaused: Boolean }`
  - Emits: `toggle-pause`, `request-shutdown`, `request-logout`, `open-shift-modal`
- FooterBar.vue
  - Props: `{ indicators: Object }`
- PortsGrid.vue
  - Props: `{ ports: Array, selectedId?: Number }`
  - Emits: `click-port(id: Number)`
- ConfirmDialog.vue
  - v-model: `modelValue:Boolean`; Emits: `update:modelValue`, `confirm`, `cancel`

## Пример wsApi (псевдокод)
```js
// client/src/api/wsApi.js
import { useWebSocketGlobal } from '@/composables/useWebSocketGlobal'

const request = async (doName, payload = {}, timeout = 10000) => {
  const { getGlobalSocket } = useWebSocketGlobal()
  const socket = await getGlobalSocket()
  const message = { do: doName, ...payload }
  return await socket.sendMessage(message, timeout)
}

export const wsApi = {
  info: () => request('info'),
  smenaOpen: () => request('smena', { enable: true }),
  smenaClose: (closed) => request('smena', { enable: false, closed }),
  tehOpen: () => request('teh-smena', { enable: true }),
  tehClose: (closeObj) => request('teh-smena', { enable: false, closeObj }),
  ping: () => request('ping', {}, 1000),
}
```

## Acceptance (приемка)
- Функциональные потоки: вход → открытие смены → работа с портами → закрытие смены; тех. смена — без регрессий.
- HomePage не содержит прямых WS‑вызовов, только обращения к composables/API.
- Визуальное поведение/верстка без отличий.
- Консоль без ошибок, DEV‑логи выключаемы в PROD.

## Риски и смягчение
- Риск рассинхронизации протокола WS: сначала вводим `wsApi`, затем переносим логику — минимальные изменения UI.
- Риск утраты поведения в модалках: сначала выделяем ConfirmDialog и покрываем кейсы выход/выключение, затем переносим формы смен.
- Риск сбоев из‑за «битых» строк: поэтапная замена строк UTF‑8 в изменяемых файлах.

## План отката
- Каждая итерация — отдельный коммит/PR. При регрессии — revert последней итерации.

## Оценка трудозатрат (грубая)
- Итерация 0–1: 4–6 часов (wsApi + PortsGrid).
- Итерация 2–3: 6–8 часов (Header/Footer + модалки).
- Итерация 4–6: 10–14 часов (composables, перенос логики).
- Итерация 7: 2–4 часа (полировка/приемка).