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>
2026-03-22 14:34:50 +05:00
commit 4f1b611065
4 changed files with 665 additions and 0 deletions
@@ -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/
@@ -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)         |
+
+---
+
+## Команда
+
+| Роль              | Участник           |
+|-------------------|--------------------|
+| Дизайн + контент  | О!Клиника          |
+| Разработка        | совместно с ИИ     |
+
+---
+
+*Проект разрабатывается итеративно. Документация обновляется в ходе спринтов.*
@@ -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 минимум
@@ -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 конструктор страниц
+- История версий экспериментальных компонентов
+- Мультиязычность (если потребуется)
+- Раздел «Логотип» (после получения вектора)