401 lines
19 KiB
Markdown
401 lines
19 KiB
Markdown
# Верстак — Пошаговый план разработки
|
||
|
||
## Принципы работы
|
||
|
||
1. После каждого шага — **СТОП**. Влад проверяет, даёт обратную связь.
|
||
2. Следующий шаг начинается **ТОЛЬКО** после одобрения.
|
||
3. Каждый шаг — отдельный git commit.
|
||
4. Периодически сверяться с этим планом и документацией в docs/.
|
||
|
||
## Статус шагов
|
||
|
||
| # | Шаг | Статус |
|
||
|---|-----|--------|
|
||
| 1 | Git init + Skeleton | ✅ выполнен |
|
||
| 2 | Init + SQLite + First Migration | ✅ выполнен |
|
||
| 3 | Nodes Repository + CRUD + CLI Node | ✅ выполнен |
|
||
| 4 | Vault Files: Trash + File Service + CLI File | ✅ выполнен |
|
||
| 5 | Markdown Notes: Create/Read/Save + CLI Note | ✅ выполнен |
|
||
| 6 | GUI (browser prototype): Sidebar + Main Panel | ✅ выполнен |
|
||
| 7 | Actions + Worklog | ✅ выполнен |
|
||
| 8 | FTS5 Search | ✅ выполнен |
|
||
| 9 | Section assignment + Sidebar filtering | ✅ выполнен |
|
||
| 10 | Plugin Manager (discovery + templates) | ✅ выполнен |
|
||
| 11 | **Wails Desktop GUI** | ✅ выполнено (v2, full Svelte UI) |
|
||
| 12 | **Files/Folders full workflow** | ✅ выполнено (copy/link/import/tree) |
|
||
| 13 | **Drag-and-drop** | ✅ выполнено (internal + external drops) |
|
||
| 14 | **MVP stabilization** | ✅ выполнено |
|
||
| 15 | **Sync Server + Client** | ✅ выполнено |
|
||
| 16 | **Activity Suggestions** | ✅ выполнено базово — global worklog dashboard + conservative suggestions + UX |
|
||
| 17 | **File Scanner/Watcher** | ✅ выполнено — fsnotify, snapshot scanner |
|
||
| 18 | **Plugins: Lua runtime** | ✅ скелет — gopher-lua, хуки, песочница, шедулер, Calendar-пример |
|
||
| 19 | **Browser Extension** | ✅ выполнено — tracking, capture, evidence |
|
||
| 20 | **Calendar/Kanban** | ⏳ ожидает — view by date, board view |
|
||
| 21 | **Integrity Check + Repair** | ⏳ ожидает — checksums, crash recovery |
|
||
| 22 | **New templates/integrations** | ⏳ ожидает — community plugins |
|
||
|
||
---
|
||
|
||
## Выполненные шаги (1-14)
|
||
|
||
### ШАГ 1 — Git Init + Skeleton
|
||
- go module `verstak`, структура cmd/internal/migrations
|
||
- CLI `verstak --version`
|
||
- README.md
|
||
|
||
### ШАГ 2 — Init + SQLite
|
||
- storage.go: DB wrapper, migration runner
|
||
- vault.go: Init() создаёт .verstak/ + index.db
|
||
- config.go: YAML config
|
||
|
||
### ШАГ 3 — Nodes Repository
|
||
- Node struct + CRUD (Create, Get, ListChildren, ListRoots, UpdateTitle, Move, SoftDelete)
|
||
- Meta KV + tests
|
||
|
||
### ШАГ 4 — Files
|
||
- FileService: AddExternal, CopyIntoVault, Get, ListByNode, MarkMissing, DeleteToTrash, Open
|
||
- file_test.go: 5 tests
|
||
|
||
### ШАГ 5 — Notes
|
||
- NoteService: Create, Read, Save (с backup), Delete
|
||
- note_test.go: 3 tests
|
||
|
||
### ШАГ 6 — GUI (browser prototype)
|
||
- Go HTTP SPA на случайном порту
|
||
- Sidebar tree + разделы (Сегодня, Неразобранное, Клиенты, Проекты...)
|
||
- Dashboard дела + вкладки (Обзор, Заметки, Файлы, Действия, Журнал, Активность)
|
||
- Модальное окно "+ Добавить" с выбором типа
|
||
- Поиск по корневым нодам
|
||
- **Это legacy prototype — не развивать как основной GUI**
|
||
|
||
### ШАГ 7 — Actions + Worklog
|
||
- ActionService: Create, Get, ListByNode, Delete, Run (open_url/file/folder, run_command)
|
||
- WorklogService: Add, Update, ListByNode, Delete, SumMinutes, Report
|
||
- CLI: `action add/list/run/delete`, `log add/list/report`
|
||
- GUI вкладки с кнопками действий и журналом работ
|
||
|
||
### ШАГ 8 — FTS5 Search
|
||
- SearchService: Index, Remove, Rebuild, Search (FTS5 MATCH)
|
||
- FTS5 virtual table создаётся лениво (работает с/без FTS5)
|
||
- Fallback на LIKE по заголовкам нод
|
||
- CLI: `verstak index rebuild`
|
||
- GUI search bar
|
||
|
||
### ШАГ 9 — Section assignment
|
||
- Колонка `section` в nodes (clients/projects/recipes/documents/archive/inbox)
|
||
- Фильтрация разделов по `?section=` в API
|
||
- Root-ноды без section → inbox
|
||
|
||
### ШАГ 10 — Plugin Manager
|
||
- Discovery: `.verstak/plugins/<name>/plugin.json`
|
||
- Enable/disable, templates → pre-filled node trees
|
||
- Built-in шаблон "Клиент" (Overview + Документы/Переписка/Скриншоты)
|
||
- Template selector в модалке создания дела
|
||
- POST /api/nodes/from-template
|
||
- CLI: `plugin list/enable/disable/templates`
|
||
- Lua runtime — stub (placeholder)
|
||
|
||
### ШАГ 11 — Wails Desktop GUI
|
||
|
||
**Прогресс:**
|
||
- ✅ Wails v2 shell (window opens, no SIGSEGV)
|
||
- ✅ Layout fix (full viewport, dark theme, sidebar+main)
|
||
- ✅ Notes bindings + UI (create/read/save/dirty state)
|
||
- ✅ Tabs (Overview/Notes/Files/Actions/Worklog/Activity)
|
||
- ✅ Node creation + template selection (FromTemplate)
|
||
- ✅ 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
|
||
- ✅ i18n (ru/en)
|
||
- ✅ First-run/recovery flow без авто-создания vault
|
||
- ✅ Settings window: General, Workspace, Templates, Plugins, Files, Activity, Sync, Backup
|
||
- ✅ Sync settings перенесены в Settings; в основном UI остался status/manual sync widget
|
||
- ✅ Rendered GUI smoke: first-run, recovery, Settings icons, workspace, tabs, files back button, create flows, worklog, sync conflict/applyError warnings, mobile viewport
|
||
|
||
Архитектура:
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Frontend (Wails) │
|
||
│ frontend/src/ │
|
||
│ App.svelte │
|
||
│ FileTreeRow, TreeNode │
|
||
│ lib/FileBreadcrumbs, FilePreviewModal, ... │
|
||
│ lib/i18n/ locales (ru, en) │
|
||
└──────────────────┬──────────────────────────────┘
|
||
│ Wails bindings
|
||
┌──────────────────▼──────────────────────────────┐
|
||
│ Go Core (internal/core/) │
|
||
│ nodes, vault, storage, notes, files, │
|
||
│ actions, worklog, search, plugins, sync, │
|
||
│ activity │
|
||
└──────────────────┬──────────────────────────────┘
|
||
│
|
||
┌──────────────────▼──────────────────────────────┐
|
||
│ Vault filesystem + SQLite │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### ШАГ 12 — Files/Folders full workflow
|
||
|
||
Core service extensions:
|
||
- `AddPathCopy` — рекурсивный импорт директорий
|
||
- `AddPathLink` — привязка внешних файлов без копирования
|
||
- Folder model: node type `folder`
|
||
- Name conflict resolution: `name (2)`, `name (3)`
|
||
- Safety checks: PreviewImport с summary (count, size, warnings)
|
||
- Trash: soft delete → `.verstak/trash`
|
||
|
||
### ШАГ 13 — Drag-and-drop
|
||
|
||
- Internal DnD: перетаскивание узлов в дереве
|
||
- External DnD: файлы из ОС → активное дело / вкладка Файлы
|
||
- Диалог подтверждения с выбором: копировать / переместить / привязать
|
||
|
||
### ШАГ 14 — MVP stabilization
|
||
|
||
- Все операции атомарны (DB+FS)
|
||
- Template файлы/папки создаются как полноценные ноды с rollback
|
||
- fs_path валидируется (SafeVaultPath)
|
||
- sync_apply FS-first
|
||
- Delete находит ошибки trash-переноса
|
||
- 24+ integration tests проходят
|
||
- **Известные пробелы:** Restore из trash не реализован, ensureTemplateChildren продолжает при ошибках (backward compat), parent_id+title в applyRemoteNodeUpdate без полной транзакции
|
||
|
||
---
|
||
|
||
## Завершённый базовый этап: ШАГ 16 — Activity Suggestions
|
||
|
||
**Статус:** ✅ базово выполнено — activity-based suggestions + global worklog dashboard + conservative estimator.
|
||
|
||
Что реализовано:
|
||
- `suggest.go` — структура Suggestion (nodeId, nodeTitle, summary, suggestedMin, confidence)
|
||
- `bindings_suggest.go` — GetSuggestions с burst detection + conservative estimator (5–30 min)
|
||
- `bindings_suggest.go` — AcceptSuggestionWith (date/minutes overrides)
|
||
- `worklog/report.go` — ReportFilter, ListReport, Summary, ExportCSV, ExportMarkdown
|
||
- `app.go` — WorklogDTO расширен: date, details, approximate, billable, nodeTitle
|
||
- `bindings_worklog.go` — CreateWorklogFull, ListWorklogReport, WorklogSummary, Export*
|
||
- Новый системный раздел "Журнал" с таблицей, фильтрами (даты, includeChildren), сводкой
|
||
- Предложения на экране "Сегодня" + вкладке "Журнал" + вкладке "Журнал дела"
|
||
- Badge с количеством предложений в боковом меню
|
||
- Консервативный estimator:
|
||
- burst detection (группировка событий в окне 10 мин)
|
||
- time spread analysis
|
||
- 5–30 мин, 60+ только при сильном evidence
|
||
- Confidence: low/medium/high + reason
|
||
|
||
---
|
||
|
||
## Завершённый этап: ШАГ 17 — File Scanner/Watcher
|
||
|
||
**Статус:** ✅ выполнено
|
||
|
||
Что реализовано:
|
||
- `internal/core/watcher/scanner.go` — Snapshot scanner:
|
||
- Итерирует все ноды с FsPath, сканирует их директории на диске
|
||
- Детектит missing файлы (запись в БД есть — файла нет) → MarkMissing + activity event
|
||
- Детектит restored файлы (был missing — снова на диске) → MarkMissing(false) + activity event
|
||
- Детектит modified файлы (SHA256 не совпал) → обновление размера/SHA в БД + activity event
|
||
- Считает new файлы на диске без записи в БД (не авто-добавляет, только счётчик)
|
||
- Пропускает `.verstak/` и скрытые директории
|
||
- `internal/core/watcher/watcher.go` — fsnotify Watcher:
|
||
- Реальное время: CREATE/REMOVE/RENAME/WRITE события
|
||
- Debounce 2 секунды для группировки burst-событий
|
||
- CREATE → авто-добавление file record + `file_added` event
|
||
- REMOVE → MarkMissing(true) + `file_deleted` event
|
||
- WRITE → обновление SHA256 + `file_modified` event
|
||
- Рекурсивное добавление watcher-ов на поддиректории
|
||
- Пропускает скрытые файлы и `.verstak/`
|
||
- `internal/core/watcher/service.go` — Объединённый сервис:
|
||
- Start(enableWatcher) → snapshot scan + опционально запуск real-time watcher
|
||
- Stop() → остановка watcher
|
||
- RunScanner() → одноразовое сканирование
|
||
- `internal/core/activity/activity.go` — Новые типы событий: `file_modified`, `file_restored`
|
||
- `internal/core/storage/migrations_017.sql.go` — Таблица `watcher_state` для трекинга состояния файлов
|
||
- `internal/core/config/appconfig.go` — Настройка `Vault.FileWatcher` (по умолчанию true)
|
||
- `cmd/verstak-gui/app.go` — Интеграция в App: initVault запускает сканер + watcher, closeVault останавливает
|
||
- `cmd/verstak-gui/bindings_watcher.go` — Bindings: WatcherStatus(), RunSnapshotScan(), ToggleFileWatcher()
|
||
- `internal/core/watcher/watcher_test.go` — 5 тестов: no changes, missing, restored, modified, hidden filter
|
||
- `internal/core/files/file.go` — Новые методы: ListAllVault(), ListAllVaultWithTrashed()
|
||
- `internal/core/nodes/repository.go` — Новый метод: ListAllWithFsPath()
|
||
|
||
### Как включить/отключить
|
||
|
||
| Способ | Команда | Действие |
|
||
|--------|---------|----------|
|
||
| **GUI** | Settings → "File Watcher" toggle | Вкл/выкл real-time, snapshot всегда |
|
||
| **Config** | `~/.config/verstak/config.json` → `vault.file_watcher: false` | Навсегда |
|
||
| **Env** | `VERSTAK_NO_WATCHER=1 ./verstak-gui` | На сессию (переопределяет config) |
|
||
| **CLI** | `./verstak-gui --no-watcher` | Один запуск (переопределяет всё) |
|
||
|
||
Важно: **snapshot scan** (сверка диска с БД) выполняется ВСЕГДА при открытии vault.
|
||
Real-time fsnotify watcher управляется отдельно.
|
||
|
||
### Как проверить что работает
|
||
|
||
После запуска в логе:
|
||
```
|
||
[watcher] snapshot: 0 missing, 0 restored, 0 modified, 0 new
|
||
```
|
||
|
||
Через GUI: `WatcherStatus()` — true если watcher активен.
|
||
Через консоль (отладка): создать/удалить файл в vault → в activity появятся события `file_added`/`file_missing`/`file_modified`.
|
||
|
||
## Выполненные шаги (18-22 частично)
|
||
|
||
### ШАГ 18 — Plugins: Lua runtime ✅ скелет
|
||
|
||
**Статус:** ✅ Скелет готов — рантайм, хуки, песочница, шедулер, Calendar-пример.
|
||
|
||
Что реализовано:
|
||
- `internal/core/plugins/runtime.go` — gopher-lua VM: загрузка main.lua, вызов хуков, таймауты
|
||
- `internal/core/plugins/api.go` — регистрация таблицы `verstak` с субмодулями
|
||
- `internal/core/plugins/api_node.go` — `verstak.node.*` (заглушки, ждут реализации)
|
||
- `internal/core/plugins/api_ext.go` — `verstak.db.*`, `verstak.config.*`, `verstak.state.*`, `verstak.ui.*`, `verstak.schedule.*`, `verstak.http.*` (state — работает, остальное — заглушки)
|
||
- `internal/core/plugins/api_utils.go` — вспомогательные функции
|
||
- `internal/core/plugins/scheduler.go` — фоновые задачи по расписанию (goroutine + ticker)
|
||
- `internal/core/plugins/manager.go` — обновлён: InitRuntimes, CallInitHooks, StartSchedulers, etc.
|
||
- `internal/core/plugins/runtime_test.go` — 5 тестов: hook call, missing hook, sandbox, state, Manager lifecycle
|
||
- `contrib/plugins/calendar/` — пример-плагин: plugin.json, main.lua, HTML-panel, migrations, background task
|
||
|
||
**Следующее:** реализовать `verstak.node.*`, `verstak.db.*`, `verstak.config.*`, `verstak.ui.*` полноценно, и пройтись по Calendar-плагину вживую.
|
||
|
||
### ШАГ 19 — Browser Extension
|
||
- Расширение для браузера: трекинг времени, скриншоты, evidence
|
||
|
||
### ШАГ 20 — Calendar/Kanban
|
||
- Календарный вид по датам
|
||
- Канбан-доска по статусам
|
||
|
||
### ШАГ 21 — Integrity Check + Repair
|
||
- Проверка целостности vault
|
||
- Контрольные суммы, восстановление после сбоев
|
||
|
||
### ШАГ 22 — New templates/integrations
|
||
- Community-плагины и шаблоны
|
||
|
||
---
|
||
|
||
## Структура репозитория
|
||
|
||
```
|
||
verstak/
|
||
go.mod
|
||
README.md
|
||
AGENTS.md # Инструкции для AI-ассистента
|
||
|
||
cmd/
|
||
verstak/ # CLI
|
||
verstak-gui/ # Wails v2 GUI main
|
||
verstak-server/ # Sync server
|
||
|
||
frontend/ # Wails v2 Svelte frontend
|
||
package.json
|
||
vite.config.js
|
||
src/
|
||
App.svelte
|
||
FileTreeRow.svelte
|
||
TreeNode.svelte
|
||
lib/
|
||
FileBreadcrumbs.svelte
|
||
FilePreviewModal.svelte
|
||
ConfirmModal.svelte
|
||
FileIcon.svelte
|
||
FileActions.svelte
|
||
fileUtils.js
|
||
i18n/ # Локали (ru, en)
|
||
api/verstak.js
|
||
|
||
scripts/
|
||
build.sh # Раздельная сборка (gui/server/all)
|
||
check-i18n.sh # Проверка интернационализации
|
||
|
||
internal/
|
||
core/
|
||
nodes/
|
||
vault/
|
||
storage/
|
||
notes/
|
||
files/
|
||
actions/
|
||
worklog/
|
||
activity/
|
||
search/
|
||
sync/
|
||
config/
|
||
templates/
|
||
plugins/ # manager, lua (stub)
|
||
|
||
i18n/ # Go-локали (ru, en)
|
||
|
||
contrib/
|
||
plugins/
|
||
importer-dokuwiki/
|
||
|
||
migrations/
|
||
001_init.sql
|
||
002_add_meta.sql
|
||
003_add_files.sql
|
||
004_add_notes.sql
|
||
005_add_actions.sql
|
||
006_add_worklog.sql
|
||
007_search.sql
|
||
008_sync.sql
|
||
009_section.sql
|
||
...
|
||
|
||
docs/
|
||
00_README.md
|
||
01_Product_Spec.md
|
||
02_Architecture.md
|
||
03_Data_Model_Storage.md
|
||
04_Sync_Backup_Activity.md
|
||
05_UI_UX.md
|
||
06_Roadmap.md
|
||
09_Extensibility.md
|
||
10_Sync_Server_Guide.md
|
||
PLAN.md
|
||
TEMPLATES.md
|
||
VAULT_LAYOUT.md
|
||
```
|
||
|
||
## Сборка
|
||
|
||
```bash
|
||
# Полная сборка
|
||
./scripts/build.sh
|
||
|
||
# По отдельности
|
||
./scripts/build.sh gui # Wails v2 GUI
|
||
./scripts/build.sh server # Sync server
|
||
./scripts/build.sh all # Оба
|
||
|
||
# GUI smoke check перед коммитом
|
||
./scripts/check-gui.sh
|
||
|
||
# Полная проверка GUI:
|
||
# - i18n/source hygiene
|
||
# - frontend production build
|
||
# - embedded Wails assets == frontend/dist
|
||
# - go build с тегами "webkit2_41 desktop production"
|
||
# - rendered Chromium smoke с Wails-mock и action-flow проверками
|
||
|
||
# Только rendered smoke фронтенда с Wails-mock
|
||
cd frontend && npm run smoke:gui
|
||
|
||
# Dev-режим GUI
|
||
cd frontend && npm run dev
|
||
```
|
||
|
||
## RAID
|
||
|
||
- **Критично:** Wails требует Node.js для frontend-сборки
|
||
- **Критично:** go-sqlite3 + cgo; gcc уже установлен
|
||
- **Сборка GUI:** требуется `webkit2_41` tag для WebKitGTK 4.1+
|