write full project README

2026-09-07 09:48:39 +03:00
parent 7c58cd0d4c
commit f3885dc0fc
1 changed files with 124 additions and 0 deletions
@@ -1,2 +1,126 @@
 # 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/             # локальные бэкапы
+```