Документация

1Общие сведения

2Назначение

Каркас — модульная система управления содержимым и движок интернет-магазинов для среднего и малого бизнеса. Предназначена для создания и эксплуатации корпоративных сайтов, контентных порталов и интернет-магазинов с интеграцией в учётные системы (1С), российские платёжные сервисы и службы доставки. Занимает нишу между конструкторами сайтов и тяжёлыми промышленными CMS: даёт гибкость профессиональной разработки при простоте управления через административную панель.

Продукт является самостоятельной разработкой правообладателя, эксплуатируется на промышленных проектах (действующие интернет-магазины и корпоративные сайты), не является тестовой версией и не является надстройкой над сторонним ядром.

3Функциональные характеристики

3.1Управление каталогом и товарами

• ведение каталога товаров с категориями и справочниками;
• товарные вариации (цвет, размер и произвольные оси) с отдельными ценами и остатками;
• живой предпросмотр карточки товара в административной панели;
• импорт товаров из файлов (CSV) и из учётной системы 1С;
• управление медиа-файлами товаров (загрузка, сортировка, обложка), обработка изображений.

3.2Корзина, оформление и оплата

• корзина покупателя с контролем остатков и защитой от перепродажи;
• оформление заказа с расчётом стоимости и доставки;
• приём оплаты через российские платёжные сервисы (эквайринг);
• формирование фискальных чеков в соответствии с 54-ФЗ;
• идемпотентная обработка возвратов и повторных операций.

3.3Интеграция с 1С

• двусторонний обмен по протоколу CommerceML: импорт номенклатуры, цен, остатков, изображений;
• экспорт оформленных заказов в учётную систему;
• настраиваемое сопоставление полей и режимов обмена.

3.4Доставка

• интеграция с российскими службами доставки (расчёт стоимости и оформление);
• поддержка самовывоза и доставки, конфигурируемые способы.

3.5Оптовый режим

• разграничение розничного и оптового доступа (оптовые цены и условия для авторизованных клиентов), управляемое данными.

3.6Управление содержимым (CMS)

• типизированная модель содержимого (страницы, новости, кейсы, услуги и произвольные типы), описываемая декларативно (config-as-code) с автоматической генерацией форм администратора;
• визуальный редактор содержимого с работой в оформлении темы;
• меню, разделы, главная страница с блоками;
• разграничение видимости и статусов публикации.

3.7Поисковая оптимизация (SEO)

• генерация структурированных данных Schema.org (FAQPage, HowTo, Article, BreadcrumbList, Organization, Service, LocalBusiness);
• канонические ссылки, управление meta-тегами, карта сайта;
• система редиректов (301/302) с управлением из административной панели;
• поля бизнеса (адрес, телефон, часы, координаты, регион обслуживания) для локального SEO.

3.8Уведомления

• каналы уведомлений о заказах и заявках: электронная почта (SMTP), Telegram, Bitrix24, MAX;
• настройка каналов через административную панель.

3.9Оформление и брендирование

• система тем и дизайн-токенов для настройки внешнего вида под бренд заказчика;
• серверный рендеринг страниц (собственная реализация, без сторонних фреймворков рендеринга).

3.10Администрирование и эксплуатация

• административная панель (список-дровер, drag-and-drop сортировка, канбан заказов, глобальный поиск, массовые операции над записями);
• многопользовательский доступ с ролями (администратор, контент-редактор, менеджер) и журналом аудита действий; ограничение числа пользователей по редакции;
• триаж входящих заявок (статусы: новая / в работе / завершена / спам) и сводка «Требует внимания»;
• автоматическая очистка персональных данных по настраиваемым срокам хранения (соответствие требованиям 152-ФЗ);
• проверка работоспособности (health-эндпоинт с версией сборки);
• обновление штатным сценарием с резервной копией, проверкой и автоматическим откатом при сбое; контроль лицензии с уведомлениями в панели;
• автоматическое тестовое покрытие (957 автоматических тестов на момент подачи).

4Сведения о российском происхождении

• ПО является самостоятельной разработкой правообладателя, не является модификацией или надстройкой над иностранным программным продуктом;
• ключевые функции не зависят от иностранных сервисов; внешние интеграции — российские (платёжные сервисы РФ, службы доставки РФ, 1С, Bitrix24);
• сторонние программные компоненты — свободные библиотеки с разрешительными лицензиями (MIT, Apache-2.0), без ограничений на коммерческое использование и использование на территории РФ (перечень — в отдельном документе «Перечень компонентов»);
• гарантийное обслуживание и техническая поддержка осуществляются на территории РФ;
• средства хранения исходного и объектного кода, средства сборки размещены на территории РФ;
• персональные данные обрабатываются и хранятся на серверах на территории РФ.

