first prd
This commit is contained in:
52
PRD.md
Normal file
52
PRD.md
Normal file
@@ -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.
|
||||||
298
cnc-sync-prd.md
Normal file
298
cnc-sync-prd.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user