IoTManagerWeb/plan.md

IoTManagerWeb Refactor Plan (Cursor-friendly, zero behavior change)

0. Жёсткие правила (обязательные)

0.1. Backend = reference only • Backend не меняем. • При сомнениях: ../IoTManager → IoTManager/src/WsServer.cpp и src/modules/virtual/Loging*.

0.2. Протокол/форматы не менять • Команды и разделитель | — без изменений. • Blob протокол: 6-символьный header + размер (4 байта текстом) + payload. • Единственная входящая строка, которую обрабатываем: event.data === "/tstr|". Всё остальное string — игнор.

0.3. Не “улучшать” странности • Не переименовывать apdateWidgetByArray (опечатка намеренно). • Не менять reverse-команды: /tuoyal|, /gifnoc|, /oiranecs|, /sgnittes|, /tsil|, /rorre| и т.д. • Не “чинить” костыли charta (срезы и substring(0, len-1)).

0.4. Комментарии в новом коде — только EN • В существующих файлах можно не трогать.

⸻

1. Инварианты (то, что нельзя сломать)

Сохраняем и проверяем после каждого шага.

1.1. Критичная цепочка: первое устройство → devlist → подключение ко всем

Исходное состояние: • deviceList на старте содержит 1 элемент: { name:"--", id:"--", ip: myip, ws:0, status:false }. • firstDevListRequest = true ставится в onMount перед connectToAllDevices().

Шаг 1: подключаем только ws=0 • connectToAllDevices() создаёт сокеты для устройств где status === false || undefined. • Изначально это только индекс 0 → подключение к myip:81.

Шаг 2: в open handler • Только когда firstDevListRequest && ws === 0 → отправляем "/devlist|". • Это должно быть один раз (первый open первого сокета).

Шаг 3: приём devlis • В parseBlob по header === "devlis": incDeviceList = out.json → вызвать initDevList().

Шаг 4: initDevList() • Если firstDevListRequest: • devListOverride() полностью заменяет deviceList = incDeviceList, сортирует, • затем обязательно: deviceList[0].status = true (чтобы не переподключить первый сокет). • Иначе: • devListCombine() (combineArrays по IP + sortList). • Затем: firstDevListRequest = false → снова connectToAllDevices().

Запрещено менять порядок: onMount → firstDevListRequest=true → connectToAllDevices → open(ws0) → /devlist| → devlis → initDevList → override/combine → connectToAllDevices снова

1.2. Страница List (devices list) — контракт не ломать • Таблица строится по deviceList. • Удалять первую строку нельзя (кнопка удаления только при i > 0). • udps режим: • onModeChange: saveSett() + applicationReboot(). • onSaveList: • manual: если showInput → addDevInList() → saveList() → applicationReboot(). • manual без showInput → saveList() → applicationReboot(). • auto → saveList() + alert о переходе в ручной. • saveList() отправляет /tsil| с JSON deviceList, но статусы сбрасываются в false перед отправкой.

1.3. String vs Blob входящие

В message handler: • typeof event.data === "string": • обрабатывается только точное совпадение "/tstr|" → ack(ws, true). • любые другие строки игнорируем. • Все полезные данные приходят как Blob → только parseBlob/parseAllBlob.

1.4. Отправка данных устройству (WS) • Все команды уходят как строка через wsSendMsg(ws, msg)/sendToAllDevices(msg). • Формат не менять: "/command|payload" где payload JSON/текст. • На backend sendStringToWs(...) отправляет бинарно, но на фронте это всё равно Blob. Исключение — "/tstr|".

1.5. Charts — строгая совместимость

Цепочка: • пришёл layout → sortingLayout(ws) → отправить "/params|". • пришёл params → updateAllStatuses(ws) → отправить "/charts|". • пришли charta/chartb → apdateWidgetByArray(...) по topic.