5Стоимость и порядок предоставления

ПО распространяется на возмездной основе по двум моделям:

• Лицензия на установку (on-premise) — разовая лицензия на право использования при установке на сервер заказчика;
• Подписка (SaaS) — периодическая плата за облачный доступ к экземпляру, размещённому на инфраструктуре правообладателя на территории РФ.

Актуальные цены и условия приобретения размещены на официальном сайте продукта: https://karkac-cms.ru/tarify.

Официальный сайт правообладателя (ООО «АЙТИТЕК»): https://it-uu.ru/. Сайт продукта «Каркас»: https://karkac-cms.ru/.

Стоимость лицензии выделяется отдельной строкой в договоре/счёте (для применения льготы по НДС в соответствии с пп. 26 п. 2 ст. 149 НК РФ при реализации ПО из реестра).

6Контакты поддержки

ООО «АЙТИТЕК». Сайт: https://it-uu.ru/. Телефон: +7 (3012) 599-513. E-mail: info@it-uu.ru.
Юридический адрес: 670000, Республика Бурятия, г. Улан-Удэ, ул. Ленина, д. 44, оф. 11.

Техническая поддержка и гарантийное обслуживание осуществляются на территории Российской Федерации.

1Системные требования

1.1Программные требования

Компонент	Требование
Операционная система	Linux (рекомендуется Ubuntu 22.04 LTS или совместимая)
Среда исполнения	Node.js версии 20 или выше
Менеджер пакетов	pnpm (устанавливается через corepack)
СУБД	PostgreSQL версии 14 или выше
Веб-сервер (реверс-прокси)	nginx или совместимый (для публикации и TLS)

1.2Аппаратные требования (минимальные, на один экземпляр)

Ресурс	Минимум	Рекомендуется
Процессор	2 vCPU	4 vCPU
Оперативная память	2 ГБ	4 ГБ
Дисковое пространство	10 ГБ	20 ГБ и более (зависит от объёма медиа-каталога)

Вся инфраструктура (серверы приложения, БД, хранилище резервных копий) размещается на территории Российской Федерации.

2Состав дистрибутива

Исходный код организован как монорепозиторий (pnpm workspace) и включает функциональные модули (пакеты) и приложения. Перечень модулей и их назначение приведены в документе «Архитектура и компоненты».

3Установка на сервер заказчика (on-premise)

Шаг 1. Подготовка окружения

1. Установить Node.js версии 20+ и включить менеджер пакетов:

2. Установить и запустить PostgreSQL 14+, создать базу данных и учётную запись для приложения.

Шаг 2. Размещение кода

1. Разместить дистрибутив в рабочем каталоге на сервере.
2. Установить зависимости:

Шаг 3. Конфигурация

1. Задать строку подключения к базе данных в переменной окружения DATABASE_URL.
2. Задать прочие параметры окружения (профиль носителя, порт, параметры интеграций) согласно конфигурационному описанию.

Шаг 4. Инициализация базы данных

1. Применить схему БД (миграции Prisma):

2. При необходимости выполнить первичное наполнение демонстрационными данными (seed).

Шаг 5. Запуск

1. Запустить приложение (административный API и витрину) согласно скриптам запуска.
2. Настроить реверс-прокси (nginx) на порт приложения, включить TLS-сертификат.

Шаг 6. Проверка работоспособности

1. Открыть health-эндпоинт (/healthz) — должен вернуть статус и версию сборки.
2. Открыть витрину и административную панель, проверить вход.

4Развёртывание в облаке (SaaS)

При облачной модели поставки экземпляр разворачивается на инфраструктуре правообладателя (на территории РФ), заказчику предоставляется доступ по подписке:

1. Правообладатель создаёт изолированный экземпляр для заказчика (модель single-tenant — один экземпляр на клиента), выполняя шаги раздела 3 на своей инфраструктуре.
2. Настраивается поддомен/домен заказчика и TLS.
3. Заказчику передаются учётные данные администратора.
4. Обновления, резервное копирование и мониторинг обеспечивает правообладатель.

