81 lines
5.4 KiB
Markdown
81 lines
5.4 KiB
Markdown
# 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.
|