Полная документация для передачи проекта (ТЗ, решения, статус, задачи): docs/HANDOFF.md
Учёт часов отработки студентов общежития: REST API на Rust (axum + sqlx/Postgres,
server/), веб-панель администратора React (admin/) и мобильное приложение Expo
для студентов, комендантов и преподавателей (mobile/, см. mobile/README.md).
- student — студент: видит долг/баланс, начинает/завершает сессии по QR, покупает награды за минуты баланса.
- teacher — преподаватель: назначает часы отработки студентам по группам.
- komendant — комендант: показывает QR для старта/финиша сессий, подтверждает/отклоняет сессии.
- admin — администратор: веб-панель, пользователи, группы, награды, заказы, проверка фото, месячные сводки, логи. Может вызывать teacher-эндпоинты.
cp .env.example .env # заполнить DB_PASSWORD, JWT_SECRET, QR_SECRET, ADMIN_PASSWORD
docker compose up --buildAPI слушает http://localhost:8080, Postgres — postgres:16.
Указать DOMAIN=prila.example.com в .env (A-запись домена → IP VPS, порты 80/443
открыты) и запустить docker compose --profile https up -d — Caddy сам получит
сертификат Let's Encrypt и проксирует на сервер (Caddyfile).
scripts/backup.sh [каталог] — pg_dump базы и архив фото (по умолчанию ./backups,
хранит KEEP_DAYS=14 дней). Cron на VPS:
0 3 * * * cd /opt/worker-plus && scripts/backup.sh /var/backups/prila >> /var/log/prila-backup.log 2>&1.
Восстановление:
docker compose exec -T db pg_restore -U prila -d prila --clean --if-exists < db-XXXX.dump
docker compose exec -T server tar -C /data -xzf - < photos-XXXX.tar.gzscripts/dev-db.sh install # скачать встроенный Postgres 16 в .devdb/ (без root)
scripts/dev-db.sh start # поднять на 127.0.0.1:5433, создать БД prila
cd server
cp ../.env.example .env # и дописать DATABASE_URL=postgres://prila@127.0.0.1:5433/prila
cargo run # миграции и первый админ создаются при старте| Переменная | По умолчанию | Описание |
|---|---|---|
DATABASE_URL |
— | строка подключения Postgres |
JWT_SECRET |
— | секрет подписи JWT (HS256, 7 дней) |
QR_SECRET |
— | секрет HMAC для QR-кодов коменданта |
APP_TIMEZONE |
Asia/Vladivostok |
локальная таймзона (месяцы, сводки) |
PHOTO_DIR |
./data/photos |
каталог фото сессий и наград |
LOG_DIR |
./data/logs |
каталог audit.log / komendant.log |
STATIC_DIR |
— | dist админ-панели (SPA fallback на index.html) |
BIND_ADDR |
0.0.0.0:8080 |
адрес прослушивания |
ADMIN_LOGIN / ADMIN_PASSWORD |
admin / — |
первый админ создаётся при старте, если админов нет |
EXPO_PUSH_ENABLED |
false |
слать push через Expo |
EXPO_PUSH_URL |
https://exp.host/--/api/v2/push/send |
endpoint Expo push |
CORS_ORIGINS |
* |
список origin через запятую или * |
MAX_SESSION_HOURS |
4 |
лимит реального времени сессии (без коэффициента) |
TRUST_PROXY |
false |
брать IP клиента из последнего X-Forwarded-For (только за Caddy, вместе с PORT=127.0.0.1:8080) |
DOMAIN |
— | домен для профиля https (Caddy) |
groups, users (role/login/full_name/group_id/debt_minutes/balance_minutes/
is_active), push_tokens, assignments (назначенные часы), work_sessions
(status: active → pending_confirmation → credited | komendant_rejected | expired;
coefficient 1/2; raw_seconds → rounded_minutes → credited_minutes;
applied_to_debt / applied_to_balance; photo_review: pending → approved/rejected),
rewards, orders, notifications, audit_log, komendant_log,
monthly_summaries + summary_rows.
Все суммы — целые минуты. Все метки времени — серверные (timestamptz).
Правила: округление rounded_minutes = (raw_seconds + 30) / 60;
credited = rounded * coefficient; при подтверждении to_debt = min(debt, credited),
остаток — в баланс; при отклонении фото зачёт откатывается (что не удалось
забрать с баланса — возвращается в долг). QR: prila1.<komendant>.<difficulty>.<window>.<hmac16>,
окно 30 с, валиден текущее и предыдущее окно.
Ошибки: { "error": { "code", "message" } } (message по-русски). Списки:
{ items, total, page, per_page }. Авторизация: Authorization: Bearer <jwt>.
POST /api/auth/login{login,password}→{token,user}; лимит: 10 неудачных попыток за 15 мин (по ip+login) → 429too_many_attemptsGET /api/me·POST /api/me/password{old_password,new_password}POST /api/me/push-token/DELETE /api/me/push-token{token}GET /api/notifications·POST /api/notifications/{id}/read·POST /api/notifications/read-allGET /api/health
POST /api/student/sessions/start{qr}POST /api/student/sessions/finish(multipart:qr,photojpeg/png/heic/webp ≤10МБ)GET /api/student/sessions·GET /api/student/sessions/active(сserver_now)GET /api/student/assignments·GET /api/student/orders·GET /api/student/orders/{id}GET /api/rewards·POST /api/rewards/{id}/buy·GET /api/rewards/{id}/image
POST /api/komendant/qr/open{difficulty: light|hard}→{qr,expires_at}(логируется)GET /api/komendant/qr?difficulty=— обновление QR (не логируется)GET /api/komendant/sessions?status=POST /api/komendant/sessions/{id}/confirm·POST /api/komendant/sessions/{id}/reject {reason}GET /api/komendant/sessions/{id}/photo(также доступна студенту-владельцу и админу)
GET /api/groups·GET /api/groups/{id}/studentsGET /api/students/{id}— профиль + сессии + назначенияPOST /api/students/{id}/assignments{minutes, reason}
- Пользователи:
GET/POST /api/admin/users(фильтры role, group_id, q, is_active),GET/PATCH/DELETE /api/admin/users/{id}(delete = деактивация),POST /api/admin/users/{id}/reset-password,POST /api/admin/users/{id}/adjust{debt_delta,balance_delta,reason},POST /api/admin/users/import(multipart CSV/XLSX:ФИО, Логин, Пароль, Роль, Группа— атомарно, ошибки по строкам) - Группы:
GET/POST /api/admin/groups,PATCH/DELETE /api/admin/groups/{id} - Сессии:
GET /api/admin/sessions(status, photo_review, student_id, komendant_id, from, to),GET /api/admin/sessions/{id}/photo,POST /api/admin/sessions/{id}/photo-review{approved, comment} - Награды:
POST /api/admin/rewards,PATCH/DELETE /api/admin/rewards/{id},POST /api/admin/rewards/{id}/image(multipart) - Заказы:
GET /api/admin/orders,POST /api/admin/orders/{id}/issue,POST /api/admin/orders/{id}/cancel - Сводки:
GET /api/admin/summaries,GET /api/admin/summaries/{id},GET /api/admin/summaries/{id}/xlsx,POST /api/admin/summaries/generate {year,month} - Логи:
GET /api/admin/audit-log,GET /api/admin/komendant-log(фильтры actor/komendant, action, from, to, пагинация)
- каждые 60 с:
activeсессии старшеMAX_SESSION_HOURS→expired(+уведомления). - каждые 60 с: 1-го числа после 00:05 локального времени → сводка за прошлый месяц.
Типы DTO для клиентов экспортируются в shared/api-types/*.ts через cargo test (ts-rs).