TeamFrame

TeamFrame Docs

Technická dokumentace

Praktická mapa systému TeamFrame podle aktuálního průchodu Codexem: architektura, citlivé vrstvy, release proces, licence, WEB, Dashboard, MiniDocky, PLC foundation a bezpečné checklisty.

Datum záznamu: 26.05.2026Bez tokenů, klíčů a HWIDLAN-first výrobní systém
Flask

WEB vrstva, Blueprinty a polling přes fetch().

PyQt6

Client, Dashboard, MiniDocky a desktop moduly.

Nuitka

Produkční EXE buildy, installer a release flow.

1. Co TeamFrame aktuálně je

TeamFrame je interní výrobní systém pro provoz v lokální síti. Není to jen jedna aplikace, ale propojený ekosystém serveru, klienta, dashboardu, webové vrstvy, licencí, installeru a výrobních modulů.

Primární filozofie systému je LAN-first provoz, jednoduchá údržba, rychlé lokální zobrazení dat a stabilita ve výrobě.

  • TeamFrame Server: backend, API, směny, data, launcher a web dashboard.
  • TeamFrame Client: hlavní PyQt6 klient pro každodenní práci.
  • TeamFrame Dashboard: PyQt6 dashboard pro výrobu, TV režim a moduly.
  • TeamFrame WEB Dashboard: Flask web vrstva pro mobil, tablet, PC a TV v LAN.
  • Installer/release pipeline: Nuitka EXE buildy, installer, update metadata a changelog.
  • Licence: lokální licenční vrstvy plus Cloudflare Worker/KV server.
  • MiniDock systém: malé top-level dock widgety mezi Clientem, Dashboardem a ServerLauncherem.
  • Budoucí vrstvy: PLC manager a metrics/OEE foundation.

2. Citlivé části, na které sahat opatrně

