mirivlad
/
verstak
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
verstak/docs/PLAN.md

13 KiB
Raw Blame History

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

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

  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 🔄 в работе — HTTP API, push/pull, blob sync
16 Activity Suggestions ⏳ ожидает — подсказки из activity_events
17 File Scanner/Watcher ⏳ ожидает — fsnotify, snapshot scanner
18 TUI MVP (Bubble Tea) ⏳ ожидает — tree/search, add worklog
19 Plugins: Lua runtime ⏳ ожидает — gopher-lua, hooks, sandbox
20 Browser Extension ⏳ ожидает — tracking, capture, evidence
21 Calendar/Kanban ⏳ ожидает — view by date, board view
22 Integrity Check + Repair ⏳ ожидает — checksums, crash recovery
23 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)

Архитектура:

┌─────────────────────────────────────────────────┐
│  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 без полной транзакции

Текущий этап: ШАГ 15 — Sync Server + Client

Статус: ✅ Сервер собран и работает. Клиент реализован. Нужна доработка и тестирование.

Стек синхронизации:

  • cmd/verstak-server/ — HTTP API сервер (порт, API key, push/pull)
  • internal/core/sync/ — клиент синхронизации
  • SQLite-based sync state (migrations/008_sync.sql)
  • FS-first apply: изменения применяются через файловую систему, БД — индекс

Ожидающие шаги (16-23)

ШАГ 16 — Activity Suggestions

Подсказки для журнала работ на основе activity_events:

  • анализировать события за день
  • предлагать записи в worklog

ШАГ 17 — File Scanner/Watcher

  • fsnotify watcher на vault
  • snapshot scanner для обнаружения изменений при закрытом приложении
  • обнаружение missing файлов

ШАГ 18 — TUI MVP (Bubble Tea)

  • Терминальный интерфейс: дерево дел, поиск, добавление worklog, запуск действий, sync

ШАГ 19 — Plugins: Lua runtime

  • gopher-lua runtime
  • хуки на события (node created, file added, etc.)
  • песочница

ШАГ 20 — Browser Extension

  • Расширение для браузера: трекинг времени, скриншоты, evidence

ШАГ 21 — Calendar/Kanban

  • Календарный вид по датам
  • Канбан-доска по статусам

ШАГ 22 — Integrity Check + Repair

  • Проверка целостности vault
  • Контрольные суммы, восстановление после сбоев

ШАГ 23 — New templates/integrations

  • Community-плагины и шаблоны

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

verstak/
  go.mod
  README.md
  PLAN.md
  build.sh                          # Полная сборка (GUI + сервер)
  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), builtin templates
      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

Сборка

# Полная сборка
./build.sh

# По отдельности
./scripts/build.sh gui      # Wails v2 GUI
./scripts/build.sh server   # Sync server
./scripts/build.sh all      # Оба

# Dev-режим GUI
cd frontend && npm run dev

RAID

  • Критично: Wails требует Node.js для frontend-сборки
  • Критично: go-sqlite3 + cgo; gcc уже установлен
  • Сборка GUI: требуется webkit2_41 tag для WebKitGTK 4.1+