docs(docs): актуализировано ТЗ и потоки ingest

- Зачем:
  - убрать рассинхрон между кратким ТЗ, архитектурой и планом генератора
- Что:
  - сокращен docs/DE-task.md до формата краткого ТЗ проекта
  - обновлены docs/ARCHITECTURE.md и README.md: bootstrap через kafka_load и steady-stream через generator-service
  - обновлен plans/generator_demo_stream_plan.md: режим steady-stream и тик-публикация
- Проверка:
  - просмотрен git diff по измененным файлам
  - в коммит включены только мои документационные изменения
This commit is contained in:
2026-06-09 17:26:31 +03:00
committed by Dmitry Dementiev
parent 8d0c8f46fd
commit cbc2f72871
4 changed files with 95 additions and 68 deletions
+16 -11
View File
@@ -1,4 +1,4 @@
# План реализации: простой автономный генератор (rev4)
# План реализации: простой автономный генератор (rev5)
Дата ревизии: 14 февраля 2026.
@@ -44,11 +44,13 @@
---
## 4) Единственный режим генерации: `steady`
## 4) Единственный режим генерации: `steady-stream`
Логика режима:
- каждую минуту публикуем фиксированный объём событий;
- публикуем в Kafka **постепенно**, короткими тиками (например, каждые 1-10 секунд);
- на каждом тике отправляем небольшую порцию сообщений;
- держим целевую интенсивность в `events/min`, а не крупный минутный batch;
- распределяем события по 4 топикам:
- `browser_events`
- `location_events`
@@ -59,15 +61,16 @@
- обновляем `event_timestamp`;
- сохраняем реалистичные связи `event_id <-> location`, `click_id <-> device/geo`.
Этого достаточно, чтобы стенд жил часами и данные выглядели не статично.
Этого достаточно, чтобы стенд жил часами, выглядел как реальный streaming и не создавал искусственных «пакетов раз в минуту».
### 4.1 Минимальная статистическая модель (Poisson)
Чтобы линия не была «ровной», используем простую интенсивность событий:
Чтобы линия не была «ровной», используем простую интенсивность:
- число событий на тик: `N_t ~ Poisson(lambda_t)`;
- базовая интенсивность: `lambda_base` (например, 200 событий/мин);
- плавный профиль времени: `lambda_t = lambda_base * hour_factor(t)`.
- базовая интенсивность в минуту: `lambda_minute` (например, 200 событий/мин);
- для текущего тика:
- `lambda_tick = lambda_minute * hour_factor(t) * tick_seconds / 60`;
- `N_t ~ Poisson(lambda_tick)`.
Где `hour_factor(t)` можно сделать очень простым:
@@ -82,6 +85,8 @@
Итог: поведение уже похоже на живой поток, но код остаётся компактным.
Важно: режим «раз в минуту» не удаляем полностью, но рассматриваем только как опцию (`GEN_TICK_SECONDS=60`) для контролируемых демо.
---
## 5) Как упростить реализацию
@@ -104,8 +109,7 @@
Через env:
- `GEN_TICK_SECONDS` (по умолчанию `60`)
- `GEN_EVENTS_PER_TICK` (например, `200`)
- `GEN_TICK_SECONDS` (по умолчанию `5`)
- `GEN_JITTER_PCT` (например, `20`)
- `GEN_SEED` (для воспроизводимости)
- `KAFKA_BOOTSTRAP_SERVERS`
@@ -117,6 +121,7 @@
- `GEN_ENABLED` (быстро включать/выключать цикл)
- `GEN_HOUR_PROFILE` (простая карта коэффициентов по часам)
- `GEN_TICK_SECONDS=60` (опциональный режим «раз в минуту»)
---
@@ -188,7 +193,7 @@ MVP успешен, если:
1. Генератор автономно работает 2-4 часа.
2. Потребители можно останавливать/запускать отдельно, генератор продолжает работу.
3. Данные остаются совместимыми с текущим пайплайном.
4. Есть базовые метрики и понятные логи.
4. Поток публикуется равномерно малыми порциями (без искусственного минутного burst).
5. Есть история batch-ов для учебного разбора.
---