416 lines
13 KiB
Markdown
416 lines
13 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 | Wails GUI MVP: Sidebar + Main Panel | ⬜ не начат |
|
||
| 7 | Actions: Run URL/File/Command + GUI Tab | ⬜ не начат |
|
||
| 8 | Worklog: Entries + Report + GUI Tab | ⬜ не начат |
|
||
| 9 | FTS5 Search: Rebuild Index + GUI Search Bar | ⬜ не начат |
|
||
| 10 | DokuWiki Importer | ⬜ не начат |
|
||
| 11 | Sync Server Skeleton | ⬜ не начат |
|
||
| 12 | Sync Client MVP | ⬜ не начат |
|
||
| 13 | Activity + File Scanner/Watcher | ⬜ не начат |
|
||
| 14 | TUI MVP (Bubble Tea) | ⬜ не начат |
|
||
| 15 | Integrity Check + Repair + Vault Restore | ⬜ не начат |
|
||
| 16 | Plugins System (Lua + Templates) | ⬜ не начат |
|
||
|
||
---
|
||
|
||
## ШАГ 1 — Git Init + Skeleton
|
||
|
||
**Цель:** репозиторий создан, пустая структура, "hello world" билдится.
|
||
|
||
**Acceptance:**
|
||
- `go build ./...` проходит
|
||
- `go test ./...` проходит
|
||
- `verstak --version` выводит версию
|
||
- Повторный init безопасен
|
||
|
||
**Действия:**
|
||
- git init, .gitignore (Go, Wails)
|
||
- `go mod init verstak`
|
||
- Структура: `cmd/verstak/`, `internal/core/`, `migrations/`
|
||
- `cmd/verstak/main.go`: --version flag
|
||
- README.md
|
||
|
||
**Commit:** `step 1: skeleton`
|
||
|
||
---
|
||
|
||
## ШАГ 2 — Init + SQLite + First Migration
|
||
|
||
**Цель:** `verstak init --vault ./test` создаёт vault с index.db.
|
||
|
||
**Acceptance:**
|
||
- `go test ./...` проходит
|
||
- init создаёт `.verstak/index.db`
|
||
- повторный init безопасен
|
||
|
||
**Действия:**
|
||
- migration runner (cmd + SQL migrations/)
|
||
- миграция 001_init.sql (таблица nodes)
|
||
- `_ "github.com/mattn/go-sqlite3"` или modernc driver
|
||
- CLI `init`: vault dir + `.verstak/` + `index.db`
|
||
|
||
**Commit:** `step 2: init + sqlite + first migration`
|
||
|
||
---
|
||
|
||
## ШАГ 3 — Nodes Repository + CRUD + CLI Node
|
||
|
||
**Цель:** можно создать/прочитать/переместить/удалить дело через CLI.
|
||
|
||
**Acceptance:**
|
||
- nodes + node_meta таблицы
|
||
- NodeRepository: Create, Get, ListChildren, UpdateTitle, Move, SoftDelete
|
||
- CLI: `node create`, `node list`, `node move`, `node delete`
|
||
- unit tests проходят
|
||
|
||
**Действия:**
|
||
- Полная схема nodes (id, parent_id, type, title, slug, path, sort_order, created_at, updated_at, deleted_at, revision, device_id)
|
||
- node_meta (node_id, key, value)
|
||
- Node struct + Repository
|
||
- UUID вместо auto-increment
|
||
- Soft delete (deleted_at)
|
||
- безопасный slug для path
|
||
- Tests: in-memory SQLite
|
||
|
||
**Commit:** `step 3: nodes repository + CRUD`
|
||
|
||
---
|
||
|
||
## ШАГ 4 — Vault Files: Trash + File Service + CLI File
|
||
|
||
**Цель:** можно добавить файл в дело, открыть системным приложением, удалить в trash.
|
||
|
||
**Acceptance:**
|
||
- `.verstak/trash/` создаётся при init
|
||
- copy file into vault работает
|
||
- open with system app работает
|
||
- delete-to-trash работает
|
||
- тесты проходят
|
||
|
||
**Действия:**
|
||
- Таблица files (id, node_id, filename, path, storage_mode, size, sha256, mime, ...)
|
||
- VaultService: CopyFile, LinkExternal, OpenFile, DeleteToTrash, RestoreFromTrash
|
||
- CLI: `file add`, `file list`, `file open`, `file trash`
|
||
|
||
**Commit:** `step 4: vault files + trash + CLI`
|
||
|
||
---
|
||
|
||
## ШАГ 5 — Markdown Notes: Create/Read/Save + CLI Note
|
||
|
||
**Цель:** можно создать заметку, писать в неё, читать обратно.
|
||
|
||
**Acceptance:**
|
||
- type "note" для nodes
|
||
- создать .md файл в vault
|
||
- save делает backup старой версии
|
||
- тесты проходят
|
||
|
||
**Действия:**
|
||
- Таблица notes (node_id, file_id, format, original_format, encrypted)
|
||
- NoteService: CreateNote, ReadNote, SaveNote (с backup)
|
||
- CLI: `note create`, `note read`, `note write`
|
||
- Backup старой версии перед перезаписью
|
||
|
||
**Commit:** `step 5: markdown notes`
|
||
|
||
---
|
||
|
||
## ШАГ 6 — Wails GUI MVP
|
||
|
||
**Цель:** GUI запускается, видно дерево дел, можно создать дело и заметку.
|
||
|
||
**Acceptance:**
|
||
- sidebar tree показывает дела
|
||
- create node работает
|
||
- markdown textarea editor с save
|
||
- file list + add file + open file
|
||
- главный пользовательский поток работает
|
||
|
||
**Действия:**
|
||
- Wails app init (Go backend + Svelte/Vue)
|
||
- Backend bindings: NodeService, VaultService, NoteService
|
||
- Frontend: sidebar tree, main panel, modals, markdown editor
|
||
- Поток: дело → заметка → файл → открыть файл
|
||
|
||
**Commit:** `step 6: Wails GUI MVP`
|
||
|
||
---
|
||
|
||
## ШАГ 7 — Actions
|
||
|
||
**Цель:** можно создать кнопку "Открыть сайт", нажать, сайт открылся.
|
||
|
||
**Acceptance:**
|
||
- open_url, open_file, open_folder, run_command
|
||
- confirm_required диалог
|
||
- action log
|
||
- GUI вкладка "Действия"
|
||
|
||
**Действия:**
|
||
- Таблица actions
|
||
- ActionService: Run с confirm, exec.Command БЕЗ shell, args массивом
|
||
- CLI: `action add`, `action list`, `action run`
|
||
- GUI: вкладка с кнопками
|
||
|
||
**Commit:** `step 7: actions`
|
||
|
||
---
|
||
|
||
## ШАГ 8 — Worklog
|
||
|
||
**Цель:** можно записать "3ч обновил витрину", скопировать отчёт.
|
||
|
||
**Acceptance:**
|
||
- add/edit/delete entry
|
||
- approximate minutes + billable flag
|
||
- copy report копирует в буфер
|
||
- GUI вкладка "Журнал"
|
||
|
||
**Действия:**
|
||
- Таблица worklog_entries
|
||
- WorklogService: Add, Edit, Delete, CopyReport
|
||
- CLI: `worklog add`, `worklog list`, `worklog report`
|
||
- GUI: вкладка журнал + кнопка copy report
|
||
|
||
**Commit:** `step 8: worklog`
|
||
|
||
---
|
||
|
||
## ШАГ 9 — FTS5 Search
|
||
|
||
**Цель:** можно найти "витрину" по заметкам, файлам, журналу.
|
||
|
||
**Acceptance:**
|
||
- `verstak index rebuild` перестраивает индекс
|
||
- поиск по node titles, note content, filenames, worklog summaries
|
||
- GUI search bar + результаты с type/path
|
||
|
||
**Действия:**
|
||
- Таблица search_index (FTS5): node_id, title, content, path, tags, type
|
||
- Триггеры для автоматического обновления или manual rebuild
|
||
- SearchService: RebuildIndex, Search(query)
|
||
- CLI: `index rebuild`
|
||
- GUI: search bar в header
|
||
|
||
**Commit:** `step 9: FTS5 search`
|
||
|
||
---
|
||
|
||
## ШАГ 10 — DokuWiki Importer
|
||
|
||
**Цель:** можно импортировать страницы DokuWiki как дерево дел.
|
||
|
||
**Acceptance:**
|
||
- namespaces → folders
|
||
- pages → notes
|
||
- оригиналы сохранены в `.verstak/originals/dokuwiki/`
|
||
|
||
**Действия:**
|
||
- DokuWiki парсер: namespaces как nodes tree
|
||
- страницы как note nodes с .md файлами
|
||
- CLI: `import-dokuwiki --pages /path --media /path --target-node ...`
|
||
- Originals сохраняются без изменений
|
||
|
||
**Commit:** `step 10: DokuWiki importer`
|
||
|
||
---
|
||
|
||
## ШАГ 11 — Sync Server Skeleton
|
||
|
||
**Цель:** verstak-server отвечает на /health, /sync/push, /sync/pull, /blobs.
|
||
|
||
**Acceptance:**
|
||
- HTTP server на отдельном порту
|
||
- API key auth
|
||
- blob storage by sha256
|
||
- GET /health, POST /sync/push, POST /sync/pull, POST /blobs/upload, GET /blobs/{sha256}
|
||
|
||
**Действия:**
|
||
- `cmd/verstak-server/main.go`
|
||
- SQLite server db
|
||
- Push/pull operations endpoints
|
||
- Blob upload/download with sha256 naming
|
||
|
||
**Commit:** `step 11: sync server skeleton`
|
||
|
||
---
|
||
|
||
## ШАГ 12 — Sync Client MVP
|
||
|
||
**Цель:** `verstak sync` отправляет локальные операции на сервер и получает обратно.
|
||
|
||
**Acceptance:**
|
||
- sync_ops таблица
|
||
- операции создаются при каждом изменении
|
||
- push local ops + pull remote ops
|
||
- upload/download blobs
|
||
- conflict copy при неуверенности
|
||
|
||
**Действия:**
|
||
- Таблица sync_ops (опционально добавить триггеры в repository)
|
||
- SyncClient: Push, Pull, UploadBlob, DownloadBlob
|
||
- CLI: `verstak sync`
|
||
- Server URL + API key в .verstak/config
|
||
|
||
**Commit:** `step 12: sync client MVP`
|
||
|
||
---
|
||
|
||
## ШАГ 13 — Activity + File Scanner/Watcher
|
||
|
||
**Цель:** фиксируется открытие/редактирование, scanner видит новые файлы.
|
||
|
||
**Acceptance:**
|
||
- activity_events таблица
|
||
- scanner сравнивает реальность с SQLite
|
||
- watcher (fsnotify) ускоряет обнаружение
|
||
- экран "Активность" с группировкой по делу
|
||
- можно создать worklog из events
|
||
|
||
**Действия:**
|
||
- Таблица activity_events
|
||
- Запись событий из nodes/notes/files/actions
|
||
- Snapshot scanner (источник правды)
|
||
- fsnotify watcher (ускоритель)
|
||
- CLI: `scan`, `activity list`
|
||
- GUI: экран "Активность"
|
||
|
||
**Commit:** `step 13: activity + scanner/watcher`
|
||
|
||
---
|
||
|
||
## ШАГ 14 — TUI MVP (Bubble Tea)
|
||
|
||
**Цель:** быстрый поиск дела, добавление worklog, запуск action.
|
||
|
||
**Acceptance:**
|
||
- fuzzy search tree
|
||
- open node
|
||
- add worklog
|
||
- run action
|
||
- sync now
|
||
|
||
**Действия:**
|
||
- `cmd/verstak-tui/main.go` с Bubble Tea
|
||
- Модели: search, node view, worklog form, action runner
|
||
- Не повторяет весь GUI — только быстрые действия
|
||
|
||
**Commit:** `step 14: TUI MVP`
|
||
|
||
---
|
||
|
||
## ШАГ 15 — Integrity Check + Repair + Vault Restore
|
||
|
||
**Цель:** `verstak vault check` находит проблемы, repair чинит, restore восстанавливает.
|
||
|
||
**Acceptance:**
|
||
- check: missing files, orphan files, SQLite references, hash mismatch
|
||
- repair: устраняет найденные проблемы
|
||
- restore с сервера восстанавливает vault
|
||
|
||
**Действия:**
|
||
- CLI: `vault check` — сканирует и отчитывается
|
||
- CLI: `vault repair` — чинит найденное
|
||
- CLI: `restore --server <url> --api-key <key> --target <path>`
|
||
|
||
**Commit:** `step 15: integrity + restore`
|
||
|
||
---
|
||
|
||
## ШАГ 16 — Система плагинов (Lua + шаблоны дел)
|
||
|
||
**Цель:** можно положить Lua-скрипт в `.verstak/plugins/` — и он работает.
|
||
|
||
**Acceptance:**
|
||
- `.verstak/plugins/<name>/plugin.json` — мета
|
||
- `main.lua` — загрузка через gopher-lua
|
||
- `on_init`, `on_vault_open`, `on_node_create` хуки
|
||
- `verstak.node.register_type()` — новые типы дел
|
||
- `verstak.http.route()` — API для GUI
|
||
- шаблоны дела (JSON) → предзаполненное дерево
|
||
- CLI: `verstak plugin list / install / enable`
|
||
|
||
**Действия:**
|
||
- `internal/core/plugins/manager.go` — сканирование, загрузка, валидация
|
||
- Lua runtime (gopher-lua) с песочницей
|
||
- Plugin API: node, config, activity, http, ui, vault
|
||
- Миграции плагинов (SQL)
|
||
- Реестр типов дел → GUI рендерит разные карточки
|
||
- CLI: plugin list/install/enable
|
||
- Базовый шаблон дела (client.json)
|
||
|
||
**Commit:** `step 16: plugins system`
|
||
|
||
---
|
||
|
||
## Сводка структуры репозитория
|
||
|
||
```
|
||
verstak/
|
||
go.mod
|
||
README.md
|
||
PLAN.md
|
||
|
||
cmd/
|
||
verstak/ # CLI
|
||
verstak-gui/ # Wails GUI
|
||
verstak-tui/ # Bubble Tea TUI
|
||
verstak-server/ # Sync server
|
||
|
||
internal/
|
||
core/
|
||
nodes/
|
||
vault/
|
||
storage/
|
||
notes/
|
||
files/
|
||
actions/
|
||
worklog/
|
||
activity/
|
||
search/
|
||
importers/
|
||
sync/
|
||
security/
|
||
config/
|
||
plugins/
|
||
|
||
frontend/ # Wails frontend (Svelte/Vue)
|
||
|
||
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_add_activity.sql
|
||
008_add_fts.sql
|
||
009_add_sync.sql
|
||
```
|
||
|
||
## RAID (Risks, Assumptions, Issues, Dependencies)
|
||
|
||
- **Критично:** Wails v3 может быть нестабилен — проверить перед шагом 6
|
||
- **Критично:** go-sqlite3 нужен cgo; modernc — чистый Go, выбрать до шага 2
|
||
- **Зависимость:** Шаги 12 (sync client) зависят от 11 (server)
|
||
- **Зависимость:** Шаг 6 (GUI) лучше откладывать до стабильности core
|
||
- **Риск:** Svelte/Vue фронтенд потребует node/npm — подготовить
|