Tyto části jsou bezpečnostně nebo provozně citlivé. Změny dělat jen cíleně, po záloze a bez velkého refactoru.

  • licence, HWID, auth.enc, secure_key.bin
  • encryption, security router, security layer
  • Cloudflare licenční vrstva
  • ShiftBrain a commit engine
  • existing server.py API a existing /api/* endpointy
  • Incident Engine a Machine Status logika
  • existující Dashboard moduly, pokud se řeší jiná vrstva

3. Důležité složky

Projektové složky v typickém vývojovém nebo build workspace. Konkrétní umístění se může lišit podle instalace.

  • server/
  • TeamFrame/
  • TeamFrameDashboard/
  • InstallerProject/
  • server_license_storage/
  • teamframe_web/
  • TeamFrameBuild/

4. Server a WEB architektura

Produkční cílová architektura používá samostatné EXE procesy: server_api.exe, server_web.exe a server_launcher.exe.

Vývojový režim má spouštět Python zdrojáky. Produkční frozen/Nuitka režim má spouštět EXE. Detekce má být automatická, typicky přes getattr(sys, "frozen", False).

  • DEV: python server.py a python server_web.py
  • PROD: server_api.exe, server_web.exe a server_launcher.exe
  • WEB port: 8080
  • Lokální URL: http://127.0.0.1:8080
  • Dashboard route: /web/dashboard
  • WEB vrstva: Flask, Blueprinty, polling přes fetch(), bez FastAPI/Quart/SocketIO refactoru

5. WEB Dashboard

WEB dashboard je určený pro mistra a výrobu. Priorita je čitelnost z dálky, rychlost v LAN, stabilita a kompaktní průmyslový vzhled.

Dashboard nesmí jako hlavní text zobrazovat jen raw employee hash/ID. Hlavní text má být jméno, příjmení nebo display name. ID může být malé a šedé pod jménem.

  • login skeleton a session login
  • role admin/zaměstnanec jako příprava
  • ACTIVE/NEXT panely
  • machine cards
  • /web/api/status, /web/api/shifts a /web/api/machines
  • employee metadata enrichment
  • employee avatary přes backend endpoint
  • hodiny oddělené od polling refresh manageru
  • čas ve formátu 18.05.2026 22:47
  • statusy: provoz zelená, stop červená, přehoz oranžová, paused/pauza žlutá

6. Release a changelog systém

Release systém je v InstallerProject. Changelog je vedený přes pending_changes.json jako release queue.

Během vývoje se nové položky přidávají do pending. Přesun do deployed probíhá až při ostrém release buildu s -Publish. PlanOnly ani test build nesmí pending queue mazat.

  • build_full_release.ps1
  • build_test_sql_release.ps1
  • add_pending_change.ps1
  • update_changelog.ps1
  • CHANGELOG.md
  • release_notes.txt
  • release.json
  • teamframe_web/public/releases/latest.json
  • teamframe_web/public/releases/X.X.X.json
  • Výstupy mají být česky a UTF-8 safe

7. Download web

Download stránka už automaticky načítá /releases/latest.json a dynamicky renderuje changelog. Layout, dark theme, download box, counter logika, version.json a installer URL logika se nemají zbytečně měnit.

  • Soubor: teamframe_web/app/download/DownloadClient.tsx
  • Pokud latest.json neexistuje, changelog se nezobrazí.
  • Nesmí spadnout stránka ani Next.js hydration.

8. Licence a trial

Trial a placená licence musí být oddělené. Aktivace placené licence nesmí lokálně smazat trial_status.

Placená licence může přičíst zbývající trial dny k délce licence. Trial záznam má zůstat zachovaný pro audit.

  • Client a Dashboard maskují license_key a hwid v logu.
  • Server licence storage zachovává existující data při ukládání klíče.
  • Cloudflare Worker umí trial bonus dny.
  • Generátor licenčních klíčů nemá držet Cloudflare API token ve zdrojovém kódu.
  • Tokeny, licenční klíče a HWID neukládat do dokumentace.

9. Cloudflare Worker

Worker slouží jako licence server nad Cloudflare KV. KV binding musí být LICENSES.

Opravená verze workeru byla připravená na ploše jako teamframe_license_worker_fixed.js.

  • /api/license/check
  • /api/license/trial
  • /api/version
  • /api/download
  • /api/download-count
  • kontrola produktu server/client/dashboard
  • HWID lock
  • trial aktivace
  • expirování licence
  • download counter

10. MiniDock systém

MiniDocky běží mezi různými procesy: TeamFrame Client, TeamFrame Dashboard a TeamFrame ServerLauncher.

Cílem je jednotný bottom-right stack systém, který drží pořadí, nepřekrývá se a přežije zavření nebo restart jednotlivých procesů.

  • cross-process stack registry
  • řazení odspodu nahoru podle pořadí spuštění
  • auto realign po zavření/restartu docku
  • manuální vertikální drag reorder
  • persistentní pořadí docků
  • tooltip nad dockem
  • fullscreen suppress pro Dashboard fullscreen režim

11. Dashboard stabilita

Řešil se problém tichého ukončení Dashboardu bez tracebacku při rychlém fullscreen toggle a při některých těžších modulech.

U Dashboard modulů je potřeba hlídat duplicitní QTimer intervaly, těžké opakované vytváření widgetů a reentrantní Qt render.

  • debounce ochrana fullscreen toggle
  • bezpečné skrývání top-level MiniDock oken
  • logování closeEvent a aboutToQuit
  • sledování Snail overlay lifecycle
  • podezřelé oblasti: grafy, planned/preparing moduly, finished preparings, pyqtgraph

12. Snail overlay

V Clientu byla opravena chyba, kdy se oddělení s diakritikou posílalo přímo do URL a urllib padal na ASCII encode.

Dashboard snail už URL encoding používal.

  • Soubor: TeamFrame/snail/snail_anim.py
  • Příčina: dept=Montáž v raw URL
  • Oprava: urllib.parse.quote(str(dept), safe="")
  • Stejná API chyba se loguje max jednou za 30 sekund

13. ShiftEngine

12h ShiftEngine měl problém na decrypt/load vrstvě s chybou 'module' object is not callable. 8h ShiftEngine fungoval.

Směr opravy byl nepřepisovat security/encryption, ale použít stejný bezpečný AES-GCM employee decrypt helper jako zbytek serveru.

  • Nerozbíjet 8h ShiftEngine
  • Nerozbíjet encrypted employee files
  • Nerozbíjet existing decrypt architecture
  • Nerozbíjet ACTIVE/NEXT export contract

14. PLC a Metrics foundation

Byly připravené backend foundation vrstvy pro budoucí PLC/OEE architekturu. Zatím nejde o plné řízení výroby ani kompletní OEE dashboard.

PLC a metrics výpočty mají zůstat server-side, ne v GUI.

  • server/plc/plc_manager.py
  • server/plc/base_driver.py
  • server/plc/drivers/simulation_driver.py
  • server/plc/drivers/modbus_driver.py
  • server/plc/drivers/opcua_driver.py
  • server/metrics/metrics_manager.py
  • availability_engine, performance_engine, quality_engine, oee_engine
  • future OPC UA / Siemens / Modbus integrace

15. PLC Manager widget

PLC Manager widget je konfigurační GUI v TeamFrame Clientu. Není to realtime dashboard a nemá počítat OEE.

Modul má být napojený do existujícího TeamFrame module loaderu, ne otevíraný jako standalone okno.

  • Soubor: TeamFrame/widgets/plc_manager_widget.py
  • MODULE_KEY = plc_manager
  • správa PLC zařízení
  • machine mapping
  • metrics settings
  • české menu a ikonka

16. Installer a sdílená složka

Installer nesmí vytvářet nebo přepisovat sdílení ProgramData složky stylem Everyone/FULL. To je nebezpečné pro serverová data.

Cíl je zachovat přístup ostatních PC v LAN, ale bez otevřených práv pro každého.

  • nepoužívat Everyone/FULL
  • preferovat bezpečnější Authenticated Users/Change podle potřeby
  • čistit starý explicitní Everyone grant
  • hlídat ProgramData/share permissions hlavně na čisté instalaci

17. Ochrana proti vícenásobnému spuštění

Client ochranu měl, ServerLauncher a Dashboard byly doplněné stejným stylem přes Qt lock soubor.

Cíl je zabránit duplicitním procesům, které by rozbily dock stack, registry nebo provozní data.

  • Qt QLockFile
  • jeden běžící ServerLauncher
  • jeden běžící Dashboard
  • neotevírat duplicity

18. Testovací checklisty

Client

  1. Spustit TeamFrame Client.
  2. Přepnout oddělení na Montáž.
  3. Sledovat konzoli.
  4. Nemá se opakovat ASCII SNAIL API ERROR.
  5. Snail overlay má dál fungovat.

Dashboard

  1. Spustit Dashboard.
  2. Otevřít TV dashboard.
  3. Zapnout/vypnout fullscreen pomalu i rychle.
  4. Client/Server docky mají zůstat za fullscreenem.
  5. Dashboard se nemá tichounce ukončit.

WEB

  1. Spustit ServerLauncher.
  2. Spustit API a WEB.
  3. Otevřít http://127.0.0.1:8080/web/dashboard.
  4. Ověřit ACTIVE/NEXT, machine cards, status bar a čas.
  5. Z mobilu/tabletu otevřít LAN adresu serveru.

Release

  1. .\build_full_release.ps1 -Version X.X.X -PlanOnly
  2. Pending queue se nesmí změnit na deployed.
  3. latest.json se nesmí přepsat.
  4. .\build_full_release.ps1 -Version X.X.X -Publish
  5. Pending změny se přesunou do deployed a vygeneruje se latest.json.

19. Doporučení pro další práci

Krátkodobě se vyplatí sjednotit logging, projít encoding textových konstant, držet release queue aktuální a doplnit jednoduché healthchecky.

Střednědobě má smysl dokumentovat release pipeline, licence/trial flow, testy ShiftEngine 8h/12h a safe config editor.

Dlouhodobě je dobrý směr PLC simulation, metrics API, OEE dashboard až po stabilním backendu a lepší installer permission audit.

  • Nejdřív záloha, potom úprava.
  • Malé kroky místo velkého refactoru.
  • U licencí nikdy nelogovat tajné údaje.
  • U WEB dashboardu držet jednoduchost: Flask, Blueprint, fetch polling.
  • U výroby preferovat čitelnost a stabilitu před efekty.
  • U ShiftEngine nikdy netestovat na ostrých datech bez zálohy.

20. Užitečné příkazy

Přejít do TeamFrame Client projektu

cd <workspace>\TeamFrame

Py compile jednoho souboru

python -m py_compile .\snail\snail_anim.py

Přejít do InstallerProject

cd <workspace>\InstallerProject

Ověření pending changelog JSON

python -c "import json; from pathlib import Path; json.loads(Path('pending_changes.json').read_text(encoding='utf-8-sig')); print('OK')"

Přidání pending změny do release queue

.\add_pending_change.ps1 -Category "Fixed" -Module "client" -Text "Popis změny česky."

Release preview

.\build_full_release.ps1 -Version 1.6.10 -PlanOnly

Ostrý release

.\build_full_release.ps1 -Version 1.6.10 -Publish

Přejít do webu a spustit vývojový server

cd <workspace>\teamframe_web
npm install
npm run dev

Ověřit pouze dokumentační stránku

cd <workspace>\teamframe_web
npm exec eslint app/docs/page.tsx

Build webu

cd <workspace>\teamframe_web
npm run build

21. Krátké shrnutí hodnoty projektu

TeamFrame už není jednoduchý nástroj. Je to lokální výrobní platforma s vlastním serverem, dashboardy, webem, licencemi, installerem, updatery, šifrovanými daty, směnami, stroji, incidenty a release procesem.

Největší hodnota není jen v kódu. Je v tom, že systém řeší reálný provozní problém výroby: kdo je kde, co běží, co stojí, co se má dělat a jak to rychle vidí mistr, obsluha i vedení.