Step 2: Project Example

# Stages

Эта папка содержит stage definitions для проекта.

Каждый файл stage должен описывать:
- цель этапа
- business value
- scope
- out of scope
- backend/frontend/db/infra work
- acceptance criteria
- required tests
- риски
- зависимости
- deliverables

Рекомендуемый workflow:
1. Сначала создать или обновить stage file.
2. Затем отдать stage агенту в режиме plan.
3. После согласования — отдать в build.
4. После завершения — создать report в `/docs/reports`.

Именование файлов:
- `stage-00-foundation.md`
- `stage-01-catalog-mvp.md`
- `stage-02-auth-and-user-identity.md`

# Stage 00 — Foundation

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

## Business value
Этот этап не дает конечную пользовательскую фичу, но превращает проект в управляемую инженерную систему.
Без него последующая разработка будет хаотичной, плохо тестируемой и трудно воспроизводимой.

## Scope
- backend application skeleton
- frontend application skeleton
- database connection and migration framework
- local development environment
- base CI checks
- env/config conventions
- health endpoints
- docs bootstrap

## Out of scope
- каталог товаров
- auth
- корзина
- checkout
- админка
- платежи

## Backend work
- создать базовый backend app
- выделить модули: app, config, health, db
- добавить `/health` endpoint
- подключить конфигурацию через env
- подключить ORM / query layer

## Frontend work
- создать базовый frontend app
- базовый layout
- routing shell
- API client skeleton
- env config support

## Database work
- подключить БД
- настроить миграции
- создать baseline migration
- настроить seed framework

## Infra / DevEx work
- docker compose для локального запуска
- `.env.example`
- команды запуска backend/frontend/db
- lint/test/typecheck commands
- CI skeleton

## Acceptance criteria
- проект поднимается локально по инструкции
- backend отвечает на `/health`
- frontend стартует и открывается
- БД подключается
- миграции применяются
- есть базовые команды `dev`, `lint`, `test`
- CI запускает минимум lint + tests smoke

## Required tests
### Unit
- smoke unit для config parsing при наличии такой логики

### Integration
- backend health endpoint
- DB connectivity check

### Smoke / e2e
- frontend стартует
- frontend может запросить backend health

## Risks
- слишком ранняя усложненная архитектура
- нестабильный локальный setup
- env drift между backend/frontend

## Dependencies
- решение по стеку backend
- решение по стеку frontend
- выбор БД

## Deliverables
- working repo skeleton
- local setup
- initial CI
- stage report
- updated AGENTS.md if needed

# Stage 01 — Catalog MVP

## Goal
Пользователь может открыть каталог товаров и карточку отдельного товара.

## Business value
Это первый демонстрируемый кусок продукта. Он делает магазин похожим на реальный продукт и позволяет проверить ранние решения по data model, API и UI.

## Scope
- product/category schema
- backend product list endpoint
- backend product detail endpoint
- seed data for products
- frontend catalog page
- frontend product detail page
- loading / error / empty states

## Out of scope
- auth
- cart
- checkout
- admin
- payments
- search beyond basic filters

## Backend work
- создать модели Product и Category
- реализовать `GET /products`
- реализовать `GET /products/:id`
- поддержать базовую фильтрацию по category
- добавить seeds

## Frontend work
- реализовать страницу каталога
- реализовать карточки товаров
- реализовать страницу товара
- подключить frontend к реальному backend API
- обработать loading/error/empty states

## Database work
- создать таблицы `products`, `categories`
- задать индексы для lookup и category filters
- добавить demo seed data

## Infra / DevEx work
- обновить тестовые данные для локальной среды
- обновить CI для backend + frontend checks по новому stage

## Acceptance criteria
- каталог открывается и показывает список товаров
- карточка товара открывается по ID/slug
- фронтенд не использует мок-данные
- API возвращает корректные payloads
- есть smoke-check основных пользовательских шагов

## Required tests
### Unit
- product mapping / serialization rules

### Integration
- `GET /products`
- `GET /products/:id`
- category filter behavior

### Smoke / e2e
- открыть каталог
- перейти в карточку товара
- увидеть empty/error state при соответствующих условиях

## Risks
- слишком богатый payload слишком рано
- сильная связка frontend с конкретным API shape
- плохая seed strategy

