docs: add pre-flight checklist to AGENTS.md, commit missing plan.md

This commit is contained in:
Sergey Krylov 2026-06-20 13:47:01 +03:00
parent 23a077536c
commit 93d18f1218
2 changed files with 391 additions and 0 deletions

View File

@ -269,6 +269,18 @@ Portfolio Dashboard
Если информации недостаточно — остановиться и запросить уточнение вместо того, чтобы делать предположения. Если информации недостаточно — остановиться и запросить уточнение вместо того, чтобы делать предположения.
### Pre-flight checklist (обязателен перед реализацией любой фичи)
Агент не имеет права начать реализацию, пока не выполнены все пункты:
- [ ] Feature branch создана: `codex/<feature-name>`
- [ ] spec.md написана и утверждена пользователем
- [ ] plan.md написан и утверждён пользователем
- [ ] tasks.md создан с чекбоксами до начала работы
- [ ] Все тесты проходят на текущем состоянии
Нарушение любого пункта = остановиться и вернуться к пропущенному шагу.
### Anti-Loop: лимит на итерации ### Anti-Loop: лимит на итерации
Если после 3 последовательных неудачных попыток исправить одну и ту же проблему в рамках одной гипотезы симптом не изменился — остановиться и запросить помощь у пользователя. Если после 3 последовательных неудачных попыток исправить одну и ту же проблему в рамках одной гипотезы симптом не изменился — остановиться и запросить помощь у пользователя.

View File

