CREATIVE_tg1/github-copilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add test coverage checklist, report template, and stack matrix for ecommerce project

Browse Source 
- Created a test coverage checklist to ensure comprehensive testing of backend and frontend components.
- Added a test report template to standardize reporting on test execution results and gaps.
- Introduced a test stack matrix to guide the selection of testing tools and frameworks for backend and frontend.
- Established a skill for repairing failing tests, including a failure triage checklist and a test repair template.
- Documented recommended MCP stack for ecommerce development with FastAPI and React/Next.js.
- Developed a detailed README outlining the project structure, agent capabilities, and recommended workflows.
- Compiled a comprehensive workflow guide detailing step-by-step commands for project setup, testing, and SEO implementation.
This commit is contained in:
ВяткинАртём
2026-05-20 18:09:24 +03:00
parent 5699670ea0
commit 2817cf8dc6
96 changed files with 2987 additions and 2888 deletions
Download Patch File Download Diff File Expand all files Collapse all files
site-fullstack/README.md
+364
View File
@@ -0,0 +1,364 @@
# 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).