API

Прийнята архітектура · 1 жовтня 2026, варіант 2

Agentfy містить harness; API Store Deputy надає єдиний MCP; модуль OpenCart — захищений REST/JSON API. Store Deputy перевіряє підключення, контекст працівника/покупця, права, погодження й аудит, не створюючи другого harness. Connect → вхід/реєстрація → безпечне підключення → автоматичне створення агента в Agentfy з MCP Store Deputy → повернення в модуль. В app: команди, агенти, акаунт, білінг і чат із кожним агентом.

Це замінює попереднє рішення того самого дня про MCP безпосередньо в модулі. Код і прототипи нижче ще не реалізують нову інтеграцію. Сесії покупців і справжній кошик OpenCart мають окрему перевірену прив'язку; cookie залишається в магазині. Див. рішення про єдиний MCP: межі, етапи та подальша робота над контрактом.

Зроблено; працює на машині розробника · 1 жовтня 2026. Не розгорнуто. Спілкувався лише з двома локальними тестовими магазинами. Функцій каталогу, цін і агентів у ньому немає.

API — єдиний сервіс, який знає, хто ця людина, в якій вона команді, що дозволяє її роль і які магазини команда підключила. Усі інші частини питають його. Більше ніхто до магазину не звертається.

Що він робить сьогодні

Акаунти. Реєстрація, вхід, продовження сесії, вихід. Вихід діє одразу: кожен запит звіряється з живою сесією, а не лише з токеном, який він несе.
Команди й ролі. Магазини належать команді. Її учасники — власники (owner), адміни (admin) та учасники (member). Запрошують власники й адміни; змінювати ролі, прибирати іншого власника й видаляти команду може лише власник. Команду не можна лишити без власника.
Магазини. Підключити магазин за одноразовим кодом з його модуля, отримати список магазинів команди, переглянути один, відключити. Секрет, спільний із магазином, зберігається зашифрованим.
Службові перевірки. Перевірка «сервіс живий» та інтерактивний опис усіх маршрутів.

Область	Маршрути
Вхід	`/auth/register`, `/auth/login`, `/auth/refresh`, `/auth/logout`, `/auth/me`
Власний профіль	`/users/me`
Команди	`/teams`, `/teams/:teamId`
Членство	`/teams/:teamId/members`, `/teams/:teamId/members/:memberId`
Магазини	`/teams/:teamId/stores`, `/teams/:teamId/stores/connect`, `/teams/:teamId/stores/:storeId`
Стан	`/health`

Реєстрація, вхід, продовження сесії та перевірка стану відкриті. Будь-який інший маршрут вимагає людини, що увійшла.

Як влаштовано код

Увесь код лежить у слайсах. Є дві групи слайсів функцій і одна група службових.

api/src/slices/
  setup/          спільна інфраструктура, без бізнес-правил
    prisma/       підключення до бази даних
    error/        єдиний формат будь-якої помилки
    response/     кожна успішна відповідь — { data, success: true }
    crypto/       шифрує збережені секрети підключень
    core/         позначка для маршрутів, яким вхід не потрібен
    health/       перевірка стану
  user/           хто діє — тека-простір імен без власного коду
    user/         людина
    auth/         вхід, сесії та перевірка на кожному маршруті
    team/         команда, якій належать магазини
    userTeam/     членство й ролі
  store/
    store/        підключений магазин і клієнт, що говорить з його модулем

Слайс функції щоразу має ту саму форму. Для прикладу — слайс магазину:

store/store/
  store.module.ts         пов'язує кожен контракт із його реалізацією
  store.controller.ts     подання: маршрути, ввід, вивід
  store.prisma            таблиці цього слайса
  dtos/                   подання: форми запитів і відповідей
  domain/                 правила й контракти
    store.service.ts        хто може підключати, які адреси прийнятні
    store.gateway.ts        контракт: збереження й читання магазинів
    bridge.gateway.ts       контракт: розмова з модулем магазину
    store.types.ts
    errors/                 по файлу на кожну помилку
  data/                   реалізації
    store.gateway.ts        PostgreSQL через Prisma
    store.mapper.ts         рядки бази в доменні типи
    bridge.gateway.ts       відповіді модуля в доменні результати
    repositories/bridge/    HTTP-клієнт Bridge Protocol v1

