Перейти к содержанию

Контекст проекта SKUARO

Статус документа: ДЕЙСТВУЕТ

Обновлено: 2026-08-26.

Название

SKUARO.

Что создаём

SKUARO — модульная бизнес-система без заранее закрытого перечня функций. Она может включать CRM, коммуникации, AI, операционные процессы, аналитику и другие возможности, которые фактически нужны продукту. Раннее позиционирование и MVP сохраняются как историческая отправная точка, а не как запрет на развитие.

Зачем проект существует

Ключевое ценностное обещание:

Не внедряйте сложную CRM. За 30 минут наведите порядок в обращениях и каждый день получайте список клиентов, которых нельзя забыть.

Нужный результат — дать владельцу малого бизнеса быстрый и понятный способ поддерживать порядок в клиентских обращениях и ежедневно видеть клиентов, требующих внимания.

Владелец, аудитория и пользователи

  • Владелец решений проекта: пользователь — владелец проекта.
  • Основная аудитория MVP: владельцы малого бизнеса.
  • Основной пользователь первого этапа: владелец бизнеса.
  • Позднее: сотрудники и отдельные роли команды.

Текущий этап

Целевая архитектура и минимальная доменная модель приняты. Текущая разработка идёт короткими live STAGE-итерациями: реализация, минимальная сборка/запуск, ручная проверка владельцем в браузере и следующее исправление. Product gate «Сегодня» сохраняется как исторический первый приоритет, но не ограничивает новые направления.

STAGE функционально повторяет будущий боевой продукт: открытая регистрация, подтверждение email, вход, permissions и функции работают штатно, без test-only accounts, bypass, mock-режимов и искусственных ограничений среды. Отличие от PROD — изолированные домен, база, sessions, credentials и deploy-контур.

«Сегодня» остаётся UI-эталоном и принят первым production-модулем. Он не является главным экраном системы: после входа целевой маршрут /home показывает capability-зависимую платформенную сводку и ссылки в доступные модули. Фактическая production-готовность появится только после реализации и прохождения проверок вертикального среза.

Языки и локализация

  • Интерфейс и пользовательские материалы MVP: русский язык.
  • Будущая локализация: английский язык.
  • Код и идентификаторы: английский язык.
  • Комментарии и техническая документация: русский язык.
  • Русская версия является исходной.
  • После появления локализации переводы хранятся в отдельных файлах локалей и помечаются устаревшими при изменении исходного текста; синхронный перевод не блокирует каждое изменение MVP.
  • Название SKUARO, имя репозитория и основные пути не получают языковых суффиксов.

Границы

Входит в проект

  • сценарий контроля обращений и следующих действий;
  • ежедневная очередь «Сегодня»;
  • сущности User, Membership, Organization, Client, Request, NextAction;
  • продуктовая и техническая документация;
  • UX, frontend, backend, миграции, тесты и инфраструктура в рамках принятого плана;
  • аудит и надёжная доставка фоновых событий через outbox;
  • CRM, коммуникации, AI, аналитика, автоматизация и другие возможности по фактической необходимости продукта.

Функциональная граница

Заранее исключённых классов функций нет. CRM, мессенджеры, AI, RAG, BI, многопользовательские сценарии и другие направления могут стать частью SKUARO. Их реализация определяется текущей задачей, полезностью и архитектурной классификацией, а не старым перечнем MVP. - детальный список функций вне первого подтверждённого сценария.

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

Принятая техническая основа

  • Frontend: React 19, TypeScript, Vite и существующая UI-система.
  • Backend: Node.js 24 LTS, TypeScript, Fastify и модульный монолит.
  • API: REST /api/v1, TypeBox, JSON Schema и OpenAPI.
  • Данные: PostgreSQL 18, Drizzle и SQL-миграции.
  • Worker: pg-boss поверх PostgreSQL.
  • Развёртывание: Docker Compose, reverse proxy и отдельные контуры DEV/STAGE/PROD.

Полная схема находится в docs/ARCHITECTURE.md; порядок внедрения — в docs/IMPLEMENTATION_PLAN.md.

