# Касса 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 медленный — что делать
Тёплый старт кассы — доли секунды (окно из локальной SQLite, синк в фоне). Медленный
только САМЫЙ первый запуск сразу после установки: Windows Defender на лету сканирует
свежий неподписанный бандл (~115 МБ, self-contained + R2R). Замер на Win11 VM:
холодный старт **10 с без исключения → 4,5 с с исключением Defender**; тёплый ~0,6 с.
Готовый установщик — `deploy/pos-install.ps1` (распаковка + исключение Defender от
админа + прогрев `--smoke` + ярлык). Вручную:
1. **Исключение в Defender** для папки кассы (одноразово, от админа):
   `Add-MpPreference -ExclusionPath "<папка кассы>"`.
2. **Прогрев** — один запуск `foodmarket.Pos.exe --smoke` после распаковки.
3. **Подпись exe** (code signing) — на решение владельца, пока НЕ покупали: OV ~ $200–400/год
   (Sectigo/DigiCert), EV ~ $300–600/год. Подписанный бинарник Defender сканирует быстрее,
   EV сразу снимает предупреждение SmartScreen без исключения Defender.
Полные замеры до/после (Linux + Windows, 30 000 товаров) — см. docs/pos-progress.md,
раздел «Мгновенный старт».