food-market/docs/pos.md

Касса food-market — инструкция (кассир и администратор)

Кроссплатформенная касса на Avalonia 11 / .NET 8. Работает на Windows 10/11 и Linux x64. Быстрая, без лишнего; офлайн-режим; сервер — food-market (api/pos/v1).

Установка

Windows 10/11

1. Скачайте food-market-pos-win-x64-<версия>.zip (ссылка — в админке, раздел «Точки продаж») и распакуйте в любую папку, напр. C:\food-market-pos.
2. Запустите foodmarket.Pos.exe. .NET устанавливать НЕ нужно (сборка self-contained).
3. Ярлык на рабочий стол — по желанию (правой кнопкой по exe → «Создать ярлык»).

Linux x64 (Ubuntu и др.)

1. Распакуйте food-market-pos-linux-x64-<версия>.tar.gz.
2. chmod +x foodmarket.Pos && ./foodmarket.Pos.
3. Для весов/принтера по COM добавьте пользователя в группу dialout.
4. Либо запустите переносимый food-market-pos-<версия>-x86_64.AppImage (если собран).

Скачать (администратор)

В админке на странице «Кассы» (точки продаж) — карточка «Кассовое приложение» со ссылками «Скачать для Windows / для Linux». Ссылки и версия задаются на сервере в конфигурации (секция Pos: LatestVersion, DownloadWindows, DownloadLinux).

Автообновление

При старте касса сверяет свою версию (VERSION.txt в сборке) с GET /api/pos/v1/version и при более новой версии показывает в статус-баре «Доступно обновление …» со ссылкой.

Первый запуск (администратор точки)

1. Адрес сервера — URL вашего food-market (напр. https://admin.food-market.kz).
2. Регистрация устройства — касса привязывается к точке продаж (retail point). Кассир видит только свои точки (к которым он привязан в админке).
3. Вход кассира — логин и PIN/пароль учётной записи кассира.

Горячие клавиши (работа без мыши)

• Сканер — печатает штрихкод в поле ввода, Enter добавляет товар (keyboard-wedge, фокус не нужен).
• F1 — помощь · F2 — поиск товара по названию · F7 — внесение/выплата.
• F9 — возврат · F10 — смена (открыть/закрыть, X/Z) · F12 — оплата · Esc — отмена/очистить чек.
• Del — удалить выделенную строку · +/− — количество.

Смена

• Открыть смену (ввести размен). Без открытой смены продавать нельзя.
• Внесение / выплата наличных (инкассация) — с причиной.
• X-отчёт — промежуточный (смена не закрывается); Z-отчёт — при закрытии (должно быть / факт / разница). Деньги смены учитываются сервером в остатках счетов (см. docs/money.md).

Продажа

• Пробитие по сканеру или поиск по названию.
• Весовой товар: вес с весов по COM (CAS / Масса-К) или ручной ввод; весовой штрихкод с префиксом 20–29 (код + вес/цена) распознаётся автоматически.
• Скидка на позицию и на чек (по праву).
• Оплата: наличные / карта / смешанная; показывается сдача.
• Отложенный чек — кнопка «Отложить» сохраняет текущий чек и открывает новый (обслужить другого покупателя), «Вернуть» — восстанавливает отложенный.

Возврат

• По чеку (номер или скан QR) — частичный или полный.
• Без чека — по праву администратора.

Весы (COM/serial)

• Протоколы: CAS, Масса-К (ASCII). Настройка: порт (COM1 / /dev/ttyUSB0), скорость.
• Нет весов/связи — ручной ввод веса.

Печать чека

• ESC/POS на чековый принтер: USB (/dev/usb/lp0 или COMn), сеть (tcp:IP:9100), ширина 58 мм (32 симв.) или 80 мм (48 симв.).
• Запасной вариант — текстовый/обычный принтер/PDF.
• X/Z-отчёты печатаются так же.

Офлайн

• Каталог (товары, цены, штрихкоды, весовые) хранится локально (SQLite) — первичная загрузка + дельта-синхронизация.
• Без сети касса продолжает работать: чеки пишутся локально и уходят на сервер очередью с идемпотентным ключом (повтор не создаёт дублей).
• В статус-баре: «на связи / нет связи» и число чеков в очереди.

Фискализация (ОФД Казахстана)

Сейчас касса НЕ фискализирует чеки (интерфейс-заглушка IFiscalProvider). Для реальной фискализации KZ потребуется:

• Договор с ОФД-оператором (Казахтелеком/Webkassa/др.) и регистрация онлайн-ККМ.
• Реализация IFiscalProvider.RegisterSaleAsync под API выбранного оператора (регистрация чека, получение фискального номера и QR, печать на чеке).
• Хранение ключей/токенов ОФД защищённо (как refresh-токен кассира).
• Серверная синхронизация фискальных признаков (поля уже есть в RetailSale).

Производительность (замеры)

• Поиск по штрихкоду — ~14 мс, по названию на 30 000 товаров — ~47 мс (локальный SQLite с индексами).
• Первичная загрузка 30 000 товаров — ~9 с (однократно при настройке).
• Сборка self-contained + ReadyToRun (R2R). Холодный старт: Linux ~120 мс; Windows прогретый — ~220 мс (R2R) / ~150 мс (без R2R).

Первый запуск на Windows медленный (4–5 с) — что делать

Самый первый запуск кассы сразу после установки занимает 4–5 с (с R2R; без R2R было 7,5 с). Это НЕ код кассы: Windows Defender на лету сканирует свежий неподписанный exe (~114 МБ, self-contained), плюс холодное чтение файла с диска. Каждый следующий запуск — ~0,2 с. Как ускорить первый запуск на кассовом ПК:

1. Исключение в Defender для папки кассы (одноразово, администратором): Add-MpPreference -ExclusionPath "C:\food-market-pos" (PowerShell от админа).
2. Прогрев при установке — установщик может один раз запустить foodmarket.Pos.exe (например, --smoke) после распаковки, чтобы Defender просканировал файлы заранее.
3. Подпись exe (code signing) — позже; подписанный бинарник Defender сканирует быстрее и не держит пользователя на SmartScreen. Замеры холодного старта (Linux/Windows, R2R и без) — см. docs/pos-progress.md.