docs: инициализация проекта, структура репозитория и проектная документация

- README.md: стек, структура monorepo, git-workflow, быстрый старт - docs/BRANDBOOK_SCOPE.md: полный состав цифрового брендбука - docs/SPRINTS.md: план 12 недельных спринтов - .gitignore: node_modules, .env, .next, .DS_Store, .claude Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 week ago · 4f1b611065
4 changed files with 665 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,31 @@
 # Dependencies
 node_modules/
 .pnpm-store/
 # Environment
 .env
 .env.local
 .env.*.local
 # Build output
 .next/
 dist/
 build/
 # Logs
 *.log
 npm-debug.log*
 # OS
 .DS_Store
 Thumbs.db
 # IDE
 .idea/
 .vscode/settings.json
 # Prisma
 prisma/migrations/*.sql.bak
 # Claude
 .claude/
--- a/README.md
+++ b/README.md
@ -0,0 +1,205 @@
 # О!Клиника — Интерактивный брендбук
 Живой цифровой брендбук клиники «О!Клиника» (oclinica.ru).
 Формат: **Living Styleguide** — полноценное веб-приложение, где дизайнеры видят все UI-компоненты, блоки и страницы в реальном виде, а также могут создавать и сохранять экспериментальные элементы.
 ---
 ## Стек технологий
 | Слой       | Технология                  |
 |------------|-----------------------------|
 | Frontend   | Next.js (App Router)        |
 | Backend    | NestJS                      |
 | База данных| PostgreSQL                  |
 | ORM        | Prisma                      |
 | Стилизация | CSS Modules / Tailwind CSS  |
 | Шрифт      | Fira Sans (Google Fonts)    |
 ---
 ## Структура монорепозитория
 ```
 oclinica-brandbook/
 ├── apps/
 │   ├── web/          # Next.js — фронтенд брендбука
 │   └── api/          # NestJS — REST API
 ├── packages/
 │   └── tokens/       # Дизайн-токены (цвета, типографика) — shared
 ├── docs/             # Проектная документация
 │   ├── BRANDBOOK_SCOPE.md
 │   ├── SPRINTS.md
 │   └── decisions/    # ADR — Architecture Decision Records
 ├── .env.example
 ├── docker-compose.yml
 └── README.md
 ```
 ---
 ## Быстрый старт (локальная разработка)
 ### Требования
 - Node.js >= 20
 - pnpm >= 9
 - Docker (для PostgreSQL)
 ### 1. Клонировать репозиторий
 ```bash
 git clone <repo-url>
 cd oclinica-brandbook
 ```
 ### 2. Установить зависимости
 ```bash
 pnpm install
 ```
 ### 3. Настроить окружение
 ```bash
 cp .env.example .env
 # Отредактировать .env — указать DATABASE_URL и другие переменные
 ```
 ### 4. Запустить PostgreSQL через Docker
 ```bash
 docker-compose up -d
 ```
 ### 5. Применить миграции Prisma
 ```bash
 cd apps/api
 pnpm prisma migrate dev
 pnpm prisma db seed  # опционально — тестовые данные
 ```
 ### 6. Запустить проект
 ```bash
 # Из корня монорепозитория
 pnpm dev
 # web: http://localhost:3000
 # api: http://localhost:3001
 ```
 ---
 ## Переменные окружения
 Создайте `.env` в корне на основе `.env.example`:
 ```env
 # База данных
 DATABASE_URL="postgresql://user:password@localhost:5432/brandbook"
 # API
 API_PORT=3001
 API_URL=http://localhost:3001
 # Web
 NEXT_PUBLIC_API_URL=http://localhost:3001
 ```
 ---
 ## Git-workflow
 ### Ветки
 | Ветка         | Назначение                                      |
 |---------------|-------------------------------------------------|
 | `main`        | Стабильный production-ready код                 |
 | `develop`     | Интеграционная ветка, основа для спринтов       |
 | `sprint/N`    | Ветка текущего спринта (например `sprint/2`)    |
 | `feature/xxx` | Конкретная фича или компонент                   |
 | `fix/xxx`     | Исправление бага                                |
 ### Процесс работы
 ```
 main ← develop ← sprint/N ← feature/component-name
 ```
 1. Новую задачу начинаем с ветки от `sprint/N`:
   ```bash
   git checkout develop
   git checkout -b feature/hero-block
   ```
 2. Коммитим по конвенции (см. ниже)
 3. Открываем PR в `sprint/N` (или напрямую в `develop` для мелких правок)
 4. В конце спринта `sprint/N` мержится в `develop`
 5. После тестирования `develop` мержится в `main` и деплоится
 ### Конвенция коммитов (Conventional Commits)
 ```
 <type>(<scope>): <описание на русском или английском>
 feat(colors): добавлена цветовая палитра primary
 fix(button): исправлен hover-стейт для ghost-кнопки
 docs(readme): обновлена инструкция по запуску
 refactor(card): вынесен компонент DoctorCard
 style(typography): выровнены размеры заголовков
 chore(deps): обновлена версия Prisma
 ```
 Типы: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
 ---
 ## Деплой
 ### Production (сервер)
 ```bash
 # На сервере
 pnpm build
 pnpm start
 ```
 ### Docker (опционально)
 ```bash
 docker-compose -f docker-compose.prod.yml up -d
 ```
 > Подробности деплоя — в `docs/deployment.md` (создаётся в ходе разработки)
 ---
 ## Структура базы данных (схема Prisma)
 Основные модели:
 - `Component` — экспериментальный компонент (name, html, css, status, author)
 - `Page` — экспериментальная страница (name, blocks[], status)
 - `Block` — блок страницы (name, componentId, order)
 ---
 ## Документация
 | Файл                       | Содержание                          |
 |----------------------------|-------------------------------------|
 | `docs/BRANDBOOK_SCOPE.md`  | Полный состав брендбука             |
 | `docs/SPRINTS.md`          | План спринтов                       |
 | `docs/decisions/`          | Архитектурные решения (ADR)         |
 ---
 ## Команда
 | Роль              | Участник           |
 |-------------------|--------------------|
 | Дизайн + контент  | О!Клиника          |
 | Разработка        | совместно с ИИ     |
 ---
 *Проект разрабатывается итеративно. Документация обновляется в ходе спринтов.*
--- a/docs/BRANDBOOK_SCOPE.md
+++ b/docs/BRANDBOOK_SCOPE.md
@ -0,0 +1,180 @@
 # Содержание брендбука — Клиника «О!Клиника» (oclinica.ru)
 > Документ описывает полный состав интерактивного цифрового брендбука.
 > Формат: Living Styleguide — веб-приложение для дизайнеров (внутренних и внешних подрядчиков).
 ---
 ## 1. Фундамент бренда (Brand Foundation)
 ### 1.1 Цветовая палитра
 - Основные цвета (Primary) — из файла брендбука клиники
 - Дополнительные цвета (Secondary)
 - Нейтральные / серые оттенки
 - Цвета состояний UI: success, warning, error, info
 - Для каждого цвета: hex, RGB, HSL, название, рекомендации по применению
 - Примеры сочетаний (color pairs) с проверкой контрастности (WCAG AA)
 ### 1.2 Типографика
 - Шрифт: **Fira Sans** (веса 300, 400)
 - Шкала размеров: h1–h6, body, caption, label, overline
 - Межстрочный интервал, межбуквенный интервал для каждого стиля
 - Правила использования: жирный, курсив, caps
 - Примеры живого текста (заголовки, абзацы, списки)
 ### 1.3 Логотип
 - Основная версия (светлый фон)
 - Инвертированная версия (тёмный фон)
 - Монохромная версия
 - Охранная зона (минимальные отступы)
 - Минимальные размеры
 - Недопустимые варианты использования
 - Скачивание файлов (SVG, PNG)
 > ⏳ Логотип будет добавлен после получения вектора
 ### 1.4 Иконография
 - Принципы выбора иконок
 - Рекомендованная сторонняя библиотека (определяется в процессе разработки)
 - Размеры: 16px, 20px, 24px, 32px
 - Правила цвета иконок
 ---
 ## 2. Базовые UI-компоненты (Components)
 ### 2.1 Кнопки (Buttons)
 - Primary, Secondary, Ghost/Outline, Danger
 - Размеры: sm, md, lg
 - Состояния: default, hover, active, focus, disabled, loading
 - Иконка + текст, только иконка
 ### 2.2 Поля ввода (Form Controls)
 - Text input: default, focus, error, success, disabled
 - Textarea
 - Select / Dropdown
 - Checkbox (одиночный, группа)
 - Radio button (группа)
 - Toggle/Switch
 - Подписи (label), подсказки (hint), сообщения об ошибках
 ### 2.3 Бейджи и теги (Badges & Tags)
 - Бейджи статуса (цветные)
 - Теги фильтрации
 - Счётчики (notification badge)
 ### 2.4 Алерты и уведомления
 - Inline: info, success, warning, error
 - Toast-уведомления
 ### 2.5 Карточки (Cards)
 - Карточка врача (фото, имя, специализация, кнопка записи)
 - Карточка услуги / заболевания
 - Карточка новости (превью, дата, заголовок, анонс)
 - Карточка отзыва (автор, текст, рейтинг, дата)
 - Карточка цены (услуга, стоимость, описание)
 ### 2.6 Модальные окна
 - Информационное
 - Форма записи на приём
 - Подтверждение действия
 ### 2.7 Навигация
 - Главное меню (header nav)
 - Мобильное меню (бургер)
 - Хлебные крошки (breadcrumbs)
 - Пагинация
 ### 2.8 Таблицы
 - Базовая таблица цен
 - Таблица с сортировкой
 ---
 ## 3. Блоки страниц (Page Blocks / Sections)
 ### 3.1 Hero-блок
 - Вариант с фоновым изображением + заголовок + CTA-кнопка
 - Вариант с иллюстрацией сбоку
 - Вариант с формой записи внутри
 ### 3.2 CEO / Вступительный текст
 - Блок с фото руководителя/главного врача
 - Цитата, подпись, должность
 ### 3.3 Наши врачи
 - Сетка карточек врачей (3–4 в ряд)
 - Фильтрация по специализации
 - Кнопка «Все врачи»
 ### 3.4 Отзывы пациентов
 - Карусель отзывов
 - Статичная сетка
 - Блок рейтинга (звёзды, количество)
 ### 3.5 Новости / Статьи
 - Сетка превью (3 в ряд)
 - Горизонтальный список
 - Блок «Последние новости» (сайдбар)
 ### 3.6 Форма контакта / Запись на приём
 - Короткая форма (имя, телефон, кнопка)
 - Расширенная форма (имя, телефон, специализация, врач, дата)
 - Форма в модальном окне
 ### 3.7 Контактный блок
 - Карта + адрес + часы работы
 - Схема проезда
 ### 3.8 Услуги / Заболевания
 - Сетка иконок с названиями
 - Список с описанием
 ### 3.9 Преимущества клиники
 - Иконки + текст (3–4 колонки)
 ---
 ## 4. Страницы (Pages)
 Каждая страница показывается в брендбуке как полноразмерный макет, собранный из утверждённых блоков.
 | Страница           | Ключевые блоки                                                       |
 |--------------------|----------------------------------------------------------------------|
 | Главная            | Hero, Преимущества, Наши врачи, Услуги, Отзывы, Новости, Форма записи |
 | Заболевание        | Hero (мини), CEO-текст, Описание, Врачи по теме, Форма контакта      |
 | Все врачи          | Фильтры, Сетка карточек врачей, Пагинация                           |
 | Врач (профиль)     | Фото + инфо, Специализации, Расписание, Форма записи, Отзывы         |
 | Цены               | Фильтры, Таблица цен, Форма контакта                                |
 | Контакты           | Карта, Адрес + часы, Форма контакта                                  |
 ---
 ## 5. Экспериментальная секция (Experimental)
 > Ключевая особенность брендбука — возможность создавать и сохранять новые компоненты и страницы прямо в интерфейсе.
 ### 5.1 Конструктор компонентов
 - Создание нового компонента через UI
 - Редактирование параметров (цвет, размер, текст)
 - Сохранение в базу данных
 - Статус: draft / review / approved
 ### 5.2 Конструктор страниц
 - Drag-and-drop сборка страницы из блоков
 - Сохранение как эксперимент
 - История версий
 ### 5.3 Библиотека экспериментов
 - Список всех экспериментальных компонентов/страниц
 - Фильтрация по статусу
 - Возможность «утвердить» и перенести в основную секцию
 ---
 ## 6. Технические требования брендбука
 - Адаптивность: desktop (1440px), tablet (768px), mobile (375px)
 - Темная тема (опционально, обсудить)
 - Копирование CSS/кода компонента в один клик
 - Экспорт цветов в Figma-токены (JSON)
 - Доступность: WCAG AA минимум
--- a/docs/SPRINTS.md
+++ b/docs/SPRINTS.md
@ -0,0 +1,249 @@
 # План спринтов — Брендбук О!Клиника
 > Недельные спринты. Каждый спринт = 1 рабочая неделя.
 > Базовая дата начала: уточняется при старте разработки.
 ---
 ## Обозначения
 - **FE** — задача фронтенда (Next.js)
 - **BE** — задача бэкенда (NestJS + Prisma)
 - **DB** — изменения схемы базы данных
 - **Design** — дизайн-решения, требующие согласования
 ---
 ## Sprint 1 — Инициализация проекта
 **Цель:** Рабочее окружение, monorepo, базовая архитектура.
 ### Задачи
 - [ ] FE: Инициализация Next.js (App Router) в `apps/web`
 - [ ] BE: Инициализация NestJS в `apps/api`
 - [ ] DB: Подключение PostgreSQL + Prisma, базовая схема
 - [ ] Настройка Docker Compose для локальной разработки
 - [ ] Настройка monorepo (pnpm workspaces)
 - [ ] Создание `.env.example`
 - [ ] Git: инициализация репозитория, ветки `main` и `develop`
 - [ ] FE: Базовая структура брендбука (layout, навигация по секциям)
 - [ ] FE: Подключение шрифта Fira Sans
 **Результат спринта:** Запускается `pnpm dev` — открывается пустой брендбук с навигацией.
 ---
 ## Sprint 2 — Цвета и типографика (Brand Foundation)
 **Цель:** Секция «Фундамент бренда» — цвета и шрифты живые в брендбуке.
 ### Задачи
 - [ ] Design: Получить и зафиксировать все цвета из файла брендбука клиники
 - [ ] FE: Создать CSS-переменные / дизайн-токены для всей цветовой палитры
 - [ ] FE: Страница «Цвета» — отображение палитры с hex/RGB/HSL, копирование в клик
 - [ ] FE: Страница «Типографика» — все стили текста (h1–h6, body, caption и т.д.)
 - [ ] FE: Живые примеры типографики с Fira Sans
 - [ ] FE: Экспорт токенов в JSON (Figma-compatible)
 - [ ] Design: Согласование охранных зон и правил применения цветов
 **Результат спринта:** Раздел «Фундамент» полностью готов (без логотипа).
 ---
 ## Sprint 3 — Базовые компоненты: кнопки и поля ввода
 **Цель:** Все варианты кнопок и форм-контролов в брендбуке.
 ### Задачи
 - [ ] FE: Компонент Button (все варианты: primary/secondary/ghost/danger, размеры, состояния)
 - [ ] FE: Компонент Input (text, password, focus/error/disabled)
 - [ ] FE: Компонент Textarea
 - [ ] FE: Компонент Select
 - [ ] FE: Компонент Checkbox и Radio
 - [ ] FE: Компонент Toggle/Switch
 - [ ] FE: Страница брендбука «Компоненты → Кнопки» с документацией
 - [ ] FE: Страница брендбука «Компоненты → Форм-контролы»
 - [ ] FE: Копирование HTML/CSS кода компонента в один клик
 **Результат спринта:** Раздел «Базовые компоненты — кнопки и ввод» готов.
 ---
 ## Sprint 4 — Карточки (Cards)
 **Цель:** Все типы карточек, используемых на сайте.
 ### Задачи
 - [ ] FE: Карточка врача (DoctorCard) — фото, имя, специализация, кнопка записи
 - [ ] FE: Карточка услуги / заболевания
 - [ ] FE: Карточка новости — превью, дата, заголовок, анонс, читать далее
 - [ ] FE: Карточка отзыва — автор, текст, рейтинг (звёзды), дата
 - [ ] FE: Карточка цены — услуга, стоимость, описание
 - [ ] FE: Бейджи, теги, алерты (inline и toast)
 - [ ] FE: Страница «Компоненты → Карточки» с документацией
 **Результат спринта:** Все карточки задокументированы и показаны в брендбуке.
 ---
 ## Sprint 5 — Hero-блок и CEO-текст
 **Цель:** Ключевые верхние блоки страниц.
 ### Задачи
 - [ ] FE: Hero-блок вариант 1 — фон + заголовок + CTA
 - [ ] FE: Hero-блок вариант 2 — иллюстрация сбоку
 - [ ] FE: Hero-блок вариант 3 — с встроенной формой записи
 - [ ] FE: Блок CEO-текст — фото руководителя, цитата, подпись
 - [ ] FE: Блок «Преимущества клиники» — иконки + текст
 - [ ] FE: Страница «Блоки → Hero и вступление»
 - [ ] Design: Согласование вариантов Hero под разные страницы
 **Результат спринта:** Hero и CEO-секция полностью задокументированы.
 ---
 ## Sprint 6 — Врачи и профиль врача
 **Цель:** Блоки и компоненты, связанные с врачами.
 ### Задачи
 - [ ] FE: Блок «Наши врачи» — сетка карточек с фильтром по специализации
 - [ ] FE: Блок «Врач — профиль» (полная страница): фото, биография, специализации, расписание
 - [ ] FE: Компонент «Расписание / слоты записи»
 - [ ] FE: Компонент навигации (header menu, breadcrumbs)
 - [ ] FE: Пагинация
 - [ ] FE: Страница «Блоки → Врачи»
 **Результат спринта:** Все блоки о врачах готовы.
 ---
 ## Sprint 7 — Отзывы и новости
 **Цель:** Контентные блоки сайта.
 ### Задачи
 - [ ] FE: Блок отзывов — карусель
 - [ ] FE: Блок отзывов — статичная сетка
 - [ ] FE: Блок рейтинга (звёзды + количество отзывов)
 - [ ] FE: Блок новостей — сетка превью (3 в ряд)
 - [ ] FE: Блок новостей — горизонтальный список
 - [ ] FE: Блок «Последние новости» для сайдбара
 - [ ] FE: Блок услуг / заболеваний — иконки + список
 - [ ] FE: Страница «Блоки → Отзывы и новости»
 **Результат спринта:** Контентные блоки задокументированы.
 ---
 ## Sprint 8 — Формы контакта и модальные окна
 **Цель:** Все формы и диалоги взаимодействия с пациентом.
 ### Задачи
 - [ ] FE: Форма записи — короткая (имя, телефон)
 - [ ] FE: Форма записи — расширенная (имя, телефон, специализация, врач, дата)
 - [ ] FE: Форма записи в модальном окне
 - [ ] FE: Контактная форма (имя, email, сообщение)
 - [ ] FE: Блок «Контакт» — карта + адрес + часы работы
 - [ ] FE: Модальное окно — информационное
 - [ ] FE: Модальное окно — подтверждение
 - [ ] FE: Страница «Блоки → Формы и контакты»
 **Результат спринта:** Все формы и диалоги готовы.
 ---
 ## Sprint 9 — Страницы: Главная и Заболевание
 **Цель:** Первые две полноразмерные страницы в брендбуке.
 ### Задачи
 - [ ] FE: Страница «Главная» — сборка из утверждённых блоков
 - [ ] FE: Страница «Заболевание» — Hero (мини), описание, врачи по теме, форма
 - [ ] FE: Раздел «Страницы» в навигации брендбука
 - [ ] FE: Адаптивность страниц (desktop / tablet / mobile)
 - [ ] Design: Ревью и согласование страниц
 **Результат спринта:** 2 страницы задокументированы в брендбуке.
 ---
 ## Sprint 10 — Страницы: Врачи, Врач, Цены
 **Цель:** Три страницы с ключевым контентом.
 ### Задачи
 - [ ] FE: Страница «Все врачи» — фильтры, сетка, пагинация
 - [ ] FE: Страница «Врач (профиль)»
 - [ ] FE: Страница «Цены» — фильтры, таблица, форма
 - [ ] FE: Таблица цен с сортировкой
 - [ ] FE: Адаптивность всех трёх страниц
 - [ ] Design: Ревью страниц
 **Результат спринта:** Ещё 3 страницы в брендбуке.
 ---
 ## Sprint 11 — Страница Контакты и Экспериментальная секция (MVP)
 **Цель:** Последняя страница + запуск механизма экспериментов.
 ### Задачи
 - [ ] FE: Страница «Контакты»
 - [ ] BE + DB: Модели `Component`, `Page`, `Block` в Prisma
 - [ ] BE: CRUD API для компонентов (`/api/components`)
 - [ ] BE: CRUD API для страниц (`/api/pages`)
 - [ ] FE: Секция «Эксперименты» в брендбуке
 - [ ] FE: Форма создания нового экспериментального компонента
 - [ ] FE: Список экспериментальных компонентов со статусами
 **Результат спринта:** Все страницы готовы, эксперименты — базовый функционал.
 ---
 ## Sprint 12 — Деплой, полировка, документация
 **Цель:** Финальный релиз и публикация.
 ### Задачи
 - [ ] BE + FE: Полный smoke-тест всего брендбука
 - [ ] FE: Мобильная адаптация — финальная проверка всех страниц
 - [ ] FE: Accessibility-аудит (WCAG AA)
 - [ ] Деплой: настройка CI/CD, публикация на сервере
 - [ ] Docs: Создание `docs/deployment.md`
 - [ ] Docs: Обновление README.md финальными инструкциями
 - [ ] Design: Финальный ревью брендбука
 **Результат спринта:** Брендбук задеплоен и доступен по URL.
 ---
 ## Сводная таблица
 | Спринт | Тема                                  | Ключевой результат                      |
 |--------|---------------------------------------|-----------------------------------------|
 | 1      | Инициализация                         | Запускается пустой брендбук             |
 | 2      | Цвета и типографика                   | Раздел «Фундамент» готов                |
 | 3      | Кнопки и форм-контролы                | Базовые компоненты готовы               |
 | 4      | Карточки                              | Все карточки задокументированы          |
 | 5      | Hero и CEO-текст                      | Ключевые блоки страниц готовы           |
 | 6      | Врачи                                 | Блоки о врачах готовы                   |
 | 7      | Отзывы и новости                      | Контентные блоки готовы                 |
 | 8      | Формы и модальные окна                | Все формы задокументированы             |
 | 9      | Страницы: Главная, Заболевание        | 2 страницы в брендбуке                  |
 | 10     | Страницы: Врачи, Цены                 | 3 страницы в брендбуке                  |
 | 11     | Контакты + Эксперименты MVP           | Все страницы + система экспериментов    |
 | 12     | Деплой и полировка                    | Брендбук живёт в продакшне              |
 ---
 ## Backlog (вне основных спринтов)
 - Тёмная тема
 - Экспорт компонентов в Figma
 - Drag-and-drop конструктор страниц
 - История версий экспериментальных компонентов
 - Мультиязычность (если потребуется)
 - Раздел «Логотип» (после получения вектора)