EventHubSpec/WORKFLOW.md

EventHub — правила работы

Живой документ процесса разработки. Дополняется по мере появления новых договорённостей.

Репозитории: EventHubBack, EventHubFrontAdmin, EventHubSpec
Трекер: https://git.sabilin.com/EventHub
Cursor skill для задач: eventhub-gitea

---

1. Задачи (Gitea)

Язык

Все задачи, комментарии и описания — на русском.
Исключение: имена файлов, пути API, идентификаторы в backticks.

Жизненный цикл

Этап	Действие
Старт	Прочитать issue → назначить на себя → комментарий «Беру в работу»
План	Предложить 1–3 варианта решения с trade-offs → ждать утверждения
Работа	После утверждения — код в репозитории-владельце; коммиты с Refs EventHub/<repo>#N
Финиш	Тесты зелёные → комментарий с итогом → закрыть issue

Метки (единый набор во всех репо)

Метка	Назначение
Bug	Дефект
Task	Техническая задача
Story	Пользовательская история
Epic	Крупная инициатива
Future	Отложено

Синхронизация меток: ~/.cursor/skills/eventhub-gitea/scripts/sync-labels.ps1

Приоритеты

P0 → P1 → P2 (указывается в заголовке задачи).

---

2. Тестирование (обязательный gate)

Нельзя закрывать задачу и нельзя обновлять спеку, пока:

• пройдены релевантные тесты репозитория;
• выполнена ручная проверка, если автотестов нет;
• нет известных регрессий в затронутой области.

Репозиторий	Минимум
EventHubBack	make test / make eunit / целевые API-тесты (см. §2.1 WSL)
EventHubFrontAdmin	npm run lint, npm run build, npm run test:e2e (Playwright mock-suite)
EventHubSpec	ревью текста, ссылки на код

IFT smoke Admin UI (живой API после деплоя): npm run test:e2e:ift / workflow e2e-ift.yml — secrets E2E_ADMIN_EMAIL, E2E_ADMIN_PASSWORD (+ опц. E2E_IFT_BASE_URL). Контракт селекторов: EventHubFrontAdmin/e2e/TESTIDS.md.

---

2.1. Локальная разработка (WSL)

Окружение: WSL + asdf (Erlang/OTP 28, rebar3). PowerShell/Windows — только IDE; сборка и тесты — в WSL.

cd /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubBack
bash scripts/wsl-ext4-dirs.sh          # один раз: logs/data на ext4
bash scripts/fix-rebar-unit-symlink.sh # перед CT, если rebar сломал unit/api
rebar3 as test eunit
rebar3 ct --suite=api_admins_SUITE

Git-коммиты из WSL (Agent и разработчик)

Коммиты из Agent Shell / PowerShell ломаются: Cursor подставляет --trailer "Co-authored-by: Cursor <cursoragent@cursor.com>", а PowerShell падает на <.

Решение: Agent коммитит через WSL-скрипт в ~/.cursor/eventhub/ (в команде нет строки git commit):

EH=/mnt/c/Users/alexc/IdeaProjects/eventHub
GIT=/mnt/c/Users/alexc/.cursor/eventhub

bash $GIT/git-commit.sh $EH/EventHubBack \
  "сообщение. Refs EventHub/EventHubBack#N" \
  path/to/file ...

Ручной коммит — тот же вызов в WSL-терминале.

Push на remote

Agent делает git push только после явного подтверждения пользователя («пуш», «отправь», «push»):

bash $GIT/git-push.sh $EH/EventHubBack

До подтверждения: коммиты остаются локально; в конце задачи Agent напоминает, что можно пушить.

Attribution в Cursor (Settings → Agent → Attribution) можно выключить дополнительно.

---

3. Спецификация (после успешных тестов)

Если изменение затрагивает поведение, API, модель данных или роли:

1. Обновить соответствующий файл в EventHubSpec/:
   • backend → EventHubBackSpec.md
   • admin → EventHubFrontAdminSpec.md
2. В комментарии к issue указать: «Спека обновлена: …»
3. Спека описывает фактическую реализацию, не планы.

Что синхронизировать:

• endpoint-ы (путь, метод, auth);
• форматы запросов/ответов;
• поля records/таблиц;
• роли и права;
• ограничения и допущения.

Чистый рефакторинг без смены контракта — обновление спеки не обязательно (написать в issue).

---

5. Старт нового чата (передача контекста)

Новую задачу лучше начинать в отдельном чате с коротким брифом — не копировать всю переписку.

Что приложить в Cursor

• @EventHubSpec/WORKFLOW.md — этот документ
• Ссылка на issue: https://git.sabilin.com/EventHub/<Repo>/issues/N
• При необходимости: 1–3 ключевых файла кода (@src/...)

Шаблон первого сообщения

Проект: EventHub
- EventHubBack: .../EventHubBack
- EventHubFrontAdmin: .../EventHubFrontAdmin
- EventHubSpec: .../EventHubSpec

Gitea: https://git.sabilin.com/EventHub
Следуй WORKFLOW.md и skills eventhub-gitea / eventhub-workflow.

