127 lines
7.0 KiB
Markdown
127 lines
7.0 KiB
Markdown
# WhatIDo
|
||
|
||
Учётная система для образовательного центра: журнал посещений, проектные работы воспитанников, галерея групп, откреплённые файлы и публичные страницы-витрины (share-ссылки).
|
||
|
||
## Возможности
|
||
|
||
- **Журнал записей** — отметки о занятиях с фото и прикреплёнными файлами (проектные работы), мягкое удаление и корзина
|
||
- **Файлы** — централизованный раздел со всеми загруженными файлами, фильтры (имя воспитанника, группа, даты, поиск) и вкладка «Откреплённые»
|
||
- **Группы** — учебные группы, расписание (день недели, время), фотохроника группы
|
||
- **Воспитанники** — справочник с привязкой к группам
|
||
- **Share-ссылки** — публичные страницы-витрины с выбором группы / воспитанника / диапазона дат
|
||
- **Дашборд** — статистика, активные группы, активность за 14 дней, последние записи, топ воспитанников
|
||
- **Резервное копирование** — экспорт/импорт полного дампа (БД + файлы) в `tar.gz`
|
||
- **Настройки** — научные тексты футера, анти-спам интервал
|
||
- **HTTPS** — самоподписанный TLS-сертификат, автогенерация при сборке
|
||
|
||
## Технологии
|
||
|
||
- Node.js + Express
|
||
- PostgreSQL (pg)
|
||
- Multer (загрузка файлов), Tar (бэкапы)
|
||
- Docker / Docker Compose
|
||
|
||
## Быстрый старт
|
||
|
||
### Требования
|
||
|
||
- Docker + Docker Compose
|
||
|
||
### Запуск
|
||
|
||
```bash
|
||
# создайте .env с паролем администратора (см. раздел «Конфигурация»)
|
||
docker compose up -d --build
|
||
```
|
||
|
||
После старта:
|
||
|
||
- **HTTP** `http://localhost:3000` — редирект на HTTPS
|
||
- **HTTPS** `https://localhost:3443` — приложение (самоподписанный сертификат, принимайте предупреждение браузера)
|
||
- **PostgreSQL** `localhost:5432` — `app:app`, база `whereldo`
|
||
|
||
Управление:
|
||
|
||
```bash
|
||
docker compose ps # статус
|
||
docker compose logs -f app
|
||
docker compose down # остановка (данные сохраняются)
|
||
```
|
||
|
||
## Конфигурация
|
||
|
||
Переменные окружения (`.env`):
|
||
|
||
| Переменная | По умолчанию | Назначение |
|
||
|------------------|--------------|-------------------------------------|
|
||
| `ADMIN_PASSWORD` | `admin` | Пароль администратора (X-Admin-Token) |
|
||
| `DATABASE_URL` | см. compose | Строка подключения к PostgreSQL |
|
||
|
||
Внутри контейнера `db` также задаются `POSTGRES_DB=whereldo`, `POSTGRES_USER=app`, `POSTGRES_PASSWORD=app`, `TZ=Europe/Moscow`.
|
||
|
||
## Структура данных
|
||
|
||
- `groups` — группы, расписание (`day_of_week`, `time_start`, `time_end`)
|
||
- `students` — воспитанники
|
||
- `entries` — записи журнала (фото `photo_path`, описание, мягкое удаление `deleted_at`)
|
||
- `project_files` — файлы записей (`token`, `path`, привязка `entry_id`, отметка `detached_at`)
|
||
- `group_photos` — фотохроника групп
|
||
- `share_links` — публичные ссылки-витрины
|
||
- `settings` — пары ключ/значение (анти-спам интервал, футер)
|
||
|
||
Схема инициализируется при первом запуске из `db/init.sql`; миграции существующей БД — в `db/migration.sql`.
|
||
|
||
## Хранилище файлов
|
||
|
||
Загруженные фото и файлы хранятся в каталоге `uploads/` на хосте и монтируются в контейнер (`./uploads:/app/uploads`). Это даёт прямой доступ к данным из-под хост-системы. Данные БД хранятся в именованном томе `pgdata`.
|
||
|
||
## Бэкапы
|
||
|
||
В админке (Настройки → Бэкап) можно:
|
||
|
||
- Скачать полный бэкап — `tar.gz`, содержащий `data.json` (все таблицы) и `uploads/`
|
||
- Восстановить из файла бэкапа
|
||
|
||
Также доступны скрипты на хосте:
|
||
|
||
```bash
|
||
./scripts/backup.sh # дамп БД + фото в backups/whatido-backup-<дата>.tar.gz
|
||
./scripts/restore.sh # восстановление из архива
|
||
```
|
||
|
||
## Основные API
|
||
|
||
| Метод | Путь | Назначение |
|
||
|-------|------|------------|
|
||
| `GET` | `/api/entries` | Записи журнала (с фильтрами) |
|
||
| `POST` | `/api/entries` | Создать запись (photo + files) |
|
||
| `PUT/DELETE` | `/api/entries/:id` | Обновить / мягко удалить |
|
||
| `GET` | `/api/files` | Все файлы (фильтры) |
|
||
| `GET` | `/api/files/detached` | Откреплённые файлы |
|
||
| `POST` | `/api/files/:id/detach` | Открепить файл от записи |
|
||
| `GET` | `/api/files/:token` | Скачать/показать файл по токену (публично) |
|
||
| `GET` | `/api/groups` | Список групп |
|
||
| `POST/PUT/DELETE` | `/api/groups/:id(?)` | CRUD групп |
|
||
| `GET/POST` | `/api/groups/:id/photos` | Фотохроника группы |
|
||
| `GET/POST/PUT/DELETE` | `/api/share/...`, `/api/links` | Публичные ссылки |
|
||
| `GET` | `/api/backup` | Скачать бэкап |
|
||
| `POST` | `/api/restore` | Восстановить из бэкапа |
|
||
| `GET` | `/api/dashboard`, `/api/stats` | Статистика |
|
||
|
||
Защищённые админ-маршруты требуют заголовок `X-Admin-Token` с `ADMIN_PASSWORD`.
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
├── docker-compose.yml # сервисы app + db
|
||
├── Dockerfile # сборка образа (Node 20, генерация TLS-сертификата)
|
||
├── server.js # Express-приложение
|
||
├── db/
|
||
│ ├── init.sql # схема при первом запуске
|
||
│ └── migration.sql # миграции существующей БД
|
||
├── public/ # статика (HTML/CSS/JS админки и витрин)
|
||
├── scripts/ # вспомогательные скрипты
|
||
├── uploads/ # загруженные файлы (bind-монт, вне git)
|
||
└── backups/ # локальные бэкапы
|
||
```
|