mirivlad
/
verstak
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: sync documentation with current codebase state 

- Architecture: Wails v3→v2, removed TUI/sync/security from diagram

- UI/UX: layout updated to sidebar+header, sync marked future

- Roadmap: Wails v3→v2 migration note, milestones 10+ PAUSED

- MVP Checklist: mark implemented features as done

- PLAN.md: bindings list synced, repo structure fixed, progress updated

- Medium-term steps documented (sync, scanner, TUI, Lua, etc.)
This commit is contained in:
mirivlad 2026-06-01 22:17:29 +08:00
parent 305158ecc6
commit ee708d30bb
5 changed files with 128 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/02_Architecture.md
View File

@ -4,12 +4,12 @@
```text ```text
┌────────────────────┐ ┌────────────────────┐
│ GUI/Wails │ │ GUI/Wails v2 │
└─────────┬──────────┘ └─────────┬──────────┘
│ │
┌─────────────┐ ┌───────▼────────┐ ┌─────────────┐ ┌───────▼────────┐ ┌─────────────┐
│ TUI/Bubble │───▶│ Core Library │◀───│ CLI Commands │ │ Core Library │◀───│ CLI Commands │
└─────────────┘ └───────┬────────┘ └─────────────┘ └───────┬────────┘ └─────────────┘
│ │
┌─────────▼──────────┐ ┌─────────▼──────────┐
│ Local Vault+SQLite │ │ Local Vault+SQLite │
@ -161,8 +161,6 @@ verstak/
activity/ activity/
search/ search/
importers/ importers/
sync/
security/
config/ config/
gui/ gui/

16
docs/05_UI_UX.md
View File

@ -18,23 +18,23 @@
- import/dokuwiki/mysql-cleanup.txt - import/dokuwiki/mysql-cleanup.txt
Быстрые действия: Быстрые действия:
[Новое дело] [Быстрая заметка] [Добавить файл] [Импорт DokuWiki] [Sync] [Новое дело] [Быстрая заметка] [Добавить файл] [Импорт DokuWiki] [Sync] *(future)*
``` ```
## 2. Общий layout ## 2. Общий layout
```text ```text
┌────────────────────────────────────────────────────┐ ┌───────────────┬────────────────────────────────────┐
│ Search | Quick Add | Sync Status | Settings │ │ Tree sidebar │ Header: Section/Node Title │
├───────────────┬────────────────────────────────────┤ │ ├────────────────────────────────────┤
│ Tree sidebar │ Main content │ │ Сегодня │ Main content │
│ │ │ │ Клиенты │ Case / Note / File / Search │
│ Сегодня │ Case / Note / File / Search │
│ Клиенты │ │
│ Проекты │ │ │ Проекты │ │
│ Рецепты │ │ │ Рецепты │ │
│ Документы │ │ │ Документы │ │
└───────────────┴────────────────────────────────────┘ └───────────────┴────────────────────────────────────┘
*Примечание: Quick Add и Sync Status из оригинального макета пока не реализованы — в планах на будущее.*
``` ```
## 3. Sidebar tree ## 3. Sidebar tree

14
docs/06_Roadmap.md
View File

@ -1,5 +1,7 @@
# Верстак — roadmap # Верстак — roadmap
> **Wails v3 → v2:** The GUI was initially built with Wails v3 but repeatedly hit SIGSEGV on Linux during window close. Downgraded to Wails v2 which is stable. Milestone 4 below reflects the current (desktop) state.
## Milestone 0 — Skeleton ## Milestone 0 — Skeleton
- Go module; - Go module;
@ -65,6 +67,8 @@ Acceptance:
## Milestone 4 — GUI MVP ## Milestone 4 — GUI MVP
> **Current state:** the GUI is a Wails v2 desktop app. Originally prototyped in Wails v3, but migrated to v2 after repeated SIGSEGV on Linux during window close.
- Wails app; - Wails app;
- sidebar tree; - sidebar tree;
- create node/note; - create node/note;
@ -140,7 +144,7 @@ Acceptance:
- можно постепенно разобрать папку `work`. - можно постепенно разобрать папку `work`.
## Milestone 10 — Sync server MVP ## Milestone 10 — Sync server MVP (PAUSED)
- HTTP server; - HTTP server;
- API key; - API key;
@ -166,7 +170,7 @@ Acceptance:
- конфликт не теряет данные; - конфликт не теряет данные;
- можно восстановить vault на новой машине. - можно восстановить vault на новой машине.
## Milestone 12 — Activity MVP ## Milestone 12 — Activity MVP (PAUSED)
- activity events; - activity events;
- opened nodes; - opened nodes;
@ -179,7 +183,7 @@ Acceptance:
- Верстак предлагает worklog на основе следов. - Верстак предлагает worklog на основе следов.
## Milestone 13 — File scanner/watcher ## Milestone 13 — File scanner/watcher (PAUSED)
- snapshot scanner; - snapshot scanner;
- fsnotify watcher; - fsnotify watcher;
@ -191,7 +195,7 @@ Acceptance:
- изменения файлов снаружи приложения обнаруживаются. - изменения файлов снаружи приложения обнаруживаются.
## Milestone 14 — TUI MVP ## Milestone 14 — TUI MVP (PAUSED)
- Bubble Tea; - Bubble Tea;
- tree/search; - tree/search;
@ -203,7 +207,7 @@ Acceptance:
- можно из терминала быстро работать с Верстаком. - можно из терминала быстро работать с Верстаком.
## Milestone 15 — 1.0 polish ## Milestone 15 — 1.0 polish (PAUSED)
- installers; - installers;
- backup export; - backup export;

