# Дейл (Deal) — архитектурный дизайн-док

> Исторический документ (архитектурный дизайн-черновик, 2026-09-05). Актуальное состояние — `docs/superpowers/STATUS.md` и `docs/technical/Техническая-документация-Дейл.md`.

> Версия: 0.1 (черновик для согласования)
> Дата: 2026-09-05
> Статус: фиксирует согласованные решения по переписыванию LeadRadar в новый продукт «Дейл»

---

## 1. Контекст и цели

**LeadRadar** — рабочий прототип (Python/FastAPI/DuckDB/Vue), проверенный на тестовых данных.
**«Дейл»** — новая реализация: SaaS-продукт, который мониторит Telegram-каналы и группы клиентов,
отсеивает рекламу/скам/дубликаты и показывает **реальные заказы и клиентов**, совпадающих с
профилем пользователя (сфера, стек, бюджет). Клиенты подключают свои Telegram-аккаунты.

### Цели переписывания
1. Код, который владелец продукта может поддерживать сам (типизированный .NET вместо Python).
2. Стабильность и строгость типов, интерфейсов, слоёв — «как сеньор-архитектор».
3. Мультитенантный SaaS (схема на тенанта) — фундамент для роста до сотен/тысяч клиентов.
4. Безопасность «с первого дня» (публичный продукт).
5. Полная документация: ТЗ, инструкция пользователя, техдок — параллельно с кодом.

### Не-цели (сейчас)
- Переписывание фронтенда (Vue остаётся как есть).
- Kafka/кубер (отложены до реального масштаба; архитектура готова к ним).
- Биллинг-провайдер (лимиты в ядре, биллинг — позже).
- Саморегистрация тенантов (только инвайты).

---

## 2. Решения верхнего уровня (зафиксированы)

| # | Решение | Выбор |
|---|---|---|
| 1 | Стратегия | Big Bang: пишем новый бэкенд целиком; старые данные не мигрируем (тестовые) |
| 2 | Фронтенд | Vue не трогаем; HTTP-контракт `/api/...` — замороженная спецификация миграции |
| 3 | Архитектура | Модульный монолит в `core` (один процесс, одно sln); сервисы — отдельные процессы/sln |
| 4 | Стек | .NET (актуальная LTS), C# современный, Postgres |
| 5 | Мультитенантность | Одна Postgres-БД, **схема на тенанта** (`tenant_<id>.*`), системное в `public` |
| 6 | Владение данными | Каждый модуль владеет своими таблицами; межмодульно — интерфейсы/доменные события |
| 7 | Межпроцессно | gRPC + mTLS; шина событий за портом `IEventBus` (outbox → Kafka позже) |
| 8 | Telegram | Отдельный `telegram-service`: ферма сессий, 1 аккаунт/тенант, анти-бан; исполняет команды ядра, ничего не знает о бизнес-логике |
| 9 | ML | Отдельный `ml-service`: .NET + ONNX, пул моделей per-tenant, обучение на действиях |
| 10 | AI (LLM) | Отдельный `ai-service`: фасад провайдеров, промпты, учёт токенов |
| 11 | Клиенты SaaS | Подключают свои Telegram-аккаунты и настраивают обработку под свою сферу |
| 12 | Доступ тенантов | Инвайты: тенанта создаёт оператор, клиент по ссылке задаёт пароль |
| 13 | Аутентификация | Логин = email + пароль (email уникален глобально); `tenantId` в сессии/JWT |
| 14 | Название | «Дейл» (бренд), namespace `Deal` |
| 15 | Код-стайл | Документ пользователя + 5 адаптаций; 1 тип = 1 файл; `.editorconfig` + анализаторы |
| 16 | Наблюдаемость | Serilog + OpenTelemetry → Grafana + Loki + Promtail |
| 17 | Админка | Операторская (A): тенанты, лимиты, health, impersonation, аудит |
| 18 | Бэкапы | Ежедневные: Postgres + minio + сессии |
| 19 | Лимиты | Бюджет токенов на тенанта (LLM); fallback на ML/локальную обработку |
| 20 | Деплой | docker compose на своём VPS; Cloudflare перед origin; k8s позже |

