247 lines
13 KiB
Markdown
247 lines
13 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
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`):
|
||
|
||
```bash
|
||
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
|
||
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/...`)
|
||
|
||
### Шаблон первого сообщения
|
||
|
||
```markdown
|
||
Проект: 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 спеки |
|