# AIDB Children Structure Canon

## Статус

Статус: active children structure canon.

Дата: 2026-05-20.

Этот документ фиксирует каноническую структуру `children/` в проекте AIDB.

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

`children/` хранит реальную клиентскую и бизнесовую инстанс-структуру.

То есть:

- созданные сущности;
- установленные сущности;
- клиентский файловый инвентарь;
- client-owned storefront pages;
- documents;
- uploads;
- локальный runtime state;
- локальные каталоги;
- локальные operational files.

`children/` не хранит системные шаблоны и не хранит системный код.

Для этого существует `system/`.

## 2. Каноническая верхняя структура

```text
children/
  business-centers/
    <business_center_id>/
```

Всё начинается с `business_center`.

Любой клиент получает `business_center` как корневую рабочую сущность, поэтому папка `business_center` создается всегда.

## 3. Базовая структура business-center

```text
children/
  business-centers/
    <business_center_id>/
      manifest.json
      settings.json
      card/
      storefront/
      staff/
      catalogs/
      uploads/
      runtime/
      levels/
```

`business_center` получает папку всегда.

Это обязательное правило.

## 4. Базовая структура business-level

```text
children/
  business-centers/
    <business_center_id>/
      levels/
        <business_level_id>/
          manifest.json
          settings.json
          card/
          storefront/
          staff/
          catalogs/
          uploads/
          runtime/
          digital-spaces/
          contours/
          applications/
```

`business_level` получает папку всегда.

Это обязательное правило, потому что это реальная структурная сущность клиента.

## 5. Базовая структура digital-space

```text
children/
  business-centers/
    <business_center_id>/
      levels/
        <business_level_id>/
          digital-spaces/
            <digital_space_id>/
              manifest.json
              settings.json
              card/
              staff/
              uploads/
              runtime/
```

`digital_space` получает папку всегда.

Даже если она легче по наполнению, это отдельная реальная организационная сущность.

## 6. Installed business contour

Установленный `business_contour` не обязан получать папку автоматически только по факту установки.

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

- документы;
- каталоги;
- uploads;
- storefront pages;
- локальные operational files;
- локальный runtime state.

Рекомендуемая структура:

```text
children/
  business-centers/
    <business_center_id>/
      levels/
        <business_level_id>/
          contours/
            <business_contour_instance_id>/
              manifest.json
              settings.json
              card/
              documents/
              catalogs/
              uploads/
              storefront/
              runtime/
```

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

## 7. Installed application

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

Папка создается, если приложению нужны:

- uploads;
- локальные файлы;
- локальный runtime state;
- локальные exports/imports;
- другие отдельные client-owned operational files.

Рекомендуемая структура:

```text
children/
  business-centers/
    <business_center_id>/
      levels/
        <business_level_id>/
          applications/
            <app_instance_id>/
              manifest.json
              settings.json
              uploads/
              runtime/
```

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

## 8. Storefront pages

Публичные страницы живут внутри владельца.

Это жёсткое правило.

Нельзя хранить storefront pages в общей оторванной папке без принадлежности к сущности.

Storefront конкретной сущности живет:

- у `business_center`;
- у `business_level`;
- у `business_contour`, если ему разрешена своя публичная поверхность.

Пример:

```text
children/
  business-centers/
    <business_center_id>/
      storefront/
        main/
        catalog/
        landing/
```

## 9. Uploads

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

Uploads не смешиваются:

- с documents;
- с catalogs;
- с storefront pages;
- с runtime state.

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

## 10. Runtime inside children

`children runtime` - это локальный runtime state конкретного владельца.

Он отличается от `system runtime`.

В `children runtime` живет:

- локальное состояние конкретной сущности;
- локальные processing results;
- локальные runtime files;
- локальные очереди и кэш, если они относятся именно к владельцу.

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

## 11. Card storage inside children

Карточка конкретной созданной или установленной сущности может иметь свою файловую зону внутри владельца.

Но карточка не должна превращаться в склад файлов.

Карточка остается паспортом, а тяжелые материалы уходят в:

- documents;
- uploads;
- storefront;
- runtime.

## 12. Commercial proposals inside children

Коммерческие предложения могут иметь локальные файлы и вложения.

Структурная часть предложения живет в базе.

Файловая часть предложения живет у владельца:

- в `uploads/`;
- в `documents/`;
- или в другой разрешенной локальной подзоне.

Не создавать общую глобальную файловую свалку предложений.

## 13. Что всегда получает папку

Всегда получают папку:

- `business_center`
- `business_level`
- `digital_space`

Это базовые структурные сущности клиента.

## 14. Что получает папку по условию

Папку по условию получают:

- installed `business_contour`
- installed `app`

Условие:

у сущности должен появиться свой локальный инвентарь.

## 15. Правило создания папки

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

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

Если этого нет, достаточно записи в базе.

## 16. Что нельзя класть в children

В `children/` нельзя класть:

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

Все это живет в `system/`.

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

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

- всех документов;
- всех картинок;
- всех uploads;
- всех runtime files;
- всех storefront pages.

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

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

Это обязательное правило масштабирования.

## 18. Быстрорастущие файловые зоны

Файлы, которые могут быстро расти, должны быть отделены заранее.

К таким зонам относятся:

- uploads;
- documents;
- catalog media;
- storefront assets;
- runtime temp files;
- exports;
- imports;
- вложения заказов;
- вложения коммерческих предложений.

Их нельзя смешивать в одну общую папку сущности.

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

Это делается заранее, а не после роста проекта.

## 19. Критерий готовности

Children structure считается зафиксированной, если:

- структурные сущности клиента получают свои обязательные папки;
- installed contours и installed apps создают папки только при локальном инвентаре;
- storefront pages живут у владельца;
- uploads отделены;
- runtime отделен;
- `children/` не превращается в замену `system/`.