food-market/docs/architecture.md

Архитектура food-market

Общая схема

┌─────────────────────────────────────────────────────────┐
│                  Internet / LAN магазина                 │
└─────────┬────────────────────────┬──────────────────────┘
          │                        │
          │ HTTPS                   │ HTTPS (+ офлайн-буфер)
          ▼                        ▼
┌───────────────────┐     ┌──────────────────────┐
│  web admin (React) │     │  Windows POS (WPF)   │
│   — браузер         │     │   — с локальной БД    │
│                    │     │   — работает с весами │
└─────────┬──────────┘     └──────────┬───────────┘
          │                           │
          └─────────────┬─────────────┘
                        ▼
          ┌──────────────────────────────┐
          │     food-market.api          │
          │  ASP.NET Core + OpenIddict   │
          │  SignalR hubs для sync       │
          └──────────┬───────────────────┘
                     │
         ┌───────────┼──────────┐
         ▼           ▼          ▼
   ┌─────────┐ ┌──────────┐ ┌──────────┐
   │Postgres │ │ Hangfire │ │  Logs    │
   │  16     │ │ (jobs)   │ │ Serilog  │
   └─────────┘ └──────────┘ └──────────┘

Слои сервера (Clean Architecture)

1. Domain — сущности, value objects, события домена. Не зависит ни от чего.
2. Application — use cases (MediatR handlers), DTO, интерфейсы (репозитории, внешние сервисы). Зависит только от Domain + Shared.
3. Infrastructure — EF Core DbContext, репозитории, Identity, OpenIddict EF store, HTTP-клиенты к внешним сервисам (ОФД, SMS и т.д.). Зависит от Application + Domain.
4. Api — ASP.NET Core host: controllers, middleware, DI wiring, хостинг. Зависит от всех выше.

Мультитенантность

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

• Organization — корневая сущность тенанта. Сама НЕ tenant-scoped.
• Любая другая доменная сущность реализует ITenantEntity (поле OrganizationId).
• User.OrganizationId — к какой организации принадлежит пользователь.

Изоляция

• При каждом запросе HttpContextTenantContext извлекает org_id из JWT.
• AppDbContext.OnModelCreating проходит по всем Entity Types и для каждого ITenantEntity добавляет HasQueryFilter через reflection.
• В итоге _db.Products.ToListAsync() вернёт только товары текущей организации.
• Роль SuperAdmin обходит фильтр (для техподдержки).

Стамповка

• При SaveChanges если добавляется новая ITenantEntity и её OrganizationId == Empty, она автоматически получает OrganizationId из текущего tenant context.
• То же с timestamps: CreatedAt при add, UpdatedAt при modify.

Аутентификация

• OpenIddict 5 в роли OAuth2/OIDC сервера.
• Password Flow для первичного логина (логин/пароль → токены).
• Refresh Token Flow для продления сессии.
• В dev подписи/шифрование — ephemeral ключи; в prod — настоящие X.509 сертификаты.
• Access token содержит claims: sub (user id), name, email, role, org_id.
• Токен валидируется через AddValidation().UseLocalServer() (без дополнительного запроса к IdP).

Синхронизация с POS

Паттерн: Pull-sync + incremental

1. POS периодически (каждые N сек/мин + по событию) запрашивает у сервера delta: GET /api/pos/sync?since={lastSyncTs}.
2. Сервер возвращает JSON с изменениями справочников (товары, цены, сотрудники, настройки) за период.
3. POS применяет изменения в локальной SQLite БД в одной транзакции.
4. Продажи, совершённые на POS, пушатся обратно: POST /api/pos/sales с массивом документов.
5. Если связи нет — POS продолжает работать, копит изменения в локальной очереди, отправляет при восстановлении.

Conflict resolution

• Сервер — источник правды для справочников.
• POS — источник правды для продаж на своей кассе (каждая продажа имеет posTerminalId + локальный externalId, которые серверу гарантируют идемпотентность).

Фоновые задачи

Hangfire + PostgreSQL storage:

• Агрегация дневной выручки для dashboard.
• Очистка логов старше 90 дней.
• Ретрай отправки чеков в ОФД (когда появится интеграция).
• Еженедельная инвентаризация напоминаний.