ERP Platform Docs

2.1 Order Service

время чтения ~4 мин.

BR 2.1: Order Service — Сервис заказов

Зависит от:

Контекст

Заказы — ядро бизнеса. Без Order Service невозможно: пробить товар, принять оплату, отследить выручку. POS-терминал делается параллельно другой командой — Order Service предоставляет API, POS его потребляет.

MVP: простейший сценарий шаурмечной — кассир пробивает товары, клиент оплачивает, заказ закрыт. Типы заказов заложены (навынос/на месте/доставка), но реализован только takeaway.

В YumaPos заказы поддерживают: 5 типов, множественные способы оплаты, кухонный дисплей, возвраты. Phase 1 — минимум.

Требования

1. Новый микросервис

  • Репозиторий: erp-order-service
  • Порт: :3005
  • Stack: Java + Spring Boot + PostgreSQL (как остальные)
  • Database: order_db
  • Auth: JWT (franchise_id, store_ids, role из токена)

Требуется создать новый репозиторий

GitHub: nearbyErp/erp-order-service. Dockerfile, docker-compose в erp-infrastructure.

2. Заказ (order)

Поля:

  • ID
  • Номер заказа (автоинкремент per-store per-day: #001, #002…)
  • Тип заказа: takeaway (MVP) | dine_in | delivery (заложены, не реализованы)
  • Статус: new → in_progress → ready → closed | cancelled
  • ТТ (store_id)
  • Итого (total) — сумма всех позиций
  • Способ оплаты: cash | card | qr | mixed | null (до оплаты)
  • Сумма оплаты (paid_amount)
  • Комментарий (опционально)
  • Создал (created_by — ID кассира/менеджера)
  • Дата создания, оплаты, завершения, отмены

3. Позиция заказа (order_item)

Поля:

  • ID
  • Заказ (order_id)
  • Товар (product_id, product_name — денормализовано)
  • Количество
  • Цена за единицу
  • Стоимость (кол-во × цена)
  • Модификаторы (JSON: [{group_name, option_name, price}])
  • Комментарий к позиции (опционально, “без лука”)

4. Статусная машина

new → in_progress → ready → closed
  ↘                        ↗
           cancelled
  • new — заказ создан. Можно добавлять/убирать позиции.
  • in_progress — отправлен на кухню (Phase 2). MVP: можно пропустить и сразу ready.
  • ready — готов к выдаче.
  • closed — выдан клиенту, оплачен. Финальный статус.
  • cancelled — отменён. Из new или in_progress. Из closed нельзя (возврат — Phase 2).

5. Оплата

Order Service не проводит платёж — только фиксирует факт. POS-терминал проводит платёж (PBF ядро), затем сообщает Order Service:

POST /orders/{id}/pay
{
  "method": "cash",     // cash | card | qr | mixed
  "amount": 630.00,
  "rrn": null,          // для карты — от PBF
  "card_last4": null    // для карты
}

Order Service: проставляет paid_at, payment_method, paid_amount. Статус → ready (или closed если сразу выдано).

6. Фронт в erp-admin

Секция “Заказы” в sidebar:

Заказы
├── Активные
└── История

Активные заказы (/orders/active):

  • Фильтр по ТТ (dropdown, как на стоп-листах)
  • Таблица: №, Время, Тип, Статус badge, Сумма, Оплата, Кассир
  • Обновление по таймеру (каждые 30 сек) или по кнопке

История заказов (/orders/history):

  • Фильтр по ТТ + дате + статусу
  • Таблица: №, Дата, Тип, Статус, Сумма, Оплата, Кассир
  • Клик по заказу → детали с позициями

Карточка заказа (/orders/:id):

  • Шапка: номер, статус, ТТ, дата, кассир
  • Таблица позиций: товар, кол-во, цена, модификаторы, стоимость
  • Итого
  • Данные оплаты (если оплачен)

Read-only для всех ролей в админке. Управление заказами — через POS.

Бизнес-правила

  1. Номер per-store per-day — #001 сбрасывается каждый день для каждой ТТ
  2. Позиции только в new — добавлять/убирать можно пока статус new
  3. Отмена — только до closed. После закрытия — возврат (Phase 2)
  4. Оплата — фиксация факта, не проведение. POS отвечает за платёж
  5. Денормализация — product_name и цена копируются в заказ (не зависят от изменений каталога после создания)
  6. Модификаторы — JSON в order_item, денормализованы (имя + цена на момент заказа)

Ролевой доступ

ДействиеФраншизаФранчайзиМенеджерКассир
Просмотр заказовВсе ТТСвои ТТСвоя ТТСвоя ТТ
Создать заказ (через API)———Да (POS)
Оплатить (через API)———Да (POS)
ОтменитьЛюбойСвои ТТСвоя ТТСвой заказ
Просмотр в админкеДаДаДаНет

Затронутые сервисы

СервисЧто меняется
Order Service (НОВЫЙ)erp-order-service :3005. Таблицы: orders, order_items. CRUD + статусная машина. ~10 эндпоинтов.
erp-admin (BFF)Proxy routes для Order Service
erp-admin (web)Секция “Заказы”: активные + история + карточка заказа
erp-infrastructureDocker Compose: добавить order-service
07-Tasks/Repositories.mdОбновить: добавить erp-order-service

Что НЕ входит (Phase 2+)

  • POS-терминал UI (делается другой командой)
  • Кухонный дисплей
  • Доставка (логистика, курьеры)
  • Возвраты/рефанды
  • Скидки/промокоды
  • Лояльность (баллы как оплата)
  • Подарочные карты
  • Авто-списание со склада при продаже (Kafka → Warehouse)
  • Фискализация (PBF — POS отвечает)
  • Разделение счёта (групповые заказы)
  • Привязка клиента к заказу
  • Статус in_progress (кухня) — MVP пропускает

Ссылки

Вид графа

Обратные ссылки