# AIDB Foundation Canon

## Статус

Статус: approved foundation canon for new project start.

Дата: 2026-05-20.

Этот документ является стартовым архитектурным каноном проекта `AIDB`.
Он описывает новый проект как самостоятельную систему, без ссылок на старые проекты, старые домены, старые термины и старую историю.

## 1. Проект

`AIDB` - это бизнес-платформа.

Новый проект создается как самостоятельная система по пути:

`/home/elmar/aidb`

Основной домен проекта:

`aidb.center`

Минимальный корень проекта:

- `system/`
- `docs/`
- `children/`

## 2. Главная иерархия

Главная иерархия AIDB:

`Бизнес-платформа -> Бизнес-центр -> Бизнес-уровень -> Цифровое пространство -> Бизнес-контур -> Приложение`

Смысл уровней:

- `Бизнес-платформа` - верхний системный уровень;
- `Бизнес-центр` - корневой рабочий контур клиента;
- `Бизнес-уровень` - крупный рабочий слой внутри бизнес-центра;
- `Цифровое пространство` - внутренняя зона порядка, видимости и доступа;
- `Бизнес-контур` - готовая рабочая бизнес-система;
- `Приложение` - инструмент.

Клиент не видит верхний технический уровень платформы как свою основную рабочую точку.
Клиент начинает работу с `Бизнес-центра`.

## 3. Утвержденные термины

Публичные и технические термины:

| Публичный термин | Технический термин |
| --- | --- |
| Бизнес-платформа | `platform` |
| Бизнес-центр | `business_center` |
| Бизнес-уровень | `business_level` |
| Цифровое пространство | `digital_space` |
| Бизнес-контур | `business_contour` |
| Приложение | `app` |
| AppMarket | `appmarket` |
| Текущий контур | `current_contour` |

Во внешней и внутренней owner-facing архитектуре не использовать другие публичные названия для этих сущностей.

## 4. Бизнес-платформа

`Бизнес-платформа` - верхний системный уровень AIDB.

Она отвечает за:

- регистрацию;
- trial;
- подписки;
- тарифы;
- лимиты;
- управление бизнес-центрами;
- глобальные настройки;
- системные правила;
- AppMarket;
- жизненный цикл платных сущностей;
- разрешения на расширенные коммерческие режимы.

Бизнес-платформа управляет средой, но не управляет торговым содержимым клиентов.

Она не должна решать:

- что именно продает клиент;
- кто именно продает;
- какие товары и услуги публикуются;
- какие предложения принимаются;
- какую цену ставит клиент;
- как конкретный бизнес-центр строит свою коммерческую стратегию.

Эти решения принадлежат владельцу бизнес-центра.

Бизнес-платформа управляет тем, доступен ли конкретному бизнес-центру режим расширенной торговой сети.

Публичное имя такого режима:

`Централизованный прием предложений`

Технический флаг централизованного маршрута предложений:

`central_offer_intake_enabled`

Если разрешение включено, бизнес-центр может:

- принимать офферы от внешних поставщиков;
- принимать офферы от нижних внутренних контуров;
- обрабатывать предложения;
- публиковать товары и услуги на общей внешней витрине.

Если разрешение выключено, бизнес-центр работает без общей схемы supplier/offer aggregation.

## 5. Бизнес-центр

`Бизнес-центр` - корневой рабочий контур клиента.

Любая регистрация клиента создает `Бизнес-центр`.

Даже если клиент хочет начать только с одного `Бизнес-контура`, система все равно создает:

`Бизнес-центр -> Бизнес-контур`

Причина:

- клиент может вырасти;
- можно добавить бизнес-уровни;
- можно добавить новые бизнес-контуры;
- не нужна болезненная миграция структуры.

Бизнес-центр:

- может быть trial;
- может быть платным;
- может иметь тариф;
- может иметь карточку;
- может иметь сайт, поддомен и внешний домен;
- может иметь собственную внешнюю витрину;
- может быть главным владельцем общей коммерческой витрины.

Бизнес-центр может существовать в двух режимах:

- обычный;
- с централизованным приемом предложений.

Если `central_offer_intake_enabled = true`, все разрешенные источники предложений отправляют свои коммерческие предложения в бизнес-центр.

