# PRD — Дашборд клинической кафедры медицинского университета

**Версия документа:** 1.0
**Дата:** 26.06.2026
**Владелец продукта:** Issida Ashirmatova
**Живая страница:** https://pages.git.vibe42.kz/Issida_Ashirmatova/clinical-dashboard/
**Репозиторий:** https://git.vibe42.kz/Issida_Ashirmatova/clinical-dashboard

---

## 1. Обзор продукта

Веб-дашборд для учёта преподавателей клинической кафедры медицинского университета. Представляет собой редактируемую таблицу, где каждый преподаватель — отдельная строка, а каждый параметр (ФИО, дата рождения, образование, научная степень, категория, сертификат специалиста, членство в ассоциациях, клиническая база) — вводимое поле. Дашборд строит многопараметрические отчёты и выгружает их в CSV.

Продукт реализован как **статический сайт** (HTML + CSS + JS) без сервера, базы данных и авторизации. Данные хранятся в браузере (localStorage).

---

## 2. Цели и задачи

### Цели
- Дать кафедре единое место для учёта кадрового состава преподавателей.
- Обеспечить ввод и редактирование данных непосредственно в таблице, без форм и модальных окон.
- Позволить получать аналитические отчёты по нескольким параметрам одновременно (например, «сколько преподавателей с научной степенью и какой категорией»).

### Задачи (метрики успеха)
- Ввод строки преподавателя занимает < 1 минуты.
- Отчёт по любому набору параметров строится мгновенно, без ручного подсчёта.
- Данные не теряются между перезагрузками страницы.

---

## 3. Целевые пользователи

| Роль | Сценарий |
|------|----------|
| **Ответственный по кафедре (администратор)** | Ведёт общую таблицу, собирает анкеты преподавателей, формирует отчёты для руководства. |
| **Преподаватель** | Вводит собственные данные в свою строку, выгружает анкету файлом и отправляет администратору. |

> ⚠️ Ограничение платформы: настоящая многопользовательская авторизация с общим хранилищем в статической песочнице невозможна. Поэтому совместная работа организована через экспорт/импорт файлов (см. раздел 9).

---

## 4. Контекст и ограничения платформы

Платформа — учебная песочница Vibe42 (только статические сайты). Жёсткие ограничения:

- ✅ Статика: HTML + CSS + JS в браузере.
- ❌ Нет бэкенда, базы данных, Redis, Docker, nginx.
- ❌ Нет авторизации / OAuth / JWT.
- ❌ Нет тяжёлых сборщиков (npm-зависимостей).
- 📦 Данные хранятся в `localStorage` браузера (персонально для устройства и браузера).

---

## 5. Границы продукта (Scope)

### В объёме (In scope)
- Редактируемая таблица преподавателей со всеми параметрами.
- Расширяемый набор параметров (пользовательские поля).
- Статистические карточки (сводка по кафедре).
- Поиск и фильтрация.
- Многопараметрические отчёты с диаграммами и перекрёстной таблицей.
- Экспорт в CSV, импорт/экспорт JSON (резервные копии, сбор анкет).

### Вне объёма (Out of scope)
- Многопользовательский вход и общее серверное хранилище.
- Загрузка файлов/фотографий на сервер.
- Сложная бизнес-логика (расчёт стажа, автозаполнение из внешних баз).
- Уведомления и email-рассылки (возможно добавление позже через Formspree).

---

## 6. Пользовательские истории