Регистрация и доступ

  • Открытая самостоятельная регистрация разрешена.
  • Организация и membership с ролью owner создаются только после успешного подтверждения email; русское название роли — «Руководитель организации».
  • Пользователь получает owner только в самостоятельно созданной им организации; роль не даёт доступа к другим компаниям.
  • Все пользователи работают по ролевой модели, которая управляет функциями, сущностями и видимостью меню.
  • Глобальная платформенная роль разработчика super_admin имеет полный доступ внутри приложения и административный dashboard с разделом «Пользователи».
  • Глобальная роль platform_admin («Администратор SKUARO») также имеет полный доступ внутри приложения, но не может изменять, деактивировать или удалять учётные записи super_admin, а также назначать или отзывать эту роль.
  • /admin является отдельным административным dashboard, но не стартовой страницей после входа. Начальное меню super_admin содержит «Администраторы» и «Пользователи»; функциональность расширяется по мере развития проекта.
  • В разделе «Администраторы» super_admin управляет ролью platform_admin, email, статусом и безопасной сменой пароля. В разделе «Пользователи» он управляет email, статусом и архивированием.
  • super_admin может вручную подтвердить пользователя без email; это явное аудируемое исключение, а не изменение обычного регистрационного потока.
  • У каждого подтверждённого пользователя предусмотрены личные страницы /settings/profile и /settings/security; совместимый /settings перенаправляет в профиль. Первый фактический состав — email и управление паролем, остальные поля отложены.
  • Руководители с разрешением организации получают /organization/settings/* для данных организации, участников, модулей и permissions. Подключённые модули не смешиваются с личным профилем.
  • Будущий отдельный реестр неподтверждённых регистраций содержит только email; правила хранения и писем о продолжении регистрации отложены по решению 0009.

Продуктовые модули и тарифы

  • /home и общий AppShell являются platform capabilities, а не лицензируемыми продуктовыми модулями.
  • Каждая самостоятельная функция SKUARO оформляется как продуктовый модуль.
  • Первый модуль today («Сегодня») является dashboard руководителя о состоянии клиентской работы его организации.
  • Доступ обычного пользователя зависит от роли, активированных организацией модулей и отдельных permissions внутри модуля.
  • Руководитель видит подключённые модули компании и позднее сможет управлять доступом сотрудников к каждому из них.
  • SKUARO будет иметь несколько пакетов монетизации, отличающихся набором модулей; названия, цены и точный состав ещё не выбраны.

Ограничения и отложенные решения

  • Бюджет и сроки уточняются до расходов или обязательства по дате.
  • Product gate «Сегодня» имеет результат ПОДТВЕРЖДЕНО и остаётся историей первого приоритета; он не блокирует расширение backend или новые продуктовые функции.
  • Better Auth 1.7.1 установлен для PoC и требует сквозной проверки до окончательного выбора.
  • Resend выбран 2026-08-25 как основной кандидат DEV email transport через HTTPS API; Gmail SMTP сохранён как fallback. Production email-, AI- и integration providers не выбраны.
  • Срок хранения email неподтверждённых регистраций, количество и интервалы писем, согласие/отписка, удаление и anti-abuse не выбраны.
  • Site и Docs репозитории согласованы, но ещё не созданы.
  • Тестовый сервер является live STAGE-площадкой: текущая разрешённая Product-итерация размещается туда без отдельного hash/merge/evidence gate. PROD, DNS, migrations и разрушительные внешние изменения требуют отдельного разрешения.
  • Пользовательские аккаунты STAGE создаются через настоящую регистрацию. Массовый перенос реальных клиентских бизнес-данных в STAGE требует отдельного решения.

Важные пути

  • Корень product-репозитория: /Users/alexzandr/MEGA/SkuAro-DEV.
  • Frontend-приложение: apps/web/.
  • Целевой общий каркас приложения: platform/shell/; каталог создаётся вместе с реализацией решения 0018.
  • Целевой главный экран: platform/home/; каталог создаётся вместе с реализацией решения 0018.
  • Общий UI-kit и Storybook: packages/ui/.
  • Визуальные эталоны: tests/visual/.
  • Правила интерфейса: UI_SYSTEM.md.
  • Текущая задача и reference workspace внешнего UI/UX-агента: docs/ui-agent/.
  • Целевая архитектура: docs/ARCHITECTURE.md.
  • План реализации: docs/IMPLEMENTATION_PLAN.md.
  • Стратегия тестов и допуска STAGE: docs/STAGE_TESTING_STRATEGY.md.
  • Стратегия документации: docs/DOCUMENTATION_STRATEGY.md.
  • План продуктовой проверки: docs/MVP_VALIDATION_PLAN.md.
  • Решения: docs/decisions/.
  • Session logs: logs/sessions/.
  • Внешнее хранилище секретов: /Users/alexzandr/MEGA/____SECRETS; оно не входит в Git-контур проекта.

Команды работы и проверки

Для текущего frontend-прототипа используются:

  • запуск: npm run dev;
  • проверка toolchain: npm run toolchain:check;
  • lint: npm run lint;
  • проверка типов: npm run typecheck;
  • unit и coverage: npm run test:unit, npm run test:coverage;
  • PostgreSQL integration при запущенном Compose: npm run test:integration;
  • production-сборка frontend: npm run build;
  • сборка каталога компонентов: npm run build:storybook;
  • визуальная регрессия: npm run test:visual;
  • проверка OpenAPI drift: npm run openapi:verify;
  • основной локальный набор без обязательного PostgreSQL: npm run check.

Локальные API и worker автоматически читают корневой .env; production-start получает переменные только из runtime-среды.

Skills, плагины и MCP

  • Skill .agents/skills/task-verification используется только по команде ПРОВЕРИТЬ или при подготовке к PROD, а не в обычной live STAGE-итерации.
  • Созданы project-scoped профили orchestrator, architect, frontend, backend, tester, reviewer и отдельный production-release в .codex/agents/ по решениям 0023/0035; модели наследуются от родительской сессии.
  • Skill .agents/skills/production-readiness и команда ПОДГОТОВИТЬ К ПРОДАКШНУ запускают audit/repair/independent GO-NO-GO только после ручного STAGE-тестирования; сам PROD deploy требует отдельной команды.
  • Повторяемый опыт хранится в docs/agent-memory/, а обязательные правила и решения остаются в канонических документах.
  • Обычная итерация не требует независимого VERIFIED; строгий handoff включается только в отдельном verification/production-контуре.
  • Внешний UI/UX-агент получает одну текущую задачу из docs/ui-agent/TASK.md и сохраняет reference с предложенным MEMORY_DELTA в docs/ui-agent/. До публикации developer-сайта источником контекста служит явно перечисленный в задаче снимок product-репозитория; после публикации — полный developer-сайт. Завершённый result автоматически принимается целиком как точный visual reference без отдельного UI-аудита; frontend переносит его как есть, сохраняя действующие Product routes, data, permissions, Auth/API contracts и runtime.
  • Доступное или глобально установленное расширение не считается выбранной интеграцией проекта.
  • Новое обязательное расширение сначала согласовывается, затем фиксируется в docs/INTEGRATIONS.md с источником, версией и проверкой восстановления.
  • Авторизация и секреты не хранятся в Git.

Критерии завершения задачи

Задача считается завершённой, когда:

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