Техническое задание (ТЗ) проекта Карометр

1. Введение

1.1 Наименование и назначение

Karometr — защищённая web-платформа для агрегации, расчёта и анализа индексов спроса и предложения на автомобильном рынке.

1.2 Цели проекта

1. Получать оперативные рыночные индикаторы на базе ежедневных дилерских данных.
2. Снизить задержку принятия управленческих решений по сравнению с помесячной статистикой.
3. Предоставить масштабируемый B2B-сервис по подписке.

1.3 Горизонт первого релиза

• Срок: 12 месяцев
• Бюджет первого этапа: ~1 000 000 ₽
• Результат: коммерчески готовый продукт v1

2. Область применения

Система предназначена для:

• официальных дилеров и дилерских групп;
• дистрибьюторов/импортёров/OEM;
• аналитических подразделений и отраслевых экспертов;
• B2B-пользователей, работающих с рыночными прогнозами.

3. Роли и права доступа

3.1 Роли

1. SUPER_ADMIN — полный доступ к платформе и настройкам.
2. ORG_ADMIN — управление пользователями организации, тарифом, доступами.
3. ANALYST — просмотр аналитики, выгрузка отчётов.
4. DEALER_PROVIDER — загрузка и контроль переданных дилерских данных.
5. BILLING_MANAGER — просмотр и управление подписками/платежами.
6. READ_ONLY — ограниченный просмотр разрешённых дашбордов.

3.2 Политика доступа

1. Базовая модель: ABAC (attribute-based access control).
2. Роли (RBAC) используются как атрибуты субъекта в ABAC-политиках.
3. Все операции журналируются (audit trail).

4. Функциональные требования

4.1 Модуль управления доступом (IAM)

FR-AUTH-1: Регистрация и вход (email + пароль, опционально SSO в v2).

FR-AUTH-2: JWT access/refresh, ротация refresh.

FR-AUTH-3: Принудительный logout и отзыв сессий.

FR-AUTH-4: Восстановление пароля.

FR-AUTH-5: Централизованная авторизация через Keycloak (OIDC/OAuth2, realm/clients/roles).

FR-AUTH-6: Поддержка MFA для привилегированных ролей (SUPER_ADMIN, ORG_ADMIN).

FR-AUTH-7: Service-to-service авторизация по client credentials (machine tokens).

FR-AUTH-8: Принудительная проверка токена и ролей на каждом backend-сервисе.

4.2 Модуль интеграции данных

FR-INGEST-1: Импорт файлов CSV/XLSX через UI.

FR-INGEST-2: API-интеграции источников дилеров.

FR-INGEST-3: Валидация формата и бизнес-правил.

FR-INGEST-4: Нормализация справочников (бренд, модель, регион, дилер).

FR-INGEST-5: Идемпотентная повторная загрузка.

FR-INGEST-6: Журнал ошибок и отчёт о качестве загрузки.

FR-INGEST-7: Поддержка подключения нового дилера с режимом первичной загрузки исторических данных (backfill за согласованный период).

FR-INGEST-8: Суточный регламент обработки данных: окно загрузки 23:00-04:00, окно пересчёта индексов 04:00-06:00.

FR-INGEST-9: Автоматическое уведомление дилера при пропуске отправки данных в суточном окне SLA.

FR-INGEST-10: Автоматическое выявление расхождений во входных данных/справочниках, автоисправление типовых ошибок и ручной контроль спорных случаев.

4.3 Модуль аналитического ядра

FR-CORE-1: Расчёт текущего индекса (период к предыдущему периоду).

FR-CORE-2: Расчёт годового индекса (период к аналогичному периоду прошлого года).

FR-CORE-3: Срезы по брендам, моделям, регионам, дилерским группам.

FR-CORE-4: Исторические ряды по индексам.

FR-CORE-5: Предрасчёт витрин для ускорения дашбордов.

4.4 Модуль визуализации

FR-DASH-1: Интерактивные графики динамики спроса/предложения.

FR-DASH-2: Фильтры по периоду, бренду, модели, региону.

