299 lines
5.2 KiB
Markdown
299 lines
5.2 KiB
Markdown
# 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
|