github-copilot/site-fullstack/README.md

# shop-fullstack

Набор кастомизаций для GitHub Copilot в VS Code под ecommerce-проекты: FastAPI backend, React или Next.js frontend, storefront, admin panel, back office, PostgreSQL, mobile-first UX и двухшаговая подготовка через .ai/STORE-BRIEF.md перед генерацией кода.

## Что создано

В текущем репозитории:
- Агент: .github/agents/shop-fullstack-fastapi-react.agent.md
- Инструкции: .github/instructions/
- Промпты: .github/prompts/
- Skills: .github/skills/ecommerce-store-foundation, .github/skills/ecommerce-store-evolution, .github/skills/ecommerce-brief-preparation, .github/skills/ecommerce-build-from-brief, .github/skills/ecommerce-seo-strategy, .github/skills/ecommerce-seo-implementation, .github/skills/ecommerce-seo-review, .github/skills/ecommerce-code-review, .github/skills/ecommerce-test-implementation и .github/skills/ecommerce-test-repair

## Что умеет агент

- Создавать ecommerce-сайт с нуля.
- Дорабатывать существующий storefront, backend и admin panel.
- Работать в monorepo и split repo режиме.
- По умолчанию использовать FastAPI, PostgreSQL, React и Next.js.
- Сначала собирать нормализованный brief в .ai/STORE-BRIEF.md.
- После brief создавать или обновлять AGENTS.md.
- Для Python ориентироваться на конфигурацию pyproject и quality-toolchain проекта: mypy или ty, ruff, deptry.
- Для React держать код читаемым, предсказуемым и удобным для ручной доработки.
- Писать и прогонять автотесты для backend и frontend, а при падениях запускать отдельный fix-loop до зеленого статуса или явных blockers.
- Учитывать mobile-first адаптацию, анимации, категории, фильтры, сортировку, корзину, авторизацию, личный кабинет и back office.
- Подготавливать prompts для генерации изображений, если готовых ассетов нет.

## Рекомендуемый workflow

Основной сценарий теперь такой:

1. Сначала запустить подготовку brief.
2. Агент задает только важные вопросы.
3. Агент создает файл .ai/STORE-BRIEF.md.
4. После согласования brief запускается сборка сайта по .ai/STORE-BRIEF.md.
5. Перед кодом агент создает AGENTS.md, затем реализует backend, storefront и admin panel.

## Как использовать агента

### Вариант 1. Через выбор агента

1. Открой чат Copilot в VS Code.
2. Выбери агент shop-fullstack-fastapi-react.
3. Передай задачу в свободной форме и попроси сначала подготовить .ai/STORE-BRIEF.md.

Пример:

```text
Подготовь .ai/STORE-BRIEF.md для интернет-магазина косметики в monorepo. Backend на FastAPI и PostgreSQL, frontend на Next.js. Нужны storefront, admin panel, личный кабинет, фильтры, сортировка, корзина, анимации и адаптация под мобильные устройства. После brief я отдельно запущу сборку.
```

### Вариант 2. Через prompt-файлы

Доступны готовые сценарии:
- /Ecommerce Prepare Brief
- /Ecommerce Build From Brief
- /Ecommerce SEO Strategy
- /Ecommerce SEO Implementation
- /Ecommerce SEO Review
- /Ecommerce Code Review
- /Ecommerce Test Implementation
- /Ecommerce Test Repair
- /Ecommerce From Zero
- /Ecommerce Extend Existing
- /Ecommerce Visual Pack