charta: особый формат • header: bytes 0..6 = "charta" • size: bytes 7..11 (текст) • addJson: bytes 12..size (JSON) через getJsonAsJson(blob, size, out) • payload points: bytes size..end (TEXT) через getPayloadAsTxt(blob, size) • костыль массива: txt = "[" + txt.substring(0, txt.length - 1) + "]" — не менять

chartb: • обычный JSON payload через getPayloadAsJson(blob, size, out).

1.6. Export/Import config — формат файла не менять

Export: • exportJson = { mark: "iotm", config: configJson } • файл: pretty JSON + "\n\nscenario=>" + scenarioTxt • имя: export.json, MIME application/json

Import: • читать текст • проверки по порядку: 1. содержит "scenario=>" 2. jsonPart парсится 3. json.mark === "iotm" • затем (после confirm): • configJson = json.config • scenarioTxt = txtPart • перед присвоением: configJson = [], scenarioTxt = "" для реактивности

1.7. Backend reference locations (для сверки) • IoTManager/src/WsServer.cpp — текстовые команды и отправка • IoTManager/src/modules/virtual/Loging*/ — charta/chartb • IoTManager/data_svelte/ — test fixtures (items/config/widgets/layout/scenario/settings…)

⸻

2. Якоря для поиска в коде (вместо line numbers)

Cursor должен ориентироваться по строкам/сигнатурам.

2.1. devlist chain anchors • "/devlist|" (только в open handler) • "devlis" (в parseBlob) • firstDevListRequest • deviceList[0].status = true • connectToAllDevices()

2.2. message handler anchors • event.data === "/tstr|" (строгая проверка) • event.data instanceof Blob

2.3. charts anchors • "charta" / "chartb" • getJsonAsJson(blob, size, out) • txt.substring(0, txt.length - 1) • "/params|", "/charts|"

2.4. export/import anchors • "scenario=>" • mark: "iotm" • export.json

⸻

3. Backups (Step 1 — MUST DO)

3.1. Create _backup_refactor/ and copy files

Create folder _backup_refactor/ in project root (or src/_backup_refactor/).

Copy: • src/App.svelte • src/main.js • src/pages/{Config,Connection,Dashboard,List,Login,Profile,System}.svelte • src/widgets/{Chart,Input,Range,Toggle,Anydata}.svelte • src/components/{Alarm,Card,Modal,ModalPass,Progress}.svelte

Optional: add _backup_refactor/ to .gitignore.

DoD • Backup folder exists and contains exact copies.

Quick check • diff -ru src/App.svelte _backup_refactor/App.svelte shows identical before any edits.

⸻

4. Refactor Steps (small, safe, incremental)

Важное правило для Cursor: каждый шаг — отдельный минимальный дифф, после него smoke-check.

Step A — HTTP transport wrapper (priority 1, low risk)

Goal: вынести fetch-логику из App/pages в src/api/.

A1. Create src/api/http.js • helper requestJson({ url, method, headers, body, mode }) • returns { ok, status, data } or throws with structured error (но не ломаем поведение: лучше возвращать ok=false).

DoD • New module exists, used by ровно одной функцией (например getUser) без изменения результата.

A2. Create src/api/portal.js • Move portal calls: • getUser (/api/user/email, Bearer token token_iotm2) • getModInfo, getProfile (portal/compiler) — как сейчас • getConfigs, makePost (Config page) — как сейчас

DoD • В App/pages только импорт и вызов, UI поведение не меняется.

A3. Create src/api/firmware.js • Move getVersionsList (ver.json from settingsJson.serverip)

DoD • Версии как раньше отображаются/подгружаются.

Checks • Логин/профиль/конфиг-портал/версия работают как до.

⸻

Step B — WebSocket transport wrapper deviceSocket.js (priority 2, medium risk)

Goal: вынести только создание сокета + send/isOpen. Никакого протокола, никакого parse, никакого reconnect.