## Dependencies
- завершенный Foundation stage

## Deliverables
- working product catalog MVP
- backend/frontend tests
- stage report
- release notes

# Stage 02 — Auth and User Identity

## Goal
Пользователь может зарегистрироваться, войти и получить доступ к своему профилю.

## Business value
Без identity нельзя развивать user-specific capabilities: корзину, checkout, историю заказов, персональные данные.

## Scope
- sign up
- sign in
- session / token flow
- profile endpoint
- protected frontend routes
- logout

## Out of scope
- social login
- MFA
- admin panel
- order history

## Backend work
- user entity
- password hashing
- signup/signin endpoints
- session or refresh-token flow
- `/me` endpoint
- auth middleware

## Frontend work
- login page
- register page
- session state handling
- protected routes
- profile page
- logout flow

## Database work
- `users`
- `sessions` or token storage table if needed
- unique indexes on email / login identifier

## Acceptance criteria
- user can sign up
- user can sign in
- user can sign out
- protected page requires auth
- profile loads for authenticated user
- invalid credentials handled safely

## Required tests
### Unit
- auth validators
- password policy logic if present

### Integration
- signup flow
- signin flow
- protected endpoint access
- `/me` endpoint

### Smoke / e2e
- sign up -> sign in -> open profile -> sign out

## Risks
- auth token storage mistakes
- insecure default session behavior
- leaking auth state into unrelated UI

## Dependencies
- Foundation

## Deliverables
- working auth flow
- tests
- report
- ADR if auth design requires one

# Stage 03 — Cart MVP

## Goal
Пользователь может добавлять товары в корзину, менять количество и удалять позиции.

## Business value
Корзина — первый stage, где каталог превращается в покупательский поток.

## Scope
- cart read endpoint
- add/update/remove cart item
- cart UI
- subtotal calculation
- guest or authenticated cart strategy

## Out of scope
- checkout
- payments
- promotions
- coupons

## Backend work
- cart and cart items entities
- add item endpoint
- update quantity endpoint
- remove item endpoint
- get cart endpoint
- subtotal calculation on server

## Frontend work
- add to cart action from product page and catalog
- cart page or drawer
- quantity change UI
- remove item UI
- empty cart state

## Database work
- `carts`
- `cart_items`
- cart ownership strategy

## Acceptance criteria
- user can add item to cart
- quantity updates correctly
- item removal works
- subtotal is shown correctly
- frontend and backend stay in sync

## Required tests
### Unit
- cart subtotal calculation
- quantity validation

### Integration
- add/update/remove cart item
- get cart

### Smoke / e2e
- open catalog -> add item -> open cart -> change qty -> remove item

## Risks
- client-side subtotal becoming source of truth
- cart ownership ambiguity
- stale item prices

## Dependencies
- Catalog MVP
- optionally Auth stage depending on cart strategy

## Deliverables
- working cart MVP
- tests
- report

# Stage 04 — Checkout Draft

## Goal
Пользователь может начать оформление заказа и подтвердить черновик заказа.

## Business value
Это первый stage, где система начинает превращать intent в order.

## Scope
- address capture
- order draft creation
- order items snapshot
- server-side recalculation
- checkout review page

## Out of scope
- real payment provider
- promotions engine
- advanced shipping integrations

## Backend work
- draft order creation from cart
- shipping address handling
- server recalculation
- order snapshot creation
- order validation

## Frontend work
- checkout page
- address form
- order review block
- submit order draft flow

## Database work
- `orders`
- `order_items`
- shipping address structure
- order status enum / table

## Acceptance criteria
- checkout starts from current cart
- user can enter address
- server validates order
- order draft is created correctly
- order summary reflects server truth

## Required tests
### Unit
- order total recalculation
- order status initial rules

### Integration
- create draft order from cart
- invalid address / invalid cart scenarios

### Smoke / e2e
- add to cart -> start checkout -> submit valid order draft

## Risks
- trusting client totals
- poor order snapshot model
- checkout and cart falling out of sync

## Dependencies
- Cart MVP
- Auth if checkout requires signed-in users

## Deliverables
- working checkout draft
- tests
- report
- ADR if order model decisions are significant

# Stage 05 — Payment Flow