Если `central_offer_intake_enabled = false`, локальные контуры и участники работают по обычной модели без централизованного приема предложений.

По умолчанию именно `Бизнес-центр` считается правильным уровнем для общей витрины, если требуется:

- единый коммерческий владелец;
- прием офферов из нескольких источников;
- централизованная публикация товаров и услуг наружу.

## 6. Бизнес-уровень

`Бизнес-уровень` - крупный рабочий слой внутри бизнес-центра.

Он может означать:

- бренд;
- направление;
- страну;
- сеть;
- группу бизнесов;
- крупный самостоятельный слой бизнеса.

Бизнес-уровень:

- может быть trial;
- может быть платным;
- может иметь тариф;
- может иметь карточку;
- может иметь сайт, поддомен и внешний домен;
- может содержать цифровые пространства;
- может содержать бизнес-контуры;
- может содержать приложения;
- может иметь собственную личную витрину.

`Бизнес-уровень` может работать как самостоятельная компания с собственной витриной и продажами.

Но по умолчанию `Бизнес-уровень` не считается агрегатором офферов от других контуров и не является центром общей многоисточниковой витрины.

Если клиенту нужна расширенная модель:

- прием офферов;
- единая внешняя витрина;
- нижние внутренние источники предложений;
- внешние поставщики;

то используется `Бизнес-центр`.

## 7. Цифровое пространство

`Цифровое пространство` - внутренний организационный уровень.

Это не отдельный бизнес и не арендуемая автономная сущность.

Оно нужно для:

- группировки;
- видимости;
- прав доступа;
- отделов;
- регионов;
- направлений;
- назначения руководителя;
- назначения сотрудников.

Цифровое пространство:

- бесплатное;
- не тарифицируется отдельно;
- не автономное;
- не имеет собственного сайта;
- не является отдельной бизнес-единицей;
- создается свободно;
- нужно для RBAC и порядка.

В цифровое пространство можно устанавливать:

- приложения;
- бизнес-контуры.

## 8. Бизнес-контур

`Бизнес-контур` - полноценная рабочая бизнес-система.

Он может быть:

- внутренним;
- автономным.

Бизнес-контур может иметь:

- сотрудников;
- роли;
- права;
- документы;
- операции;
- кассу, если это предусмотрено его доменной моделью;
- trial;
- тариф;
- lifecycle;
- карточку;
- сайт, поддомен и внешний домен.

Бизнес-контур может быть установлен:

- в бизнес-центр;
- в бизнес-уровень;
- в цифровое пространство.

В одном бизнес-уровне может быть много одинаковых бизнес-контуров.

Конкретные имена реальных контуров в этом документе не фиксируются.

## 9. Приложение

`Приложение` - это инструмент, а не бизнес.

Приложение:

- не автономно как отдельный бизнес;
- не имеет собственного владельца как бизнес-единица;
- не имеет собственного сайта;
- не выбирается как стартовая регистрационная сущность клиента.

Приложение может иметь:

- карточку;
- права;
- тариф;
- trial;
- подписку;
- внутреннюю или публичную презентационную карточку.

Приложения можно устанавливать в:

- бизнес-центр;
- бизнес-уровень;
- цифровое пространство.

Приложения не устанавливаются внутрь бизнес-контура.

## 10. AppMarket

`AppMarket` - это внутренний market расширений AIDB.

Он используется только пользователями системы AIDB внутри платформы.

AppMarket не является внешней клиентской витриной товаров и услуг.

AppMarket предназначен для:

- выбора приложений;
- выбора бизнес-контуров;
- установки приложений;
- установки бизнес-контуров;
- управления доступными расширениями.

AppMarket не определяет самостоятельно, что платно, что доступно по trial и что доступно по подписке.

Цена, тариф, trial и подписка определяются политикой бизнес-платформы.

В AppMarket есть два типа устанавливаемых сущностей:

1. `Приложения`
2. `Бизнес-контуры`

AppMarket - это внутренний рынок системных расширений.

## 11. Единый канон карточки

Каждая сущность имеет свою карточку.

Карточка - это паспорт сущности:

- кто это;
- зачем это;
- что это делает;
- какие функции дает;
- какую проблему решает;
- что должен понимать пользователь;
- что должен понимать разработчик.

