Family Blueprint

Family Backend — мінімальний план

#TODO — сторінка сира. Структура є, але опис кожної секції треба пройти і звірити з реальним кодом / партнерськими контрактами. Помітки shared? — поки кандидати на обговорення, не рішення.

Карта того що має бути в новому Family-беку коли стартує новий партнерський проєкт (як зараз golden / prime / udate / chathouse). Один екран — мінімум сервісів, очікуваний партнерський API, і помітки що варто винести в спільний мікросервіс.

Family-моноліт — повноцінний бек на один бренд: своя БД, свій набір ui-triggered сервісів, свої workers, інтеграція з партнерським API. Контракт — у Swagger. Зразок — stack-golden.

Стандартний набір ui-triggered сервісів

Дзеркало UI з stack-client (ui-family/*) + специфічні для Family контракти. Один controller, обернутий у @JsonController('/path').

Сервіс	Призначення	Мітка
admin	Адмін панель
auth	Family-специфічна авторизація поверх stack-auth
agency	Список RU які робили витрати
lady	Управління TU
man	Управління RU
global-man	Всі RU	shared?
operator	Управління операторами
supervisor	Управління тімлідами
top-manager	Top-manager функції
task	Таски
workspace	Робочий простір
dashboard	Dashboard метрики
favorites	Фаворити
request	Точка для запитів
statistics	Статистика
metric	Метрики поверх ClickHouse	shared?
online-analysis / online-time	Аналіз і облік онлайну	shared?
analyst	Аналітика для аналітика-ролі
ai-notes	AI-нотатки оператора
error-report	Збір помилок з UI
debug	Debug-ендпоінти (dev only)

Мітка shared? — логіка схожа в усіх Family. Кандидат на винесення в окремий мікросервіс щоб не дублювати (див. секцію нижче).

Стандартний набір workers

Фонові задачі по таймеру/події. Bull-черги поверх Redis.

Worker	Призначення	Мітка
download-main-statistics	Регулярне завантаження статистики з партнерського API
download-temp-statistics	Завантаження тимчасової (поточний день) статистики
check-family-ladies	Періодична перевірка стану TU
update-data-family-ladies	Оновлення даних TU з партнерського API
update-temp-online	Оновлення тимчасового онлайн-стану	shared?
getting-online	Збір онлайн-статусів	shared?
generate-dashboard	Аґрегація для dashboard
job-close-operator-task	Bull-job для закриття задач оператора

Інтеграції

Інтеграція	Опис
official-api	HTTP-клієнт до партнерського API (див нижче)
clickhouse	OLAP-сховище аналітики (read+write)
rmq	RabbitMQ events із stack + electron + інші Family

Очікуваний партнерський API

Мінімум що партнер має надати щоб ми взагалі змогли побудувати Family-бек. Якщо чогось нема — або просимо в партнерів додати, або робимо костиль і ставимо #fix.

Еталон контракту — Prime / Chathouse (стабільні, єдина точка документації). Goldenbride — повний обсяг, але контракт нестабільний (#fix у golden/integrations/official-api). UDate — поки не задокументовано.

Auth

• POST /auth/login — {id_api, password} → JSESSIONID + cookie
• GET /auth/check — перевірка сесії
• Stack кешує session per TU (ladyId_api).

TU (профіль і медіа)

• GET /ladies/list — список TU агенції
• GET /ladies/{ladyId} — деталі TU
• POST /ladies/update — оновити профіль/фото
• POST /ladies/photos/upload — завантажити фото

Чати

• GET /chats/dialog/{ladyId}/{manId} — повний діалог
• POST /chats/send — відправити повідомлення
• GET /chats/invites/{ladyId} — список запрошень

Mail

• GET /mail/folders/{ladyId} — папки (inbox / sent / draft / trash)
• GET /mail/letters/{ladyId}/{folder} — список листів
• POST /mail/send — відправити лист
• POST /mail/attachments/upload — вкладення

Online + статистика

• GET /online/{ladyId} — поточний онлайн-статус
• GET /statistics/{ladyId}/daily/{date} — статистика дня
• GET /statistics/{ladyId}/period?from=&to= — період

Якщо новий партнер пропонує сильно інший контракт — потрібен окремий integration-шар який нормалізує під цей набір.

Кандидати на спільний мікросервіс

Логіка яка зараз дублюється в кожному Family-беку — варта винесення в окремий сервіс, спільний для всіх.

Логіка	Поточний стан	Куди винести
Збір і облік онлайн-статусів	Дублюється: getting-online worker + online-time / online-analysis сервіси в кожній Family	Новий stack-online — централізовано пулить, віддає API всім Family
Метрики поверх ClickHouse	Дублюється: кожен Family пише і читає clickhouse сам	Новий stack-metrics
DeepL переклади	Поки в Electron	stack-ai або окремий stack-translate
Global Man реєстр	Дублюється логікою в кожній Family	Новий stack-man-registry
AI-нотатки + AI-генерація	Часткова в ai-notes контролері кожного Family	Перенести у stack-ai
Recruit / онбординг операторів	Вже в stack	OK

Чек-ліст для нового Family

Коли стартує новий партнерський проєкт:

1. Створити репо stack-<family> за патерном golden
2. Налаштувати CLAUDE.md за шаблоном
3. Створити docs/ каркас (див. CONVENTIONS)
4. Додати в API Map як TBD
5. Запитати в партнерів API-контракт. Якщо відрізняється від мінімуму вище — окремий integration-шар.
6. Зібрати мінімум ui-triggered сервісів (admin / auth / lady / man / operator / task / …)
7. Зібрати мінімум workers (download-statistics, update-data-ladies, …)
8. Підняти Mongo-колекції <family>_*
9. Інтегрувати у stack як новий маршрут
10. Додати UI у stack-client/docs/ui-family/ і stack-electron/docs/ui/

Зв’язки

• Архітектура → Architecture
• Карта Swagger-ів → API Map
• Правила формату → CONVENTIONS
• Процес заповнення → AUTHORING