# 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-тесты |
| EventHubFrontAdmin | `npm run lint`, `npm run build` |
| EventHubSpec | ревью текста, ссылки на код |

---

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

Если изменение затрагивает **поведение, 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/`.

---

## История

| Дата | Изменение |
|------|-----------|
| 2026-07-07 | Правило: варианты решения и утверждение перед реализацией |
| 2026-07-07 | Первая версия: Gitea workflow, gate тестирования, sync спеки |