Browse Source

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>
sprint/1
AR 15 M4 1 week ago
commit
4f1b611065
  1. 31
      .gitignore
  2. 205
      README.md
  3. 180
      docs/BRANDBOOK_SCOPE.md
  4. 249
      docs/SPRINTS.md

31
.gitignore vendored

@ -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/

205
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) |
---
## Команда
| Роль | Участник |
|-------------------|--------------------|
| Дизайн + контент | О!Клиника |
| Разработка | совместно с ИИ |
---
*Проект разрабатывается итеративно. Документация обновляется в ходе спринтов.*

180
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 минимум

249
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 конструктор страниц
- История версий экспериментальных компонентов
- Мультиязычность (если потребуется)
- Раздел «Логотип» (после получения вектора)
Loading…
Cancel
Save