1. Как администратор, я хочу добавить преподавателя и заполнить все его параметры прямо в таблице, чтобы не открывать отдельные формы.
2. Как администратор, я хочу редактировать любое поле строки одним кликом, чтобы быстро исправлять данные.
3. Как администратор, я хочу видеть сводку: сколько всего преподавателей, сколько с научной степенью, сколько с сертификатом.
4. Как администратор, я хочу построить отчёт одновременно по нескольким параметрам, чтобы анализировать состав кафедры.
5. Как администратор, я хочу выгрузить отчёт в CSV для предоставления руководству.
6. Как преподаватель, я хочу ввести свои данные и выгрузить анкету файлом, чтобы передать её администратору.
7. Как администратор, я хочу импортировать полученные анкеты, чтобы они добавились в общую таблицу без дубликатов.
8. Как администратор, я хочу добавлять собственные параметры (например, «стаж», «учёное звание»), чтобы учитывать специфику кафедры.

---

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

### 7.1. Структура интерфейса
- **Верхняя панель:** название, кнопки «+ Преподаватель», «⚙ Настроить поля», «⤓ Экспорт CSV», «⤒ Импорт».
- **Вкладки:** «Преподаватели» и «Отчёты».
- **Вкладка «Преподаватели»:** карточки статистики → панель поиска/фильтров → таблица.
- **Вкладка «Отчёты»:** выбор параметров → графики распределения → перекрёстная таблица → сводка.

### 7.2. Таблица преподавателей (инлайн-редактирование)
- Каждая строка = один преподаватель.
- Каждый параметр = поле ввода прямо в ячейке.
- Типы полей зависят от параметра (см. раздел 8).
- **Автосохранение** в `localStorage` при вводе (с debounce ~350 мс).
- Действия по строке:
  - `⤓` — выгрузить анкету одного преподавателя в JSON.
  - `🗑` — удалить строку (с подтверждением).
- Кнопка «+ Преподаватель» добавляет пустую строку, фокус на поле «ФИО».
- Все базовые поля свободно вводимы (выпадающие поля — редактируемые комбобоксы: выбор из подсказок **или** ввод своего значения).

### 7.3. Параметры преподавателя (модель данных)

**Базовые поля (нельзя удалить):**

| Ключ | Название | Тип | Обязательное | Варианты |
|------|----------|-----|--------------|----------|
| `fullName` | ФИО | text | да | — |
| `birthDate` | Дата рождения | date | нет | — |
| `education` | Образование | textarea | нет | — |
| `academicDegree` | Научная степень | select (комбобокс) | нет | Нет / Кандидат наук / Доктор наук + свободный ввод |
| `category` | Категория | select (комбобокс) | нет | Нет / Вторая / Первая / Высшая + свободный ввод |
| `specialistCertificate` | Сертификат специалиста | text | нет | — |
| `associations` | Членство в ассоциациях | text | нет | — |
| `clinicalBase` | Клиническая база | text | нет | — |

**Пользовательские поля:** добавляются через «⚙ Настроить поля». Доступные типы: текст, дата, число, выпадающий список (комбобокс), длинный текст, да/нет (чекбокс). Удаляемы (с подтверждением; значения у всех преподавателей теряются).

### 7.4. Статистика (карточки)
- Всего преподавателей.
- С научной степенью (кандидат / доктор).
- Докторов наук.
- С сертификатом специалиста.
- Члены ассоциаций.
Обновляется автоматически при редактировании таблицы.

### 7.5. Поиск и фильтрация
- Полнотекстовый поиск по всем полям.
- Фильтры: по научной степени, по категории, по клинической базе.
- Счётчик «Показано: X из Y».

### 7.6. Отчёты (многопараметрические)
- Выбор **нескольких** параметров чекбоксами.
- По каждому выбранному параметру — диаграмма распределения (количество по значениям).
- По первым двум выбранным — **перекрёстная таблица** (pivot): строки × столбцы, в ячейках количество преподавателей, с итогами по строкам/столбцам и общим.
- Сводка: всего преподавателей, % с научной степенью, число параметров в отчёте.
- Экспорт отчёта в CSV (все распределения + перекрёстная таблица).
- Пустые значения отображаются как «(не указано)».