Когда использовать основные новые сценарии:
- Ecommerce Prepare Brief: задает важные вопросы и создает .ai/STORE-BRIEF.md.
- Ecommerce Build From Brief: читает .ai/STORE-BRIEF.md, создает AGENTS.md и строит проект.
- Ecommerce SEO Strategy: создает .ai/SEO-PLAN.md или проводит SEO-аудит и формирует реализационный план.
- Ecommerce SEO Implementation: внедряет .ai/SEO-PLAN.md прямо в код проекта.
- Ecommerce SEO Review: проводит повторный SEO-аудит проекта и пишет .ai/SEO-REVIEW.md с приоритетами и планом исправлений.
- Ecommerce Code Review: делает жесткий code review всего проекта с учетом pyproject, package.json, версий языка и доступных современных возможностей.
- Ecommerce Test Implementation: пишет автотесты для backend и frontend, затем запускает их и пишет .ai/TEST-REPORT.md.
- Ecommerce Test Repair: разбирает падения тестов, чинит код или тесты, гоняет suite повторно и пишет .ai/TEST-REPAIR.md.

Когда использовать:
- Ecommerce From Zero: запуск нового магазина с нуля.
- Ecommerce Extend Existing: развитие уже существующего проекта.
- Ecommerce Visual Pack: подготовка визуального направления и prompts для генерации изображений.

### Вариант 3. Через skills

Skills подключаются автоматически по описанию задачи или через slash-команду, если VS Code их показывает.

- ecommerce-brief-preparation: превращает сырую идею в .ai/STORE-BRIEF.md.
- ecommerce-build-from-brief: строит проект по .ai/STORE-BRIEF.md.
- ecommerce-seo-strategy: готовит сильную SEO-стратегию, технический SEO-план, схему страниц, schema markup и измерение результата.
- ecommerce-seo-implementation: вносит SEO-изменения прямо в кодовую базу по .ai/SEO-PLAN.md.
- ecommerce-seo-review: проверяет фактическую SEO-реализацию и пишет .ai/SEO-REVIEW.md с findings и remediation plan.
- ecommerce-code-review: делает жесткий обзор качества Python, React, архитектуры, производительности и dependency hygiene с отчетом в .ai/CODE-REVIEW.md.
- ecommerce-test-implementation: добавляет backend и frontend автотесты, запускает их и фиксирует результат в .ai/TEST-REPORT.md.
- ecommerce-test-repair: чинит падения тестов и повторно прогоняет suite с отчетом в .ai/TEST-REPAIR.md.
- ecommerce-store-foundation: старт нового магазина.
- ecommerce-store-evolution: развитие существующего магазина.

## Как агент принимает решения

Если вводных не хватает, агент должен уточнить:
- monorepo или split repos
- нужен ли личный кабинет
- нужна ли гостевая корзина
- где хранить корзину: localStorage, cookie, серверное состояние
- нужен ли checkout или достаточно заявки
- какие модули обязательны в admin panel
- какой визуальный стиль нужен

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

## Логика .ai/STORE-BRIEF.md и AGENTS.md

- .ai/STORE-BRIEF.md создается раньше кода и раньше AGENTS.md.
- .ai/STORE-BRIEF.md фиксирует нормализованные требования, ответы на вопросы, допущения, scope storefront, scope admin panel, интеграции, визуал и этапы сборки.
- На основе .ai/STORE-BRIEF.md агент создает AGENTS.md.

- В monorepo агент должен создать один корневой AGENTS.md для frontend и backend.
- В split repo агент должен создать отдельный AGENTS.md в frontend repo и backend repo.
- В AGENTS.md агент фиксирует архитектуру, структуру репозитория, рабочие правила, контракты, роли, требования к storefront и admin panel, а также правила работы с ассетами.

## Бэкапы перед серьезными изменениями

- Перед любым серьезным изменением backend или frontend агент должен создать snapshot в .backup/.
- В имени snapshot должна быть дата со временем до секунд, например .backup/20260520-143708-storefront/.
- Папка .backup считается append-only: внутри нее можно только создавать новые snapshot, изменять или удалять старые запрещено.
- Если сохранять еще нечего, потому что backend или frontend пока не существуют, пустой backup создавать не нужно.

## Архитектура кода

- Backend и frontend должны строиться как крупный проект, а не как плоский набор файлов.
- На backend код должен быть разложен по своим зонам ответственности: api или routers, models, schemas, services, repositories, db, config или core, integrations, tests.
- На frontend код должен быть разложен по своим зонам ответственности: app или routes, pages, features, entities, components, api или services, hooks, config, lib, styles, tests.
- Бизнес-логика не должна оседать в route handlers, page-файлах или UI-компонентах, если ей место в service или domain-слое.

