Структура проекта

Настройка и конфигурация

Перед любым действием прочтите Перед началом работы и Основные сведения о терминале. В этих инструкциях предполагается, что вы открыли полный монорепозиторий supastack в VS Code; его корень package.json отмечает корень репозитория. В командах pnpm пакет рабочей области представляет собой папку приложения или общего кода; В продукте рабочее пространство — это контейнер данных и граница безопасности команды. corepack pnpm --filter ... выбирает один пакет из монорепозитория, пока команды выполняются из его корня. Если вы открыли только синхронизированную папку мобильного устройства или рабочего стола, она не содержит веб-серверной части, настройки Docker или корневых сценариев: запустите серверную часть из этого монорепозитория или доступного размещенного сервера и используйте собственные сценарии папки платформы. Переменная среды — это именованный параметр, хранящийся в локальном файле .env или на панели управления хостингом; перезапустите соответствующее приложение после его изменения и не допускайте попадания секретов сервера в значения NEXT_PUBLIC_ и EXPO_PUBLIC_.

1. Откройте корневой файл package.json в VS Code, затем найдите apps/web для веб-сайта, apps/mobile для Expo, apps/desktop для оболочки рабочего стола и пакеты для общих частей.

2. Из корня репозитория запустите corepack pnpm --filter @supastack/web dev.

3. Откройте http://localhost:3000. Ожидается: веб-приложение запускается с apps/web, а общие пакеты остаются в том же репозитории; окно рабочего стола оборачивает это веб-приложение, а не содержит второй продукт.

Воркспейс pnpm содержит Next.js в apps/web, Expo в apps/mobile и общие пакеты в packages. Запускайте команды воркспейса из корня репозитория. Маршруты приложений компонуют общие модули; продуктовое поведение принадлежит потребляющему продукту.

Прочитайте AGENTS.md и .ai/PROJECT_CONTEXT.md до изменения поведения. Файловые зеркала в .ai/ объясняют решения и ограничения, которые могут быть неочевидны из одного компонента.

apps/web/app/       Routes and layouts
packages/web-core/src/  Shared pages, components and server composition
apps/mobile/        Expo application
packages/           Shared contracts and adapters
tests/              Cross-module and browser checks
docs/               Operational guides

Команды для копирования

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

corepack pnpm --filter @supastack/web dev

Куда поместить изменение

Перед редактированием решите, какому приложению или пакету принадлежит изменение. Эмпирическое правило: если оно нужно только одной поверхности продукта — поместите его в это приложение; если нужно всем поверхностям — поместите в общий пакет внутри packages/.

Веб-репозиторий и монорепозиторий All Platforms содержат все папки ниже. Отдельная выгрузка Mobile или Desktop содержит только своё приложение — серверный код остаётся в веб-репозитории.

• Создайте первую функцию

• Новая маркетинговая или лендинг-страница → apps/web/app/ — публичный сайт.
• Новый экран внутри продукта после входа → apps/web/app/ для маршрута плюс packages/web-core/src/ для его логики — страницы компонуют общие пакеты.
• Новый API-маршрут → apps/web/app/api/ — серверная половина веб-приложения.
• Изменение, общее для всех приложений — таблица базы данных, контракт, адаптер провайдера → соответствующая папка в packages/.
• Экран только для телефона → apps/mobile/ — он обращается к API веб-приложения, а не содержит собственный бэкенд.
• Поведение только для десктопа → apps/desktop/ — оболочка Tauri оборачивает веб-приложение и почти никогда не ответвляет продуктовый интерфейс.

Рабочий процесс внедрения

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

Добавляя маршрут, решите, публичный он или аутентифицированный. Разрешайте аутентифицированное владение на сервере до доступа к записям пользователя и держите серверные креденшелы вне клиентских импортов.

Проверка и устранение неполадок

Если команда сообщает, что ни один проект не соответствует фильтру, убедитесь, что терминал находится в папке, содержащей корневой файл package.json. Если порт 3000 уже используется, сначала остановите другой локальный веб-сервер. Не ищите отдельную реализацию чата или входа в систему на рабочем столе; оболочка рабочего стола загружает веб-сервер.

Запускайте соответствующие тесты и проверку типов после изменения контракта пакета. Инспектируйте и веб-, и мобильных потребителей при изменении общих типов. Успешная веб-сборка сама по себе не устанавливает совместимость с нативным приложением.