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