B1. Create src/api/deviceSocket.js Exports: • createConnection(wsIndex, ip, callbacks) • const socket = new WebSocket("ws://" + ip + ":81") • socket.binaryType = "blob" (fix bug: on instance) • socket.addEventListener("open"...) etc • store sockets by wsIndex in private map/array • send(wsIndex, msg) (only if open) • isOpen(wsIndex) • optional getSocket(wsIndex) (only if needed for debug parity)

Callbacks object:

{ onOpen(wsIndex, event), onMessage(wsIndex, data, event), onClose(wsIndex, event), onError(wsIndex, event), }

DoD • App still controls: • when to send /devlist| • whether to parseBlob/parseAllBlob • ack/reconnect • Only transport moved.

B2. Replace wsConnect/wsSendMsg usage minimally • Keep App’s logic structure intact. • wsConnect(ws) becomes something like: • compute ip via existing getIP(ws) • call deviceSocket.createConnection(ws, ip, { callbacks calling existing handlers })

Hard constraints • open handler must still contain: • if (firstDevListRequest && ws === 0) wsSendMsg(ws, "/devlist|"); • (или эквивалент через deviceSocket.send) • message handler must still contain strict /tstr| check and Blob-only parsing.

DoD • First device → devlist chain works unchanged. • binaryType is correct on each socket instance.

Checks (manual) • On first open of ws=0 exactly one /devlist| goes out. • devlis arrives and triggers initDevList. • After that, new sockets created for other devices.

⸻

Step C — UI layout components (priority 3, low risk)

Goal: split header/nav/footer into components without changing props/logic.

Create: • src/components/layout/AppHeader.svelte • src/components/layout/AppNav.svelte • src/components/layout/AppFooter.svelte (optional)

DoD • App.svelte becomes smaller but routes/props unchanged. • No logic moved besides markup.

⸻

Step D — Extract logic into lib/ (priority 3–4, highest risk; do in micro-steps)

Golden rule: move one “узкий контракт” at a time.

D1. src/lib/deviceListManager.js Exports: • sortList(list) • combineArrays(a, b) (merge by IP, preserve ws/index rules) • devListOverride(deviceList, incDeviceList): • returns new list or mutates (choose one, but keep App reactive updates) • MUST set deviceList[0].status = true • devListCombine(deviceList, incDeviceList) • initDevList({ deviceList, incDeviceList, firstDevListRequest }): • chooses override vs combine • returns { deviceList: newList, firstDevListRequest: false }

DoD • App still calls initDevList() from devlis branch, and then calls connectToAllDevices() exactly like before.

Checks • first device is not reconnected (status true for index 0 after override).

D2. src/lib/deviceConnection.js Exports: • getIP(wsIndex, deviceList) (single source of truth) • connectToAllDevices({ deviceList, createConnection }) • createConnection is from api/deviceSocket • connect only devices with status false/undefined • createOpenHandler({ firstDevListRequestRef, currentPageNameRef, selectedWsRef, markDeviceStatus, send, sendCurrentPageNameToSelectedWs }) • returns onOpen(wsIndex) • MUST keep logic: • markDeviceStatus(ws, true) • if firstDevListRequest && ws===0 → send(”/devlist|”) • page request logic as before • handleDevListReceived({ incDeviceList, getState, setState, initDevList, connectToAllDevices }) • calls deviceListManager.initDevList • then calls connectToAllDevices again

DoD • The entire chain “first device → devlis → connect all” remains identical, only moved.

Checks • same order of events, same number of connects/sends.

D3. src/lib/blobProtocol.js Goal: move Blob parsing mechanics (not “what to do after parsing”). Exports: • getPayloadAsJson, getPayloadAsTxt, getJsonAsJson • parseBlob(blob, ws, handlers) • parseAllBlob(blob, ws, handlers)

handlers is a map from header to callback: • itemsj, widget, config, scenar, settin, ssidli, errors, devlis, prfile, otaupd, corelg • for devlis, handler must call handleDevListReceived(...) (passed from App)

Charts handling inside parseAllBlob must preserve: • layout flow triggers /params| • params flow triggers /charts| • charta slicing + substring hack • chartb normal JSON

