From a5266618258f2e59fa25f24165324efa2a1d5f4f Mon Sep 17 00:00:00 2001 From: mirivlad Date: Thu, 4 Jun 2026 03:32:02 +0800 Subject: [PATCH] docs: align vault storage documentation with code --- README.md | 7 ++-- cmd/verstak-gui/bindings_config.go | 30 ++++++++-------- docs/03_Data_Model_Storage.md | 57 ++++++++++++++++-------------- docs/PLAN.md | 2 +- docs/VAULT_LAYOUT.md | 24 ++++++++----- 5 files changed, 65 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 5d81678..9f93c78 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ ```bash # Всё сразу (GUI + сервер) -./build.sh +./scripts/build.sh # Или по отдельности ./scripts/build.sh gui # только GUI @@ -107,8 +107,7 @@ go run ./cmd/verstak/ --help │ └── ...svelte # Компоненты ├── migrations/ # SQL-миграции ├── docs/ # Документация -├── build.sh # Скрипт полной сборки -└── scripts/ # Вспомогательные скрипты +└── scripts/ # Вспомогательные скрипты и сборка ``` ## CLI команды @@ -125,7 +124,7 @@ go run ./cmd/verstak/ sync status # Статус синхронизации ``` vault/ - .verstak/ # Служебные данные (БД, кеш, бэкапы) + .verstak/ # Служебные данные: index.db, config.yml, trash, blobs Проекты/ # Пользовательские папки-дела Клиенты/ Рабочие/ diff --git a/cmd/verstak-gui/bindings_config.go b/cmd/verstak-gui/bindings_config.go index 5025b11..af60887 100644 --- a/cmd/verstak-gui/bindings_config.go +++ b/cmd/verstak-gui/bindings_config.go @@ -23,12 +23,12 @@ import ( // StartupStatus describes the application startup state. type StartupStatus struct { - Status string `json:"status"` // "first_run", "recovery", "ready" - VaultPath string `json:"vaultPath"` // configured or default vault path - VaultExists bool `json:"vaultExists"` // whether vault.db exists at the path - DefaultPath string `json:"defaultPath"` // default vault path suggestion - Error string `json:"error,omitempty"` - AppConfig *config.AppConfig `json:"appConfig,omitempty"` + Status string `json:"status"` // "first_run", "recovery", "ready" + VaultPath string `json:"vaultPath"` // configured or default vault path + VaultExists bool `json:"vaultExists"` // whether index.db exists at the path + DefaultPath string `json:"defaultPath"` // default vault path suggestion + Error string `json:"error,omitempty"` + AppConfig *config.AppConfig `json:"appConfig,omitempty"` } // GetStartupStatus checks the global config and vault state. @@ -336,7 +336,7 @@ func (a *App) CheckVaultPath(vaultPath string) (*CheckVaultPathResult, error) { } } - desc := describeVaultPath(vaultPath, exists, hasVault) + desc := describeVaultPath(exists, hasVault) return &CheckVaultPathResult{ Exists: exists, @@ -355,7 +355,7 @@ func checkDirWritable(dir string) bool { return true } -func describeVaultPath(path string, exists, hasVault bool) string { +func describeVaultPath(exists, hasVault bool) string { if !exists { return "Путь не существует. Будет создан новый vault." } @@ -367,13 +367,13 @@ func describeVaultPath(path string, exists, hasVault bool) string { // VaultInfo returns information about the currently open vault. type VaultInfo struct { - Path string `json:"path"` - DBPath string `json:"dbPath"` - FilesPath string `json:"filesPath"` - TrashPath string `json:"trashPath"` - Healthy bool `json:"healthy"` - NodeCount int `json:"nodeCount"` - FileCount int `json:"fileCount"` + Path string `json:"path"` + DBPath string `json:"dbPath"` + FilesPath string `json:"filesPath"` + TrashPath string `json:"trashPath"` + Healthy bool `json:"healthy"` + NodeCount int `json:"nodeCount"` + FileCount int `json:"fileCount"` } func (a *App) GetVaultInfo() (*VaultInfo, error) { diff --git a/docs/03_Data_Model_Storage.md b/docs/03_Data_Model_Storage.md index 42b88f2..5a8d82c 100644 --- a/docs/03_Data_Model_Storage.md +++ b/docs/03_Data_Model_Storage.md @@ -9,8 +9,9 @@ .verstak/ index.db config.yml - device.yml - sync_state.db + device_token.json + blobs/ + plugins/ trash/ history/ originals/ @@ -51,6 +52,10 @@ CREATE TABLE nodes ( title TEXT NOT NULL, slug TEXT NOT NULL, path TEXT NULL, + section TEXT NULL, + template_id TEXT NOT NULL DEFAULT '', + fs_path TEXT NOT NULL DEFAULT '', + archived INTEGER NOT NULL DEFAULT 0, sort_order INTEGER NOT NULL DEFAULT 0, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, @@ -135,6 +140,7 @@ CREATE TABLE worklog_entries ( billable INTEGER NOT NULL DEFAULT 0, summary TEXT NOT NULL, details TEXT NULL, + source TEXT NOT NULL DEFAULT 'unknown', created_at TEXT NOT NULL, updated_at TEXT NOT NULL ); @@ -145,38 +151,25 @@ CREATE TABLE worklog_entries ( ```sql CREATE TABLE activity_events ( id TEXT PRIMARY KEY, - node_id TEXT NULL REFERENCES nodes(id), - source TEXT NOT NULL, + node_id TEXT NOT NULL, + parent_id TEXT, event_type TEXT NOT NULL, - title TEXT NULL, - path TEXT NULL, - url TEXT NULL, - app_name TEXT NULL, - process_name TEXT NULL, - started_at TEXT NOT NULL, - ended_at TEXT NULL, - duration_seconds INTEGER NULL, - metadata_json TEXT NULL, - confidence INTEGER NOT NULL DEFAULT 100, + target_type TEXT, + target_id TEXT, + target_path TEXT, + title TEXT NOT NULL DEFAULT '', + metadata TEXT NOT NULL DEFAULT '{}', created_at TEXT NOT NULL ); ``` -### worklog_suggestions +### worklog_entry_events ```sql -CREATE TABLE worklog_suggestions ( - id TEXT PRIMARY KEY, - node_id TEXT NOT NULL REFERENCES nodes(id), - date TEXT NOT NULL, - started_at TEXT NULL, - ended_at TEXT NULL, - suggested_minutes INTEGER NULL, - summary TEXT NOT NULL, - evidence_json TEXT NOT NULL, - status TEXT NOT NULL DEFAULT 'pending', - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL +CREATE TABLE worklog_entry_events ( + entry_id TEXT NOT NULL REFERENCES worklog_entries(id) ON DELETE CASCADE, + event_id TEXT NOT NULL, + PRIMARY KEY (entry_id, event_id) ); ``` @@ -208,6 +201,16 @@ CREATE TABLE sync_ops ( pushed_at TEXT NULL, applied_at TEXT NULL ); + +CREATE TABLE sync_state ( + device_id TEXT PRIMARY KEY, + server_url TEXT NOT NULL DEFAULT '', + api_key TEXT NOT NULL DEFAULT '', + last_push_rev INTEGER NOT NULL DEFAULT 0, + last_pull_rev INTEGER NOT NULL DEFAULT 0, + last_sync_at TEXT, + last_pull_seq INTEGER NOT NULL DEFAULT 0 +); ``` ## 3. Правила хранения diff --git a/docs/PLAN.md b/docs/PLAN.md index 8d0375b..ca0e825 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -312,7 +312,7 @@ verstak/ ```bash # Полная сборка -./build.sh +./scripts/build.sh # По отдельности ./scripts/build.sh gui # Wails v2 GUI diff --git a/docs/VAULT_LAYOUT.md b/docs/VAULT_LAYOUT.md index f63907b..a586543 100644 --- a/docs/VAULT_LAYOUT.md +++ b/docs/VAULT_LAYOUT.md @@ -10,11 +10,13 @@ in any file manager, and find materials by browsing the folder structure. ``` vault/ .verstak/ # App data — not user-facing - vault.db - backups/ + index.db + config.yml + device_token.json + blobs/ + originals/ thumbnails/ - cache/ - sync/ + plugins/ trash/ history/ @@ -56,14 +58,20 @@ vault/ Contains all application internal data: -- `vault.db` — SQLite database -- `backups/` — automatic vault backups +- `index.db` — SQLite database +- `config.yml` — vault-local settings and vault id +- `device_token.json` — sync device token, stored separately from general config +- `blobs/` — sync blob cache +- `originals/` — imported originals - `thumbnails/` — generated thumbnails -- `cache/` — temporary cache -- `sync/` — sync state and blobs +- `plugins/` — optional local plugins - `trash/` — moved here on deletion - `history/` — file version history +Global application settings live outside the vault at +`~/.config/verstak/config.json`. This includes the active vault path, UI +settings, enabled templates and sync UI settings. + ## Migration Existing vaults can be migrated with the `MigrateVaultLayout()` command,