19 KiB

Raw Blame History

Верстак — Пошаговый план разработки

Принципы работы

После каждого шага — СТОП. Влад проверяет, даёт обратную связь.
Следующий шаг начинается ТОЛЬКО после одобрения.
Каждый шаг — отдельный git commit.
Периодически сверяться с этим планом и документацией в 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

Сборка

# Полная сборка
./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+

19 KiB Raw Blame History Unescape Escape

Верстак — Пошаговый план разработки

Принципы работы

Статус шагов

Выполненные шаги (1-14)

ШАГ 1 — Git Init + Skeleton

ШАГ 2 — Init + SQLite

ШАГ 3 — Nodes Repository

ШАГ 4 — Files

ШАГ 5 — Notes

ШАГ 6 — GUI (browser prototype)

ШАГ 7 — Actions + Worklog

ШАГ 8 — FTS5 Search

ШАГ 9 — Section assignment

ШАГ 10 — Plugin Manager

ШАГ 11 — Wails Desktop GUI

ШАГ 12 — Files/Folders full workflow

ШАГ 13 — Drag-and-drop

ШАГ 14 — MVP stabilization

Завершённый базовый этап: ШАГ 16 — Activity Suggestions

Завершённый этап: ШАГ 17 — File Scanner/Watcher

Как включить/отключить

Как проверить что работает

Выполненные шаги (18-22 частично)

ШАГ 18 — Plugins: Lua runtime ✅ скелет

ШАГ 19 — Browser Extension

ШАГ 20 — Calendar/Kanban

ШАГ 21 — Integrity Check + Repair

ШАГ 22 — New templates/integrations

Структура репозитория

Сборка

RAID

19 KiB

Raw Blame History