Рекомендуемая структура FastAPI:

```text
backend/
	app/
		api/
			v1/
				routes/
				dependencies/
		core/
		db/
		models/
		schemas/
		repositories/
		services/
		integrations/
		utils/
		main.py
	tests/
		unit/
		integration/
		api/
```

Рекомендуемая структура Next.js или React:

```text
frontend/
	src/
		app/
		pages/
		widgets/
		features/
		entities/
		shared/
			ui/
			api/
			lib/
			hooks/
			config/
			styles/
		tests/
			unit/
			integration/
	public/
```

Рекомендуемая структура admin panel или back office:

```text
frontend/
	src/
		app/
			admin/
		widgets/
			dashboard/
			data-table/
			filters/
			forms/
		features/
			catalog-management/
			order-management/
			customer-management/
			role-management/
			promotion-management/
			content-management/
			media-management/
			settings-management/
		entities/
		shared/
			ui/
			api/
			lib/
			hooks/
			config/
			styles/
		tests/
			unit/
			integration/
			admin-e2e/
```

Рекомендуемая структура monorepo:

```text
project-root/
	.ai/
	.backup/
	AGENTS.md
	backend/
	frontend/
	shared/
		types/
		contracts/
		constants/
	infra/
		docker/
		scripts/
		ci/
```

Рекомендуемая структура split repo:

```text
frontend-repo/
	.ai/
	.backup/
	AGENTS.md
	src/
	public/

backend-repo/
	.ai/
	.backup/
	AGENTS.md
	app/
	tests/
	alembic/
```

Что хранить в слоях:

- api или routes: HTTP endpoint-ы, wiring зависимостей, transport-level логика, маппинг ответа.
- models: ORM-модели и persistence-структуры.
- schemas: request/response контракты и DTO.
- repositories: прямой доступ к данным, query-логика, чтение и запись.
- services: бизнес-правила, orchestration, сценарии, транзакции.
- db: session, engine, base metadata, migrations, подключение к базе.
- core или config: settings, security, logging, bootstrap и глобальные конфиги.
- integrations: платежки, CRM, ERP, email, storage, search и другие внешние системы.
- app или pages: route entry points, layouts и page-level composition.
- widgets: крупные UI-блоки, собранные из features и shared ui.
- features: конкретные сценарии вроде auth, cart, checkout, filters, admin actions.
- entities: доменные frontend-модули вроде product, category, cart, order, user.
- shared ui: переиспользуемые UI-компоненты и design-system primitives.
- shared api: typed clients, fetchers, query adapters, transport helpers.
- hooks: переиспользуемое stateful-поведение на клиенте.
- shared styles: tokens, themes, global styles, mixins, animation primitives.
- tests: unit, integration, api и ui или e2e тесты по слоям.

Правила импортов и границ слоев:

- На backend импорты должны быть абсолютными от корня `app`, например `from app.utils.slug import build_slug`, а не `from ..utils import ...`.
- На backend не нужно писать `__all__ = ...`; лучше использовать явные прямые импорты.
- Направление зависимостей на backend должно быть односторонним: api или routes -> services -> repositories -> models или db.
- models не должны импортировать api, routes или services.
- repositories работают с данными и запросами, но не должны тянуть HTTP-логику или presentation concerns.
- services содержат бизнес-логику и orchestration, а route handlers должны оставаться тонкими.
- На frontend лучше использовать alias от корня `src`, например `@/shared/ui/button`, а не глубокие относительные цепочки вроде `../../../../shared/ui/button`.
- Направление зависимостей на frontend должно быть таким: app или pages -> widgets -> features -> entities -> shared.
- shared не должен зависеть от entities, features, widgets, pages или app.
- Barrel exports лучше не использовать там, где они скрывают ownership, размазывают ответственность или создают циклические зависимости.
- Тесты могут импортировать production-код, но production-код не должен импортировать тестовые модули.