## Goal
Заказ проходит через базовый платежный сценарий с успехом и ошибкой.

## Business value
Позволяет довести заказ до состояния, близкого к завершенной покупке.

## Scope
- payment abstraction
- payment intent / mock provider or initial integration
- order status update after payment
- success/failure handling

## Out of scope
- full reconciliation
- refunds
- advanced anti-fraud
- subscriptions

## Backend work
- payment service abstraction
- payment intent creation
- webhook or callback handling
- payment status persistence
- order status transitions

## Frontend work
- pay action
- payment result UI
- failure / retry flow

## Database work
- `payments`
- relationship between payments and orders
- status transition support

## Acceptance criteria
- order can enter payment flow
- success path updates order correctly
- failure path is visible and handled safely
- basic retry behavior is defined

## Required tests
### Unit
- order/payment status transition rules

### Integration
- payment intent creation
- status update callback/webhook flow

### Smoke / e2e
- checkout draft -> payment success
- checkout draft -> payment failure

## Risks
- duplicate callbacks
- inconsistent payment/order statuses
- over-coupling to one provider

## Dependencies
- Checkout Draft

## Deliverables
- payment stage implementation
- tests
- report
- ADR for payments abstraction if applicable

# /docs/stages/stage-06-order-history.md

# Stage 06 — Order History

## Goal
Пользователь видит список своих заказов и детали заказа.

## Business value
Это завершает пользовательский контур после покупки и повышает доверие к продукту.

## Scope
- list my orders
- order detail page
- ownership checks
- basic order status display

## Out of scope
- returns
- invoice generation
- customer support tooling

## Acceptance criteria
- user sees only own orders
- order details are readable
- statuses are shown correctly
- authz is enforced


# /docs/stages/stage-07-admin-product-management.md

# Stage 07 — Admin Product Management

## Goal
Администратор может управлять товарами.

## Scope
- admin product list
- create/edit product
- publish/unpublish
- stock and price editing

## Out of scope
- advanced media pipeline
- bulk imports

## Acceptance criteria
- admin can CRUD products
- normal user cannot
- changes are visible in catalog
- tests cover authz and key flows


# /docs/stages/stage-08-admin-order-management.md

# Stage 08 — Admin Order Management

## Goal
Администратор может видеть и управлять заказами.

## Scope
- admin orders list
- filters
- order detail
- update order status

## Acceptance criteria
- admin sees orders
- admin can update status
- transitions are controlled
- tests cover permissions and lifecycle


# /docs/stages/stage-09-search-and-ux-maturity.md

# Stage 09 — Search and UX Maturity

## Goal
Улучшить опыт работы с каталогом до более зрелого продуктового уровня.

## Scope
- search
- sorting
- richer filters
- pagination
- improved empty/loading/error states
- UX polish on key storefront flows

## Acceptance criteria
- users can search products
- filters and sorting work predictably
- pagination is stable
- key states are handled well


# /docs/stages/stage-10-production-readiness.md

# Stage 10 — Production Readiness

## Goal
Подготовить систему к стабильной эксплуатации.

## Scope
- observability basics
- structured logging
- metrics
- readiness checks
- release hardening
- rollback notes
- security review basics
- performance sanity checks

## Acceptance criteria
- health/readiness are meaningful
- release process is documented
- rollback is documented
- key critical paths are observable

# Stage Reports

Эта папка содержит отчеты по завершенным stages.

Принцип:
- stage file = план и рамка этапа
- report file = фактически реализованный результат

Каждый report должен содержать:
- objective
- implemented backend/frontend/db/infra changes
- verification performed
- what was not verified
- acceptance criteria status
- known issues
- tech debt
- assumptions
- manual QA checklist
- release notes
- recommended next stage

# Stage Report — Stage 00 Foundation

## Objective
Собрать минимальный рабочий каркас проекта для дальнейшей управляемой разработки.

## Implemented

### Backend
- создан backend skeleton
- добавлен `/health`
- подключена конфигурация через env
- добавено подключение к БД

### Frontend
- создан frontend skeleton
- добавлен базовый layout
- настроен API client shell

### Database
- настроена миграционная система
- создана baseline migration
- настроен seed entrypoint

