Canteen — Архитектурный документ

1. Назначение

Учёт заказов и фактических посещений столовой на крупном складском объекте. Основные роли:

2. Стек

3. Топология

                                ┌───────────────────────┐
                                │     HikCentral        │
                                │     (СКУД-сервер)     │
                                └──────────┬────────────┘
                                           │ webhook
                                           ▼
                                ┌───────────────────────┐
                                │        n8n            │
                                │  (workflow runner)    │
                                └──────────┬────────────┘
                                           │
                              ┌────────────┼────────────────────┐
                              │            │                    │
              ┌──── POST /events    POST /schedule/build-meal-plan
              │              ▼            │              ▼
   ┌──────────┴────────────────────────────────────────────────────┐
   │                  canteen-backend (Express)                    │
   │  events.controller / schedule.controller / orders.controller  │
   │  analytics / discrepancies / export / persons / settings      │
   │  cron: 09:55,15:30 pacs-sync   20:55,03:00 pacs-order-push    │
   └────┬───────────────────────────────────────────────────┬─────┘
        │ pg                                          REST  │
        ▼                                                    ▼
   ┌─────────────────┐                          ┌─────────────────────┐
   │ Postgres 16     │                          │ Supabase            │
   │ (canteen)       │                          │ PACS - Database     │
   │ persons         │                          │ PACS - Webhook ALL  │
   │ meal_orders     │                          │ PACS - Failed Access│
   │ check_ins       │                          │ PACS - Order Lunch  │
   │ meal_exceptions │                          │ PACS - Order Dinner │
   │ meal_refusals   │                          └─────────────────────┘
   │ settings        │
   └─────────────────┘
        ▲
        │ pg
   ┌────┴────────────────────────────────────────────┐
   │       canteen-frontend (React + nginx)          │
   │  Главная (Заказы на сегодня), Аналитика,        │
   │  Календарь, AdminPage                           │
   └─────────────────────────────────────────────────┘

4. Модель данных

4.1 persons — справочник сотрудников

4.2 meal_orders — план питания на день

4.3 check_ins — фактические события прохода

4.4 meal_exceptions — исключения (нестандартные графики)

Сотрудники, которые не проходят через КПП4 в стандартное окно 06:00–10:00 (ночная смена, удалённая работа). Заказываются вручную через календарь.

4.5 meal_refusals — отказы

Сотрудник написал «я не буду питаться у вас с такой-то даты». Запись (full_name, refusal_date, meal_type). Действует «от даты и далее» (refusal_date <= sync_date).

4.6 settings — KV-настройки

5. Ключевые потоки

5.1 Сборка плана — POST /api/schedule/build-meal-plan

{
  "date": "2026-05-30",
  "meal_type": "Обед",
  "events": [{ "personId": "1234", "deviceTime": "..." }, ...],
  "format": "xlsx"
}

5.2 Приход через СКУД — POST /api/events

Webhook от n8n, тело — массив событий HikCentral. Шаги:

5.3 Главная страница — GET /api/orders/today

Отдаёт orders, unmatched, anomalies, stats. На UI:

Дополнительно: Сверка для Antria Kitchen (две inline-редактируемые: «Выдано порций», «Остаток порций»), таблица заказов с inline-меняемым статусом (Ожидается/Не пришёл → «На другом объекте» = в статистике как Покушал).

5.4 Аналитика

Вкладки в UI: Обзор Расхождения — с фильтром Обед/Ужин. По сотрудникам Административные Логи СКУД По юр. лицам — без фильтра, агрегируют оба приёма.

5.5 Календарь исключений

UI: матрица «сотрудник × дни месяца», ячейки разделены на полу-приёмы (верх = обед, низ = ужин). Двойной клик на день — добавить/убрать shift. Двойной клик на ФИО — редактирование. Свёрнутая секция «Уволенные» внизу.

5.6 Логи СКУД

Прокси к Supabase PACS - Failed Access Report (отказы доступа).