До бази даних шлюз звертається напряму через Prisma; окремого класу-репозиторію для неї немає. Із зовнішнім сервісом інакше: модуль магазину загорнуто в репозиторій із власними типами, щоб формат протоколу не потрапляв у правила.

Один запит, шар за шаром

Власник підтверджує підключення магазину. Ось що відбувається з цим запитом.

Перевірка входу. До будь-якого слайса перевірка, зареєстрована для всіх маршрутів, встановлює, хто звертається і що його сесія ще жива.
Контролер. Приймає запит, перевіряє його форму й передає сервісу. Правил у ньому немає.
Сервіс — правила. Той, хто звертається, має бути власником або адміном команди. Магазин має бути доступний через HTTPS; звичайний HTTP приймається лише для локальної адреси в розробці й тестах. Адреса, на яку повернеться власник, має належати тому самому магазину, що підключається.
Контракт мосту. Сервіс просить: «створи пару з цим магазином». Шар даних підписує запит і надсилає його. Відповідь без дійсного підпису вважається «магазин недосяжний», навіть якщо магазин повернув статус успіху.
Контракт магазину. Сервіс просить: «збережи цей магазин». Шар даних шифрує секрет і записує рядок. Попереднє підключення того самого магазину позначається як відключене.
Контролер. Повертає магазин і адресу, на яку треба відправити власника назад.

Сервіс не імпортує ні клієнт бази даних, ні HTTP-клієнт. Він знає два контракти й нічого про те, як вони виконуються.

Правила для кожного слайса

Теки слайсів — в однині; маршрути — у множині.
Контракт — абстрактний клас у domain/. Реалізація лежить у data/, а модуль слайса пов'язує одне з іншим.
Слайс використовує інший слайс через його домен. Слайс магазину питає сервіс членства, чи дозволена роль того, хто звертається; у чужий шар даних він не заглядає.
Кожен маршрут має ім'я операції. З нього беруться назви методів згенерованого клієнта в застосунку.
Кожен маршрут вимагає входу, якщо його явно не позначено як відкритий.
Кожен слайс володіє схемою своїх таблиць. Скрипт збирає їх в одну схему перед запуском інструментів бази даних.
Імпорти між слайсами йдуть через короткі псевдоніми — #setup/…, #user/…, #store/…, — а не через довгі відносні шляхи.

Місця, де цей API свідомо відходить від CleanSlice, перелічено в огляді.

Як це перевіряється

Наскрізні сценарії виконуються на справжньому PostgreSQL у Docker, а не на заглушках. Сценаріям магазинів потрібні ще й два запущені локальні тестові магазини. Останні записані результати — у плані репозиторію, від 29 вересня 2026 року. Для цієї сторінки їх заново не запускали.

Ще не зроблено

Інструменти для агентів і будь-який зв'язок з Agentfy.
Читання каталогу магазину.
Пропозиції цін, схвалення, завдання та журнал операцій, описані в плані реалізації.
Підтвердження email і скидання пароля.
Обмеження кількості спроб входу й реєстрації.
Ротація ключа, яким підписуються запити підключення.
Будь-що для операторів платформи. Кожна людина має поле платформної ролі, але його ніщо не видає і ніщо не перевіряє. Див. Адмін-панель.
Розгортання. Хостинг не обрано.

Протокол модуля ↔ API: REST 1.0

API ​

Що він робить сьогодні ​

Як влаштовано код ​

Один запит, шар за шаром ​

Правила для кожного слайса ​

Як це перевіряється ​

Ще не зроблено ​