Цифровой бренд бук клиники. Описание элементов сайта: цвета, шрифты, блоки, формы, страницы

28 KiB

Raw Blame History

Техническое задание

Цифровой брендбук Клиники ухо, горло, нос им. проф. Е.Н. Оленевой

`oclinica-brandbook`

Версия: 1.0-draft Дата: 2026-03-22 Статус: На согласовании

Содержание

Общие сведения
Назначение и цели
Пользователи системы
Границы системы
Функциональные требования
Требования к интеграциям
Требования к данным
Нефункциональные требования
Технический стек
Архитектура системы
Безопасность и авторизация
Требования к окружению
Ограничения и допущения
Открытые вопросы

1. Общие сведения

Параметр	Значение
Полное название	Цифровой брендбук Клиники ухо, горло, нос им. проф. Е.Н. Оленевой
Краткое название	oclinica-brandbook
Сайт клиники	https://oclinica.ru
Тип системы	Веб-приложение (Living Styleguide)
Режим работы	Локальная разработка + деплой на сервер
Аудитория	Внутренние дизайнеры клиники, внешние подрядчики
Хостинг	TBD — будет прописан отдельно

2. Назначение и цели

2.1 Назначение

oclinica-brandbook — интерактивное веб-приложение, которое служит единым источником правды о визуальном языке клиники. Оно содержит все UI-компоненты, блоки страниц и полные страницы сайта в живом виде — с кодом, документацией и реальными данными.

Дополнительно система позволяет дизайнерам создавать экспериментальные компоненты и страницы непосредственно в интерфейсе брендбука, сохранять их в базе данных и переводить в статус «утверждено».

2.2 Цели

№	Цель
1	Обеспечить единый визуальный стандарт для всех, кто работает над сайтом
2	Ускорить работу дизайнеров и разработчиков за счёт готовых компонентов с кодом
3	Дать возможность безопасно экспериментировать с новыми компонентами без риска для сайта
4	Показывать компоненты с реальными данными (врачи, новости, цены) с сайта клиники
5	Создать живой инструмент, который обновляется вместе с сайтом

3. Пользователи системы

3.1 Роли

Система поддерживает две роли пользователей:

Роль: `viewer` (Наблюдатель)

Предназначена для внешних подрядчиков и всех, кому нужно ознакомиться с брендбуком.

Доступные действия:

Просмотр всех разделов брендбука (цвета, типографика, компоненты, блоки, страницы)
Просмотр кода компонентов (HTML/CSS)
Копирование кода компонента в буфер обмена
Просмотр экспериментальных компонентов со статусом approved
Скачивание дизайн-токенов (JSON)

Недоступные действия:

Создание / редактирование / удаление компонентов
Изменение статуса компонентов
Управление пользователями

Роль: `editor` (Редактор)

Предназначена для внутренних дизайнеров клиники.

Доступные действия (всё из viewer, плюс):

Создание экспериментального компонента методом дублирования существующего
Редактирование атрибутов компонента через интерактивную форму
Сохранение компонента в БД со статусом draft
Смена статуса компонента: draft → review → approved
Удаление компонента со статусом draft
Просмотр всех экспериментальных компонентов (включая draft и review)

Недоступные действия:

Управление пользователями (добавление / удаление аккаунтов)
Прямое редактирование базового кода компонентов (только через форму атрибутов)

3.2 Управление пользователями

Создание и удаление пользователей выполняется администратором системы вручную (через API или seed-скрипт) — в рамках v1.0 административный UI не предусмотрен.
Пользователи хранятся в БД с хешированным паролем (bcrypt).

4. Границы системы

Что входит в систему

Фронтенд брендбука (Next.js) — визуальная документация всех компонентов
Бэкенд API (NestJS) — управление экспериментальными компонентами, авторизация
База данных (PostgreSQL + Prisma) — хранение пользователей и экспериментальных данных
Интеграция с API сайта oclinica.ru — получение реальных данных для отображения в компонентах

Что не входит в систему (v1.0)

Административный UI для управления пользователями
Drag-and-drop конструктор страниц
История версий компонентов
Тёмная тема
Экспорт в Figma
CMS-функции (редактирование контента самого сайта oclinica.ru)

5. Функциональные требования

