Family Backend — план і каталог логік

#TODO — робочий чернетковий каталог. Логіки й орієнтовне API треба звіряти з реальним кодом і партнерськими контрактами. Помітки shared? — кандидати на обговорення, не рішення.

Цільові сутності, сервіси, Family-логіки та workers — у Family Platform. Ця сторінка лишається каталогом вимог до нового партнера та його API.

Подвійна роль сторінки:

Каталог усіх важливих логік Family — воркспейсних і поза ним (статистика, дашборд, агенція, метрики). Що є, як групується, що вже спільне.
Шпаргалка нового партнера — заходить новий бренд → проходимо каталог → бачимо які логіки треба і яке партнерське API під кожну. Чого партнер не дає — просимо додати або робимо костиль з #fix.

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

Як читати каталог

Орієнтовне API — мінімум, який партнер має дати, щоб логіку взагалі можна було зробити. — = наше, не залежить від партнера. ? = ще не звірено.
shared? — логіка схожа в усіх Family, кандидат у спільний мікросервіс (деталі — Кандидати на спільний мікросервіс).
Глибше — deep-dive сторінка, де логіка розписана (умови, таймінги, вердикти уніфікації).

Каталог логік

Платформа / доступ

Логіка	Що це	Орієнтовне API	shared?	Глибше
`auth`	Family-авторизація поверх stack-auth	—	—	index
`admin`	Family-адмінка (власники TU)	—	—	—
`lady`	Керування TU: закріплення operator / supervisor	`GET ladies/list`, `GET ladies/{id}`	—	—
`operator` / `supervisor` / `top-manager`	Керування ролями воркспейсу	—	—	glossary
`request`	Точка для запитів (тікети / доступи)	—	—	—

Воркспейс — спільне ядро

Наша платформа (Electron ↔ stack). Не залежить від партнерського API — ціль: ідентично всюди.

Логіка	Що це	Орієнтовне API	shared?	Глибше
Логін оператора + JWT	вхід у робоче місце	—	—	Unification
Перевірка версії / часу	допуск клієнта до роботи	—	—	Unification
Конект контрол-сокета → список TU	старт воркспейсу, статуси анкет	—	—	Current State
Presence / останній онлайн оператора	облік онлайну оператора (Redis)	—	shared?	—
Дисконект-політика	поведінка при втраті зв’язку	—	—	Current State
Агрегація дій оператора	підрахунок дій, кік за неактивність	—	—	—
Data-sync стану на бек	клієнт рахує → сервер зберігає	—	—	Server Coupling

Воркспейс — партнер-залежне

Потрібне всюди; поведінку уніфікуємо, реалізацію диктує API.

Логіка	Що це	Орієнтовне API	shared?	Глибше
Логін TU на сайт	сесія анкети до партнерського API	`POST auth/login`, `GET auth/check`	—	Server Coupling
Допуск анкети	перевірка стану перед логіном	статус анкети (blocked / deleted / active) `?`	—	Current State
Тримання TU онлайн	тримати анкету онлайн на сайті	`GET online/{ladyId}` або WS keep-alive	shared?	Unification
Сокет сайту (події)	реалтайм: нове повідомлення / лайк / блок / typing / ліміти	WebSocket подій партнера	—	Current State
Таски	черга задач оператора, авто-генерація / закриття	dialogs scan + WS events + limits	—	Current State §4
Сендери (чат / мейл)	авто-надсилання інвайтів	`POST chats/send`, `GET chats/invites`, `POST mail/send` + limits	—	Current State §5
Фаворити	постійні RU по TU, списки + флаги	favorites / bookmarks list + flags `?`	—	Favorites
Чат / мейл історія	перебудова діалогів з останнім повідомленням	`GET chats/dialog/{ladyId}/{manId}`, `GET mail/letters`	—	—
Айсбрейкери	список / активація ice	`GET ice`, `POST ice/activate` `?`	—	—
Створення чатів	відкриття діалогу / лімітів	endpoint створення діалогу `?`	—	—
Фрілоадери	RU лише з безкоштовним профітом	profit / spend per RU `?`	—	—
White-list	1 на TU (`ladyId_api`), авто-видалення при profit ≥ 10	— (наша логіка поверх статистики)	—	—

