commit cbed0cf298ab7bc40cf193cb2565f0f0d770cade Author: bartool Date: Sat Mar 7 15:42:30 2026 +0100 first prd diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..4da876c --- /dev/null +++ b/PRD.md @@ -0,0 +1,52 @@ +# PRD: System Wersjonowania Plików CNC (CNC-Sync) – v1.0 +## 1. Cel Projektu (Overview) + +Stworzenie rozproszonego systemu wersjonowania plików (DVCS) dla środowisk warsztatowych (CAD/CNC). System ma zapewnić spójność plików G-code oraz projektów CAD pomiędzy komputerami projektantów a maszynami CNC w lokalnej sieci LAN, eliminując potrzebę używania pendrive'ów. + +## 2. Model Stanów Pliku (State Machine) + +Każdy plik w śledzonym folderze ("Repozytorium") musi znajdować się w jednym z czterech stanów: + +* **Untracked**: Plik nowy, nieznany systemowi. +* **Tracked**: Plik zsynchronizowany z serwerem (lokalny hash == hash na serwerze). +* **Modified**: Plik znany systemowi, ale zmieniony lokalnie. +* **Staged**: Plik oznaczony przez użytkownika do wysłania (przygotowany do Commitu). + +## 3. Funkcjonalności Kluczowe (Scope) + +* **Background Watchdog**: Usługa w tle monitorująca operacje: `Create`, `Update`, `Rename`, `Delete`. +* **Windows Toasts**: Powiadomienia systemowe pytające użytkownika: "Czy śledzić nowy plik?" po wykryciu operacji Create. +* **System Tray App**: Ikona w zasobniku z trzema opcjami: + + - **Zapisz (Commit UI)**: Okno wyboru plików ze stanu Modified/Staged, pole tekstowe na opis zmian (co i dlaczego). + - **Ustawienia: Wybór** folderu repozytorium, nazwa użytkownika. + - **Przeglądarka Repozytorium (Explorer)**: + - Wgląd w pełną strukturę plików na serwerze. + - Podgląd historii wersji dla każdego pliku (kto, kiedy, co zmienił). + - Selective Sync: Możliwość zaznaczenia, które pliki/foldery mają być pobrane i utrzymywane lokalnie na danej maszynie. + - **Wyjście**: Zamknięcie agenta. + +* **Synchronizacja**: Informowanie o nowej wersji na serwerze bez automatycznego nadpisywania (użytkownik decyduje, kiedy pobrać aktualizację, zachowując tę samą nazwę pliku). + +## 4. Architektura Techniczna +* **Serwer (Centralne Repozytorium)** + - **Blob Storage**: Katalog z plikami, gdzie nazwa pliku to jego hash. Zapobiega to duplikacji tych samych wersji. + - **Metadata DB**: Baza (np. SQLite/PostgreSQL) przechowująca strukturę drzewa plików, historię commitów i powiązania hashy z nazwami plików. + +* **Klient (Agent)** + + Instalowany na maszynach i stacjach CAD. Wykorzystuje bibliotekę watchdog do monitorowania systemu plików. + Lokalna struktura zarządzania: + - Index: Plik (np. JSON lub SQLite) przechowujący aktualny stan "snapshotu" lokalnego folderu (ścieżka, hash, data ostatniej modyfikacji). Służy do szybkiego wykrywania zmian bez liczenia hashy wszystkich plików przy każdym starcie. + - Config: Plik konfiguracyjny specyficzny dla maszyny (lista plików do synchronizacji, dane serwera, nazwa użytkownika). + - Local Blobs: (Opcjonalnie) tymczasowy bufor dla plików przygotowanych do wysłania (Staged). +* **Język**: Python. + +* **Komunikacja**: Odporna na awarie sieci, wspierająca tryb offline (buforowanie zmian lokalnie). + +## 5. Dane i Bezpieczeństwo + +* **Identyfikacja**: Unikalny username dla każdej instalacji. +* **Selective Sync**: Maszyna CNC przy tokarce nie musi posiadać plików dla frezarki. Użytkownik decyduje o subskrypcji plików w Przeglądarce Repozytorium. +* **Konflikty**: Brak automatycznego łączenia (merging). System informuje o nowej wersji, użytkownik akceptuje nadpisanie lokalnego pliku wersją z serwera. +* **Skala**: Obsługa do ok. 1000 plików w jednym repozytorium. \ No newline at end of file diff --git a/cnc-sync-prd.md b/cnc-sync-prd.md new file mode 100644 index 0000000..404fb90 --- /dev/null +++ b/cnc-sync-prd.md @@ -0,0 +1,298 @@ +# PRD: System Wersjonowania Plików CNC (CNC-Sync) + +## 1. Cel Projektu + +Stworzenie systemu wersjonowania plików dla środowisk warsztatowych +(CAD/CNC), który umożliwia: + +- kontrolę wersji plików G-code i projektów CAD +- synchronizację plików pomiędzy komputerami projektantów i maszynami + CNC +- eliminację transferu plików przez USB / pendrive +- śledzenie historii zmian (kto, kiedy, dlaczego) + +System działa w sieci LAN i umożliwia selektywną synchronizację plików +między komputerami. + +------------------------------------------------------------------------ + +## 2. Model Danych Repozytorium + +Minimalne repozytorium składa się z dwóch elementów: + +### Blob Storage + +Zawiera dane plików. + +Każda wersja pliku jest zapisana jako blob identyfikowany hashem: + +blob_hash = SHA256(file_content) + +Blob nie zawiera: - nazwy pliku - autora - historii + +Zawiera wyłącznie dane. + +### Metadata + +Przechowuje informacje o wersjach plików: + +- ścieżka pliku +- numer wersji +- hash blobu +- autor +- timestamp +- message (opis zmian) + +Przykładowa struktura: + +file_path\ +version\ +blob_hash\ +author\ +timestamp\ +message + +Dzięki temu możliwe jest: - odtworzenie historii pliku - identyfikacja +zmian - deduplikacja danych + +------------------------------------------------------------------------ + +## 3. Model Stanów Pliku + +Każdy plik w workspace może znajdować się w jednym z pięciu stanów. + +### Untracked + +Plik istnieje w workspace, ale repozytorium go nie zna. + +Może to być: - nowy plik - plik ignorowany przez system + +### Tracked + +Plik istnieje w repozytorium i jego zawartość jest identyczna z ostatnią +zapisaną wersją. + +workspace_hash == repo_hash + +### Modified + +Plik jest w repozytorium, ale został zmodyfikowany lokalnie. + +workspace_hash != repo_hash + +### Staged + +Plik został oznaczony przez użytkownika do zapisania w repozytorium przy +następnym commicie. + +### Ignored + +Pliki które system ignoruje (np. autosave). + +Przykład: + +*.tmp\ +*.bak\ +autosave.nc + +------------------------------------------------------------------------ + +## 4. Workflow Użytkownika + +Typowy workflow: + +untracked → staged → commit → tracked\ +tracked → modified → staged → commit → tracked + +System nie zapisuje zmian automatycznie. + +Użytkownik decyduje kiedy zapisać wersję (commit). + +Powód: - autosave - niedokończona praca - przypadkowe zmiany + +------------------------------------------------------------------------ + +## 5. Architektura Systemu + +### Serwer (Centralne Repozytorium) + +Serwer przechowuje: + +#### Blob Storage + +/blobs/\ +ab/\ +cd1234... + +Blob przechowuje dane pliku. + +#### Metadata Database + +Baza danych zawiera: + +files\ +versions\ +users + +Przykładowa tabela versions: + +id\ +file_path\ +version\ +blob_hash\ +author\ +timestamp\ +message + +------------------------------------------------------------------------ + +### Klient (Agent) + +Agent działa jako aplikacja w tle. + +Funkcje: - monitorowanie workspace - wykrywanie zmian - staging - +commit - synchronizacja + +### Lokalna struktura klienta + +workspace/\ +repo/\ +config.json\ +index.db + +### Config + +Zawiera konfigurację klienta: + +repo_url\ +username\ +workspace_path\ +selected_files + +### Index + +Index przechowuje informacje o stanie plików: + +file_path\ +last_hash\ +last_modified + +Index pozwala szybko wykrywać zmiany bez liczenia hashy wszystkich +plików. + +------------------------------------------------------------------------ + +## 6. Synchronizacja + +Synchronizacja działa na zasadzie: + +### Push + +Klient wysyła: - nowe blob - metadata commit + +### Pull + +Klient pobiera: - nowe wersje plików - blob których nie posiada + +### Selective Sync + +Użytkownik wybiera które pliki/foldery mają być dostępne lokalnie. + +Maszyna CNC może mieć tylko część repozytorium. + +------------------------------------------------------------------------ + +## 7. Interfejs Użytkownika + +### System Tray Application + +Ikona w trayu z opcjami: + +#### Commit + +Lista plików: - modified - staged + +Pole tekstowe na opis zmian. + +#### Repository Explorer + +Funkcje: - przegląd plików - historia zmian - selective sync + +#### Settings + +- repozytorium +- workspace +- username + +#### Exit + +Zamyka agenta. + +------------------------------------------------------------------------ + +## 8. Monitorowanie Systemu Plików + +Agent monitoruje operacje: + +Create\ +Modify\ +Rename\ +Delete + +Po wykryciu nowego pliku system pyta: + +Czy śledzić ten plik? + +------------------------------------------------------------------------ + +## 9. Konflikty + +System nie obsługuje merge. + +Jeśli plik ma nową wersję na serwerze użytkownik może: + +- pobrać nową wersję +- nadpisać lokalny plik +- zachować lokalny plik + +------------------------------------------------------------------------ + +## 10. Skala Systemu + +Docelowa skala: + +- około 1000 plików +- sieć LAN +- kilka stanowisk CAD +- kilka maszyn CNC + +------------------------------------------------------------------------ + +## 11. Struktura Modułów + +repository\ +blobstore\ +metadata\ +index\ +watcher\ +sync\ +cli\ +ui + +------------------------------------------------------------------------ + +## 12. MVP (Minimalna Wersja) + +Pierwsza wersja powinna mieć tylko: + +1. zapis blob\ +2. historia pliku\ +3. commit\ +4. checkout wersji\ +5. watcher plików + +Bez: + +- GUI +- selective sync +- conflict UI