AIDB Dev Center

Readable architecture document

AIDB Children Structure Canon

Каноническая структура children/ и правила хранения клиентского инвентаря.

activesource: AIDB_CHILDREN_STRUCTURE_CANON.md

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. Каноническая верхняя структура

children/
  business-centers/
    <business_center_id>/

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

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

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

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

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

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

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

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

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.

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

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.

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

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, если ему разрешена своя публичная поверхность.

Пример:

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/.