Agentfy для платформ: организации, владельцы и плательщики
Проект спецификации · AGNT2-424
Это только документация. Организации, партнёрский API, связи аккаунтов и назначения плательщика ниже ещё не реализованы. Документ заменяет предложение AGNT2-423. Подтверждённые решения пользователя отделены от технических рекомендаций; перед выпуском нужны проверки реализации.
При прямой регистрации человек получает команду в организации Agentfy и становится её владельцем и первоначальным ответственным за оплату. BONSITE может подготовить команду клиента по стабильным внешним идентификаторам ещё до его первого посещения. По умолчанию платит BONSITE; оплата организацией и оплата командой обязательны уже в v1. Смена владельца или плательщика не меняет организацию команды.
Соглашение об именовании (утверждено)
Organization — название сущности, organizationId — её поле в модели. Канонический сегмент ресурса API — orgs: /v1/orgs/{orgId}, где orgId — параметр пути этой организации. «Партнёр» обозначает бизнес-роль или интеграцию (например, BONSITE как реселлер), а не отдельное пространство endpoints организации. Издатель идентичностей, внешний субъект и аутентификация через партнёра остаются отдельными техническими понятиями.
Подтверждённые продуктовые решения
- Agentfy — организация по умолчанию, а не признак администратора всей платформы. Её самостоятельно зарегистрированные приватные команды изолированы друг от друга.
- BONSITE управляет входом в свой продукт и серверными ключами. Email, имя и пароль передавать необязательно. Идентификаторы пользователя и команды различаются: у человека несколько команд, в команде несколько людей.
- При прямой регистрации создатель становится владельцем. При серверном создании
createdByфиксирует сервис-инициатор, а владельцем становится указанный внешний пользователь, никогда ключ. Передача личной ответственности за оплату требует согласия нового плательщика. - Администратор может разрешить покрытие расходов организацией. Покрытие Agentfy — внутреннее спонсирование, а не счёт самому себе.
- Участник клиентской команды не становится участником организации. Участники организации — операторы партнёра; ключи — сервисные субъекты, не фиктивные люди.
- Пользователь может оставаться в BONSITE, открыть интерфейс Agentfy или подключить независимо подтверждённый прямой аккаунт. Совпадение email не доказывает тождество.
Рекомендуемая архитектура
Сохраняем стабильных субъектов прав и явные связи. Прямой User и партнёрский User — разные записи. ExternalIdentity(namespace, externalUserId) указывает на партнёрского субъекта; AccountLink разрешает независимо вошедшему прямому аккаунту явно выбрать его контекст. Связь не переписывает членство, владельцев агентов, счета или историю.
Глобальное объединение пользователей уменьшило бы число записей, но превратило бы существующие запросы userId → teams в возможный обход прав. Безопасное объединение потребовало бы происхождения каждого разрешения и широкой переделки авторизации. Раздельные субъекты сохраняют смысл текущих ключей владения и позволяют отменить связь без переноса данных. Это выбранная рекомендация, не готовая схема БД.
Organization Agentfy ─ прямая команда ─ UserTeam(owner: прямой User D)
Organization BONSITE ─ команда партнёра ─ UserTeam(owner: внешний User P)
неизменяемый namespace + externalUserId ─ ExternalIdentity ─ P
D ─ AccountLink ─ P (владение не меняется)
Team ─ PayerAssignment по периодам ─ BillingAccount| Понятие | Значение и инвариант |
|---|---|
| Organization | Область администрирования и интеграции; у команды ровно одна. В v1 нет переноса команд между организациями и вложенных реселлеров. |
| Namespace | Неизменяемая область организации и окружения. Test/prod разделяют ключи, пользователей, redirect URI и ресурсы; переименование BONSITE её не меняет. |
| User | Стабильный субъект авторизации/владения. Прямой имеет независимые способы входа; партнёрский принадлежит одному namespace и может не иметь email. |
| Способ входа | Доказательство для прямого аккаунта или внешнего субъекта, не членство и не плательщик. Ключ партнёра не восстанавливает прямые credentials. |
| ExternalIdentity | Постоянная уникальная пара namespace + непрозрачный subject, включая запись об удалении; внешний ID не переиспользуется. |
| AccountLink | Одна активная связь внешнего субъекта с прямым аккаунтом; у прямого аккаунта связей может быть несколько. Нет транзитивного обхода, сопоставления email или объединения прав. |
| UserTeam | Уникальное членство субъект + команда, роль owner/admin/member. Владельцев может быть несколько; дублирующее Team.ownerUserId не вводим. |
| OrganizationMember | Отдельно назначаемая роль оператора; не следует из участия в клиентской команде. |
| BillingAccount | Ответственный прямой пользователь либо организация. Контакт для счетов — только адрес уведомлений. |
| PayerAssignment | Ровно одно действующее назначение на команду, непересекающиеся полуоткрытые интервалы и неизменяемая история. Бесплатный тариф не требует платёжного мандата. |
| Метка клиента | Необязательный externalCustomerId для отчётов; не даёт прав и не определяет долг. |
| Visitor | Гость embed-чата, не участник команды. Текущий запуск от владельца — отдельная граница продукта. |
Внутренние и внешние ID неизменяемы. Внешний ID команды уникален в namespace независимо от ID пользователя; внешний ID агента — внутри команды. Привязки сохраняются после истечения квитанции операции; удалённые ID остаются занятыми. Владение агентом не создаёт приватное пространство внутри общей команды.
Доступ и доверие
Партнёрская сессия действует только от своего внешнего субъекта, в своём namespace и при активном членстве. Связь не открывает прямые/личные команды, другие организации, список связей, credentials, личные способы оплаты или роль платформы. Прямой вход может явно выбрать связанный контекст только при активных связи, субъекте, политике организации и членстве. Аудит фиксирует фактический аккаунт аутентификации, действующего субъекта, источник, организацию, команду и ID делегирования/ключа.
BONSITE доверено подтверждение своих пользователей. Издатель, способный утверждать любой subject BONSITE, может действовать как этот пользователь и читать доступное ему содержимое. Разделение scope ограничивает обычный provisioning/billing ключ, но не скрывает содержимое от злонамеренного издателя идентичностей или оператора с правом выдавать такие ключи. Защита даже от BONSITE потребовала бы независимого пользовательского доказательства и не входит в v1. Обязательная граница даже для такого издателя — недоступность прямого аккаунта и других namespace.
| Роль/субъект | Явно разрешено | Не следует из роли |
|---|---|---|
| Владелец организации | Активация/закрытие, роли операторов, договор; отдельно подтверждаемое управление издателем идентичностей | Роль платформы, доступ к прямым аккаунтам |
| Администратор организации | Жизненный цикл команд и согласованные назначения; покрытие только с финансовым делегированием | Чаты/секреты, выдача browser-сессий обычным admin-ключом |
| Разработчик организации | Provisioning, диагностика операций, профили агентов в запросе | Финансовое согласие, повышение ролей, выдача входа provisioning-ключом |
| Billing организации | Счета, итоги, согласие организации на оплату, контакты | Чаты, секреты, членство |
| Support организации | Обезличенная диагностика; содержимое только по явному временному делегированию | Постоянная имперсонация |
| Владелец команды | Настройки, приглашения, передача владения, запрос смены плательщика, удаление | Роль организации, согласие за другого человека |
| Администратор команды | Участники в пределах политики, работа команды | Назначение/снятие владельцев, финансовое согласие, удаление команды |
| Участник команды | Разрешённые данные и действия агентов | Управление участниками или оплатой |
| Ответственный плательщик | Свой мандат, счета, принятие/прекращение будущей ответственности | Данные команды, владение; членство необязательно |
| Сервисный субъект | Точные scope и namespace, provisioning отдельно от выдачи идентичности | Человеческий владелец, прямой вход, платформа |
| Администратор платформы | Отдельно аутентифицированное вмешательство/восстановление с аудитом; причина и срок доступа support | Полномочия из organizationId=Agentfy |
Запрет по умолчанию действует в jobs, sockets, поиске, экспорте, хранилищах, подписанных ссылках и cache keys, не только в контроллере. Чужие ID дают нераскрывающий 404. Смена плательщика не даёт членства или данных; смена владельца даёт роль только целевой команды, не организации, платформы или других команд. В v1 клиентские команды партнёра принимают только внешних субъектов своего namespace; прямой клиент входит через AccountLink. Прямые приглашения применяются к командам Agentfy, операторы используют явное делегирование. Иначе внешний владелец мог бы пригласить свой прямой аккаунт и обойти последующее отключение в BONSITE.
Порядок чтения
- Идентичность и пользовательские сценарии: экраны, browser-протокол, связи и восстановление.
- Provisioning и оплата: предложенные запросы, повторы и финансовые переходы.
- Миграция и самопроверка: текущий код, атаки/гонки и условия выпуска.
Текущий биллинг и гостевое встраивание описывают реализованное поведение, не гарантии этого проекта.