Окружение: WSL + asdf (OTP 28). Git: ~/.cursor/eventhub/git-commit.sh, push — только после «пуш».
Перед CT: scripts/fix-rebar-unit-symlink.sh; logs/data: scripts/wsl-ext4-dirs.sh

Задача: EventHubBack#24 — <краткая цель>
Issue: https://git.sabilin.com/EventHub/EventHubBack/issues/24

Контекст (что уже сделано):
- #23 закрыт: auth_session, admin refresh JWT (фаза 1)

Правила: 1–3 варианта → утверждение → код; тесты перед закрытием; спека после контракта.

Минимальный вариант (одной строкой)

Берём EventHubBack#24. WORKFLOW.md. WSL, git через ~/.cursor/eventhub/. Варианты — потом утверждение. Пуш — только когда скажу.

Что не передавать

• Полные логи, diff, историю старого чата
• Токены (GITEA_TOKEN — в ~/.cursor/secrets/eventhub-gitea.env)

---

6. Версии и деплой (IFT / stage)

Product version (VERSION)

В корне EventHubBack и EventHubFrontAdmin лежит файл VERSION в формате MAJOR.MINOR (сейчас 0.1).

• Бампается вручную и редко (релиз продуктовой линейки), не на каждый push.
• Patch-уровень SemVer не используется для stage-деплоев.
• Ручные git-теги v* для выкладки на stage не нужны.

Идентичность сборки

Поле	Откуда	Назначение
product version	VERSION	«линейка» продукта
git sha	GITHUB_SHA (12 символов)	точная сборка
built_at	время CI UTC	диагностика

• FrontAdmin: bake в Vite (VITE_APP_VERSION, VITE_GIT_SHA, VITE_BUILT_AT) на шаге CI.
• Back: bake в Docker image (EVENTHUB_VERSION, EVENTHUB_GIT_SHA, EVENTHUB_BUILT_AT) → GET /admin/health и GET /v1/admin/health (version, git_sha, built_at).
• В UI (меню профиля): Admin 0.1 (sha) + API 0.1 (sha).

Registry / окружения

Окружение	Тег образа	Когда
IFT / push CI	sha-<12> + floating :ift / :dev	после зелёного CI
Stage	тот же sha-<12> + floating :stage	auto после успешного CI на master (deploy-stage.yml → promote + SSH deploy)

IFT и stage крутят одну и ту же сборку sha-*. Product version из VERSION на деплой не влияет.

E2E Admin UI (Playwright)

• CI / PR: npm run test:e2e — Chromium, API-моки (e2e/mocks), project mock.
• IFT smoke: после успешного Deploy IFT — workflow e2e-ift.yml → npm run test:e2e:ift (без моков). Secrets: E2E_ADMIN_EMAIL, E2E_ADMIN_PASSWORD, опц. E2E_IFT_BASE_URL.
• Селекторы: data-testid + a11y; контракт в EventHubFrontAdmin/e2e/TESTIDS.md.

---

4. Расширение правил

При появлении новой договорённости в работе:

1. Добавить пункт в этот файл (раздел «Правила» ниже).
2. При необходимости — задача Task в EventHubSpec на согласование.
3. Для Cursor — обновить skill eventhub-workflow.

---

Правила (накопительный список)

• Задачи в Gitea вести через skill eventhub-gitea; тексты на русском.
• Перед реализацией — предложить оптимальные варианты решения; кодить только после утверждения варианта пользователем.
• Перед закрытием issue — успешные тесты изменённого кода.
• После успешных тестов — обновить спеку, если менялся внешний контракт.
• Одна задача — один логический объём работы.
• Код фичи — в репозитории-владельце; EventHubSpec — для документации и процесса.
• Метки во всех репозиториях держать одинаковыми (sync-labels.ps1).
• Секреты и токены не коммитить; Gitea token — только в env / ~/.cursor/secrets/.
• Git commit/push — через WSL (~/.cursor/eventhub/git-commit.sh, git-push.sh); push — только после подтверждения пользователя (см. §2.1).
• Новая задача — отдельный чат с брифом по §5.
• Версии/деплой: product = VERSION (MAJOR.MINOR); IFT+stage = sha-* (+ floating :ift/:stage); без ручных stage-тегов и без patch++ на каждый push (см. §6).
• FrontAdmin E2E: mock-suite обязателен в CI; IFT smoke — после Deploy IFT (e2e-ift.yml, secrets E2E_ADMIN_*).

---

История

Дата	Изменение
2026-07-14	§6 + gate: Playwright E2E (mock CI + IFT smoke secrets)
2026-07-14	§6: VERSION MAJOR.MINOR + auto stage по sha после CI
2026-07-07	Git-скрипты Agent перенесены в ~/.cursor/eventhub/ (не в репозиториях)
2026-07-07	§5: шаблон передачи контекста в новый чат
2026-07-07	Push на remote — только после подтверждения пользователя
2026-07-07	§2.1: WSL, git-коммиты через scripts/git-commit.sh
2026-07-07	Правило: варианты решения и утверждение перед реализацией
2026-07-07	Первая версия: Gitea workflow, gate тестирования, sync спеки