5.1 Навигация и структура брендбука

ФТ-01. Брендбук имеет постоянную левую (или верхнюю) навигацию с разделами:

Фундамент → Цвета, Типографика, Логотип
Компоненты → Кнопки, Форм-контролы, Карточки, Бейджи, Алерты, Модальные окна, Таблицы, Навигация
Блоки → Hero, CEO-текст, Наши врачи, Отзывы, Новости, Формы контакта, Контакт, Услуги
Страницы → Главная, Заболевание, Все врачи, Врач, Цены, Контакты
Эксперименты

ФТ-02. Навигация поддерживает прямые URL для каждого раздела (deep linking).

ФТ-03. На каждой странице раздела отображается:

Живой пример компонента/блока
Все варианты (размеры, состояния, цветовые схемы)
HTML-код компонента с кнопкой «Скопировать»
Краткое описание и правила применения

5.2 Раздел «Цвета»

ФТ-10. Отображаются все цвета палитры: плашка цвета, название, HEX, RGB, HSL.

ФТ-11. Клик на цвет — копирует HEX в буфер.

ФТ-12. Для каждой пары цветов (текст / фон) отображается коэффициент контрастности и метка WCAG AA / AAA / Fail.

ФТ-13. Кнопка «Скачать токены» — выгружает все цвета в JSON-формате, совместимом с Figma Tokens.

5.3 Раздел «Типографика»

ФТ-20. Отображаются все текстовые стили: h1–h6, body-large, body, body-small, caption, label, overline.

ФТ-21. Для каждого стиля показаны: font-family, font-weight, font-size, line-height, letter-spacing.

ФТ-22. Живые примеры текста отображаются шрифтом Fira Sans с реальным контентом.

5.4 Компоненты — общие требования

ФТ-30. Каждый компонент отображается со всеми своими вариантами и состояниями одновременно на одной странице.

ФТ-31. Под каждым вариантом показан HTML-код с кнопкой «Скопировать».

ФТ-32. Состояния интерактивных компонентов (hover, focus, disabled) доступны живым взаимодействием — не скриншотами.

5.5 Страницы

ФТ-40. Каждая страница брендбука показывает полноразмерный макет, собранный из утверждённых блоков.

ФТ-41. Страницы отображаются с реальными данными, полученными через API oclinica.ru (врачи, новости, услуги, цены).

ФТ-42. В брендбуке доступен переключатель «Desktop / Tablet / Mobile» для предпросмотра адаптивности.

5.6 Экспериментальная секция

ФТ-50. В разделе «Эксперименты» отображается список экспериментальных компонентов:

Для viewer: только со статусом approved
Для editor: все (draft, review, approved)

ФТ-51. editor может создать новый экспериментальный компонент через кнопку «Дублировать» на любом существующем компоненте брендбука.

ФТ-52. После дублирования открывается интерактивная форма редактирования атрибутов компонента:

Текстовые поля (заголовки, описания, подписи)
Выбор цвета из палитры токенов (colour picker ограничен токенами бренда)
Выбор размера (из допустимых значений)
Предпросмотр компонента обновляется в реальном времени при изменении атрибутов
Кнопки: «Сохранить как черновик», «Отмена»

ФТ-53. Созданный компонент сохраняется в БД со статусом draft и привязкой к автору.

ФТ-54. editor может изменить статус компонента:

draft → review (передать на согласование)
review → approved (утвердить)
review → draft (вернуть на доработку)

ФТ-55. Удаление возможно только для компонентов со статусом draft.

ФТ-56. Каждый экспериментальный компонент имеет карточку: название, автор, дата создания, статус, базовый компонент (от которого дублирован), превью.

5.7 Авторизация

ФТ-60. При входе на защищённые страницы неавторизованный пользователь перенаправляется на /login.

ФТ-61. Форма входа: поле email + поле пароль + кнопка «Войти».

ФТ-62. После успешного входа пользователь перенаправляется на страницу, с которой был перенаправлен.

ФТ-63. В шапке брендбука отображается: имя пользователя, роль, кнопка «Выйти».

ФТ-64. Токен сессии хранится в httpOnly cookie.

6. Требования к интеграциям

6.1 API сайта oclinica.ru

Брендбук получает реальные данные с сайта клиники для отображения в компонентах и страницах.