По умолчанию карточка внутренняя.

Карточка может быть у:

- бизнес-центра;
- бизнес-уровня;
- цифрового пространства;
- бизнес-контура;
- приложения;
- товара;
- услуги;
- другой самостоятельной сущности.

Для разных сущностей не создаются разные базовые каноны карточки.

Действует единый канон карточки для всех сущностей.

## 12. Публичные страницы и витрина

Публичные страницы, сайт, поддомен и внешний домен могут иметь:

- бизнес-центр;
- бизнес-уровень;
- бизнес-контур.

Цифровое пространство сайта не имеет.

Приложение сайта не имеет, только карточку.

У бизнес-сущности может быть несколько публичных страниц:

- сайт-визитка;
- витрина;
- каталог;
- интерактивная страница;
- конфигуратор;
- другие публичные страницы.

Публичная витрина и публичные страницы конкретной сущности являются частью инвентаря этой сущности.

Они не должны храниться как оторванная общая поверхность без принадлежности к владельцу.

## 13. Главный принцип витрины

`AppMarket` и `Витрина` - это не одно и то же.

`AppMarket`:

- внутренний;
- системный;
- используется для установки приложений и бизнес-контуров.

`Витрина`:

- внешняя;
- клиентская;
- используется для публикации товаров и услуг.

Общая многоисточниковая внешняя витрина по умолчанию относится к `Бизнес-центру`.

`Бизнес-уровень` может иметь личную витрину собственной компании, но по умолчанию не является центром общей схемы офферов.

## 14. Регистрация клиента

Клиент при регистрации может выбрать:

- Бизнес-центр;
- Бизнес-уровень;
- Бизнес-контур.

Клиент не регистрирует приложение напрямую.

В любом варианте система создает `Бизнес-центр` как корневой контур клиента.

Если клиент регистрирует бизнес-контур:

`Бизнес-центр -> Бизнес-контур`

Если клиент регистрирует бизнес-уровень:

`Бизнес-центр -> Бизнес-уровень`

Цифровое пространство при регистрации не обязательно.

## 15. Тарифы и ограничения

Платформа управляет тарифами, лимитами и жизненным циклом платных сущностей.

Платными или trial могут быть:

- бизнес-центр;
- бизнес-уровень;
- бизнес-контур;
- приложение.

Цифровое пространство:

- бесплатное;
- не тарифицируется;
- создается свободно.

Лимиты задаются тарифом бизнес-платформы и могут меняться без изменения архитектуры.

Тариф может ограничивать:

- количество бизнес-уровней;
- количество бизнес-контуров;
- количество сотрудников;
- доступные приложения;
- trial-период;
- доступность функций;
- оплату;
- режим `Только просмотр`;
- доступность расширенной схемы торговой сети.

## 16. Lifecycle

Для платных сущностей действует lifecycle:

`Активно -> Только просмотр -> Помечено системой на удаление -> Окончательное удаление администратором`

Основной публичный термин удаления:

`Помечено на удаление`

Другие публичные owner-facing слова для этого канона не использовать.

## 17. Права и доступ

Owner-facing права:

- `Просмотр`
- `Работа`
- `Управление`

Технический scope:

`current_contour`

Это техническое имя места, где пользователь сейчас работает.

Публично в интерфейсе показываются реальные названия контуров:

- бизнес-центр;
- бизнес-уровень;
- цифровое пространство;
- бизнес-контур.

## 18. Пользователи и внешние участники

Кроме внутренних сотрудников, в системе должны быть:

- клиенты;
- поставщики;
- представители;
- комиссионные участники.

У каждого должен быть свой личный кабинет в пределах его роли и разрешений.

Клиент:

- видит свою историю;
- видит заказы;
- видит документы;
- видит статусы;
- видит доступные действия.

Поставщик:

- видит свою историю;
- может делать предложения;
- может передавать товары и услуги в поток рассмотрения.

Представитель или комиссионный участник:

- может быть связан с клиентом;
- может быть связан с поставщиком;
- может иметь свой кабинет;
- может иметь отдельную финансовую и комиссионную логику.

## 19. Личные кабинеты

Личные кабинеты реализуются как один системный модуль:

`system/applications/personal-cabinet/`

