You've already forked RekomenciBackend
ITQ
8f62c775e4
* 'main' of gitlab.prodcontest.com:team-39/backend: fix(): reset vectors similarity threshold chore(): update rfc
110 lines
6.8 KiB
Markdown
110 lines
6.8 KiB
Markdown
# Rekomenci fluon RFC
|
|
|
|
## Архитектура. *(Всё как завещал дядюшка Боб...)*
|
|
Проект следует чистой архитектуре дядюшки Боба.
|
|
|
|
|
|
# RFC-PROOD: Архитектура Recomenci Fluon
|
|
|
|
Статус: PROOOD
|
|
Дата: 23 ноября 2025
|
|
Автор: prod 39
|
|
|
|
## 1. Краткое описание
|
|
### Цель.
|
|
Описать целевую архитектуру, границы ответственности компонентов, модель разработки и деплоя для проекта рекомендаций и предсказаний зарплат (далее — проект)
|
|
|
|
RFC определяет интерфейсы для API, операционные требования и переходный план
|
|
|
|
## 2. Мотивация
|
|
- Упорядочить архитектуру для масштабируемости, тестируемости и повторяемости ML-экспериментов
|
|
- Обеспечить безопасный и предсказуемый деплой
|
|
- Определить контракты между web/API, ML-сервисом и хранилищем данных
|
|
|
|
|
|
## 3. Область и не-включения
|
|
Включено:
|
|
- Архитектура сервисов (web_api, ml)
|
|
- Хранилища: PostgreSQL, S3(далее object storage)
|
|
- CI/CD, контейнеризация и инвентори infra: Docker Compose
|
|
- Метрики, логирование, мониторинг базовой обработки ошибок
|
|
|
|
Не включено:
|
|
- Подробный дизайн интерфейсов UI
|
|
- Исследовательские ML-эксперименты (детальные датасеты/фичи) — описан процесс интеграции
|
|
|
|
|
|
## 4. Цели и критерии приёмки
|
|
Цели:
|
|
- Стабильный REST/HTTP API для вакансий и предсказаний
|
|
- Стабильный и масштабируемый REST/HTTP API, утилизирующий ML алгоритмы
|
|
|
|
|
|
## 5. Высокоуровневая архитектура
|
|
- Web API (web_api): HTTP-сервис, инкапсулирующий бизнес логику. Интегрируется с ML-сервисом
|
|
- ML сервис (ml): HTTP-сервис, инкапсулирующий ML бизнес логику
|
|
- PostgreSQL + pgvector - основное хранилище данных
|
|
- Инфра: Docker Compose для локальной разработки; Coolify для CI/CD
|
|
|
|
Коммуникация:
|
|
- HTTP REST между web_api и ml; опционально gRPC / WebSocket в будущем
|
|
- Хранение данных в PostgreSQL + pgvector, хранение файловых данных в S3
|
|
|
|
Входные/выходные схемы должны быть описаны в формате OpenAPI
|
|
|
|
### 5.1. Домены приложения
|
|
- **Resume**: управление резюме пользователей, история версий, эмбеддинги, предикты зарплаты
|
|
- **Vacancy**: каталог вакансий с эмбеддингами для поиска похожих
|
|
- **User**: пользователи, профили, аутентификация
|
|
- **Auth Identity**: методы аутентификации (email/password)
|
|
- **Notification Device**: регистрация устройств для уведомлений
|
|
|
|
### 5.2. Флоу создания резюме и предикта
|
|
1. Пользователь создает резюме через Gateway (AddResumeInteractor)
|
|
2. Gateway сохраняет резюме в хранилище и возвращает ответ
|
|
3. В фоне запускается ResumePredictionInteractor:
|
|
- Генерирует эмбеддинг резюме через ML Service (модель эмбеддинга)
|
|
- Сохраняет эмбеддинг в хранилище
|
|
- Ищет подходящие вакансии по векторному сходству (HNSW индекс, cosine similarity >= 0.5)
|
|
- Фильтрует и сортирует до 50 наиболее релевантных вакансий
|
|
- Запрашивает предикт зарплаты и рекомендуемые навыки через ML Service (алгоритм предикта)
|
|
- Сохраняет предикт в хранилище
|
|
|
|
### 5.3. Структура хранилища
|
|
- **Users**: пользователи, профили
|
|
- **Resumes**: резюме с версионированием (up_resume_id, down_resume_id)
|
|
- **Resume Embeddings**: векторные представления резюме (384 измерения)
|
|
- **Resume Predictions**: предикты зарплаты и рекомендуемые навыки
|
|
- **Resume Experience/Education/Projects**: опыт, образование, проекты
|
|
- **Vacancies**: вакансии с зарплатами и требованиями
|
|
- **Vacancy Embeddings**: векторные представления вакансий (384 измерения)
|
|
- **Key Skills**: словарь навыков для автокомплита (GIN индекс с pg_trgm для ILIKE поиска)
|
|
|
|
## 7. Деплой и CI/CD
|
|
- Локально: Docker Compose (just up/build)
|
|
- Staging/Prod: Coolify
|
|
- CI pipeline: lint → build images → full tests → push образ → deploy staging
|
|
- Резервное копирование: pg_dump + object storage snapshot.
|
|
|
|
## 8. Миграции данных и схем
|
|
- Использовать alembic для миграций схем PostgreSQL.
|
|
- Использовать вспомогательные скрипты для выгрузки датасета в хранилище
|
|
|
|
## 9. Безопасность и секреты
|
|
- Секреты в ENV (environment secrets в CI).
|
|
- Валидация входящих данных, шифрование конфиденциальных данных
|
|
|
|
## 10. Мониторинг и логирование
|
|
- Prometheus метрики через prometheus-fastapi-instrumentator
|
|
- Логирование через стандартный Python logging
|
|
- Базовый healthcheck endpoint
|
|
- Логи можно посмотреть в Coolify (см. креды в Readme.md)
|
|
- Доступны дашборды в графане с метриками контейнеров, бека, мль
|
|
|
|
## 11. Тестирование
|
|
- Unit tests - тестируют бизнес логику (entities, factories, invariants)
|
|
- E2E - тестируют весь user flow через TestApiGateway
|
|
- Интеграционные тесты для взаимодействия с хранилищем
|
|
- Unit tests - тестируют бизнес логику
|
|
- E2E - тестируют весь user flow, а также интеграцию с ml
|