• Пагинация по 100 через offset
• Кеш имени временной колонки (SendTime / created_at) — избегаем 3 лишних HTTP-вызова
• Отдельный endpoint /stats — лёгкая выборка для счётчиков (не зависят от пагинации списка)

5.7 Бэкфилл check-ins из Supabase

Когда n8n-webhook не дошёл (сервер падал) — поднимаем события из Supabase PACS - Webhook ALL.

Endpoint: POST /api/events/backfill-supabase body { from, to?, src_index? }. Кнопка в UI: AdminPage → Подтянуть отметки за день.

6. Интеграции

6.1 HikCentral

Никогда не дёргаем напрямую — всё через n8n. Источник истины для: событий СКУД, персон.

6.2 n8n workflows

6.3 Supabase

6.4 Antria Kitchen

Внешний поставщик питания. Получает xlsx из ответа build-meal-plan (через n8n email/Telegram). Отдаёт обратно «выдано N порций / остаток M» — вбивается вручную в Сверка для Antria Kitchen на главной.

7. Известные особенности и приёмы

7.1 Таймзонный баг (исправлен 30.05.2026) FIXED

В events.controller.js для вычисления session_date использовалось .toISOString().slice(0,10), что всегда даёт UTC. Для событий 00:00–05:00 местного времени (Asia/Tashkent +05:00) после −86400000 мс получалось позавчера — на день раньше нужного. Затронуло 19 записей.

Исправлено: введён helper localDateOffsetStr(d, dayOffset), который использует getFullYear/getMonth/getDate (они уважают TZ=Asia/Tashkent env-var). Исторические записи поправлены SQL-апдейтом.

7.2 Auto-create persons в build-meal-plan

Если КПП4 присылает personId, которого нет в persons — мы создаём пустую запись (full_name='', company='', position=''). Потом runPacsSync() (cron или lazy из webhook) заливает реальные данные. Это объясняет «загадочно появляющиеся ФИО» через несколько минут после первого построения плана.

7.3 Защита от затирания при runPacsSync

В upsert persons используется COALESCE(NULLIF(persons.X, ''), EXCLUDED.X) — если в локальной БД уже есть осмысленное значение, оно не перезаписывается.

Исключение — company имеет ОТДЕЛЬНУЮ принудительную синхронизацию syncCompaniesFromSupabase(), которая всегда перезаписывает (введено 30.05.2026 для актуализации после перевода сотрудника между ЮЛ). Вызывается в конце runPacsSync() и в начале каждого build-meal-plan.

7.4 Правило «Обед → Ужин»

При построении ужина: люди, которые были в обеденном meal_orders того же дня, исключаются из ужина. Кроме:

• Охранников (position ILIKE '%охран%')
• Тех, у кого есть shift на ужин в meal_exceptions

Логика — экономия порций, охрана может оставаться на ночь и быть на оба приёма.

7.5 Snapshot-ы для архивного просмотра

При первом построении плана build-meal-plan сохраняет:

• final_order_count_{date}_{meal_type} — финальное число, не дрейфует если потом меняют ручные правки
• meal_times_{date} — окна выдачи на дату

Главная страница использует эти snapshot-ы при просмотре архива через HistoryPanel.

7.6 Кириллица в HTTP-заголовках

HTTP RFC требует ASCII в названиях. Все «человекочитаемые» заголовки (например, X-Summary) URL-encode-нуты на стороне сервера. Клиент (n8n, фронт) делает decodeURIComponent для отображения.

8. Деплой

# Бэкенд (с пересборкой)
cd /opt/stacks/apps/my-projects-VPS/Canteen
docker compose up -d --build backend

# Фронтенд
docker build --pull=false -t canteen-frontend ./frontend && docker compose up -d frontend

# Оба сразу
docker build --pull=false -t canteen-frontend ./frontend && docker compose up -d --build frontend backend

Миграции применяются автоматически при старте backend (runMigrations() в app.js) — все ALTER TABLE ... ADD COLUMN IF NOT EXISTS идемпотентны.

9. Среды