Внутри этого модуля существуют разные ролевые поверхности:

- кабинет клиента;
- кабинет поставщика;
- кабинет представителя или комиссионного участника.

Это единый системный модуль личных кабинетов, а не три независимых приложения.

## 20. Коммерческое предложение

Любая карточка может использоваться как обычная внутренняя карточка.

При отдельном действии пользователя карточка может быть отправлена как:

`Коммерческое предложение`

Коммерческое предложение - это режим использования карточки, а не обязательная отдельная новая сущность по умолчанию.

Это позволяет использовать один и тот же канон карточки для:

- поставщика;
- внутреннего бизнес-контура;
- товара;
- услуги;
- другой сущности, которую разрешено предложить вверх.

## 21. Источники коммерческого предложения

Источником коммерческого предложения могут быть:

- внешний поставщик;
- внутренний бизнес-контур;
- производитель;
- другой разрешенный участник.

У всех источников действует одинаковая базовая логика:

- создать или использовать свою карточку;
- заполнить карточку;
- отправить ее как коммерческое предложение;
- передать в целевой коммерческий контур.

## 22. Поток коммерческого предложения

Базовый поток:

1. источник создает карточку или использует существующую;
2. источник заполняет карточку;
3. по действию `Сделать коммерческим предложением` карточка отправляется вверх;
4. целевой коммерческий контур получает предложение;
5. рассматривает его;
6. принимает, отклоняет или отправляет на уточнение;
7. если принимает, создает свой вид карточки для публикации на своей витрине.

Материнская карточка источника остается той же самой.

Это важно, потому что реальные заказы и поставки должны оставаться связаны с исходным источником.

## 23. Цена предложения и цена витрины

На стадии предложения не использовать термин `публичная цена` для исходной цены источника.

Нужно разделять:

- `базовая цена предложения`;
- `цена после рассмотрения`;
- `публичная цена витрины`.

Источник сначала передает `базовую цену предложения`.

Только после решения владельца витрины формируется `публичная цена витрины`.

## 24. Intercompany

В архитектуре AIDB должна существовать логика intercompany.

Бизнес-контуры могут быть:

- поставщиками;
- клиентами;
- внутренними исполнителями;
- внешними участниками.

Один бизнес-контур может предлагать товары или услуги:

- бизнес-центру;
- бизнес-уровню;
- другому бизнес-контру;
- в разрешенные цепочки отношений.

Intercompany-модель должна учитывать:

- связи между контурами;
- supplier offers;
- client offers;
- историю отношений;
- внутренние цены;
- внешние цены;
- комиссии.

## 25. Корень проекта

Минимальный корень проекта:

```text
/home/elmar/aidb/
  system/
  docs/
  children/
```

На старте не создавать лишние корневые папки без необходимости.

## 26. System

`system/` - это зона системного кода и системных правил.

Внутри должны быть архитектурные зоны для:

- shell;
- gate;
- appmarket;
- applications;
- business contour packages;
- backend;
- database;
- runtime;
- languages;
- themes;
- shared;
- storefront templates.

`Shell` не считать просто frontend-папкой.

`Shell` - это системный каркас всей платформы.

`Shell` и `Gate` являются отдельными системными пакетами:

- `system/shell/`
- `system/gate/`

У каждого свой пакет файлов:

- `interface.html`
- `logic.js`
- `manifest.json`
- `settings.json`
- `texts.json`
- `README.md`
- `developer.md`
- `contracts/`

`Gate` отвечает за вход в систему.

`Shell` отвечает за работу внутри системы.

`Shell` не хранит бизнес-данные клиентов и не заменяет приложения, бизнес-контуры или личные кабинеты.

## 27. Children

`children/` - это зона данных и инвентаря сущностей, созданных внутри конкретного бизнеса.

Туда относятся:

- бизнес-центры;
- бизнес-уровни;
- цифровые пространства;
- установленные бизнес-контуры;
- публичные страницы;
- документы;
- настройки;
- сотрудники;
- каталоги;
- commercial proposals;
- локальный runtime state;
- uploads;
- другие файлы, принадлежащие конкретной сущности.

## 28. Правило папки в children

Папка в `children/` создается, если сущность имеет:

