2.2 X и Z отчёты смены
Референс
YUMA POS:
_reference/yumapos/x-reports.md,shift-report.md,cash-balance.md,cash-flows.md,terminals-dashboard.md
Зависимость
Требует работающий Order Service (BR 2.1) — без заказов отчёт бессмыслен.
Общая идея
Кассир работает на смене: открывает, обрабатывает заказы, принимает оплату, закрывает. В любой момент смены он может посмотреть промежуточный отчёт (X-отчёт), а при закрытии формируется итоговый отчёт (Z-отчёт).
Эти отчёты нужны:
- Кассиру — чтобы сверить кассу перед закрытием
- Менеджеру — чтобы контролировать выручку точки
- Франшизе/Франчайзи — чтобы видеть аналитику по всем точкам в бэк-офисе
Что такое X-отчёт и Z-отчёт
| X-отчёт | Z-отчёт | |
|---|---|---|
| Когда | В любой момент во время смены | При закрытии смены |
| Кто запрашивает | Кассир (на POS) или менеджер (в админке) | Автоматически при закрытии смены |
| Что содержит | Промежуточные итоги с начала смены до текущего момента | Финальные итоги за всю смену |
| Обнуляет ли счётчики | Нет | Да (фиксирует итог, смена закрывается) |
| Где хранится | Не сохраняется (вычисляется на лету) | Сохраняется как документ (акт реализации) |
Состав отчёта (по YUMA POS)
Шапка
| Поле | Описание | Откуда данные |
|---|---|---|
| Сотрудник | ФИО кассира, открывшего смену | shift_records.employee_id → User Service |
| Магазин | Название ТТ | shift_records.store_id → Store Service |
| Терминал | Название кассы (POS) | Будущее — пока нет терминалов |
| Начало смены | Дата и время clock_in | shift_records.clock_in |
| Конец смены | Только для Z-отчёта | shift_records.clock_out |
Финансовые показатели
| Поле | Описание | Откуда данные |
|---|---|---|
| Дневная выручка | Общая сумма всех оплаченных заказов за смену | orders WHERE store_id + paid, SUM(paid_amount) |
| Наличными | Сумма оплат наличными | orders WHERE payment_method = ‘cash’ |
| По карте | Сумма оплат картой | orders WHERE payment_method = ‘card’ |
| QR-оплата | Сумма оплат через QR | orders WHERE payment_method = ‘qr’ |
| Возвращено | Сумма возвратов | Пока нет возвратов — 0 |
| Всего скидок | Сумма скидок | Пока нет скидок — 0 |
| Всего заказов | Количество заказов за смену | COUNT orders |
| Всего клиентов | Количество уникальных клиентов | Пока нет клиентской базы — = кол-во заказов |
| Средний чек | Выручка / кол-во заказов | Вычисляемое |
Кассовые операции (Phase 2 — пока не реализуем)
| Поле | Описание | Статус |
|---|---|---|
| Сумма начала дня | Внесено при открытии смены | ❌ Phase 2 |
| Добавлено в кассу | Внесения во время смены | ❌ Phase 2 |
| Изъято из кассы | Изъятия во время смены | ❌ Phase 2 |
| Инкассация | Авто при закрытии | ❌ Phase 2 |
| Ожидаемая сумма | Начало + выручка наличными − изъятия | ❌ Phase 2 |
| Чаевые | Наличные чаевые | ❌ Phase 2 |
Товарная аналитика (для Z-отчёта / акта реализации)
| Поле | Описание | Откуда данные |
|---|---|---|
| Продано позиций | Список товаров с количеством и суммой | order_items JOIN orders за смену |
| Топ товаров | Самые продаваемые | Агрегация order_items |
Складское списание (Phase 2)
| Поле | Описание | Статус |
|---|---|---|
| Списано ингредиентов | По техкартам проданных блюд | ❌ Зависит от интеграции Warehouse + Orders |
Phase 1 — что реализуем сейчас
Базовый X/Z отчёт без кассовых операций и складского списания:
Данные отчёта
{
"employee_name": "Иванов Иван",
"store_name": "Кофейня на Ленина",
"shift_start": "2026-04-14T09:00:00",
"shift_end": null,
"total_revenue": 45200.00,
"cash_amount": 15800.00,
"card_amount": 25400.00,
"qr_amount": 4000.00,
"refund_amount": 0.00,
"discount_amount": 0.00,
"total_orders": 47,
"completed_orders": 43,
"cancelled_orders": 2,
"average_check": 961.70,
"top_items": [
{ "name": "Латте", "quantity": 25, "amount": 5500.00 },
{ "name": "Шаурма классическая", "quantity": 18, "amount": 6300.00 }
]
}Новые эндпоинты
Order Service:
| Method | Path | Описание |
|---|---|---|
GET /orders/shift-report | Query: store_id, employee_id, from (datetime), to (datetime) | Агрегация заказов за период: выручка, разбивка по оплате, кол-во, средний чек, топ товаров |
User Service (расширение):
| Method | Path | Описание |
|---|---|---|
GET /shift-records/{id}/report | Собирает данные смены + дёргает Order Service за агрегаты | Полный X/Z отчёт для конкретной смены |
Где отображается
| Где | Что | Роль |
|---|---|---|
| POS-терминал (будущее) | Кнопка “Отчёт” в меню кассы → X-отчёт | Кассир |
| POS-терминал (будущее) | При закрытии смены → Z-отчёт (печать на чековый принтер) | Кассир |
| Админка → Активность → Терминалы | Дашборд по кассам: смены, выручка, сотрудник | Менеджер, Франчайзи, Франшиза |
| Админка → Детали смены | Полный отчёт по конкретной смене (кликнуть из расписания или активности) | Менеджер, Франчайзи, Франшиза |
Phase 2 — кассовые операции
Когда POS будет реализован:
Денежный ящик
- Внесение при открытии смены (размен)
- Изъятие (передача выручки в сейф)
- Инкассация (авто при закрытии)
Статьи калькуляции (как в Юме)
Настраиваемые типы операций:
- Доход — деньги приходят (курьер сдал наличные)
- Расход — деньги уходят (выплата зарплаты из кассы)
- Перевод — перемещение внутри предприятия (из кассы в сейф)
Баланс денежных средств
Страница в бэк-офисе: наличные + безнал + дебиторка + кредиторка по каждому ЮЛ.
Phase 3 — складское списание
Автоматическое списание ингредиентов при закрытии заказа:
- Заказ закрыт → по техкарте каждого блюда → вычитаем ингредиенты со склада ТТ
- В Z-отчёте (акте реализации) → вкладка “Списано”
Ролевой доступ
| Действие | Франшиза | Франчайзи | Менеджер | Кассир |
|---|---|---|---|---|
| X-отчёт (текущая смена на POS) | — | — | — | Свою смену |
| Z-отчёт (после закрытия) | Все ТТ | Свои ТТ | Своя ТТ | Свою смену |
| Дашборд терминалов (админка) | Все ТТ | Свои ТТ | Своя ТТ | Нет |
| Просмотр отчёта по смене (админка) | Все | Свои | Своя ТТ | Нет |
Связи с другими BR
- BR 2.1 (Order Service) — данные по заказам, товарам, оплатам
- BR 1.4.1 (Сотрудники) — смены (
shift_records), дашборд активности - BR 1.5 (Торговые точки) — привязка к ТТ
- Будущее: Finance Service — кассовые операции, баланс, денежные потоки
Приоритеты
| Очередь | Что | Зависимости |
|---|---|---|
| 1 | Эндпоинт агрегации в Order Service | Order Service должен работать |
| 2 | Эндпоинт отчёта по смене в User Service | Зависит от п.1 |
| 3 | Страница “Отчёт по смене” в админке | Зависит от п.2 |
| 4 | Дашборд терминалов (аналог Юмы “Работа касс”) | Зависит от п.2 |
| 5 | Интеграция с POS (когда появится) | POS BFF + POS App |
Что НЕ входит в эту BR
| Фича | Почему | Когда |
|---|---|---|
| Кассовые операции (внесение/изъятие/инкассация) | Нужен POS + Finance Service | Phase 2 |
| Статьи калькуляции | Отдельный модуль финансов | Phase 2 |
| Баланс денежных средств | Нужен Finance Service | Phase 2 |
| Печать отчёта на чековый принтер | Нужен POS | Phase 2 |
| Складское списание при закрытии заказа | Нужна интеграция Warehouse ↔ Orders | Phase 3 |
| Возвраты | Не реализованы в Order Service | Отдельная BR |
| Скидки | Не реализованы | Отдельная BR |
Принятые решения (закрытые вопросы)
| # | Вопрос | Решение | Обоснование |
|---|---|---|---|
| 1 | Граница смены для заказов | По дате оплаты (paid_at) | X/Z отчёт = движение денег. Заказ попадает в смену когда была оплата. |
| 2 | Несколько смен за день | Два отдельных Z-отчёта | Как в Юме — закрыл смену → Z-отчёт. Открыл новую → новый счётчик. |
| 3 | Параллельные кассы | По каждой кассе отдельно | Как в Юме — каждый терминал = свой отчёт. В дашборде видно выручку каждой кассы. |