DoD • App owns: state vars, onParced, pageReady, and when to clear/reset. • blobProtocol only parses and calls callbacks.

D4. src/lib/wsReconnect.js Exports: • ack(ws, st) with per-ws timeouts and ping calc • wsTestMsgTask() style function (or start/stop wrapper)

Hard constraints • ack timeout logic stays identical: • on false → start waiting timeout (18s) → mark offline • on true → clear timeout and compute ping • send heartbeat /tst| for online sockets, reconnect offline sockets.

DoD • Heartbeat and reconnect behavior unchanged in UI (percent/timers etc).

⸻

5. App.svelte end state (what remains)

App should keep: • All state variables (deviceList/layoutJson/paramsJson/parsed/pageReady/settingsJson/configJson/scenarioTxt/etc). • Routing (tinro), handleNavigation, UI gating (Alarm vs Routes). • onParced logic and calls to HTTP functions (getVersionsList/getModInfo/getProfile). • Wiring: builds handler maps and passes them into deviceSocket, blobProtocol, deviceConnection, wsReconnect.

App should NOT own: • low-level WS creation (deviceSocket) • list merge/sort logic (deviceListManager) • blob slicing/parsing mechanics (blobProtocol) • reconnect/ack timer internals (wsReconnect) • connection lifecycle logic (deviceConnection)

⸻

6. Smoke Test (manual, but strict)

Run after each step.

6.1. Boot + devlist chain • Open app with one known IP (myip). • Confirm: 1. connects only ws=0 initially 2. on open(ws=0) sends /devlist| 3. receives devlis (Blob) 4. initDevList runs, override sets deviceList[0].status = true 5. connects to other devices (ws=1..n)

6.2. Dashboard chain • On /: • after layout → sends /params| • after params → sends /charts| • receives charta/chartb updates widgets by topic

6.3. List page • Cannot delete first row. • Add device in manual mode works. • Save list sends /tsil| with statuses reset false. • udps toggle triggers saveSett + reboot.

6.4. Config page • Export produces JSON + scenario=>. • Import validates scenario=>, JSON, mark=“iotm”. • After import config/scenario apply correctly. • moduleOrder buttons (btn*) still send /order|....

6.5. Heartbeat • /tst| goes out periodically, /tstr| comes back as string and triggers ack only. • Any other string message is ignored.

⸻

7. “Ripgrep checklist” (after each step)

Cursor должен прогонять поиск и убедиться, что паттерны на месте. • rg -n 'firstDevListRequest' src/App.svelte src/lib -S • rg -n '"/devlist|"' src -S • rg -n 'event.data === "/tstr|"' src -S • rg -n 'instanceof Blob' src -S • rg -n 'charta|chartb' src -S • rg -n 'substring(0, txt.length - 1)' src -S • rg -n 'scenario=>' src -S • rg -n 'mark:\s*"iotm"' src -S • rg -n 'apdateWidgetByArray' src -S

⸻

8. Backend reference notes (quick) • Text commands parsing: IoTManager/src/WsServer.cpp (headerStr до |) • sendFileToWsByFrames: binary frames with 6-char headers (itemsj/widget/config/scenar/settin/layout/params/devlis/prfile/otaupd/charta…) • sendStringToWs: header|0012|payload but sent as binary (front receives Blob) • Exception: /tstr| sent as WStype_TEXT and arrives as string • Logging modules: IoTManager/src/modules/virtual/Loging*/ produce charta/chartb • Test fixtures: IoTManager/data_svelte/

⸻

9. Target folder tree (after completion)

src/ api/ http.js portal.js firmware.js deviceSocket.js lib/ blobProtocol.js deviceListManager.js deviceConnection.js wsReconnect.js dashboardLayout.js # optional components/layout/ AppHeader.svelte AppNav.svelte AppFooter.svelte App.svelte pages/ widgets/ ... _backup_refactor/