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
EventHubSpec	ревью текста, ссылки на код

---

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)

---

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.

---

История

Дата	Изменение
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 спеки