Необходимые данные и источники:

Данные	Раздел брендбука	Тип запроса
Список врачей	Блок «Наши врачи», страница «Врачи»	GET
Профиль врача	Страница «Врач»	GET by ID
Список новостей	Блок «Новости»	GET
Список услуг	Блок «Услуги / Заболевания»	GET
Цены	Страница «Цены»	GET
Отзывы	Блок «Отзывы»	GET

ИНТ-01. Сайт oclinica.ru работает на Drupal. Для получения данных используется Drupal JSON:API (если доступен) или стандартный REST API Drupal (/node?_format=json).

Требует уточнения: наличие и формат API на стороне oclinica.ru — необходимо проверить доступные эндпоинты до начала Sprint 1.

ИНТ-02. Запросы к API oclinica.ru выполняются на стороне бэкенда (NestJS), не из браузера — для обхода возможных CORS-ограничений.

ИНТ-03. Данные кэшируются на бэкенде с TTL 15 минут, чтобы не создавать нагрузку на сайт клиники.

ИНТ-04. Если API oclinica.ru недоступен — компоненты отображаются с заглушками (mock data), брендбук не падает.

7. Требования к данным

7.1 Схема базы данных (основные модели)

`User`

Поле	Тип	Описание
id	UUID	Первичный ключ
email	String	Уникальный, логин
name	String	Имя для отображения
passwordHash	String	bcrypt-хеш пароля
role	Enum	`viewer` / `editor`
createdAt	DateTime

`ExperimentalComponent`

Поле	Тип	Описание
id	UUID	Первичный ключ
name	String	Название компонента
baseComponent	String	Идентификатор базового компонента-источника
attributes	JSON	Атрибуты компонента (цвет, текст, размер...)
status	Enum	`draft` / `review` / `approved`
authorId	UUID	FK → User
createdAt	DateTime
updatedAt	DateTime

`ExperimentalPage` (планируется в backlog)

Поле	Тип	Описание
id	UUID
name	String
blocks	JSON	Упорядоченный список блоков
status	Enum	`draft` / `review` / `approved`
authorId	UUID	FK → User

8. Нефункциональные требования

8.1 Производительность

Страница брендбука загружается менее чем за 3 секунды при стабильном соединении.
Предпросмотр компонента при редактировании атрибутов обновляется без задержки (оптимистичный рендер на клиенте).

8.2 Адаптивность

Брендбук корректно отображается на: Desktop (1440px), Tablet (768px), Mobile (375px).
Компоненты и страницы имеют встроенный переключатель viewport для предпросмотра.

8.3 Доступность (Accessibility)

Все базовые компоненты соответствуют стандарту WCAG 2.1 AA.
Клавиатурная навигация поддерживается для всех интерактивных элементов.
Контрастность текста проверяется автоматически в разделе «Цвета».

8.4 Кроссбраузерность

Поддерживаемые браузеры: Chrome 120+, Firefox 120+, Safari 17+, Edge 120+.

8.5 Надёжность

При отсутствии данных от API oclinica.ru — graceful degradation (заглушки, нет ошибок).
Все API-эндпоинты возвращают понятные коды ошибок (4xx, 5xx) с описанием.

8.6 Масштабируемость

Архитектура monorepo позволяет добавлять новые пакеты (packages/) без переработки ядра.
База данных спроектирована с возможностью расширения моделей без breaking changes.

9. Технический стек

Слой	Технология	Версия	Обоснование
Фронтенд	Next.js (App Router)	15.x	SSR/SSG, оптимизация, экосистема React
Бэкенд	NestJS	10.x	Типизированный Node.js фреймворк, DI, модули
База данных	PostgreSQL	16.x	Надёжная реляционная БД, JSON-поля для атрибутов
ORM	Prisma	5.x	Type-safe запросы, миграции, seed
Стилизация	CSS Modules	—	Изоляция стилей, нет рантайм-зависимостей
Дизайн-токены	CSS Custom Properties	—	Нативно поддерживается всеми браузерами
Шрифт	Fira Sans	—	Google Fonts, кириллица, веса 300 и 400
Авторизация	JWT + httpOnly cookie	—	Безопасное хранение токена
Пакетный менеджер	pnpm	9.x	Monorepo workspaces, скорость
Контейнеризация	Docker + Compose	—	Единообразное окружение dev/prod