---

## 3. Структура репозитория

```
src/
  core/                          # МОДУЛЬНЫЙ МОНОЛИТ — один процесс, один sln
    Deal.sln
    Deal.Api/                    # host: Web API (/api-контракт), gRPC-сервер, SSE, DI
    Deal.Modules.Pipeline/       # очередь → стоп-лист → дедуп → ML/ИИ → карточка
    Deal.Modules.Kanban/         # карточки, колонки, правила, архив/корзина
    Deal.Modules.Projects/       # «Выбранные» (проектный канбан)
    Deal.Modules.Discovery/      # поиск каналов, вступление, чёрный список
    Deal.Modules.Settings/       # настройки тенанта, промпты, валюты
    Deal.Modules.Tenants/        # тенанты, инвайты, лимиты, админка
    Deal.SharedKernel/           # Result, доменные события, время, tenant-контекст
    Deal.Infrastructure/         # Postgres, миграции, outbox, IEventBus, файлы (MinIO)
    Deal.Contracts/              # DTO для /api + gRPC-контракты наружу
    tests/                       # Deal.Tests.* (unit/integration модулей)

  ml-service/                    # Deal.Ml.sln — .NET + ONNX, обучение/предсказание per-tenant
  ai-service/                    # Deal.Ai.sln — LLM-фасад, промпты, учёт токенов
  telegram-service/              # Deal.Telegram.sln — ферма сессий, анти-бан

  contracts/                     # общие .proto (gRPC): ml.proto, ai.proto, telegram.proto
  frontend/                      # Vue — переезжает как есть
  docker-compose.yml             # dev-подъём всех процессов
```

Правила:
- `core` — единственное место с бизнес-логикой и БД.
- Каждый сервис самодостаточен: свой sln, свой контейнер.
- `.proto` — единственный общий «язык» между процессами, лежит в `contracts/`.

---

## 4. Мультитенантность

### Модель БД
- Одна Postgres-БД, **схема на тенанта**: `tenant_<id>.*`.
- Системные таблицы (реестр тенантов, пользователи, инвайты, глобальные настройки,
  ключи приложения Telegram) — в схеме `public`.
- DAL получает схему из tenant-контекста (claim в JWT / gRPC-метаданные);
  пул соединений переключает `search_path`.
- Миграции применяются ко всем схемам тенантов (специальный механизм, см. §10).
- «Золотым» клиентам позже — выделенный инстанс: стратегия выбора схемы/БД в одном месте.

### Изоляция (критично)
- `tenantId` **только из сессии/JWT**, никогда из тела запроса.
- Каждый SQL-запрос исполняется в контексте схемы тенанта; модуль проверяет
  принадлежность объекта тенанту (IDOR-защита).
- Интеграционные тесты на перекрёстный доступ тенантов — обязательны.

### Обработка per-tenant
- Настройки обработки (стоп-фразы, промпты, колонки/правила, ключи) — per-tenant.
- **ML-модель — per-tenant** (модель дизайнера не учится на действиях кровельщика):
  `ml-service` держит пул моделей, core передаёт `tenantId` в каждом вызове.

---

## 5. Модули core и их границы

Модули заводятся сразу как отдельные проекты; **внутренние интерфейсы между ними
не выдумываются заранее** — появляются в момент реальной зависимости.

