commit 4f1b6110656bda689d33ec296ff063e8daedf022 Author: AR 15 M4 Date: Sun Mar 22 14:34:50 2026 +0500 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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..15b04bc --- /dev/null +++ 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/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..8011003 --- /dev/null +++ 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 +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) + +``` +(): <описание на русском или английском> + +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) | + +--- + +## Команда + +| Роль | Участник | +|-------------------|--------------------| +| Дизайн + контент | О!Клиника | +| Разработка | совместно с ИИ | + +--- + +*Проект разрабатывается итеративно. Документация обновляется в ходе спринтов.* diff --git a/docs/BRANDBOOK_SCOPE.md b/docs/BRANDBOOK_SCOPE.md new file mode 100644 index 0000000..74f46ab --- /dev/null +++ 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 минимум diff --git a/docs/SPRINTS.md b/docs/SPRINTS.md new file mode 100644 index 0000000..54760f4 --- /dev/null +++ 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 конструктор страниц +- История версий экспериментальных компонентов +- Мультиязычность (если потребуется) +- Раздел «Логотип» (после получения вектора)