- собственные файлы;
- собственные публичные страницы;
- собственные документы;
- собственные каталоги;
- собственный runtime state;
- собственные uploads;
- собственный локальный инвентарь.

Если установка означает только запись в базе и включение видимости, отдельная папка может не создаваться.

## 29. Database

База данных в AIDB одна.

Не создавать отдельную базу данных под каждый модуль.

Архитектура должна отдельно определить:

- database config;
- migrations;
- schema/models;
- seed/demo data;
- границу между данными в базе и файлами в children;
- границу между данными в базе и runtime state.

## 30. Правило разделения хранения

Разделение хранения должно быть заложено заранее.

Нельзя смешивать в одном слое:

- структурную правду;
- постоянный файловый инвентарь;
- uploads;
- временный runtime state.

### 30.1. Что хранится в базе

В базе хранится структурная правда:

- пользователи;
- роли;
- права;
- связи;
- бизнес-центры;
- бизнес-уровни;
- цифровые пространства;
- установленные бизнес-контуры;
- установленные приложения;
- карточки как структурные сущности;
- коммерческие предложения как структурные сущности;
- заказы;
- статусы;
- история;
- intercompany-связи;
- подписки;
- тарифы.

База не должна быть основным местом хранения тяжелых файлов.

### 30.2. Что хранится в children

`children/` хранит постоянный инвентарь конкретного владельца:

- документы;
- каталоги;
- публичные страницы;
- storefront assets;
- локальные operational files;
- exports;
- imports;
- другие постоянные файлы сущности.

`children/` - это файловый слой конкретного клиента и его сущностей.

### 30.3. Что хранится в uploads

`uploads/` должны быть отдельной подзоной внутри владельца или сущности.

Uploads не должны смешиваться:

- с документами;
- с каталогами;
- с runtime state.

Uploads обычно растут быстрее всего и должны быть архитектурно отделены заранее.

### 30.4. Что хранится в runtime

Временное и живое runtime-состояние должно быть отделено от постоянного инвентаря.

Отдельно должны существовать:

- временные runtime-файлы;
- фоновые результаты;
- очереди;
- кэш;
- служебные runtime-артефакты.

Временный runtime не должен храниться вместе с постоянными документами и каталогами.

### 30.5. Правило карточки

Карточка должна оставаться паспортом сущности.

Карточка не должна превращаться в склад:

- медиа;
- больших документов;
- технических логов;
- объемных вложений;
- временных файлов.

Карточка может ссылаться на эти материалы, но не должна заменять отдельные слои хранения.

### 30.6. Правило масштабирования

Рост данных должен идти по владельцу и по сущности.

Нельзя делать общие свалки:

- всех документов в одной папке;
- всех картинок в одной папке;
- всех предложений в одной папке;
- всех runtime-файлов в одной папке.

Разбиение должно идти сверху вниз:

- business_center;
- business_level;
- digital_space;
- installed_business_contour;
- installed_app.

## 31. Backend и API

Backend живет в `system/backend/`.

API должно быть модульным с первого дня.

Не строить один большой общий route-файл.

Сразу предусматривать отдельные API зоны для:

- shell;
- gate;
- appmarket;
- applications;
- business contours;
- employees and RBAC;
- storefront and public pages;
- personal cabinet;
- commercial proposals;
- intercompany.

## 32. Runtime

Runtime должен быть разделен по смысловым зонам.

Нужно отдельно учитывать:

- runtime contracts;
- live runtime state;
- workers;
- scheduled jobs;
- upload/download handlers;
- границу между system runtime и children runtime.

## 33. Languages

Языки централизованы.

Предварительная структура:

```text
system/languages/
  en/
  ru/
  az/
  zh/
  ar/
```

Правила:

- `English` - основной интерфейсный язык;
- `English` - fallback;
- `Russian` - смысловой рабочий язык owner/team, но не fallback.

## 34. Главная формула

AIDB - это бизнес-платформа, где клиент получает бизнес-центр, может начать с одного бизнес-контура, может вырасти до бизнес-уровней, может создавать цифровые пространства для порядка, может устанавливать бизнес-контуры и приложения через AppMarket, а все тарифы, права, lifecycle, публикации и разрешения на расширенную торговую модель контролируются платформой.