Сутність «Користувач» в системі inCust

Що це таке

Користувач — обліковий запис (профіль) фізичної особи на платформі inCust. Це сутність-актор шару ідентичності: не «гість», а зареєстрований акаунт, на який може бути зареєстрований Бізнес (тенант) у ролі власника, або з яким може бути асоційований Роздрібний Покупець чи Робітник Корпоративного Покупця у програмі лояльності Бренду / контурі B2B. Користувач сам по собі не є тенантом і не несе бізнес-даних — він точка ідентичності, навколо якої будуються інші ролі та зв'язки володіння.

Ідентифікація та авторизація

Користувач ідентифікується за одним із трьох первинних ідентифікаторів:

• email (з підтвердженням);
• номер телефону (з підтвердженням);
• зовнішній ідентифікатор (external ID) — видається зовнішнім провайдером ідентичності, що не гарантує унікальності email-у.

Наявність хоча б одного з цих трьох ідентифікаторів — обов'язкова умова створення Користувача. На профілі одночасно може бути присутньо декілька ідентифікаторів різних типів — усі вони адресують один і той самий обліковий запис.

Зв'язок із зовнішніми провайдерами ідентичності

Прив'язка Користувача до зовнішніх провайдерів виконується через його первинні ідентифікатори за наступним правилом:

• Провайдери, які гарантують унікальність email-у для кожного свого користувача (Google, Apple тощо; DOC-027, DOC-028), асоціюються з email-ідентифікатором Користувача.
• Інші провайдери ідентичності — асоціюються з зовнішнім ідентифікатором (external ID) Користувача.

Пароль

Авторизація виконується за обраним первинним ідентифікатором у парі зі статичним або одноразовим паролем. Загальна послідовність авторизаційного потоку (DOC-026): фронтенд отримує облікові дані, бекенд верифікує їх, повертає локальний токен Користувача — далі вся взаємодія йде під цим токеном.

Відображення в API

У програмному інтерфейсі (API) Користувач представлений об'єктом User Profile. У межах цього об'єкта міститься вся загальна інформація про Користувача, його первинні ідентифікатори (email, номер телефону, зовнішній ID — див. розділ «Ідентифікація та авторизація»), а також додаткові ідентифікатори, асоційовані з обліковим записом понад первинні.

User Profile — єдиний об'єкт на один обліковий запис: звернення до API за будь-яким із ідентифікаторів Користувача повертає той самий User Profile.

Базовий шлях User API — /v1/user (OpenAPI 2.0, специфікація — KNOW-007). Основні методи:

Робота з профілем:

• GET /v1/user/profile — отримати User Profile цілком, включно з первинними та додатковими ідентифікаторами.
• PATCH /v1/user/profile — оновити загальну інформацію профілю.

Керування первинними ідентифікаторами (тег Auth Identifiers). Зміна та підтвердження виконуються двокроково — спочатку pre-processing виклик (…/pre), потім остаточний:

• email: POST /v1/user/email/change, POST /v1/user/email/verify, POST /v1/user/email/validate, GET /v1/user/request_confirm_email/{email}, GET /v1/user/confirm_email/{email_token}.
• номер телефону: POST /v1/user/phone/change, POST /v1/user/phone/verify, POST /v1/user/phone/validate.
• зовнішній ID: POST /v1/user/external_id/change, POST /v1/user/external_id/verify, POST /v1/user/external_id/validate.

Місце в архітектурі (DOC-008, DOC-009)

Користувач — базовий шар ідентичності під іншими акторами:

• Власник Бізнесу — Користувач, на профіль якого зареєстровано конкретний Бізнес. Виняткові права на зміну власного профілю та фінансові операції з рахунком Бізнесу (DOC-009).
• Робітник Бізнесу — окрема сутність зі своїм кодом доступу й набором Ролей у Бізнес-Панелі; пов'язана з Бізнесом, не тотожна Користувачу.
• Адміністратор Платформи — окремий шар, входить через Адмін Панель; у БП будь-якого Бізнесу отримує окрему обмежену роль, що ігнорує його рольову модель.
• Роздрібний Покупець (Retail Customer) — клієнтська сутність Бренду; може бути асоційована з Користувачем через будь-який з його первинних ідентифікаторів.
• Робітник Корпоративного Покупця — фізична особа, що діє від імені Корпоративного Покупця в B2B-контурі; асоціюється з Користувачем. Сам Корпоративний Покупець (юр. суб'єкт) з Користувачем безпосередньо не асоціюється.

Зв'язок з Бізнесом

«Кожен Бізнес зареєстрований на конкретний профіль користувача (User), який є його власником.»

Зв'язок «Користувач — Бізнес у ролі власника» — один-до-одного:

• Один Бізнес → рівно один Користувач-власник.
• Один Користувач → не більше одного Бізнесу, в якому він є власником.
• Зміна профілю власника (передача Бізнесу) — привілейована операція, доступна виключно ролі Адміністратор Бізнесу та власнику в монопольному режимі (DOC-009).
• Роль «Менеджер Бізнесу» та похідні від неї не мають права змінювати профіль користувача-власника.

Фінансово-облікові аспекти

Користувач не має власного рахунку чи бонусів на рівні платформи поза контекстом інших сутностей. Усі рахунки й бонуси належать:

• Бізнесу — якщо Користувач є його власником (рахунок Бізнесу, бонуси Бізнесу).
• Покупцю — якщо Користувач асоційований з Роздрібним Покупцем (рахунки та бонуси на рівні Бренду).
• Корпоративному Покупцю — якщо Користувач діє як його Робітник (рахунки Корпоративного Покупця на рівні Бізнесу).

Наслідки для запитів і доступу

• Одна фізична особа (один Користувач) може одночасно фігурувати як власник Бізнесу, як Роздрібний Покупець у Брендах різних Бізнесів і як Робітник одного або кількох Корпоративних Покупців. Запити «за Користувачем» на рівні платформи перетинають межі тенантів і вимагають окремого контуру доступу.
• Пошук Користувача по будь-якому з його ідентифікаторів (email, телефон, зовнішній ID) має повертати той самий профіль — це важливо для дедуплікації при імпорті покупців і при логіні через зовнішніх провайдерів.
• Аудит дій (DOC-009, секція Система аудиту) ведеться за Робітниками, а не за Користувачами; дії власника в монопольному режимі фактично логуються як дії Адміністратора Бізнесу.
• Авторизаційні дані (паролі, прив'язки до зовнішніх провайдерів ідентичності) — атрибути Користувача, не Бізнесу й не Покупця.

Джерела з Shared Drive

• DOC-008 incust.v02.pdf — Загальна архітектура inCust: https://drive.google.com/file/d/1etBcLVrYA0NfTqElUSt4Od1VixmKJUW3/view
• DOC-009 Ролёва модель inCust: https://drive.google.com/file/d/1-N9UDIETI3e9odPWNgZ2O9efBGG9fp3PncrRmpyQAAM/view
• DOC-026 General auth flow: https://drive.google.com/file/d/1QAckD-n8vn6XppUp1blDnjIYxkhfaQUmWXsOhqK4dDM/view
• DOC-027 Google Auth flow: https://drive.google.com/file/d/1ZYYUrbhesox88OR4Y36c14ugn3m2uspK4Y8CvrgKgNk/view
• DOC-028 Apple Auth flow: https://drive.google.com/file/d/1whkafjpYZ7DHZNsf2rAfsr8X8ADsJ88O86-NCvFm5SY/view