### Infrastructure / DevEx
- добавлен `docker-compose.yml`
- добавлен `.env.example`
- добавлены базовые скрипты `dev`, `lint`, `test`
- добавлен минимальный CI workflow

## Files / modules affected
- backend/
- frontend/
- db/migrations/
- docker-compose.yml
- .env.example
- .github/workflows/

## Verification performed
### Automated checks run
- backend lint — passed
- frontend lint — passed
- backend tests — passed
- frontend smoke test — passed

### Manual checks performed
- backend `/health` отвечает
- frontend открывается локально
- frontend может достучаться до backend health

### Not verified
- production deployment
- staging environment

## Acceptance criteria status
- local setup works — Done
- backend health endpoint — Done
- frontend starts — Done
- DB migrations work — Done
- minimal CI exists — Done

## Known issues
- структура env пока базовая
- seed data framework без реальных доменных данных

## Tech debt introduced or preserved
- нет полноценного observability bootstrap
- нет hot-reload optimization notes

## Assumptions
- единый monorepo остается выбранной структурой
- локальная разработка идет через docker compose

## Risks
- возможен drift локальной среды и CI при росте проекта

## Manual QA checklist
- скопировать `.env.example` в `.env`
- поднять `docker compose up`
- открыть frontend
- проверить `/health`
- выполнить миграции

## Release notes
### Added
- project skeleton
- DB migration framework
- local compose environment
- base CI

### Changed
- initialized docs and commands

### Deferred
- observability
- staging release flow

## Recommended next stage
Stage 01 — Catalog MVP, потому что он дает первый реальный пользовательский поток.

# Stage Report — Stage 01 Catalog MVP

## Objective
Реализовать минимальный каталог товаров с карточкой товара.

## Implemented

### Backend
- добавлены модели Product и Category
- реализован `GET /products`
- реализован `GET /products/:id`
- добавлена базовая фильтрация по category

### Frontend
- создана страница каталога
- создана страница товара
- frontend подключен к реальному API
- реализованы loading/error/empty states

### Database
- добавлены таблицы `products`, `categories`
- добавлены seed-данные для демо каталога

### Infrastructure / DevEx
- CI обновлен для прогонки backend integration tests и frontend smoke

## API / contract changes
- добавлен endpoint `GET /products`
- добавлен endpoint `GET /products/:id`
- payload списка и карточки согласован с frontend

## Verification performed
### Automated checks run
- backend unit tests — passed
- backend integration tests — passed
- frontend tests — passed
- smoke scenario catalog -> product detail — passed

### Manual checks performed
- открыть `/catalog`
- открыть карточку товара
- проверить empty state при пустом каталоге

### Not verified
- pagination under large dataset
- image CDN behavior

## Acceptance criteria status
- product list works — Done
- product detail works — Done
- frontend uses real API — Done
- smoke coverage exists — Done

## Known issues
- фильтрация пока минимальная
- payload карточки пока плоский и может потребовать расширения позже

## Tech debt
- search еще не выделен в отдельный capability
- category tree пока упрощен

## Risks
- возможен рефакторинг product media model на будущих stages

## Manual QA checklist
- открыть каталог
- перейти в 3 разные карточки товара
- проверить unknown product route
- проверить category filter

## Release notes
### Added
- product catalog
- product detail page
- category-based filtering

### Changed
- repo now contains first end-to-end business flow

### Deferred
- search
- sorting
- pagination

## Recommended next stage
Stage 03 Cart MVP или Stage 02 Auth, в зависимости от выбранной стратегии guest cart vs auth-first checkout.

# Architecture Decision Records

Эта папка хранит архитектурные решения проекта.

ADR нужен, когда принято решение, которое:
- влияет на несколько модулей
- может быть пересмотрено в будущем
- важно для AI-агента и разработчиков
- несет компромиссы

Формат ADR:
- статус
- контекст
- решение
- последствия
- альтернативы

Именование:
- `0001-monorepo-structure.md`
- `0002-backend-architecture.md`
- `0003-frontend-data-fetching.md`

# /docs/adr/0001-monorepo-structure.md

# ADR 0001 — Monorepo Structure

## Status
Accepted

## Context
Проект включает frontend, backend, database migrations, docs и инфраструктурные файлы. Нужно выбрать структуру репозитория.

