Конвенции Zerovibe

Конвенции Zerovibe

Приложение на стэке Go + HTMX + SQLite с чистой архитектурой. Соблюдай эти правила при генерации и изменении кода — они отражают эталонный скелет.

Общение с пользователем (ВАЖНО — соблюдай всегда)

Пользователь Zerovibe — создатель продукта, НЕ программист. Он мыслит продуктом и пользователями, а не кодом. Поэтому:

• Технические решения принимай сам, опираясь на эти конвенции и эталонный скелет. НЕ спрашивай пользователя про код, архитектуру, библиотеки, типы данных, схему БД, API, фреймворки, способ вёрстки и т.п. — это твоя зона ответственности.
• Спрашивай только продуктовое — и только когда это правда меняет результат для пользователя: что должно быть в приложении, как себя ведёт, что видит конечный пользователь, какие поля важны по смыслу. Если продуктовый выбор очевиден или некритичен — прими разумное умолчание и двигайся дальше, кратко упомянув что выбрал.
• Говори на языке продукта, без жаргона. Не «добавил usecase и репозиторий для сущности Expense с миграцией» → а «сделал, теперь можно добавлять и удалять траты, внизу появилась таблица и общая сумма».
• НИКОГДА не называй технологии и внутреннюю кухню в разговоре. Под полным запретом в общении с пользователем: название и тип БД (SQLite, «база данных», «таблица в БД», «миграция», «volume»), язык/фреймворки (Go, HTMX, CSS), слои/архитектура (usecase, repository, domain, port, handler), Docker, контейнер, деплой-внутрянка. Пользователю это пустой звук и пугает. Говори про то, что он видит и делает: «данные сохраняются», «добавилась страница», «приложение опубликовано». Если очень нужно сослаться на хранение — «данные приложения», без слова про БД.
• Никогда не проси пользователя что-то сделать в коде/терминале руками (кроме трёх команд плагина: /zerovibe:install, /zerovibe:init, /zerovibe:deploy). Запуск, сборку, тесты, исправления делай сам.
• Плохие новости — на языке последствий, не причин. Не «SQLITE_BUSY из-за гонки записи» → а «при одновременном сохранении могла теряться запись, починил».

Короткое правило: продуктовые вопросы — пользователю; технические — себе.

Слои и зависимости (строго внутрь)

internal/
  domain/              сущности + инварианты + ошибки. ТОЛЬКО stdlib. Без БД, без HTTP, без тегов.
  usecase/             бизнес-логика + порты (интерфейсы репозиториев). Зависит только от domain.
  repository/sqlite/   реализация портов поверх SQLite.
  platform/db/         SQLite + ОЧЕРЕДЬ ЗАПИСИ (единый писатель). Не трогать без необходимости.
  transport/web/       HTTP/HTML на HTMX. Зависит от usecase.
cmd/server/            composition root: склейка слоёв.

• domain не импортирует ничего из проекта и никаких json/db-тегов не несёт.
• usecase объявляет порты (интерфейсы), реализации внедряются снаружи.
• Конвертация между представлениями — на стыках слоёв, не протекает вглубь.

База данных: очередь записи

• ВСЕ записи (INSERT/UPDATE/DELETE) идут через db.Write(ctx, func(*sql.DB) error {...}) — это сериализует их в единой writer-горутине, поэтому SQLITE_BUSY не возникает.
• Чтения — через db.Read(...), параллельно.
• Никогда не пиши в БД в обход db.Write.

Миграции (goose)

• Схема БД живёт ТОЛЬКО в SQL-миграциях goose: internal/platform/db/migrations/NNNNN_*.sql (встроены через embed, применяются при старте через db.MigrateUp).
• Новая таблица/колонка = НОВЫЙ файл миграции (следующий номер), а НЕ правка существующего и НЕ inline CREATE TABLE в коде репозитория. Так у уже задеплоенных приложений база корректно доедет до новой версии.
• Формат файла: секции -- +goose Up и -- +goose Down.

Готовое в шаблоне (не изобретать заново)

В эталоне УЖЕ есть, бери как данность:

• Аутентификация: пользователи, роли (гость→user→admin), вход/выход, сессии (cookie), восстановление пароля письмом, подтверждение почты, рейт-лимиты. Регистрация по умолчанию закрыта (allow_signup), подтверждение почты по умолчанию выключено (require_email_verification) — обе управляются настройками.
• Настройки приложения: типизированный реестр (config + secret) в internal/domain/setting.go, CRUD под admin (/admin/settings). Новая настройка = запись в реестре.
• Платформенные переменные: при деплое платформа сама прокидывает в приложение PLATFORM_API_URL/PLATFORM_API_KEY (для отправки писем), APP_BASE_URL, SECURE_COOKIE. Креатор о них не думает — НЕ проси задавать их руками.

HTMX (ключевой паттерн рендеринга)

• GET страницы — отдаёт ПОЛНУЮ страницу (layout + content).
• Мутации (POST/PUT/DELETE) возвращают РОВНО ТОТ HTML-фрагмент, который меняется (например, один элемент списка), а не всю страницу. htmx подменяет его на клиенте через hx-target / hx-swap.
• Шаблоны — html/template (stdlib), встроены через embed. Фрагмент = отдельный {{define "..."}}.
• Оформление — чистый CSS (static/app.css, локальная статика). Дизайн экранов переносится из макета Pencil — см. skill design. Не сочиняй внешний вид сам, бери его из макета.

Ошибки

• Доменные ошибки — типы в domain (ErrValidation, ErrNotFound, ...).
• Транспорт мапит их в HTTP-коды в ОДНОЙ функции (fail в transport/web), через errors.As / errors.Is. Новую доменную ошибку добавляй туда же.

Стиль Go

• Конструкторы-валидаторы в domain (NewX) — единственное место инвариантов сущности.
• context.Context первым аргументом во все методы, ходящие в БД/сеть.
• Без лишних зависимостей: предпочитай stdlib. SQLite — modernc.org/sqlite (без CGO).
• Каждый публичный тип/функция — с кратким комментарием на русском.

Не делать

• Не вводить ORM, фреймворки, JS-сборку, SPA — стэк намеренно минимален.
• Не писать в БД мимо очереди записи.
• Не описывать схему через inline CREATE TABLE IF NOT EXISTS в коде — только goose-миграции (см. раздел «Миграции»).
• Не возвращать полную страницу из мутаций (ломает HTMX-паттерн).
• Не протаскивать SQL/HTTP в domain/usecase.
• Не переписывать аутентификацию/настройки с нуля — они уже в шаблоне.