| Модуль | Ответственность | Владеет таблицами (в схеме тенанта) |
|---|---|---|
| Pipeline | очередь входящих → стоп-лист → дедуп → ML/ИИ → карточка; отсев; обработка | очередь, отсев, dedup |
| Kanban | карточки, колонки, правила, архив/корзина, комментарии, файлы | карточки, колонки |
| Projects | «Выбранные»: свой канбан, стадии, история, напоминания | проекты |
| Discovery | задачи поиска каналов, кандидаты, чёрный список, квоты | discovery-таблицы |
| Settings | настройки тенанта, промпты, валюты | настройки |
| Tenants | тенанты, пользователи, инвайты, лимиты, аудит, операторская админка | tenant-реестр (в `public`) |

Общие справочники (например, «колонки» нужны и Pipeline при создании карточки, и Kanban
при отрисовке) живут в модуле-владельце (Kanban); доступ — через его публичный интерфейс.

---

## 6. Контракты

### 6.1 `/api` — замороженный контракт миграции
- Фронтенд Vue продолжает ходить в `/api/...` без изменений.
- Снимаем точную карту с работающего LeadRadar (эндпоинты + формы ответов, которые
  реально потребляет фронт) → фиксируем как OpenAPI-спецификацию.
- Новый `Deal.Api` обязан воспроизводить её 1:1.
- Ведём реестр «кривых мест»: если правка фронта на 1 строку убирает слой костылей —
  выносим на решение владельца по одному (не молча).

### 6.2 gRPC-контракты (`contracts/`)
- `telegram.proto`: команды ядра (подключить аккаунт, слушать канал, перечитать,
  вступить/выйти) + поток сырых сообщений → ядро.
- `ml.proto`: predict (текст → решение), train (действие → обучение), health.
- `ai.proto`: classify/filter/generate (текст → структура), учёт токенов.
- Каждый вызов несёт `tenantId`; сервисы проверяют принадлежность по своей модели
  (сессии/модели), не доверяя полю на слово.

### 6.3 Шина событий
- Порт `IEventBus` в SharedKernel.
- Реализация сейчас: outbox в Postgres (транзакционно событие + эффект, фоновый диспетчер).
- Kafka — позже, сменой реализации без правки бизнес-логики.

---

## 7. Сервисы

### 7.1 telegram-service
- Отдельный процесс, свой sln. Ничего не знает о данных и бизнес-логике.
- **Сессии привязаны к тенанту** (`tenantId → session`, 1:1): команды исполняются только
  на сессии своего тенанта; нет сессии для tenantId → отказ.
- Проверка принадлежности диалога: read/subscribe только для диалогов аккаунта тенанта.
- Join — только от имени тенанта, под его квотами и анти-баном.
- Исходящий поток сообщений помечен `tenantId` (источник определён на входе, в сервисе).
- Сервисная аутентификация (mTLS) + аудит команд `(tenantId, действие, диалог, результат)`.
- Один аккаунт на тенанта на старте (связь тенант→аккаунты уже таблицей — расширение позже).

### 7.2 ml-service
- .NET + ONNX (не ML.NET для онлайн-обучения): пул моделей по тенантам, обучение на
  реальных действиях пользователя и результатах ИИ.
- Ничего не знает о домене: получает текст, отдаёт решение; обучение — по контракту.
- Экспорт/импорт моделей — по контракту (для переноса между инстансами).

### 7.3 ai-service
- Фасад LLM-провайдеров (DeepSeek и др., включая локальные OpenAI-совместимые),
  библиотека промптов, классификация, генерация.
- **Учёт токенов**: каждый вызов оценивается в токенах и списывается с бюджета тенанта.
- При исчерпании бюджета — fallback на ML/локальную обработку + уведомление
  (приём сообщений не блокируется).

---

## 8. Безопасность

### Слой приложения (core)
- SQL-инъекции: запрет конкатенации SQL; только параметризация (EF Core/Dapper);
  анализаторы; Postgres-роль без DDL.
