# AIDB Storefront and Publication Canon

## Статус

Статус: Stage 4 business flows canon draft.

Дата: 2026-05-20.

Этот документ фиксирует архитектуру внешней витрины, публикации карточек и потока коммерческих предложений в AIDB.

Документ не описывает реализацию кода.

## 1. Назначение

Этот canon закрывает:

- storefront/publication model;
- card publication model;
- commercial proposal flow;
- `central_offer_intake_enabled`;
- границу между внутренней карточкой, коммерческим предложением и публичным видом;
- границу между AppMarket и внешней витриной;
- границу между `system/` и `children/`.

## 2. Канонические термины

| Публичный смысл | Технический смысл |
| --- | --- |
| Витрина | `storefront` |
| Публичный вид | `publication_view` |
| Внутренняя карточка | `internal_card` |
| Коммерческое предложение | `commercial_proposal` |
| Централизованный прием предложений | `central_offer_intake_enabled` |
| Базовая цена предложения | `proposal_base_price` |
| Цена после рассмотрения | `reviewed_price` |
| Публичная цена витрины | `storefront_public_price` |

`AppMarket` не является витриной.

`Storefront` не является AppMarket.

## 3. AppMarket and storefront boundary

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

`Storefront` - внешняя клиентская поверхность для публикации товаров, услуг, карточек и публичных страниц бизнес-сущностей.

В AppMarket публикуются:

- системные приложения;
- системные бизнес-контуры;
- install cards;
- trial/subscription availability;
- правила установки.

На внешней витрине публикуются:

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

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

- карточку приложения в AppMarket;
- карточку товара или услуги на внешней витрине;
- install flow;
- commercial order/request flow.

## 4. System and children boundary

`system/storefront/` хранит только системную сторону витрины:

- storefront engines;
- storefront contracts;
- storefront templates;
- publication helpers;
- rendering rules;
- системные assets шаблонов.

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

- опубликованные страницы;
- storefront assets;
- media;
- локальные catalog files;
- локальные documents;
- uploads;
- локальный runtime state владельца.

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

Они всегда принадлежат владельцу:

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

Если витрина принадлежит business-level:

```text
children/
  business-centers/
    <business_center_id>/
      levels/
        <business_level_id>/
          storefront/
```

Если бизнес-контур имеет разрешенную публичную поверхность и локальный инвентарь:

```text
children/
  business-centers/
    <business_center_id>/
      levels/
        <business_level_id>/
          contours/
            <business_contour_instance_id>/
              storefront/
```

## 5. Владельцы витрины

Витрину могут иметь:

- `business_center`;
- `business_level`;
- `business_contour`, если это разрешено его системным пакетом и политикой владельца.

Витрину не имеют:

- `digital_space`;
- `app`.

`business_center` - канонический владелец общей многоисточниковой витрины.

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

`business_level` по умолчанию не является агрегатором предложений от многих источников.

`business_contour` может иметь собственную публичную поверхность только если его доменная модель это требует и разрешает.

## 6. Card publication model

Внутренняя карточка - это паспорт сущности.

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

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

- business-center;
- business-level;
- digital-space;
- business-contour;
- app;
- товара;
- услуги;
- поставщика;
- другой разрешенной самостоятельной сущности.

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

Результат публикации - `publication_view`.

`publication_view`:

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

Публичный вид не должен заменять внутреннюю карточку.

Исходная карточка остается внутренним паспортом и точкой связи с владельцем, поставщиком, исполнителем или товаром.

## 7. Boundary: card, commercial proposal, publication view

| Слой | Что это | Кто владеет | Где используется |
| --- | --- | --- | --- |
| `internal_card` | паспорт сущности | владелец сущности | внутри платформы |
| `commercial_proposal` | режим отправки карточки на рассмотрение | источник предложения и целевой владелец | intake/review flow |
| `publication_view` | публичный вид после решения владельца витрины | владелец витрины | внешняя витрина |

Внутренняя карточка не становится автоматически предложением.

Коммерческое предложение не становится автоматически публичной страницей.

Публичный вид не становится новым владельцем товара, услуги или источника.