@ -0,0 +1,379 @@
# Frontend FSD Shared Layer — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Создать FSD-слой `shared/` с API-инфраструктурой и truly generic UI-компонентами, используя стратегию coexistence (re-export shims) как в broker pilot.
**Architecture:** Копирование файлов из `api/``shared/api/` и `components/SkeletonBlock`, `components/TableSkeleton``shared/ui/`, превращение исходников в re-export shims, затем массовое переключение импортов на `@/shared/...`. Все изменения чисто структурные — поведение не меняется.
**Tech Stack:** React 18, TypeScript, Vite, Vitest
---
## Карта файлов
### Будут созданы
- `src/shared/api/index.ts` — barrel для shared/api
- `src/shared/api/client.ts` — базовый HTTP-клиент + доменные API-функции (копия api/client.ts)
- `src/shared/api/client.test.ts` — тесты клиента (копия)
- `src/shared/api/responses.ts` — все типы ответов (копия api/responses.ts)
- `src/shared/api/types.ts` — generated OpenAPI types (копия api/types.ts)
- `src/shared/ui/index.ts` — barrel для shared/ui
- `src/shared/ui/SkeletonBlock.tsx` — скелетон (копия components/SkeletonBlock.tsx)
- `src/shared/ui/TableSkeleton.tsx` — табличный скелетон (копия components/TableSkeleton.tsx)
### Будут изменены (становятся re-export shims)
- `src/api/client.ts`
- `src/api/responses.ts`
- `src/api/types.ts`
- `src/components/SkeletonBlock.tsx`
- `src/components/TableSkeleton.tsx`
### Будут изменены (импорты → @/shared/)
~50 файлов в `entities/`, `widgets/`, `pages/`, `hooks/`, `context/`, `components/`, `test/`
---
## Task 1: Создать shared/api/ + re-export shims
**Файлы:**
- Create: `src/shared/api/index.ts`
- Create: `src/shared/api/client.ts`
- Create: `src/shared/api/client.test.ts`
- Create: `src/shared/api/responses.ts`
- Create: `src/shared/api/types.ts`
- Modify: `src/api/client.ts` → re-export shim
- Modify: `src/api/responses.ts` → re-export shim
- Modify: `src/api/types.ts` → re-export shim
- [ ] **Step 1: Создать shared/api/ директорию**
```bash
mkdir -p apps/frontend/src/shared/api
```
- [ ] **Step 2: Скопировать api/client.ts в shared/api/client.ts**
```bash
cp apps/frontend/src/api/client.ts apps/frontend/src/shared/api/client.ts
cp apps/frontend/src/api/client.test.ts apps/frontend/src/shared/api/client.test.ts
```
- [ ] **Step 3: Скопировать api/responses.ts в shared/api/responses.ts**
```bash
cp apps/frontend/src/api/responses.ts apps/frontend/src/shared/api/responses.ts
```
- [ ] **Step 4: Скопировать api/types.ts в shared/api/types.ts**
```bash
cp apps/frontend/src/api/types.ts apps/frontend/src/shared/api/types.ts
```
- [ ] **Step 5: Создать shared/api/index.ts barrel**
```typescript
export { request, setAccessToken, getAccessToken, setOnUnauthorized, getHealth, searchSecurities, getShare, getShareMarketData, getShareDividends, getShareHistory, getBond, getBondMarketData, getBondHistory, getShareCandles, getBondCandles } from './client';
export type { ApiResponseMeta, ApiEnvelope, StockMarketData, ShareResponse, DividendItem, ShareHistoryItem, BondMarketData, BondResponse, BondHistoryItem, CandleItem, SearchResultItem, HealthResponse, UserResponse, AuthResponse, Portfolio, PositionWithPrice, PortfolioDetail, Position, PortfolioSummary, AnalyticsResponse, ScreenerItem, ScreenerResult, BrokerMoney, BrokerAccount, BrokerPosition, BrokerPortfolio, BrokerOperationCategory, BrokerOperation, BrokerOperationsPage, BrokerPositionsPage } from './responses';
```
- [ ] **Step 6: Превратить api/client.ts в re-export shim**
```typescript
export { request, setAccessToken, getAccessToken, setOnUnauthorized, getHealth, searchSecurities, getShare, getShareMarketData, getShareDividends, getShareHistory, getBond, getBondMarketData, getBondHistory, getShareCandles, getBondCandles } from '../shared/api/client';
```
- [ ] **Step 7: Превратить api/responses.ts в re-export shim**
```typescript
export type { ApiResponseMeta, ApiEnvelope, StockMarketData, ShareResponse, DividendItem, ShareHistoryItem, BondMarketData, BondResponse, BondHistoryItem, CandleItem, SearchResultItem, HealthResponse, UserResponse, AuthResponse, Portfolio, PositionWithPrice, PortfolioDetail, Position, PortfolioSummary, AnalyticsResponse, ScreenerItem, ScreenerResult, BrokerMoney, BrokerAccount, BrokerPosition, BrokerPortfolio, BrokerOperationCategory, BrokerOperation, BrokerOperationsPage, BrokerPositionsPage } from '../shared/api/responses';
```
- [ ] **Step 8: Превратить api/types.ts в re-export shim**
```typescript
export * from '../shared/api/types';
```
- [ ] **Step 9: Проверить, что тесты проходят**
Run: `npm test -w apps/frontend`
Expected: PASS
- [ ] **Step 10: Закоммитить**
```bash
git add apps/frontend/src/shared/api apps/frontend/src/api/client.ts apps/frontend/src/api/responses.ts apps/frontend/src/api/types.ts
git commit -m "refactor(frontend): create shared/api layer with re-export shims"
```
---
## Task 2: Создать shared/ui/ + re-export shims
**Файлы:**
- Create: `src/shared/ui/index.ts`
- Create: `src/shared/ui/SkeletonBlock.tsx`
- Create: `src/shared/ui/TableSkeleton.tsx`
- Modify: `src/components/SkeletonBlock.tsx` → re-export shim
- Modify: `src/components/TableSkeleton.tsx` → re-export shim
- [ ] **Step 1: Создать shared/ui/ директорию**
```bash
mkdir -p apps/frontend/src/shared/ui
```
- [ ] **Step 2: Скопировать SkeletonBlock и TableSkeleton в shared/ui/**
```bash
cp apps/frontend/src/components/SkeletonBlock.tsx apps/frontend/src/shared/ui/SkeletonBlock.tsx
cp apps/frontend/src/components/TableSkeleton.tsx apps/frontend/src/shared/ui/TableSkeleton.tsx
```
- [ ] **Step 3: Обновить shared/ui/TableSkeleton.tsx — импорт SkeletonBlock из shared/ui**
```typescript
// replace: import { SkeletonBlock } from './SkeletonBlock';
// with: import { SkeletonBlock } from '@/shared/ui/SkeletonBlock';
```
Edit `apps/frontend/src/shared/ui/TableSkeleton.tsx` line 1:
```
import { SkeletonBlock } from './SkeletonBlock'; → import { SkeletonBlock } from '@/shared/ui/SkeletonBlock';
```
- [ ] **Step 4: Создать shared/ui/index.ts barrel**
```typescript
export { SkeletonBlock } from './SkeletonBlock';
export { TableSkeleton } from './TableSkeleton';
```
- [ ] **Step 5: Превратить components/SkeletonBlock.tsx в re-export shim**
```typescript
export { SkeletonBlock } from '../shared/ui/SkeletonBlock';
```
- [ ] **Step 6: Превратить components/TableSkeleton.tsx в re-export shim**
```typescript
export { TableSkeleton } from '../shared/ui/TableSkeleton';
```
- [ ] **Step 7: Проверить, что тесты проходят**
Run: `npm test -w apps/frontend`
Expected: PASS
- [ ] **Step 8: Закоммитить**
```bash
git add apps/frontend/src/shared/ui apps/frontend/src/components/SkeletonBlock.tsx apps/frontend/src/components/TableSkeleton.tsx
git commit -m "refactor(frontend): create shared/ui layer with skeleton components"
```
---
## Task 3: Переключить импорты FSD entities/widgets/pages на @/shared/
**Файлы:** Все файлы в `entities/`, `widgets/`, `pages/` (FSD-части), которые импортируют из `api/client`, `api/responses`, `components/SkeletonBlock`, `components/TableSkeleton`.
Замена:
- `from '../../../api/responses'``from '@/shared/api/responses'`
- `from '../../../api/client'``from '@/shared/api/client'`
- `from '../../api/responses'``from '@/shared/api/responses'`
- `from '../../api/client'``from '@/shared/api/client'`
- `from '../../../components/SkeletonBlock'``from '@/shared/ui/SkeletonBlock'`
- `from '../../../components/TableSkeleton'``from '@/shared/ui/TableSkeleton'`
- `from '../../components/SkeletonBlock'``from '@/shared/ui/SkeletonBlock'`
- `from '../../components/TableSkeleton'``from '@/shared/ui/TableSkeleton'`
- [ ] **Step 1: Заменить импорты в entities/**
```bash
cd apps/frontend/src/entities
# api/responses → @/shared/api/responses (relative depth 3: ../../../)
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./\.\./api/responses'|from '@/shared/api/responses'|g"
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./\.\./api/client'|from '@/shared/api/client'|g"
```
- [ ] **Step 2: Заменить импорты в widgets/**
```bash
cd apps/frontend/src/widgets
# api/responses → @/shared/api/responses (relative depth 3: ../../../)
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./\.\./api/responses'|from '@/shared/api/responses'|g"
# components/SkeletonBlock → @/shared/ui/SkeletonBlock (relative depth 3)
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./\.\./components/SkeletonBlock'|from '@/shared/ui/SkeletonBlock'|g"
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./\.\./components/TableSkeleton'|from '@/shared/ui/TableSkeleton'|g"
```
- [ ] **Step 3: Заменить импорты в pages/ (FSD-страницы)**
```bash
cd apps/frontend/src/pages
# api/responses → @/shared/api/responses (from pages/broker-*/ and pages/broker-positions/)
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./\.\./api/responses'|from '@/shared/api/responses'|g"
# components/SkeletonBlock → @/shared/ui/SkeletonBlock
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./\.\./components/SkeletonBlock'|from '@/shared/ui/SkeletonBlock'|g"
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./\.\./components/TableSkeleton'|from '@/shared/ui/TableSkeleton'|g"
```
**Files matched and updated:**
- `entities/broker-account/api/brokerAccountApi.ts` — 2 импорта
- `entities/broker-account/model/brokerAccountsOverview.ts` — 1 импорт
- `entities/broker-account/model/brokerAccountsOverview.test.ts` — 1 импорт
- `entities/broker-account/model/useBrokerAccounts.ts` — 1 импорт
- `entities/broker-account/model/useBrokerAccountPortfolios.ts` — 1 импорт
- `entities/broker-account/model/useBrokerPortfolio.ts` — 1 импорт
- `entities/broker-position/model/useBrokerPositions.ts` — 1 импорт
- `entities/broker-position/model/brokerDisplay.ts` — 1 импорт
- `entities/broker-position/model/brokerDisplay.test.ts` — 1 импорт
- `entities/broker-position/model/brokerAllocation.ts` — 1 импорт
- `entities/broker-position/model/brokerAllocation.test.ts` — 1 импорт
- `entities/broker-operation/model/useBrokerOperations.ts` — 1 импорт
- `entities/broker-operation/model/operationFilters.ts` — 1 импорт
- `widgets/broker-account-card/ui/BrokerAccountCard.tsx` — 1 импорт + SkeletonBlock
- `widgets/broker-accounts-summary/ui/BrokerAccountsSummary.tsx` — SkeletonBlock
- `widgets/broker-allocation-chart/ui/BrokerAllocationChart.tsx` — 1 импорт
- `widgets/broker-operations-table/ui/BrokerOperationsTable.tsx` — 1 импорт + TableSkeleton
- `pages/broker-account/ui/BrokerAccountOverviewPage.tsx` — 1 импорт + SkeletonBlock
- `pages/broker-positions/ui/BrokerPositionsPage.tsx` — 1 импорт + TableSkeleton
- [ ] **Step 4: Проверить, что заменилось корректно**
```bash
cd apps/frontend/src
rg "from '\.\./\.\./\.\./api/(responses|client)'" --include '*.ts' --include '*.tsx' entities widgets pages
rg "from '\.\./\.\./\.\./components/(SkeletonBlock|TableSkeleton)'" --include '*.ts' --include '*.tsx' entities widgets pages
```
Expected: no matches (все импорты заменены)
- [ ] **Step 5: Проверить, что тесты проходят**
Run: `npm test -w apps/frontend`
Expected: PASS
- [ ] **Step 6: Закоммитить**
```bash
git add -u apps/frontend/src/entities apps/frontend/src/widgets apps/frontend/src/pages
git commit -m "refactor(frontend): update fsd entities imports to use @/shared/"
```
---
## Task 4: Переключить legacy импорты на @/shared/
**Файлы:** `hooks/`, `context/`, `components/` (legacy каталоги), `pages/` (legacy страницы), `test/`, которые импортируют из `api/client`, `api/responses`, `api/types` с относительными путями `../` или `../../`.
Замена:
- `from '../api/responses'``from '@/shared/api/responses'`
- `from '../api/client'``from '@/shared/api/client'`
- `from '../api/types'``from '@/shared/api/types'`
- `from '../../api/responses'``from '@/shared/api/responses'`
- `from '../../api/client'``from '@/shared/api/client'`
- [ ] **Step 1: Заменить импорты в hooks/**
```bash
cd apps/frontend/src/hooks
# ../api/ → @/shared/api/
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./api/responses'|from '@/shared/api/responses'|g"
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./api/client'|from '@/shared/api/client'|g"
```
- [ ] **Step 2: Заменить импорты в context/**
```bash
cd apps/frontend/src/context
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./api/responses'|from '@/shared/api/responses'|g"
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./api/client'|from '@/shared/api/client'|g"
```
- [ ] **Step 3: Заменить импорты в components/ (кроме shims)**
```bash
cd apps/frontend/src/components
# api/responses может быть на глубине ../ или ../../
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./api/responses'|from '@/shared/api/responses'|g"
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./api/responses'|from '@/shared/api/responses'|g"
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./api/client'|from '@/shared/api/client'|g"
```
- [ ] **Step 4: Заменить импорты в pages/ (legacy страницы, не FSD)**
Legacy страницы на глубине `../../` от `pages/broker/` и `../../` от `pages/portfolios/`:
```bash
cd apps/frontend/src/pages/broker
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./\.\./api/responses'|from '@/shared/api/responses'|g"
```
- [ ] **Step 5: Заменить импорты в test/**
```bash
cd apps/frontend/src/test
find . -name '*.ts' -o -name '*.tsx' | xargs sed -i '' "s|from '\.\./api/responses'|from '@/shared/api/responses'|g"
```
- [ ] **Step 6: Проверить, что не осталось относительных импортов из api/client или api/responses**
```bash
cd apps/frontend/src
rg "from '\.\./api/(responses|client|types)'" --include '*.ts' --include '*.tsx'
rg "from '\.\./\.\./api/(responses|client|types)'" --include '*.ts' --include '*.tsx'
rg "from '\.\./\.\./\.\./api/(responses|client|types)'" --include '*.ts' --include '*.tsx'
```
Expected: only shim files in `api/` itself may still have `../shared/api/` — that's correct.
- [ ] **Step 7: Проверить, что тесты проходят**
Run: `npm test -w apps/frontend`
Expected: PASS
- [ ] **Step 8: Закоммитить**
```bash
git add -u apps/frontend/src/hooks apps/frontend/src/context apps/frontend/src/components apps/frontend/src/pages apps/frontend/src/test
git commit -m "refactor(frontend): update legacy imports to use @/shared/"
```
---
## Task 5: Финальная верификация
- [ ] **Step 1: Полный прогон тестов**
Run: `npm test -w apps/frontend`
Expected: PASS
- [ ] **Step 2: Проверить lint**
Run: `npm run lint -w apps/frontend`
Expected: PASS
- [ ] **Step 3: Проверить build**
Run: `npm run build -w apps/frontend`
Expected: PASS
- [ ] **Step 4: Проверить, что все импорты корректны**
```bash
cd apps/frontend/src
# Должны остаться ТОЛЬКО импорты из api/auth, api/broker, api/portfolio, api/screener (не moved)
rg "from '\.\./(\.\./)*api/(responses|client|types)'" --include '*.ts' --include '*.tsx'
```
Expected: 0 matches (кроме shim-файлов в api/)
- [ ] **Step 5: Обновить tasks.md**
- [ ] **Step 6: Финальный коммит**
```bash
git add -A apps/frontend
git commit -m "refactor(frontend): complete shared layer migration"
```