5.2 KiB
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:
- zapis blob\
- historia pliku\
- commit\
- checkout wersji\
- watcher plików
Bez:
- GUI
- selective sync
- conflict UI