230 lines
9.6 KiB
Markdown
230 lines
9.6 KiB
Markdown
# Верстак
|
||
|
||
**Верстак** — local-first рабочий vault. Всё организовано вокруг **дел**, а не задач.
|
||
|
||
Дело может быть: клиентом, проектом, набором документов, рецептом, архивом, разовой работой.
|
||
Внутри дела: вложенные папки, Markdown-заметки, файлы, действия (URL/файл/папка/команда), журнал работ, история активности.
|
||
|
||
## Стек
|
||
|
||
| Слой | Технология |
|
||
|------|------------|
|
||
| GUI | Wails v2 + Svelte 4 |
|
||
| CLI | Go |
|
||
| Backend | Go |
|
||
| Хранилище | SQLite (индекс) + файловая система (vault) |
|
||
| Плагины | Lua |
|
||
| Синхронизация | HTTP API (опциональный сервер) |
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
┌────────────────────┐
|
||
│ GUI (Wails v2) │
|
||
└─────────┬──────────┘
|
||
│
|
||
┌─────────▼────────┐ ┌─────────────┐
|
||
│ Core Library │◄──│ CLI Commands │
|
||
└─────────┬────────┘ └─────────────┘
|
||
│
|
||
┌─────────▼──────────┐
|
||
│ Local Vault+SQLite │
|
||
└─────────┬──────────┘
|
||
│
|
||
┌─────────▼──────────┐
|
||
│ Sync Client │
|
||
└─────────┬──────────┘
|
||
│
|
||
┌─────────▼──────────┐
|
||
│ Sync Server │
|
||
└────────────────────┘
|
||
```
|
||
|
||
## Быстрый старт
|
||
|
||
### Требования
|
||
|
||
- Go 1.25+
|
||
- Node.js 20+
|
||
- libwebkit2gtk-4.1-dev, libgtk-3-dev и другие Wails-зависимости (см. [wails.io/docs/desktop/linux](https://wails.io/docs/desktop/linux))
|
||
- npm
|
||
|
||
### Сборка
|
||
|
||
```bash
|
||
# Всё сразу (GUI + сервер)
|
||
./scripts/build.sh
|
||
|
||
# Или по отдельности
|
||
./scripts/build.sh gui # только GUI
|
||
./scripts/build.sh server # только сервер
|
||
```
|
||
|
||
Проверка GUI перед коммитом:
|
||
|
||
```bash
|
||
./scripts/check-gui.sh
|
||
```
|
||
|
||
Она проверяет локали, production-сборку фронтенда, актуальность embedded Wails assets и компиляцию GUI-бинаря.
|
||
Дополнительно запускается headless Chromium smoke через Wails-mock: проверяются first-run, recovery, основное окно, Settings, workspace, вкладки дела, файлы, журнал, активность и мобильный viewport. Smoke выполняет реальные UI-действия: создание заметки, запись worklog, создание узла, вход в папку и возврат назад, а также Sync Now с предупреждениями о conflicts/applyErrors. Скриншоты пишутся в `/tmp/verstak-gui-smoke`.
|
||
|
||
Бинарники попадают в `build/`:
|
||
- `verstak` — GUI-приложение
|
||
- `verstak-server` — опциональный сервер синхронизации
|
||
|
||
### Запуск
|
||
|
||
```bash
|
||
# GUI (после сборки)
|
||
./build/verstak
|
||
|
||
# Сервер (после сборки)
|
||
./build/verstak-server --help
|
||
|
||
# CLI
|
||
go run ./cmd/verstak/ --help
|
||
```
|
||
|
||
## Firefox Extension
|
||
|
||
Расширение для Firefox — `extension-firefox/`. Распространяется как signed XPI: **Mozilla только подписывает** XPI через AMO (unlisted channel), а мы самостоятельно хостим signed XPI и управляем обновлениями через `updates.json`.
|
||
|
||
### Сборка (unsigned)
|
||
|
||
```bash
|
||
./scripts/build.sh firefox
|
||
# → build/verstak-bridge-firefox-unsigned.zip
|
||
```
|
||
|
||
### Подпись (требуются AMO-токены)
|
||
|
||
```bash
|
||
# 1. Скопировать .env.example → .env и заполнить WEB_EXT_API_KEY / WEB_EXT_API_SECRET
|
||
cp .env.example .env
|
||
|
||
# 2. Установить зависимости
|
||
cd extension-firefox && npm install && cd ..
|
||
|
||
# 3. Подписать XPI
|
||
./scripts/sign-firefox-xpi.sh
|
||
# → web-ext-artifacts/*.xpi
|
||
|
||
# 4. Полный релиз: подпись + release/firefox/ + updates.json
|
||
./scripts/release-firefox-xpi.sh
|
||
# → release/firefox/verstak-firefox-VERSION.xpi
|
||
# → release/firefox/updates.json
|
||
```
|
||
|
||
### Firefox Release Artifacts
|
||
|
||
```
|
||
release/firefox/verstak-firefox-VERSION.xpi
|
||
release/firefox/updates.json
|
||
```
|
||
|
||
Обновления: Firefox проверяет `update_url` из manifest.json, указывающий на наш `updates.json`. При выходе новой версии достаточно:
|
||
1. Подписать новый XPI
|
||
2. Заменить файл на сервере
|
||
3. Обновить `updates.json`
|
||
|
||
## Release
|
||
|
||
```bash
|
||
# Полная сборка с упаковкой в DEB/RPM
|
||
./scripts/release.sh # dry-run (без git tag); требует AMO токены
|
||
./scripts/release.sh --publish # с git tag + GitHub release
|
||
|
||
# Без подписи Firefox
|
||
./scripts/release.sh --skip-firefox-sign
|
||
```
|
||
|
||
Артефакты релиза (после `./scripts/release.sh`):
|
||
|
||
```
|
||
release/linux/verstak # GUI binary
|
||
release/linux/verstak-server # Server binary
|
||
release/linux/verstak.deb # DEB-пакет GUI
|
||
release/linux/verstak-server.deb # DEB-пакет сервера
|
||
release/linux/verstak.rpm # RPM-пакет GUI
|
||
release/linux/verstak-server.rpm # RPM-пакет сервера
|
||
release/firefox/verstak-firefox-VERSION.xpi # Signed XPI
|
||
release/firefox/updates.json # Firefox update manifest
|
||
```
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
.
|
||
├── cmd/ # Точки входа
|
||
│ ├── verstak/ # CLI
|
||
│ ├── verstak-gui/ # Wails GUI
|
||
│ └── verstak-server/ # Sync server
|
||
├── internal/
|
||
│ ├── core/ # Бизнес-логика
|
||
│ │ ├── actions/ # Действия (URL, папка, команда)
|
||
│ │ ├── config/ # Конфигурация
|
||
│ │ ├── files/ # Файлы и импорт
|
||
│ │ ├── i18n/ # Интернационализация (Go)
|
||
│ │ ├── nodes/ # Дела/узлы дерева
|
||
│ │ ├── plugins/ # Lua-плагины
|
||
│ │ ├── search/ # Поиск
|
||
│ │ ├── storage/ # SQLite + миграции
|
||
│ │ ├── sync/ # Синхронизация
|
||
│ │ ├── templates/ # Шаблоны дел
|
||
│ │ ├── vault/ # Vault layout
|
||
│ │ └── worklog/ # Журнал работ
|
||
│ └── gui/ # Wails bridge (embedded HTML)
|
||
├── frontend/ # Svelte-приложение
|
||
│ └── src/
|
||
│ ├── lib/
|
||
│ │ └── i18n/ # Локали (JS)
|
||
│ └── ...svelte # Компоненты
|
||
├── migrations/ # SQL-миграции
|
||
├── docs/ # Документация
|
||
└── scripts/ # Вспомогательные скрипты и сборка
|
||
```
|
||
|
||
## CLI команды
|
||
|
||
```bash
|
||
go run ./cmd/verstak/ sync # Синхронизация с сервером
|
||
go run ./cmd/verstak/ sync configure # Настройка сервера
|
||
go run ./cmd/verstak/ sync status # Статус синхронизации
|
||
```
|
||
|
||
## Vault layout
|
||
|
||
Данные хранятся в локальной папке (vault). Структура на диске:
|
||
|
||
```
|
||
vault/
|
||
.verstak/ # Служебные данные: index.db, config.yml, trash, blobs
|
||
Проекты/ # Пользовательские папки-дела
|
||
Клиенты/
|
||
Рабочие/
|
||
Archive/
|
||
```
|
||
|
||
Внутри папок-дел: `Notes/`, `Files/`, `Documents/`, `Overview.md`.
|
||
Vault открывается в любом файловом менеджере без специальных инструментов.
|
||
|
||
## Документация
|
||
|
||
| Раздел | Описание |
|
||
|--------|----------|
|
||
| [Описание продукта](docs/01_Product_Spec.md) | Аудитория, сценарии, фичи |
|
||
| [Архитектура](docs/02_Architecture.md) | Компоненты, плагины, sync |
|
||
| [Модель данных](docs/03_Data_Model_Storage.md) | SQLite, vault, файлы |
|
||
| [Синхронизация](docs/04_Sync_Backup_Activity.md) | Sync, backup, activity |
|
||
| [UI/UX](docs/05_UI_UX.md) | Экраны GUI |
|
||
| [Плагины](docs/09_Extensibility.md) | Lua-плагины, шаблоны |
|
||
| [Сервер синхронизации](docs/10_Sync_Server_Guide.md) | Установка и настройка сервера |
|
||
| [Vault layout](docs/VAULT_LAYOUT.md) | Структура папок на диске |
|
||
| [План](docs/PLAN.md) | Дорожная карта |
|
||
| [Шаблоны](docs/TEMPLATES.md) | Шаблоны дел |
|
||
|
||
## Лицензия
|
||
|
||
MIT
|