From 3bf9f3e307b06678c3050dd3319b8bf29fea118b Mon Sep 17 00:00:00 2001 From: AR 15 M4 Date: Sun, 22 Mar 2026 14:40:38 +0500 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=BE=20=D1=82=D0=B5=D1=85=D0=BD=D0=B8=D1=87=D0=B5?= =?UTF-8?q?=D1=81=D0=BA=D0=BE=D0=B5=20=D0=B7=D0=B0=D0=B4=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D0=B5=20=D0=BD=D0=B0=20oclinica-brandbook=20v1.0-draft?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Роли: viewer и editor - Функциональные требования: навигация, компоненты, эксперименты, авторизация - Интеграция с API oclinica.ru (прокси через NestJS, кэш 15 мин) - Схема БД: User, ExperimentalComponent - Стек: Next.js + NestJS + PostgreSQL + Prisma - Открытые вопросы по API сайта и хостингу Co-Authored-By: Claude Sonnet 4.6 --- docs/TZ.md | 462 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 462 insertions(+) create mode 100644 docs/TZ.md diff --git a/docs/TZ.md b/docs/TZ.md new file mode 100644 index 0000000..91b6623 --- /dev/null +++ b/docs/TZ.md @@ -0,0 +1,462 @@ +# Техническое задание +## Цифровой брендбук Клиники ухо, горло, нос им. проф. Е.Н. Оленевой +### `oclinica-brandbook` + +--- + +**Версия:** 1.0-draft +**Дата:** 2026-03-22 +**Статус:** На согласовании + +--- + +## Содержание + +1. [Общие сведения](#1-общие-сведения) +2. [Назначение и цели](#2-назначение-и-цели) +3. [Пользователи системы](#3-пользователи-системы) +4. [Границы системы](#4-границы-системы) +5. [Функциональные требования](#5-функциональные-требования) +6. [Требования к интеграциям](#6-требования-к-интеграциям) +7. [Требования к данным](#7-требования-к-данным) +8. [Нефункциональные требования](#8-нефункциональные-требования) +9. [Технический стек](#9-технический-стек) +10. [Архитектура системы](#10-архитектура-системы) +11. [Безопасность и авторизация](#11-безопасность-и-авторизация) +12. [Требования к окружению](#12-требования-к-окружению) +13. [Ограничения и допущения](#13-ограничения-и-допущения) +14. [Открытые вопросы](#14-открытые-вопросы) + +--- + +## 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-истории.*