60 lines
3.4 KiB
Markdown
60 lines
3.4 KiB
Markdown
# VoIdea — Specification
|
|
|
|
## Overview
|
|
|
|
VoIdea ("Голос Идей") — гибридное приложение для фиксации и проработки идей с помощью группового ИИ-анализа. Работает как PWA (устанавливается на телефон), с перспективой нативных iOS/Android-клиентов.
|
|
|
|
## Stack & Rationale
|
|
|
|
| Layer | Choice | Why |
|
|
|-------|--------|-----|
|
|
| Frontend framework | React 18.3 LTS | Стабильность, экосистема, перспектива React 19 |
|
|
| Language | TypeScript 5.5 strict | Типобезопасность, самодокументируемость |
|
|
| Styling | Tailwind CSS 3.4 | Utility-first, тёмная тема из коробки, PWA-ready |
|
|
| State management | Zustand | 1.1 KB, без Provider, работает вне React (можно читать токен в api/client) |
|
|
| Forms | react-hook-form + zod | Валидация через схему = один источник истины (типы TS = runtime) |
|
|
| Routing | react-router-dom 6 | Стандарт React |
|
|
| PWA | vite-plugin-pwa | Service worker + manifest из коробки |
|
|
| Build | Vite 5 | Быстрая сборка, HMR |
|
|
| Backend | FastAPI (Python) | Асинхронный, Pydantic-валидация |
|
|
| Database | PostgreSQL | ACID, JSONB |
|
|
| Queue | Celery + Redis | AI-вызовы, бэкапы, email |
|
|
|
|
## Key Decisions
|
|
|
|
### Zustand over Context
|
|
- Context ререндерит ВСЕХ подписчиков при изменении. Zustand — только тех, кто читает изменившееся поле.
|
|
- Zustand-стор можно читать вне React (в `api/client.ts` для token refresh).
|
|
- Для существующего `AuthContext` — постепенный перенос в `stores/auth.ts`.
|
|
|
|
### react-hook-form + zod over native forms
|
|
- Валидация через zod-схему: TypeScript тип = runtime тип, расхождение невозможно.
|
|
- `errors` из коробки, `isSubmitting`, `dirty`/`touched`.
|
|
- Для простых форм (2 поля: логин) — можно оставить нативный `<form>`.
|
|
|
|
### WCAG AA
|
|
- Целевой уровень доступности: AA (стандарт для РФ/ЕС).
|
|
- Enforcement: eslint-plugin-jsx-a11y в CI.
|
|
|
|
### Error Boundaries
|
|
- Глобальный ErrorBoundary — защита от белого экрана.
|
|
- Per-page для VoiceChat (голосовые API могут падать).
|
|
|
|
### i18n
|
|
- Сейчас: только русский.
|
|
- Но строки вынесены в `constants/strings.ts`, рендерятся через `<T>`, что позволит перейти на react-i18next без переписывания UI.
|
|
|
|
## Project Documentation Map
|
|
|
|
```
|
|
PROJECT_GUIDE.md ← навигатор по всей документации
|
|
├── SPECIFICATION.md ← этот файл
|
|
├── TECHNICAL.md ← архитектура и схемы
|
|
├── STYLE_GUIDE.md ← код-стайл webui
|
|
├── versioning.md ← версионирование
|
|
├── user-guide.md ← пользовательская инструкция
|
|
├── admin-guide.md ← администрирование
|
|
├── docs/blocks/ ← блоки правил
|
|
└── docs/design-system/ ← дизайн-токены + генераторы
|
|
```
|