Аналітика

Логіка	Що це	Орієнтовне API	shared?	Глибше
`statistics`	денний бонус-журнал, рейтинги, періоди	`GET statistics/{ladyId}/daily/{date}` + `/period`	—	Statistics
`dashboard`	графіки трендів Family по тижнях	— (з нашої статистики)	—	Dashboard
`analyst`	% вчасних, швидкість, розподіл по годинах	—	—	—
`metric`	scoring TU, зв’язки RU↔TU, time-series (ClickHouse)	—	shared?	—
`agency`	активні RU з витратами, місячний календар	фінанси per RU / період `?`	—	—
`report`	місячний xlsx-звіт по операторах	—	—	—

Дані RU / TU

Логіка	Що це	Орієнтовне API	shared?	Глибше
`man` / `global-man`	профілі RU + крос-TU реєстр	профіль RU з діалогів	shared?	—
TU профіль / медіа	оновлення профілю й фото анкети	`POST ladies/update`, `POST ladies/photos/upload`	—	—
`notes`	нотатки оператора по діалогах	—	shared?	Unification §4
`ai-notes`	AI-нотатки	—	shared?	—

Сервіс

Логіка	Що це	Орієнтовне API	shared?	Глибше
`error-report`	журнал доменних помилок: створення + resolve	—	—	—
`debug`	CPU-профайлер (start / stop / status)	—	—	—
`log-users`	журнал дій lady / operator / supervisor	—	—	—

Інтеграції

Логіка	Що це	Орієнтовне API	shared?	Глибше
`official-api`	HTTP-клієнт до партнерського API	весь контракт нижче	—	—
`official-api-ws`	WebSocket живих подій партнера	WebSocket подій	—	Server Coupling
`clickhouse`	OLAP: метрики + логи запитів	—	shared?	—
`deepl`	переклад повідомлень чату / пошти	—	shared?	—
`rmq`	шина подій між сервісами	—	—	—

Фонові задачі (воркери)

Окремими рядками не виношу — прив’язані до логік вище. Ключові крони/черги нового Family: завантаження статистики (download-main / download-temp), синк профілів TU (update-data-family-ladies, check-family-ladies), збір онлайну (getting-online — shared?), генерація дашборду, закриття тасків оператора після дисконекту.

Очікуваний партнерський API (консолідовано)

Канонічний контракт, на який посилається колонка «Орієнтовне 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= — період

Живі події (WebSocket)

Канал подій партнера: нове повідомлення, лайк / подарунок, блок, typing, зміна лімітів. Транспорт різний (Centrifuge / raw WS) — нормалізуємо в спільний набір подій.

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

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

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

Логіка	Поточний стан	Куди винести
Збір і облік онлайн-статусів	Дублюється: `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-нотатки	Частково в `notes` / `ai-notes` кожної Family	Спільна колекція + stack-ai
Recruit / онбординг операторів	Вже в stack	OK

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

Створити репо stack-<family> за патерном golden
Налаштувати CLAUDE.md за шаблоном
Створити docs/ каркас (див. CONVENTIONS)
Додати в API Map як TBD
Запитати в партнерів API-контракт. Звірити з каталогом логік вище: чого нема — окремий integration-шар / #fix.
Зібрати мінімум логік з каталогу (платформа + воркспейс-ядро + партнер-залежні під наявне API).
Зібрати воркери (download-statistics, update-data-ladies, getting-online, …)
Підняти Mongo-колекції <family>_*
Інтегрувати у stack як новий маршрут
Додати UI у stack-client/docs/ui-family/ і stack-electron/docs/ui/

Зв’язки

Проектування воркспейсу → Workspace (уніфікація, поточний стан, прив’язки до серверу)
Карта Swagger-ів → API Map
Де яка фіча реалізована й ким → Feature Matrix
Правила формату → CONVENTIONS · Процес заповнення → AUTHORING

Quartz 4

Explorer

Family Blueprint