#Структура проекта и технологический стек

Большую часть повседневной разработки можно оставить ИИ. И всё же знание структуры шаблона позволяет понять, положил ли ИИ свой код в нужное место, и упрощает поиск причин проблем.

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

Шаблон Portal основан на @nocobase/portal-template-default, исходный код — в nocobase/portal-template-default.

Эта комбинация — тот фронтенд-стек, с которым ИИ сегодня знаком лучше всего, поэтому он пишет для него точнее.

Пока Portal — это чисто фронтенд-проект, а бизнес-логика решается через API NocoBase, стандартные компоненты и тому подобное. Поддержка написания бэкенд-кода Portal силами ИИ агента появится позже.

#Структура каталогов

src/
├── app/            Маршрутизация и загрузка расширений
├── pages/          Вход, регистрация, восстановление пароля и т. п.
├── components/     Компоненты
│   ├── ui/         База компонентов shadcn/ui
│   ├── app-shell/  Макет, навигация, состояния загрузки
│   ├── auth/       Компоненты аутентификации
│   └── ...
├── extensions/     Расширения, работают сразу после установки
├── lib/            Обёртка клиента NocoBase и логика ACL
├── providers/      Провайдеры Refine
├── hooks/          Собственные хуки
└── locales/        Локализованные строки

Несколько ключевых мест:

• src/app/routes.tsx — структура маршрутов. Маршруты для вошедших и невошедших пользователей разделены, а маршруты из расширений подключаются автоматически
• src/app/extensions.tsx — загрузка расширений, через import.meta.glob сканирует src/extensions/*/extension.tsx
• src/providers/data.ts — data provider для Refine, переводит синтаксис запросов Refine в параметры API NocoBase
• src/lib/nocobase/client.ts — NocoBaseClient, низкоуровневая обёртка, стоящая за каждым запросом
• src/components/ui/ — более 60 компонентов shadcn/ui, готовых к использованию

Бизнес-страницы обычно живут в src/extensions/, по одному каталогу на функциональный модуль. См. Стандартные компоненты и расширения.

#Ключевые файлы

#Переменные окружения

nb portal dev и nb portal deploy записывают их за вас, так что обычно трогать их не нужно. Последние три требуют согласования только тогда, когда на сервере изменён способ хранения токенов аутентификации.

Во время разработки, если в NOCOBASE_API_URL указан абсолютный адрес, Vite настроит прокси для пересылки запросов — и разбираться с CORS самостоятельно не придётся.

#Часто используемые команды

Вот те, что понадобятся в повседневной работе. Установку зависимостей, обновление переменных окружения и сборку CLI берёт на себя:

Полные параметры каждой команды см. в Справочнике команд nb portal.

#Где находится рабочее пространство разработки

Рабочее пространство разработки Portal создаётся в том каталоге, где вы выполнили nb portal create или nb portal pull:

./<portal>

При создании или загрузке можно указать другое место через --path. Собранные артефакты развёртывания лежат в другом месте — в storage целевого приложения, синхронизируются командой nb portal deploy, и обычно вам с ними работать не приходится.

Если не уверены, где находится рабочее пространство разработки Portal, просто проверьте:

nb portal info main

#Связанные ссылки

• Быстрый старт AI Portal — запустите первую точку входа с фронтендом, написанным ИИ
• Стандартные компоненты и расширения — база компонентов shadcn/ui и механизм расширений
• Развёртывание и управление исходным кодом — процесс сборки и развёртывания, а также source storage
• Совместная разработка с ИИ агентом — управляйте ИИ на естественном языке, чтобы он писал страницы
• nb portal info — узнать, где находится рабочее пространство разработки Portal