5Обновление

Обновление выполняется штатным сценарием deploy/update.sh: проверка лицензии → автоматическая резервная копия → получение новой версии → применение миграций БД → перезапуск → контрольная проверка (/healthz возвращает идентификатор сборки). При сбое любого шага выполняется автоматический откат на предыдущую версию с восстановлением из резервной копии (--rollback — ручной откат). Миграции схемы поставляются вместе с версией.

6Резервное копирование

Резервные копии базы данных и медиа-хранилища выполняются штатными средствами (PostgreSQL dump, копирование каталога медиа) и хранятся на территории РФ. Периодичность настраивается регламентом эксплуатации заказчика/правообладателя.

1Назначение и роли

Каркас эксплуатируется через веб-интерфейс административной панели. Основные роли:

• Администратор/владелец — полный доступ: каталог, заказы, содержимое, настройки, интеграции, управление пользователями;
• Контент-редактор — страницы, новости, медиа, SEO (создаётся администратором в разделе «Пользователи», доступ разграничен ролью);
• Менеджер — заказы и заявки (аналогично, отдельная роль);
• Покупатель (внешний пользователь) — просмотр каталога, оформление и оплата заказа на витрине.

2Начало работы

1. Открыть административную панель по адресу экземпляра (раздел /admin или отдельный поддомен, согласно конфигурации).
2. Выполнить вход под учётной записью администратора.
3. Проверить состояние системы в разделе «Состояние» (доступность БД, версия сборки).

3Основные эксплуатационные операции

3.1Каталог и товары

• создание/редактирование товаров и категорий в разделе «Товары»;
• добавление вариаций (цвет/размер/оси), цен и остатков;
• загрузка и сортировка фотографий товара, назначение обложки;
• импорт товаров из CSV или получение через обмен с 1С.

3.2Заказы и заявки

• просмотр и обработка заказов (список и канбан-доска по статусам), серверный поиск по номеру/e-mail/телефону;
• изменение статусов, работа с оплатой и возвратами;
• заявки с форм: триаж по статусам (новая / в работе / завершена / спам), сводка «Требует внимания» на дашборде;
• экспорт заказов в 1С (при настроенной интеграции).

3.3Содержимое сайта

• управление страницами, новостями, кейсами в разделе «Страницы и новости»;
• заполнение SEO-полей (заголовки, описания), блоков FAQ, включение схем разметки (страница услуги, страница контактов) переключателями на странице;
• массовые действия (публикация/снятие) и история версий записей;
• управление меню и главной страницей.

3.4Настройки и интеграции

• раздел «Настройки»: параметры сайта, поля бизнеса (адрес, телефон, часы, координаты), коды аналитики;
• подключение платёжных сервисов, служб доставки, обмена с 1С;
• раздел «Пользователи»: создание учётных записей с ролями, смена паролей, деактивация;
• настройка сроков хранения персональных данных (авточистка обработанных заявок и журнала аудита — 152-ФЗ).

3.5Оформление

• раздел «Темы и цвета»: настройка внешнего вида через дизайн-токены под бренд.

4Контроль работоспособности

• health-эндпоинт /healthz возвращает статус и идентификатор версии сборки — используется для мониторинга и проверки после обновления;
• раздел «Состояние» в административной панели отражает доступность подсистем.

5Типовые процедуры сопровождения

5.1Обновление версии

Выполняется штатным сценарием deploy/update.sh: резервная копия → новая версия → миграции → перезапуск → контрольная проверка /healthz; при сбое — автоматический откат. Доступность обновлений отображается в панели (баннер версии/лицензии).

5.2Резервное копирование и восстановление

Регулярное резервное копирование базы данных (PostgreSQL) и каталога медиа. Восстановление — из резервной копии в обратном порядке. Хранение копий — на территории РФ.

5.3Диагностика неполадок

• проверить /healthz и раздел «Состояние»;
• проверить доступность базы данных и корректность строки подключения DATABASE_URL;
• проверить журналы приложения;
• при сбое интеграции — проверить реквизиты подключения в разделе «Настройки» кнопкой проверки.

6Жизненный цикл ПО

• разработка и сопровождение ведутся правообладателем на территории РФ;
• выпуск обновлений — регулярный, с ведением журнала изменений;
• исправление ошибок — по обращениям в службу поддержки и в порядке планового сопровождения;
• средства хранения исходного кода, сборки и учёта ошибок размещены на территории РФ.

