From e817645630691a61d3811a01ac7efb1ce937f41b Mon Sep 17 00:00:00 2001 From: Dauren777 Date: Fri, 26 Jun 2026 06:49:57 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20PRD=20=D0=BF=D1=80=D0=BE=D0=B4=D1=83?= =?UTF-8?q?=D0=BA=D1=82=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PRD.md | 235 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 PRD.md diff --git a/PRD.md b/PRD.md new file mode 100644 index 0000000..412bc7d --- /dev/null +++ b/PRD.md @@ -0,0 +1,235 @@ +# 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: "...", + : + } + ], + 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** — формат для резервных копий и обмена анкетами.