## Decision
Использовать monorepo со следующими крупными зонами:
- `frontend/`
- `backend/`
- `db/`
- `docs/`
- `infra/` при необходимости

## Consequences
### Positive
- единая точка входа для AI-assisted разработки
- проще синхронизировать frontend/backend contracts
- удобно хранить stage docs, ADR и runbooks рядом с кодом

### Negative
- CI может усложниться со временем
- требуется дисциплина границ между модулями

## Alternatives considered
### Multi-repo
Плюсы: сильнее изоляция.
Минусы: выше стоимость синхронизации и хуже агентный контекст.


# /docs/adr/0002-backend-architecture.md

# ADR 0002 — Backend Architecture

## Status
Accepted

## Context
Нужно выбрать достаточно простую, но расширяемую структуру backend.

## Decision
Использовать модульную структуру с разделением на:
- transport / API layer
- application layer
- domain logic
- persistence/infrastructure layer

## Consequences
### Positive
- легче тестировать бизнес-логику
- меньше риск смешивания HTTP concerns и domain rules
- AI-агенту проще делать локальные изменения без большого blast radius

### Negative
- немного больше шаблонного кода на ранних этапах

## Alternatives considered
### Fat controllers / routes
Отклонено из-за роста сложности на order/payment/admin flows.


# /docs/adr/0003-frontend-data-fetching.md

# ADR 0003 — Frontend Data Fetching

## Status
Accepted

## Context
Нужно унифицировать работу frontend с API.

## Decision
Использовать единый слой API client + query/data hooks abstraction.
Не разбрасывать fetch-логику по случайным компонентам.

## Consequences
### Positive
- легче менять payloads
- проще тестировать
- понятнее loading/error states

### Negative
- потребуется немного больше дисциплины на раннем MVP


# /docs/adr/0004-auth-strategy.md

# ADR 0004 — Auth Strategy

## Status
Accepted

## Context
Нужно выбрать модель пользовательской аутентификации для storefront и admin flows.

## Decision
Использовать email/password auth с session or refresh-token based flow.
Admin access строится на role-based authorization поверх общей identity модели.

## Consequences
### Positive
- простой MVP
- достаточно для storefront + admin
- можно расширить later with social auth

### Negative
- позже может потребоваться усиление security-потоков


# /docs/adr/0005-order-state-machine.md

# ADR 0005 — Order State Machine

## Status
Accepted

## Context
Order lifecycle влияет на checkout, payment, admin operations и user history.

## Decision
Явно описать допустимые статусы и переходы.
Например:
- draft
- pending_payment
- paid
- fulfillment_pending
- shipped
- delivered
- cancelled
- payment_failed

Переходы валидируются на сервере.

## Consequences
### Positive
- меньше хаоса в order logic
- проще тестировать transitions
- проще строить admin tools

### Negative
- потребуется поддерживать state machine при росте бизнес-правил


# /docs/adr/0006-payments-abstraction.md

# ADR 0006 — Payments Abstraction

## Status
Proposed

## Context
Система может начать с mock/stub payment flow, но позже подключить реального провайдера.

## Decision
Ввести payment service abstraction на backend, чтобы order lifecycle не зависел напрямую от деталей одного провайдера.

## Consequences
### Positive
- легче заменить / добавить payment provider
- тестирование проще

### Negative
- чуть больше абстракции на MVP

# Runbooks

Эта папка содержит практические инструкции по запуску, релизам, миграциям и реакции на известные сбои.

Хороший runbook должен отвечать на вопрос:
"Что мне делать шаг за шагом в конкретной ситуации?"

Типы runbooks:
- local development
- release process
- DB migration
- rollback
- seed data refresh
- incident response

# /docs/runbooks/local-development.md

# Runbook — Local Development

## Purpose
Запустить проект локально для повседневной разработки.

## Prerequisites
- Docker / Docker Compose
- runtime dependencies по стеку проекта
- `.env` создан из `.env.example`

## Steps
1. Скопировать `.env.example` в `.env`
2. Поднять зависимости через `docker compose up -d`
3. Применить миграции
4. Загрузить seed data
5. Запустить backend
6. Запустить frontend
7. Открыть storefront в браузере
8. Проверить backend `/health`

## Verification
- backend healthy
- frontend reachable
- DB connection works
- seed catalog visible

