moex-vibe/AGENTS.md

MoexVibe — Инструкция для агента

Репозиторий

npm workspaces монорепозиторий: apps/backend (NestJS), apps/frontend (React + Vite), apps/docs (Docusaurus).

Обязательный подход к разработке

• SDD (Specification-Driven Development): перед написанием кода сначала сформировать спецификацию — PRD, доменную модель, ADR, OpenAPI-контракт, архитектуру фронтенда и бэкенда, план реализации по этапам.
• Superpowers: обязательно использовать скиллы (Skills) при старте любой задачи — brainstorming, frontend-design, test-driven-development, writing-plans, executing-plans, requesting-code-review.
• MCP-инструменты: использовать MCP для анализа и генерации дизайна, работы с API, генерации кода.

Команды

Команда	Что делает
npm run dev:backend	Запуск NestJS в режиме watch на :3000
npm run dev:frontend	Vite dev-сервер на :5173, проксирует /api → :3000
npm run dev:docs	Docusaurus dev-сервер
npm run build:backend	nest build
npm run build:frontend	tsc -b && vite build (в две фазы)
npm run build:docs	docusaurus build
npm run test:backend	vitest run (SWC, не ts-jest)
npm run test:frontend	Frontend Vitest suite
npm run lint	ESLint для backend и frontend
npm run format	Prettier для всех *.{ts,tsx}
npm run codegen -w apps/frontend	openapi-typescript из локального Swagger → src/api/types.ts

Live MOEX integration tests opt-in: npm run test:integration -w apps/backend.

Один тест: npx vitest run path/to/test.spec.ts -w apps/backend

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

Переменная	По умолчанию	Описание
PORT	3000	Порт бэкенда
MOEX_BASE_URL	https://iss.moex.com/iss	Endpoint MOEX ISS
MOEX_RATE_LIMIT	10	Запросов/с к MOEX
CACHE_MARKET_DATA_TTL	900	TTL рыночных данных (с)
CACHE_HISTORY_TTL	3600	TTL истории (с)
CACHE_CANDLES_TTL	3600	TTL свечей (с)
CACHE_SECURITY_TTL	86400	TTL спецификации (с)
CACHE_SEARCH_TTL	3600	TTL результатов поиска (с)
DATABASE_URL	file:./dev.db	URL SQLite для Prisma
JWT_SECRET	dev-jwt-secret-...	Secret для access token
JWT_REFRESH_SECRET	dev-refresh-secret-...	Secret для refresh token
JWT_ACCESS_EXPIRES	15m	TTL access token
JWT_REFRESH_EXPIRES	7d	TTL refresh token

Архитектура

• Бэкенд — единственный клиент MOEX. Фронтенд никогда не обращается к MOEX напрямую.
• Feature-модули: PrismaModule (глобальный), MoexClientModule (глобальный), CacheModule (глобальный), AuthModule, SharesModule, BondsModule, SecuritiesModule, CandlesModule, PortfolioModule, HealthModule.
• MoexClientService использует p-queue (rate limiter) + circuit breaker (5 ошибок → 30s открыт).
• In-memory кеш через @nestjs/cache-manager. Путь миграции на Redis описан (см. ADR-002).
• Аутентификация: JWT access token (15m, в памяти) + refresh token (7d, httpOnly cookie, bcrypt hash в БД). Глобальный JwtAuthGuard (@Public() для открытых эндпоинтов).
• БД: SQLite через Prisma ORM. Prisma client генерируется в src/generated/prisma/.
• Глобальный префикс NestJS: /api/v1. Swagger: /api/docs.
• Глобальный ValidationPipe (transform: true, whitelist: true), HttpExceptionFilter, TransformInterceptor, middleware логирования запросов.
• Ответы API обёрнуты в { data: T, meta: { fromCache, cachedAt } }.
• Алиасы: @/* → src/* в обоих пакетах.

Фронтенд

• React 18 + react-router-dom v6 + TanStack Query v5.
• lightweight-charts v4 для графиков цен.
• openapi-fetch + рукописные типы responses.ts (не полностью codegen'овые).
• TanStack Query по умолчанию: staleTime: 900s, retry: 2, refetchOnWindowFocus: false.
• Конвенция ключей запросов: ['stock', secid], ['securities', 'search', query], и т.д.
• CSS через styles.css (CSS custom properties, без CSS-in-JS или Tailwind).

Стиль кода

• Prettier: одинарные кавычки, trailing commas, printWidth 100, точки с запятой.
• Бэкенд: const, PascalCase для модулей/контроллеров/сервисов, DTO в dto/ внутри каждого модуля.
• Бэкенд использует SWC через unplugin-swc (vitest config).
• Тесты фронтенда есть: Vitest + Testing Library + MSW.
• CI находится в .gitea/workflows/ci.yml.
• Pre-commit checks настроены через Husky и lint-staged.