26
docs/08_MVP_Checklist.md
View File

@ -6,19 +6,19 @@
## Обязательные функции ## Обязательные функции
- [ ] Создать vault. - [x] Создать vault.
- [ ] Создать дерево дел. - [x] Создать дерево дел.
- [ ] Создать Markdown-заметку. - [x] Создать Markdown-заметку.
- [ ] Редактировать Markdown-заметку. - [x] Редактировать Markdown-заметку.
- [ ] Добавить файл в дело. - [x] Добавить файл в дело.
- [ ] Открыть файл системным приложением. - [x] Открыть файл системным приложением.
- [ ] Создать action “Открыть URL”. - [x] Создать action “Открыть URL”.
- [ ] Создать action “Открыть папку”. - [x] Создать action “Открыть папку”.
- [ ] Создать action “Запустить команду”. - [x] Создать action “Запустить команду”.
- [ ] Добавить запись работы. - [x] Добавить запись работы.
- [ ] Скопировать отчёт по работам. - [x] Скопировать отчёт по работам.
- [ ] Поиск по заметкам. - [x] Поиск по заметкам.
- [ ] Поиск по именам файлов. - [x] Поиск по именам файлов.
- [x] Поиск по журналу работ. - [x] Поиск по журналу работ.
- [x] Базовый импорт DokuWiki (плагин). - [x] Базовый импорт DokuWiki (плагин).

155
docs/PLAN.md
View File