## Common issues
### DB connection refused
- проверить docker compose services
- проверить env values

### Frontend cannot reach API
- проверить public API base URL
- проверить CORS and proxy config


# /docs/runbooks/release-process.md

# Runbook — Release Process

## Purpose
Описать стандартный путь выпуска stage/release.

## Steps
1. Убедиться, что stage report заполнен
2. Убедиться, что review pass закрыт
3. Прогнать CI
4. Проверить миграции
5. Подготовить release notes
6. Задеплоить в staging
7. Пройти manual QA checklist
8. Выполнить production release
9. Проверить post-release smoke
10. Мониторить критичные маршруты

## Required artifacts
- stage report
- release notes
- migration notes
- rollback notes

## Post-release checks
- storefront catalog
- add to cart
- checkout entry
- admin login if relevant
- payment callback path if relevant


# /docs/runbooks/database-migration.md

# Runbook — Database Migration

## Purpose
Безопасно применить изменения схемы БД.

## Principles
- schema changes should be explicit
- risky destructive changes require review
- rollout order must be documented
- backward compatibility should be preserved when possible

## Steps
1. Просмотреть migration diff
2. Проверить impact on existing tables/data
3. Проверить rollback strategy
4. Прогнать migration на local/staging
5. Прогнать integration tests
6. Применить migration в release window
7. Проверить app health и critical queries

## Checklist
- migration tested locally
- affected code deployed in compatible order
- seed/test fixtures updated
- report mentions migration implications

## Warnings
- destructive column drops
- non-null additions without backfill
- large table rewrites without rollout plan


# /docs/runbooks/rollback.md

# Runbook — Rollback

## Purpose
Действия при неудачном релизе.

## When to use
- critical user flow broken
- severe checkout failure
- auth broken for majority of users
- migration caused instability

## Steps
1. Определить blast radius
2. Остановить дальнейший rollout
3. Откатить application release при возможности
4. Откатить feature flags if used
5. Оценить необходимость DB rollback
6. Проверить critical smoke paths
7. Зафиксировать incident notes

## Critical smoke after rollback
- catalog opens
- product detail opens
- login works
- cart works
- checkout entry works

## Notes
DB rollback не всегда безопасен. Иногда лучше делать forward fix.


# /docs/runbooks/seed-data.md

# Runbook — Seed Data

## Purpose
Заполнить локальную или тестовую среду предсказуемыми demo-данными.

## Seed goals
- categories
- products
- optional demo users
- optional demo orders for admin views

## Rules
- seed data should be deterministic enough for tests/demo
- avoid mixing production-like secrets
- keep product examples realistic but synthetic

## Recommended datasets
- 3-5 categories
- 20-50 demo products
- 1 normal user
- 1 admin user
- optional 3-5 demo orders


# /docs/runbooks/incident-checkout-failure.md

# Runbook — Incident: Checkout Failure

## Symptom
Пользователи не могут завершить checkout или создание order draft падает.

## Immediate checks
1. Проверить backend health
2. Проверить DB health
3. Проверить order creation logs
4. Проверить recent deploy / migrations
5. Проверить payment dependency only if payment step is involved

## Narrowing questions
- ломается ли создание draft order?
- ломается ли address validation?
- ломается ли recalculation?
- проблема у всех пользователей или части?

## Immediate mitigations
- rollback recent release if clearly related
- disable risky checkout path behind feature flag if available
- communicate degraded state internally

## Verification after fix
- cart -> checkout opens
- valid address accepted
- draft order created
- order visible in DB/admin tools


# /docs/runbooks/incident-payment-webhook-delay.md

# Runbook — Incident: Payment Webhook Delay

## Symptom
Оплата прошла у провайдера, но заказ долго остается в промежуточном статусе.

## Immediate checks
1. Проверить очередь / webhook receiver
2. Проверить provider callback logs
3. Проверить idempotency handling
4. Проверить order/payment reconciliation logic

## Risks
- двойная обработка callback
- заказ застрял в `pending_payment`
- пользователь видит неверный статус

## Immediate mitigations
- временно запустить reconciliation job if available
- не подтверждать вручную без проверки provider truth

## Verification after fix
- affected order status updated correctly
- duplicate webhook does not duplicate state transition
- user order history shows correct status