FR-DASH-3: KPI-карточки ключевых показателей.

FR-DASH-4: Сохранение пользовательских пресетов фильтрации.

FR-DASH-5: Экспорт отчётов (CSV/XLSX, PDF на этапе v1.1).

4.5 Модуль ИИ и прогнозов

FR-AI-1: Краткосрочный прогноз индексов.

FR-AI-2: Учёт макрофакторов (ставка, курс, регуляторные параметры).

FR-AI-3: Показ доверительного интервала прогноза.

FR-AI-4: Версионирование модели и метрик качества.

FR-AI-5: Автоматическая аналитическая справка по текущей ситуации (аномалии, резкие изменения показателей, потенциальные новостные поводы).

4.6 Модуль подписок и биллинга

FR-BILL-1: Тарифные планы (базовый, расширенный, enterprise).

FR-BILL-2: Ограничения по доступам и лимитам тарифа.

FR-BILL-3: Управление статусом подписки.

FR-BILL-4: История выставлений/оплат.

4.7 Зафиксированный функционал v1

1. Подключение пилотных дилеров с первичной исторической загрузкой.
2. Ежедневный автоматизированный цикл загрузки и пересчёта индексов по расписанию.
3. Базовые индексы спроса/предложения и дашборды по брендам, семействам моделей и регионам.
4. Контроль качества данных и уведомления о пропусках/ошибках загрузки.
5. ИИ-прогноз и аналитическая справка по текущей рыночной ситуации.

5. Нефункциональные требования

5.1 Производительность

1. p95 API чтения: не более 500 мс.
2. Время построения типового дашборда: не более 2 сек.
3. Время расчёта ежедневного пакета индексов: не более 30 мин.

5.2 Надёжность

1. Доступность production: 99.5% на релиз v1.
2. RPO: не более 24 часов.
3. RTO: не более 4 часов.

5.3 Безопасность

1. TLS 1.2+ для внешних интерфейсов и mTLS для внутренних сервисных вызовов.
2. Централизованная IAM через Keycloak (OIDC/OAuth2) и применение ABAC-политик на уровне backend.
3. Хранение паролей: argon2 или bcrypt (в контуре Keycloak).
4. Короткоживущие access token + refresh token с ротацией и отзывом сессий.
5. Хранение сессионных/служебных данных в Redis с TTL и контролем инвалидации.
6. Политики доступа на backend: ABAC-first (организация, регион, бренд, дилер, тариф, MFA-контекст); роли используются как атрибуты.
7. Защита от OWASP Top 10, rate limit и brute-force protection на auth endpoints.
8. Шифрование секретов и ключей, хранение в защищённом secret-store.
9. Аудит входов, действий пользователей и административных изменений.
10. Маскирование и ограничение чувствительных данных в UI, API и выгрузках.

5.4 Масштабируемость

1. Горизонтальное масштабирование API.
2. Асинхронные фоновые задачи через очередь сообщений.
3. Разделение контуров online API и batch-процессов.

6. Архитектура решения

6.1 Архитектурный стиль

1. Система строится как микросервисная архитектура.
2. Каждый сервис имеет собственную зону ответственности и независимый цикл релизов.
3. Синхронные вызовы используются для query-команд, асинхронные — для событий и тяжёлых расчётов.
4. Межсервисные контракты фиксируются через OpenAPI + event schema.

6.2 Состав микросервисов

1. api-gateway — единая точка входа для UI и внешних интеграций.
2. auth-service (Keycloak) — аутентификация, авторизация, роли, сессии, токены.
3. ingestion-service (FastAPI) — приём, валидация и нормализация входных данных.
4. analytics-service (FastAPI) — расчёт KPI, индексов, витрин и агрегатов.
5. forecast-service (FastAPI) — прогнозные модели и оценка качества прогнозов.
6. billing-service (FastAPI) — подписки, тарифы, лимиты и статусы оплаты.
7. notification-service (FastAPI) — алерты, уведомления, служебные рассылки.