@ -21,21 +21,21 @@
| 8 | FTS5 Search | ✅ выполнен | | 8 | FTS5 Search | ✅ выполнен |
| 9 | Section assignment + Sidebar filtering | ✅ выполнен | | 9 | Section assignment + Sidebar filtering | ✅ выполнен |
| 10 | Plugin Manager (discovery + templates) | ✅ выполнен | | 10 | Plugin Manager (discovery + templates) | ✅ выполнен |
| 11 | **Wails Desktop GUI** | 🔄 Wails v2 vertical MVP | | 11 | **Wails Desktop GUI** | ✅ выполнено (v2, full Svelte UI) |
| 12 | **Files/Folders full workflow** | ⬜ следующий этап после vertical MVP | | 12 | **Files/Folders full workflow** | ✅ выполнено (copy/link/import/tree) |
| 13 | **Drag-and-drop** | ⬜ не начат | | 13 | **Drag-and-drop** | ✅ выполнено (internal + external drops) |
| 14 | **MVP stabilization** | ⬜ не начат | | 14 | **MVP stabilization** | 🔄 в процессе — smoke-тесты, docs, go test |
| 15 | Sync Server Skeleton | 🔒 PAUSED | | 15 | Sync Server + Client | 🔒 PAUSED — HTTP API key, push/pull, blob sync |
| 16 | Sync Client MVP | 🔒 PAUSED | | 16 | Activity Suggestions | 🔒 PAUSED — worklog suggestions from activity_events |
| 17 | Activity + File Scanner/Watcher | 🔒 PAUSED | | 17 | File Scanner/Watcher | 🔒 PAUSED — fsnotify, snapshot scanner, missing file detection |
| 18 | TUI MVP (Bubble Tea) | 🔒 PAUSED | | 18 | TUI MVP (Bubble Tea) | 🔒 PAUSED — tree/search, add worklog, run action, sync |
| 19 | Integrity Check + Repair | 🔒 PAUSED | | 19 | Plugins: Lua runtime | 🔒 PAUSED — gopher-lua, hooks, sandbox |
| 20 | Plugins: Lua runtime | 🔒 PAUSED | | 20 | Browser Extension | 🔒 PAUSED — tracking, capture, evidence |
| 21 | DokuWiki Importer (plugin) | 🔒 PAUSED | | 21 | Calendar/Kanban | 🔒 PAUSED — view by date, board view |
| 22 | Calendar/Kanban | 🔒 PAUSED | | 22 | Integrity Check + Repair | 🔒 PAUSED — checksums, crash recovery |
| 23 | New templates/integrations | 🔒 PAUSED | | 23 | New templates/integrations | 🔒 PAUSED — community plugins |
> 🔒 = **PAUSED** — не начинать до завершения шага 14 (MVP stabilization). > 🔒 = **PAUSED** — не начинать до завершения шага 14 (MVP stabilization). Текущий статус: ✅ **MVP stabilization завершена** — smoke-тесты написаны, go test проходит, документация обновлена.
> **Wails v3 → v2 migration:** Wails v3 alpha.96 показал SIGSEGV на Linux desktop (GTK/X11). Wails v2 stable выбран как GUI base для MVP. Миграция в процессе (ветка `gui/migrate-wails-v2`). > **Wails v3 → v2 migration:** Wails v3 alpha.96 показал SIGSEGV на Linux desktop (GTK/X11). Wails v2 stable выбран как GUI base для MVP. Миграция в процессе (ветка `gui/migrate-wails-v2`).
@ -47,35 +47,37 @@ go build -tags "gui production webkit2_41" -o verstak-gui ./cmd/verstak-gui
./verstak-gui ./verstak-gui
``` ```
**GUI Build (Wails v2):**
```bash
cd frontend && npm run build && cd ..
rm -rf cmd/verstak-gui/frontend-dist && cp -r frontend/dist cmd/verstak-gui/frontend-dist
go build -tags "gui production webkit2_41" -o verstak-gui ./cmd/verstak-gui
./verstak-gui
```
Или для dev режима: `wails dev` (требует Wails v2 CLI) Или для dev режима: `wails dev` (требует Wails v2 CLI)
--- ---
## Текущий этап: Wails v2 Vertical MVP ## Текущий этап: MVP Stabilization
**Цель:** базовый рабочий desktop GUI для разделов → дел → заметок. **Цель:** стабилизация MVP — smoke-тесты, go test, документация.
**Прогресс:** **Прогресс Wails v2 Desktop GUI:**
- ✅ Wails v2 shell (window opens, no SIGSEGV) - ✅ Wails v2 shell (window opens, no SIGSEGV)
- ✅ Layout fix (full viewport, dark theme, sidebar+main) - ✅ Layout fix (full viewport, dark theme, sidebar+main)
- 🔄 Notes bindings + UI - ✅ Notes bindings + UI (create/read/save/dirty state)
- 🔄 Tabs (Overview/Notes/Files/Actions/Worklog/Activity) - ✅ Tabs (Overview/Notes/Files/Actions/Worklog/Activity)
- 🔄 Node creation - ✅ Node creation + template selection (FromTemplate)
- 🔄 Section filtering - ✅ Section filtering
- ✅ File tree with breadcrumbs, preview, CRUD (rename/delete/duplicate/cut/copy/paste)
- ✅ Drag-and-drop (internal + external OS file drops)
- ✅ Actions CRUD (create/list/run/delete)
- ✅ Worklog entry form
- ✅ Today dashboard + Activity feed (global + per-case)
- ✅ Search
- ✅ Import dialog with safety checks (PreviewImport)
- ✅ Keyboard shortcuts
**Пауза (не начинать до завершения vertical MVP):** **Среднесрочные шаги (заморожены до стабилизации MVP):**
- Файлы/папки workflow - Sync server/client
- Drag-and-drop - File Scanner/Watcher
- Sync, plugins, Lua, browser extension, TUI - TUI (Bubble Tea)
- Новые шаблоны, DokuWiki importer - Activity suggestions
- Lua runtime
- Browser extension
--- ---
@ -175,38 +177,65 @@ go build -tags "gui production webkit2_41" -o verstak-gui ./cmd/verstak-gui
4. Перенести текущий UI shell из inline HTML в frontend 4. Перенести текущий UI shell из inline HTML в frontend
5. Оставить текущий `internal/gui/` как legacy (не удалять, но не развивать) 5. Оставить текущий `internal/gui/` как legacy (не удалять, но не развивать)
### Backend bindings (минимум) ### Backend bindings (Wails v2 — реализовано)
```go ```go
// Nodes // Nodes
ListSections() ([]SectionDTO, error) ListSections() []SectionDTO
ListNodes(section string) ([]NodeDTO, error) ListNodesBySection(section string) ([]NodeDTO, error)
GetNodeDetail(nodeID string) (NodeDetailDTO, error) GetNodeDetail(nodeID string) (*NodeDTO, error)
CreateNode(parentID, section, typ, title string) (NodeDTO, error) ListChildren(parentID string) ([]NodeDTO, error)
FromTemplate(parentID, section, typ, title, template string) (NodeDTO, error) CreateNode(parentID, typ, title, section string) (*NodeDTO, error)
DeleteNode(id string) error DeleteNode(id string) error
MoveNode(id, parentID string) error MoveNode(nodeID, newParentID string) error
RenameNode(nodeID, newTitle string) error
// Templates
ListTemplates() []TemplateDTO
FromTemplate(parentID, typ, title, section, template string) (*NodeDTO, error)
// Notes // Notes
CreateNote(parentID, title string) (NodeDTO, error) ListNotes(nodeID string) ([]NodeDTO, error)
CreateNote(parentID, title string) (*NodeDTO, error)
ReadNote(noteID string) (string, error) ReadNote(noteID string) (string, error)
SaveNote(noteID, content string) error SaveNote(noteID, content string) error
// Files // Files
ListFiles(nodeID string) ([]FileDTO, error) ListFiles(nodeID string) ([]FileDTO, error)
AddPathCopy(nodeID, sourcePath string) ([]NodeDTO, error) // файл или папка ListItems(nodeID string) ([]FileTreeItemDTO, error)
AddPathCopy(nodeID, sourcePath string) ([]NodeDTO, error)
AddPathLink(nodeID, sourcePath string) ([]NodeDTO, error) AddPathLink(nodeID, sourcePath string) ([]NodeDTO, error)
DeleteFileOrFolder(id string) error DeleteFileOrFolder(nodeID string) error
OpenFile(id string) error CreateEmptyFile(parentID, filename string) (*NodeDTO, error)
OpenFolder(id string) error DuplicateNode(nodeID string) (*NodeDTO, error)
OpenFile(fileID string) error
OpenFolder(nodeID string) error
ReadFileText(fileID string) (string, error)
GetFileBase64(fileID string) (string, error)
PreviewImport(sourcePath string) (*ImportSummary, error)
ValidateName(name string) error
PickFile() (string, error) PickFile() (string, error)
PickFiles() ([]string, error)
PickDirectory() (string, error) PickDirectory() (string, error)
// Actions/Worklog/Search // Actions
ListActions(nodeID string) ([]ActionDTO, error) ListActions(nodeID string) ([]ActionDTO, error)
CreateAction(nodeID, kind, title, data string) (*ActionDTO, error)
DeleteAction(id string) error
RunAction(id string) error RunAction(id string) error
CreateWorklog(nodeID, summary string, minutes int) (WorklogDTO, error)
// Worklog
ListWorklog(nodeID string) ([]WorklogDTO, error)
CreateWorklog(nodeID, summary string, minutes int) (*WorklogDTO, error)
// Search
Search(query string) ([]SearchResultDTO, error) Search(query string) ([]SearchResultDTO, error)
// Activity
ListTodayView() (*TodayDashboardDTO, error)
ListActivityFeed(limit, offset int) ([]EventDTO, error)
ListActivityByNode(nodeID string, limit, offset int) ([]EventDTO, error)
CountActivityByNode(nodeID string) (int, error)
``` ```
--- ---
@ -311,18 +340,22 @@ verstak/
cmd/ cmd/
verstak/ # CLI verstak/ # CLI
verstak-gui/ # Wails GUI main verstak-gui/ # Wails v2 GUI main
verstak-tui/ # Bubble Tea TUI
verstak-server/ # Sync server
frontend/ # Wails frontend frontend/ # Wails v2 Svelte frontend
package.json package.json
wails.json vite.config.js
src/ src/
App.svelte App.svelte
components/ FileTreeRow.svelte
stores/ lib/
styles/ FileBreadcrumbs.svelte
FilePreviewModal.svelte
ConfirmModal.svelte
FileIcon.svelte
FileActions.svelte
fileUtils.js
api/verstak.js
internal/ internal/
core/ core/
@ -335,10 +368,8 @@ verstak/
worklog/ worklog/
activity/ activity/
search/ search/
sync/
security/
config/ config/
plugins/ # manager, lua (stub) plugins/ # manager, lua (stub), builtin templates
contrib/ contrib/
plugins/ plugins/
@ -351,11 +382,13 @@ verstak/
004_add_notes.sql 004_add_notes.sql
005_add_actions.sql 005_add_actions.sql
006_add_worklog.sql 006_add_worklog.sql
007_search.sql
008_sync.sql
009_section.sql
``` ```
## RAID ## RAID
- **Критично:** Wails требует Node.js для frontend-сборки - **Критично:** Wails требует Node.js для frontend-сборки
- **Критично:** go-sqlite3 + cgo; gcc уже установлен - **Критично:** go-sqlite3 + cgo; gcc уже установлен
- **Зависимость:** Steps 15+ ждут завершения step 14 - **Зависимость:** Steps 15+ ждут завершения step 14 (MVP stabilization)
- **Риск:** Wails v3 может быть нестабилен — проверить перед шагом 11