## 8. Commercial proposal flow

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

1. Источник создает карточку или использует существующую.
2. Источник заполняет карточку.
3. Источник выполняет действие `Сделать коммерческим предложением`.
4. Система создает `commercial_proposal`.
5. Предложение отправляется в разрешенный целевой коммерческий контур.
6. Целевой владелец рассматривает предложение.
7. Владелец принимает, отклоняет или отправляет предложение на уточнение.
8. Если предложение принято, владелец создает `publication_view`.
9. `publication_view` публикуется на витрине владельца.
10. Заказы, запросы и поставки остаются связаны с исходной карточкой и источником.

Рекомендуемые статусы предложения:

- `draft`;
- `submitted`;
- `under_review`;
- `clarification_requested`;
- `accepted`;
- `rejected`;
- `withdrawn`;
- `published`.

`published` означает, что на основе принятого предложения создан публичный вид.

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

## 9. `central_offer_intake_enabled`

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

Он включается на уровне `business_center`.

Если `central_offer_intake_enabled = true`, business-center может:

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

Если `central_offer_intake_enabled = false`:

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

`central_offer_intake_enabled` не дает источнику права публиковаться самостоятельно.

Он только открывает маршрут подачи предложения на рассмотрение.

## 10. Price model

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

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

- `proposal_base_price` - базовая цена, которую передал источник;
- `reviewed_price` - цена после рассмотрения владельцем витрины;
- `storefront_public_price` - публичная цена, показанная на витрине.

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

Владелец витрины управляет публичной ценой витрины.

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

## 11. Publication view fields

Минимальный `publication_view` должен иметь:

- `publication_id`;
- `owner_type`;
- `owner_id`;
- `source_card_id`;
- `source_owner_type`;
- `source_owner_id`;
- `commercial_proposal_id`, если публикация создана из предложения;
- публичное название;
- публичное описание;
- публичную категорию;
- статус видимости;
- language/version metadata;
- storefront placement;
- media references;
- price fields, если публикация коммерческая;
- history metadata.

Тяжелые файлы не хранятся внутри `publication_view`.

Они хранятся в разрешенных файловых зонах владельца.

## 12. Storefront pages model

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

Разрешенные типы страниц:

- `main`;
- `catalog`;
- `landing`;
- `product`;
- `service`;
- `publication`;
- другие типы, если они добавлены через storefront contract.

Структурная правда страниц и публикаций хранится в базе.

Файловая часть хранится в `children/` у владельца.

## 13. Orders and source relation

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

- с `publication_view`;
- с `commercial_proposal`, если он был;
- с исходной карточкой;
- с источником;
- с владельцем витрины.

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

Владелец витрины может управлять публичным показом.

Источник должен оставаться видимым для fulfillment, истории, документов, расчетов и intercompany-логики.

## 14. История

История должна фиксировать:

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

Критические решения не должны оставаться только в чате.

Они должны попадать в структурную историю и proof/отчеты соответствующей задачи.

## 15. Что не входит в этот Stage 4 документ

Этот документ не фиксирует:

- конкретный API routes map;
- database schema;
- workers;
- schedulers;
- payment gateway;
- налоговую модель;
- frontend design;
- поисковую индексацию;
- SEO implementation.

Эти зоны должны закрываться в Stage 5 или более поздних implementation stages.

## 16. Спорные места

Коротко зафиксированные нерешенные места:

- точная схема order/checkout не фиксируется в Stage 4;
- payment provider не выбирается в Stage 4;
- публичная SEO-индексация не проектируется в Stage 4;
- многоуровневое согласование цены может быть расширено позже, но базовые три цены уже обязательны.

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

Storefront/publication архитектура считается закрытой для Stage 4, если:

- AppMarket и внешняя витрина разведены;
- `system/storefront/` и `children/.../storefront/` разведены;
- определены владельцы витрины;
- зафиксирована граница карточки, предложения и публичного вида;
- описан поток коммерческого предложения;
- определено поведение `central_offer_intake_enabled`;
- цена предложения и публичная цена витрины не смешиваются;
- публикация сохраняет связь с исходным источником.