# 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-скрипт (в команде нет строки `git commit`):

```bash
bash scripts/git-commit.sh "сообщение. Refs EventHub/EventHubBack#N" path/to/file ...
```

Скрипт лежит в `scripts/git-commit.sh` каждого репо. Ручной коммит — тот же вызов в WSL-терминале.

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

---

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

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

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

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

---

## 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** (`scripts/git-commit.sh`), не `git commit` из Agent Shell (см. §2.1).

---

## История

| Дата | Изменение |
|------|-----------|
| 2026-07-07 | §2.1: WSL, git-коммиты через `scripts/git-commit.sh` |
| 2026-07-07 | Правило: варианты решения и утверждение перед реализацией |
| 2026-07-07 | Первая версия: Gitea workflow, gate тестирования, sync спеки |