10. Архитектура системы

10.1 Структура monorepo

oclinica-brandbook/
├── apps/
│   ├── web/                    # Next.js — фронтенд брендбука
│   │   ├── app/                # App Router (страницы брендбука)
│   │   ├── components/         # UI-компоненты брендбука
│   │   │   ├── base/           # Базовые компоненты (Button, Input...)
│   │   │   ├── blocks/         # Блоки страниц (Hero, DoctorGrid...)
│   │   │   └── experimental/   # Движок экспериментальных компонентов
│   │   └── lib/                # Утилиты, API-клиент
│   └── api/                    # NestJS — REST API
│       ├── src/
│       │   ├── auth/           # JWT авторизация
│       │   ├── users/          # Управление пользователями
│       │   ├── components/     # CRUD экспериментальных компонентов
│       │   └── oclinica/       # Прокси к API oclinica.ru (с кэшем)
│       └── prisma/
│           ├── schema.prisma
│           └── seed.ts
├── packages/
│   └── tokens/                 # Дизайн-токены (цвета, типографика) — shared
├── docs/                       # Проектная документация
├── .env.example
├── docker-compose.yml
├── pnpm-workspace.yaml
└── README.md

10.2 Потоки данных

Браузер (Next.js)
    │
    ├── Статичные компоненты ──────────► Рендер из кода (нет запросов)
    │
    ├── Реальные данные клиники ───────► NestJS API ──► кэш ──► oclinica.ru API
    │
    └── Экспериментальные компоненты ──► NestJS API ──────────► PostgreSQL

11. Безопасность и авторизация

БЕЗ-01. Авторизация реализована на JWT-токенах, хранящихся в httpOnly cookie (не localStorage).

БЕЗ-02. Пароли хранятся только в виде bcrypt-хешей (cost factor 12).

БЕЗ-03. Все мутирующие эндпоинты API (POST, PATCH, DELETE) защищены Guard-ами NestJS и требуют роль editor.

БЕЗ-04. CORS настроен явно — разрешены только домены фронтенда.

БЕЗ-05. Входные данные форм валидируются на бэкенде через class-validator (NestJS Pipes).

БЕЗ-06. В production .env файл не попадает в репозиторий (.gitignore).

12. Требования к окружению

12.1 Локальная разработка

Требование	Версия
Node.js	>= 20 LTS
pnpm	>= 9
Docker	>= 24
Docker Compose	>= 2

12.2 Production-сервер

TBD — параметры хостинга будут прописаны отдельно.

Минимальные ожидаемые требования:

ОС: Ubuntu 22.04+
RAM: 2 GB
Disk: 20 GB
PostgreSQL 16 (или managed database)
Node.js 20 LTS

13. Ограничения и допущения

№	Ограничение / допущение
1	Логотип клиники в векторном формате будет предоставлен позже — раздел «Логотип» реализуется отдельно
2	Наличие и структура API oclinica.ru требуют проверки до начала разработки интеграции
3	В v1.0 нет административного UI — управление пользователями через seed-скрипт или прямые запросы к API
4	Экспериментальные компоненты создаются только методом дублирования — прямое написание HTML/CSS не предусмотрено
5	Drag-and-drop конструктор страниц — в backlog, не в v1.0
6	Тёмная тема — в backlog, не в v1.0

14. Открытые вопросы

№	Вопрос	Ответственный	Срок
ОВ-01	Доступен ли JSON API или REST API на oclinica.ru? Каков формат ответов?	Клиника	Sprint 1
ОВ-02	Параметры хостинга для production-деплоя	Клиника	TBD
ОВ-03	Нужна ли страница «Заболевание» как отдельный тип, или это подвид страницы «Услуга»?	Клиника	Sprint 9
ОВ-04	Список иконок — какую стороннюю библиотеку утвердить? (Lucide, Heroicons, и др.)	Совместно	Sprint 2
ОВ-05	Нужен ли раздел «Логотип» в v1.0 или ждём вектор?	Клиника	Sprint 2

Документ будет обновляться по ходу проекта. Изменения фиксируются в git-истории.

28 KiB Raw Blame History