# 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