- Tenant-изоляция (IDOR): tenantId из сессии; проверка принадлежности; тесты.
- Аутентификация: Argon2id, лимит попыток, одноразовые инвайты с expiry.
- Сессии: httpOnly cookie + CSRF (не localStorage).
- XSS: экранирование на фронте (renderSourceMessage), CSP, запрет v-html без санитайзера.
- SSRF: ai/telegram не тянут произвольные URL от имени тенанта (allowlist).
- Валидация входа: DTO + FluentValidation, лимиты размеров.
- Аудит: входы, инвайты, impersonation, действия оператора — неизменяемый поток.

### Транспорт/сервисы
- TLS везде; mTLS между сервисами; service-token второй фактор.

### Инфраструктура
- Cloudflare (DDoS/WAF) → reverse proxy (TLS, rate limit по IP, security-заголовки).
- Rate limiting в приложении по тенанту (защита от «шумного соседа»).
- Docker: сервисы в изолированной сети, наружу — только прокси; non-root, read-only FS.
- Секреты: env/secret-хранилище; шифрование (enc); ничего в коде/репозитории.

### Процессы
- CI: сканирование зависимостей (NuGet/npm), SAST, trivy-скан образов.
- Обновления и алерты на CVE.
- Postgres: бэкапы ежедневные, тест восстановления.

---

## 9. Наблюдаемость, админка, бэкапы

### Observability
- Serilog (структурированные логи) + OpenTelemetry (метрики/трейсы) → Promtail → **Grafana + Loki**.
- Дашборды: health сервисов, pipeline, ML-качество, расход токенов по тенантам.
- За абстракцией экспорта — смена стека без правки кода.

### Операторская админка (только оператору)
- Создание тенантов и инвайтов, лимиты, health, impersonation (с полным аудитом),
  подозрительная активность. Отдельный защищённый вход (оператор ≠ тенант).

### Бэкапы
- Ежедневно: Postgres (pg_dump), файлы MinIO, сессии telegram.
- Retention и внешняя выгрузка — уточнить на этапе деплоя.

---

## 10. Деплой

- docker compose на одном VPS: core, ml-service, ai-service, telegram-service,
  postgres, minio, grafana/loki/promtail, reverse proxy.
- Сервисы compose = будущие k8s-деплойменты (никаких завязок на compose в коде).
- Миграции схем тенантов: механизм «миграция ко всем схемам» (список схем в `public`,
  применение по очереди, версия миграции на схему) — детализировать в плане реализации.

---

## 11. Стандарты кода

- Код-стайл: `C:\telbase\Стиль_кода.docx` + согласованные адаптации
  (без snake_case-хелперов и регионов, public-поля → свойства, XML-doc для public-контрактов,
  настройки через `IOptions<T>`, комментарии на русском).
- 1 тип = 1 файл (класс/record/struct/enum/interface — отдельный файл).
- `.editorconfig` + Roslyn-анализаторы с ошибками на нарушения.
- Второй слой правил: скилы `agent-rules-books` (Clean Code, DDD, DDIA).
- .NET-эталоны: скил `dotnet-clean-architecture-skills` (адаптировать под проект).

---

## 12. Открытые вопросы / следующие шаги

1. **Карта `/api`**: снять точную спецификацию с работающего LeadRadar (отдельная задача).
2. **Детали лимитов**: механика «бюджет токенов» (период, пороги, уведомления) — спроектировать.
3. **Бэкапы**: точная схема retention/внешнего хранилища.
4. **Миграции на 1000 схем**: детальный механизм.
5. Порядок реализации: этап 0 (каркас) → Pipeline+Kanban → ai/ml/telegram → Projects/Discovery.

---

## Приложение: глоссарий

- **Тенант** — клиент SaaS (одна организация/пользователь), владеет схемой БД и настройками.
- **Канал/источник** — Telegram-канал/группа, который слушает аккаунт тенанта.
- **Карточка** — структурированная заявка (заказ/вакансия), созданная пайплайном.
- **Outbox** — паттерн надёжной доставки событий через таблицу в той же транзакции.