## Рекомендуемый шаблон запроса для первого этапа

```text
Нужно подготовить .ai/STORE-BRIEF.md для ecommerce-проекта.
Формат: monorepo или split repo.
Ниша: ...
Аудитория: ...
Дизайн: ...
Нужны страницы: ...
Нужен личный кабинет: да или нет.
Нужна админка: да.
Нужна гостевая корзина: да или нет.
Интеграции: ...
Особые требования: ...
Сначала задай только важные вопросы и создай .ai/STORE-BRIEF.md.
```

## Рекомендуемый шаблон запроса для второго этапа

```text
Используй .ai/STORE-BRIEF.md как источник правды.
Сначала создай или обнови AGENTS.md.
После этого полностью собери проект: backend, storefront, admin panel, UX-состояния, анимации и недостающие asset prompts.
```

## Что можно расширить дальше

- Добавить отдельные prompts под monorepo и split repo.
- Добавить skill под интеграции платежей, CRM и ERP.
- Добавить шаблоны seed-данных, demo-каталога и дизайн-системы.

## Quality rules

- Для Python агент сначала смотрит на `pyproject.toml` и только потом принимает решение по quality gates.
- Если проект настроен на `mypy`, код должен соответствовать его конфигурации и по умолчанию тяготеть к strict discipline.
- Если проект настроен на `ty`, агент должен ориентироваться на `ty`, а не механически советовать `mypy`.
- Если настроены `ruff` и `deptry`, агент должен учитывать их как реальные ограничения проекта.
- Для React и Next.js код должен оставаться читаемым и легко изменяемым программистом без лишней магии и чрезмерной абстракции.

## Code review workflow

Если нужен жесткий review всего проекта:

1. Запусти /Ecommerce Code Review.
2. Агент сначала прочитает конфигурацию проекта: `pyproject.toml`, `package.json`, `tsconfig.json` и related configs.
3. Затем он проверит Python-часть по реальным правилам проекта, включая `mypy` или `ty`, а также `ruff` и `deptry` при наличии.
4. React-часть будет проверена на читаемость, поддержку, корректность паттернов и уместное использование современных возможностей версии.
5. В результате агент создаст .ai/CODE-REVIEW.md с жесткими findings, приоритетами и планом исправлений.

## Test workflow

Если нужно покрыть проект автотестами и прогнать их:

1. Запусти /Ecommerce Test Implementation.
2. Агент сначала определит текущий backend и frontend test stack.
3. Затем он добавит или обновит автотесты для backend и frontend и прогонит relevant suites.
4. Результат он запишет в .ai/TEST-REPORT.md.
5. Если есть падения, запусти /Ecommerce Test Repair.
6. Этот шаг разберет реальные ошибки, починит код или тесты, снова прогонит тесты и создаст .ai/TEST-REPAIR.md.

Правильный принцип: тесты не должны зеленеть за счет ослабления полезных проверок.

## SEO workflow

Если нужно отдельно проработать органический рост:

1. Запусти /Ecommerce SEO Strategy.
2. Агент прочитает .ai/STORE-BRIEF.md, если он есть.
3. Для широкого SEO-задачи агент создаст .ai/SEO-PLAN.md.
4. В план войдут технический SEO, архитектура страниц, keyword-intent mapping, metadata, schema markup, internal linking, Core Web Vitals и measurement.
5. После этого запусти /Ecommerce SEO Implementation, чтобы агент внедрил .ai/SEO-PLAN.md в код проекта.
6. После внедрения запусти /Ecommerce SEO Review, чтобы агент создал .ai/SEO-REVIEW.md и зафиксировал найденные пробелы, риски и приоритет исправлений.

Важно: skill оптимизирует сайт под максимально сильную органическую базу, но не обещает гарантированное первое место в поиске, так как это зависит не только от кода и структуры сайта.

## Пошаговая инструкция

Пошаговый порядок команд и рекомендованный workflow описаны в [WORKFLOW-GUIDE.md](WORKFLOW-GUIDE.md).