### 7.7. Экспорт и импорт
- **Экспорт CSV** — вся таблица преподавателей (заголовок из актуальных названий полей).
- **Резервная копия JSON** — полное состояние (преподаватели + пользовательские поля), двойной клик по кнопке «Экспорт CSV».
- **Выгрузка анкеты** (⤓ в строке) — JSON одного преподавателя.
- **Импорт** — добавление анкет из файла с защитой от дублей по ФИО (регистронезависимо). Поддерживаемые форматы: `{teachers:[...], customFields:[...]}`, массив преподавателей, один объект-преподаватель. Пользовательские поля из файла тоже сливаются.

---

## 8. Модель данных

```
state = {
  teachers: [
    {
      id: "t_...",
      fullName: "...",
      birthDate: "ГГГГ-ММ-ДД",
      education: "...",
      academicDegree: "Доктор наук",
      category: "Высшая",
      specialistCertificate: "...",
      associations: "...",
      clinicalBase: "...",
      <customFieldKey>: <value>
    }
  ],
  customFields: [
    { key, label, type, options?, locked:false }
  ]
}
```

Хранение: `localStorage["clinical_dashboard_v1"]` = JSON.stringify(state).

---

## 9. Сценарий совместной работы (сбор анкет)

Поскольку общего сервера нет, используется файловый обмен:

1. Преподаватель открывает ссылку дашборда.
2. Вводит свои данные в новую строку.
3. Жмёт `⤓` в конце строки → получает файл `anketa_ФИО.json`.
4. Отправляет файл администратору (email/мессенджер).
5. Администратор жмёт «⤒ Импорт» → анкета добавляется в таблицу (дубли по ФИО отбрасываются).

---

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

- **Доступность:** работает в любом современном браузере, адаптивная вёрстка (десктоп/планшет/телефон), таблица скроллится по горизонтали на узких экранах.
- **Производительность:** таблица до ~200 строк работает без задержек; автосохранение дебаунсится.
- **Приватность:** данные не покидают браузер пользователя (кроме случаев ручного экспорта).
- **Отказоустойчивость:** при ошибке чтения localStorage приложение не падает, начинает с пустого состояния.
- **Интернационализация:** интерфейс на русском языке.
- **Палитра:** клиническая тема — белый фон, тёмный текст, бирюзовый акцент (`#0891B2`).

---

## 11. Техническая реализация

| Файл | Назначение |
|------|------------|
| `index.html` | Структура страницы, вкладки, модальные окна. |
| `styles.css` | Оформление (клиническая тема, таблицы, карточки, отчёты). |
| `app.js` | Вся логика: состояние, рендеринг, автосохранение, отчёты, экспорт/импорт. |

Стек: чистый vanilla JS, без фреймворков и сборщиков. Публикация — push в ветку `pages` Gitea, Caddy обслуживает статике мгновенно.

---

## 12. Дорожная карта (Roadmap)

| Приоритет | Возможность |
|-----------|-------------|
| Высокий | Форма самостоятельной подачи анкеты преподавателем через Formspree/Getform (без файлов, отправка на email администратора). |
| Высокий | Общее хранилище через опубликованный Google Sheets CSV для настоящей многопользовательской работы. |
| Средний | Экспорт отчётов в PDF / печать. |
| Средний | Загрузка фото преподавателя (avatar, base64 в localStorage). |
| Средний | Валидация полей (формат даты, обязательность). |
| Низкий | Журнал изменений (audit log). |
| Низкий | Роли: просмотр только для преподавателей, редактирование для администратора. |

---

## 13. Глоссарий

- **Комбобокс** — поле, совмещающее выпадающий список подсказок и свободный ввод текста.
- **Перекрёстная таблица (pivot)** — таблица сопряжённости: строки и столбцы — значения двух параметров, в ячейках количество объектов с данной комбинацией.
- **localStorage** — хранилище данных в браузере пользователя.
- **CSV** — текстовый формат таблицы, открывается в Excel/Numbers.
- **JSON** — формат для резервных копий и обмена анкетами.