6.3 Технологический стек (утверждённый)

• Frontend: Nuxt 3 + @nuxt/ui
• Backend микросервисы: FastAPI
• Авторизация/IAM: Keycloak
• База данных: PostgreSQL
• Кэш и временные данные: Redis
• Брокер сообщений: RabbitMQ
• Объектное хранилище: MinIO

6.4 Паттерны взаимодействия

1. Синхронный контур: HTTP/REST через api-gateway.
2. Асинхронный контур: события и очереди через RabbitMQ.
3. Тяжёлые расчёты и batch-операции запускаются воркерами.
4. Для idempotency используются бизнес-ключи и dedup-проверки.

6.5 Контейнеры и окружения

1. dev — разработка и отладка.
2. stage — интеграционное тестирование.
3. prod — промышленная эксплуатация.

6.6 API-контракты (v1)

1. POST /api/v1/auth/login
2. POST /api/v1/auth/refresh
3. POST /api/v1/ingest/files
4. GET /api/v1/ingest/jobs/{id}
5. GET /api/v1/indices
6. GET /api/v1/forecasts
7. GET /api/v1/dashboard/summary
8. GET /api/v1/subscription/current

7. Модель данных (укрупнённо)

1. users, roles, user_roles
2. organizations, organization_users
3. dealers, dealer_groups
4. brands, models
5. regions
6. contracts, contract_events
7. stock_balances
8. macro_factors
9. indices_daily, indices_periodic
10. forecast_runs, forecast_points
11. subscriptions, tariffs, payments

8. Бизнес-процессы

8.1 Поставка данных

1. Дилер загружает файл или отправляет пакет по API.
2. При первом подключении дилера выполняется первичная загрузка исторических данных.
3. В ежедневном цикле 23:00-04:00 система валидирует и нормализует данные.
4. При пропуске поставки данных дилеру автоматически отправляется уведомление.
5. Запись попадает в БД и очередь пересчёта индексов.
6. В окне 04:00-06:00 пересчитываются индексы, после чего обновляются витрины и дашборды.

8.2 Потребление аналитики

1. Пользователь авторизуется.
2. Выбирает фильтры и период.
3. Получает KPI, графики, прогнозы.
4. При необходимости экспортирует отчёт.

9. Интеграции

1. Дилерские DMS/ERP-системы (через адаптеры).
2. Внешние источники макроэкономических индикаторов.
3. Платёжный провайдер для подписок.

10. План релизов

1. v0.1 (М1-М2): SRS, архитектура, auth, загрузка файлов.
2. v0.2 (М3-М4): базовые индексы, дашборд MVP.
3. v0.3 (М5-М8): интеграционные коннекторы, качество данных.
4. v1.0 (М9-М12): подписка, прогнозы, эксплуатационная готовность.

11. Тестирование и качество

11.1 Виды тестов

1. Unit-тесты бизнес-логики и расчётов.
2. Integration-тесты API и БД.
3. E2E-тесты ключевых пользовательских сценариев.
4. Нагрузочные тесты на критичные API.
5. Безопасностные тесты (SAST/DAST, пентест перед v1).

11.2 Критерии готовности релиза

1. Нет блокирующих дефектов P0/P1.
2. Покрытие критической логики тестами.
3. Пройдены интеграционные и e2e smoke-наборы.
4. Подготовлены runbook и rollback-план.

12. Критерии приёмки

1. Реализованы все обязательные требования раздела 4 для версии v1.
2. Выполнены нефункциональные требования раздела 5 в согласованных пределах.
3. Подтверждена корректность расчёта индексов на контрольных выборках.
4. Подтверждена защищённость доступа и разграничение ролей.
5. Подготовлен полный комплект проектной документации.

13. Проектные артефакты

1. SRS (подробные требования).
2. Архитектурные схемы и ADR.
3. OpenAPI-спецификация.
4. Миграции и ER-диаграмма.
5. Тест-план и отчёты о тестировании.
6. Эксплуатационная документация (runbook, backup/restore).