refactor: align frontend with FSD architecture

README.md

@@ -1,28 +1,116 @@
 # Analytical Panel
 
-Vue 3 application scaffolded with Vite and Bun.
+Frontend-приложение аналитической панели карты компетенций.
 
 ## Stack
 
-- Vue 3
+- Vue 3 + `<script setup>`
 - Vite
 - Bun
 - TypeScript
 - Vue Router
 - Pinia
+- TanStack Vue Query
+- Orval
+- Zod / Vee Validate
+- Tailwind CSS
+- Local shadcn/reka-based UI-kit
 - ESLint
 - Prettier
+- Steiger FSD lint
 - Vitest
 - Playwright
 
+## Quick Start
+
+```bash
+bun install
+cp .env.example .env
+bun run dev
+```
+
+Dev server uses Vite proxy for `/api` and `/health`.
+
+## Environment
+
+```text
+VITE_DEV_API_PROXY_TARGET=https://anal-back.dev.nii-ecos.ru
+```
+
+Optional UI-kit map components may read `VITE_MAPTILER_KEY`, but the current analytical panel flow
+does not require it.
+
 ## Commands
 
 ```bash
-bun install
-bun run dev
-bun run lint
-bun run typecheck
-bun run test:unit
-bun run test:e2e
-bun run build
+bun run dev            # local Vite dev server
+bun run build          # typecheck + production build
+bun run preview        # preview production build
+bun run lint           # ESLint
+bun run lint:fsd       # Steiger FSD lint
+bun run format:check   # Prettier check
+bun run test:unit      # Vitest
+bun run test:e2e       # Playwright
+bun run check          # lint + FSD lint + unit + build
+bun run check:full     # check + Playwright E2E
+bun run apigen         # regenerate API clients from openapi.json
 ```
+
+Before handoff use:
+
+```bash
+bun run format:check
+bun run check:full
+```
+
+## Architecture
+
+The project follows Feature-Sliced Design in a pragmatic form.
+
+Main docs:
+
+- `docs/review.md` - detailed review, refactoring plan and current status.
+- `docs/architecture.md` - FSD structure and import rules.
+- `docs/generated-api.md` - Orval/generated API workflow.
+- `docs/testing.md` - test policy and remaining coverage gaps.
+
+Key source areas:
+
+```text
+src/app/                         # router, providers, app styles
+src/pages/auth/                  # auth page
+src/pages/dashboard/             # dashboard page, model, API wrappers, UI
+src/widgets/protected-app-layout/ # protected shell, sidebar behavior, logout orchestration
+src/entities/user/               # current user entity model
+src/shared/api/                  # API client, token/session primitives, generated API facade
+src/shared/ui/                   # pure shared UI
+src/shared/ui-kit/               # local design system/vendor UI-kit
+```
+
+## Generated API
+
+Generated files live in:
+
+```text
+src/shared/api/generated-api/
+src/shared/model/generated-zod/
+```
+
+Do not edit them manually. Update `openapi.json`, then run:
+
+```bash
+bun run apigen
+```
+
+Application code should import API functions and DTO types through `@/shared/api`, not directly
+from `generated-api`.
+
+## Known Build Warnings
+
+Production build currently passes with warnings:
+
+- `INVALID_ANNOTATION` from `node_modules/@vueuse/core/dist/index.js`;
+- main `index-*.js` chunk is larger than 500 kB.
+
+These warnings are documented in `docs/testing.md` and should be handled in a separate
+bundle/performance pass.