7Техническая поддержка

Техническая поддержка и гарантийное обслуживание осуществляются правообладателем на территории Российской Федерации.

Контакты: ООО «АЙТИТЕК», сайт https://it-uu.ru/, телефон +7 (3012) 599-513, e-mail info@it-uu.ru, адрес: 670000, Республика Бурятия, г. Улан-Удэ, ул. Ленина, д. 44, оф. 11.

1Технологический стек

Уровень	Технология	Версия
Язык	TypeScript / JavaScript	—
Среда исполнения	Node.js	20+ (эксплуатируется на 22)
Менеджер пакетов	pnpm (workspace-монорепозиторий)	—
Веб-фреймворк	Express	4.21.x
ORM / доступ к БД	Prisma	6.19.x
СУБД	PostgreSQL	14+
Серверный рендеринг	Собственная реализация (без Next.js и иных сторонних SSR-фреймворков)	—
Валидация данных	Zod	3.23.x
Обработка изображений	sharp	0.34.x
Загрузка файлов	multer	2.x
Обработка XML (обмен 1С)	fast-xml-parser	5.9.x
Работа с архивами	adm-zip	0.5.x

Собственный серверный рендеринг (не заимствованный фреймворк) — существенный признак самостоятельности продукта.

2Архитектура: функциональные модули

ПО построено по модульному принципу (монорепозиторий). Модули (пакеты) и их назначение:

Модуль	Назначение
core	Ядро: реестр модулей, манифесты, базовые типы и утилиты
content	Модель содержимого (типы контента, config-as-code), формы администратора
cart-checkout	Корзина, оформление, оплата, возвраты, обмен с 1С (импорт/экспорт)
storefront	Витрина: серверный рендеринг страниц, каталог, SEO-разметка
admin	Административная панель, настройки, реестр интеграций

3Уровни архитектуры

1. Ядро (неделимое) — контент-модель, серверный рендеринг, каркас административной панели, механизм модулей и реестр, профили-носители. Не дробится и не отключается.
2. Модули (цельные функции) — каталог, корзина-checkout, формы, медиа, темы, уведомления, 1С-обмен. Включаются по профилю носителя.
3. Плагины-провайдеры — платёжные сервисы, службы доставки, каналы уведомлений; каждый — отдельный плагин под стабильный контракт (PaymentProvider / DeliveryProvider / NotificationProvider), регистрируется самостоятельно.

4Изоляция и переносимость

• один клиент — изолированный экземпляр: свой контейнер, база данных и административная панель; данные клиентов не пересекаются;
• экспорт экземпляра — самодостаточный: база, медиа, образ, инсталлятор;
• резервные копии — с контролем свежести, восстановление отработано.

1Модели предоставления

• Лицензия на установку (on-premise) — разовая лицензия на право использования ПО при установке на сервер заказчика; сопровождение — по отдельному соглашению;
• Подписка (SaaS) — периодическая плата за облачный доступ к изолированному экземпляру на инфраструктуре правообладателя (территория РФ); обновления, резервное копирование и мониторинг включены.

2Редакции

Функциональный состав определяется редакцией (профилем-носителем): «Лендинг», «Сайт», «Магазин», «Магазин+». Состав модулей по редакциям приведён на странице возможностей, матрица функций и действующие цены — на странице тарифов (https://karkac-cms.ru/tarify).

3Порядок приобретения

1. Заявка через форму на сайте или по контактам поддержки.
2. Согласование редакции и модели предоставления, выставление счёта/договора.
3. Стоимость лицензии выделяется отдельной строкой в договоре/счёте — для применения льготы по НДС в соответствии с пп. 26 п. 2 ст. 149 НК РФ при реализации ПО из реестра.

Сторонние программные компоненты, используемые в составе ПО, — свободные библиотеки с разрешительными лицензиями, без ограничений на коммерческое использование и использование на территории РФ.

Компонент	Назначение	Версия	Лицензия
Express	Веб-фреймворк	4.21.x	MIT
Prisma	ORM / доступ к БД	6.19.x	Apache-2.0
Zod	Валидация данных	3.23.x	MIT
sharp	Обработка изображений	0.34.x	Apache-2.0
multer	Загрузка файлов	2.x	MIT
fast-xml-parser	Обработка XML (обмен 1С)	5.9.x	MIT
adm-zip	Работа с архивами	0.5.x	MIT