202 lines
9.6 KiB
Markdown
202 lines
9.6 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` |
|
||
| EventHubSpec | ревью текста, ссылки на код |
|
||
|
||
---
|
||
|
||
## 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`)
|
||
|
||
---
|
||
|
||
## 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 спеки |
|