first prd

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