docs(s12): ARCHITECTURE/MULTI-TENANCY/RUNBOOK/DEVELOPER-GUIDE + k6 baseline + stage-verify CI
Документация для следующего разработчика (4 файла, ~1500 строк по
существу), реальный нагрузочный baseline на stage, и автоматический
smoke на каждый push.
Доки:
- docs/ARCHITECTURE.md — карта слоёв, модулей, Program.cs composition
root, полный поток signup→post с трассировщиком ASP.NET pipeline.
- docs/MULTI-TENANCY.md — ITenantEntity + reflection query-filter,
stamping в SaveChanges, SuperAdmin override (read-only + edit-mode
с reason), 8 подводных камней, чеклист «как добавить tenant-сущность».
- docs/RUNBOOK.md — health-чеки, backup/restore с примером, смена SDK,
disaster-recovery на новый сервер, 6 описанных инцидентов
(включая docker-compose project name), БД-troubleshooting.
- docs/DEVELOPER-GUIDE.md — локальный setup, гочи integration-тестов,
полные паттерны (controller с permission + tenant-сущность с
RowVersion + 5 шагов миграции), валидация, structured-логирование,
«НЕ делать» список.
k6 baseline:
- tests/load/ — 3 скрипта (signup-burst, retail-sales-parallel,
sales-report-heavy) + README с инструкциями.
- docs/performance-baseline.md — реальные цифры на stage:
* signup p95 446ms @ 50 RPM (IP-лимит 60/мин держит);
* retail-sale sequential — 17/sec, p95 71ms;
* retail-sale @ VU>1 — 53% failure из-за race в
GenerateNumberAsync (unique-violation 23505 не ловится в
SaveOrFkErrorAsync) — P0 для следующего рефакторинга;
* reports на 1500 чеков — p95 50-114ms до VU=5.
CI:
- .forgejo/workflows/stage-verify.yml — on workflow_run после Docker
API/Web, wait-for-ready → tests/stage-smoke.sh → Telegram пинг.
- tests/stage-smoke.sh — 7-секундный bash-смок (curl+jq+python3),
5 этапов: health, signup, token, multi-tenant изоляция (B → 404
на product A, B → пустой список), полный документ-цикл
(supplier+supply.post → stock=100 → sale.post → stock=99).
Локальный прогон против stage — все этапы зелёные.
Build чистый, локальный прогон smoke зелёный. Sprint 12 закрывает
автономно-безопасный цикл — дальше нужен вход от user'а.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
nns
parent
0d3ef81f72
commit
97e26a65d5
70
.forgejo/workflows/stage-verify.yml
Normal file
70
.forgejo/workflows/stage-verify.yml
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
name: Stage verify
|
||||
|
||||
# Запускается ПОСЛЕ успешного docker-api или docker-web — они уже
|
||||
# собирают и деплоят на stage. Эта работа делает быстрый smoke
|
||||
# (~30с): auth, multi-tenant изоляция, один полный документ-цикл
|
||||
# (signup → seed → supply.post → retail-sale.post → проверка остатка).
|
||||
#
|
||||
# Если падает — пинг в Telegram. По дефолту в notify.yml уже есть
|
||||
# perfailure нотификация для CI/Docker — этот workflow добавляет к ним.
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: ["Docker API", "Docker Web"]
|
||||
types: [completed]
|
||||
workflow_dispatch:
|
||||
|
||||
# Не запускаемся, если триггерный workflow упал — нет смысла верифировать
|
||||
# то что не задеплоилось.
|
||||
jobs:
|
||||
smoke:
|
||||
name: Smoke против stage
|
||||
if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
|
||||
runs-on: [self-hosted, linux]
|
||||
env:
|
||||
BASE_URL: https://test.admin.food-market.kz
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Wait for health/ready
|
||||
run: |
|
||||
for i in 1 2 3 4 5 6 7 8 9 10; do
|
||||
if curl -fsS "$BASE_URL/health/ready" | grep -q '"status":"Healthy"'; then
|
||||
echo "Stage ready"
|
||||
exit 0
|
||||
fi
|
||||
echo "[$i/10] not ready yet, sleeping..."
|
||||
sleep 3
|
||||
done
|
||||
echo "Stage NOT ready after 30s" >&2
|
||||
exit 1
|
||||
|
||||
- name: Run smoke suite
|
||||
env:
|
||||
BASE_URL: ${{ env.BASE_URL }}
|
||||
run: bash tests/stage-smoke.sh
|
||||
|
||||
- name: Notify Telegram on success
|
||||
if: success() && github.event_name == 'workflow_run'
|
||||
env:
|
||||
BOT: ${{ secrets.TELEGRAM_BOT_TOKEN }}
|
||||
CHAT: ${{ secrets.TELEGRAM_CHAT_ID }}
|
||||
SHA: ${{ github.event.workflow_run.head_sha }}
|
||||
run: |
|
||||
curl -sS -X POST "https://api.telegram.org/bot$BOT/sendMessage" \
|
||||
--data-urlencode "chat_id=$CHAT" \
|
||||
--data-urlencode "text=✅ stage verify OK — ${SHA:0:7}" \
|
||||
> /dev/null
|
||||
|
||||
- name: Notify Telegram on failure
|
||||
if: failure()
|
||||
env:
|
||||
BOT: ${{ secrets.TELEGRAM_BOT_TOKEN }}
|
||||
CHAT: ${{ secrets.TELEGRAM_CHAT_ID }}
|
||||
SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
|
||||
run: |
|
||||
RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
|
||||
curl -sS -X POST "https://api.telegram.org/bot$BOT/sendMessage" \
|
||||
--data-urlencode "chat_id=$CHAT" \
|
||||
--data-urlencode "text=❌ stage verify FAILED — ${SHA:0:7} — $RUN_URL" \
|
||||
> /dev/null
|
||||
397
docs/ARCHITECTURE.md
Normal file
397
docs/ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,397 @@
|
|||
# food-market — архитектура
|
||||
|
||||
Документ для разработчика, который пришёл в проект первый раз. Описывает
|
||||
слои, модули, ключевые потоки и почему некоторые вещи сделаны именно так.
|
||||
|
||||
Старая короткая версия — `docs/architecture.md` (lowercase). Этот файл
|
||||
заменяет её и расширяет.
|
||||
|
||||
## TL;DR
|
||||
|
||||
- **Что**: multi-tenant SaaS-аналог МойСклад для розничных магазинов РК.
|
||||
- **Backend**: .NET 8 LTS, ASP.NET Core, EF Core 8, PostgreSQL 14+ (dev) / 16 (prod).
|
||||
- **Auth**: OpenIddict 5 (password + refresh) поверх ASP.NET Identity.
|
||||
- **Web**: React 19 + Vite + TS, Tailwind v4, shadcn/ui, TanStack Query, AG Grid.
|
||||
- **POS**: WPF на .NET 8 Windows, оффлайн-буфер в SQLite, синк через `/api/pos/v1`.
|
||||
|
||||
## Топология deployment
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Internet / LAN магазина │
|
||||
└───────────┬───────────────────────┬─────────────────────────────┘
|
||||
│ HTTPS │ HTTPS (Bearer) + офлайн-буфер
|
||||
▼ ▼
|
||||
┌────────────────────┐ ┌──────────────────────────┐
|
||||
│ food-market.web │ │ food-market.pos (WPF) │
|
||||
│ React SPA │ │ .NET 8, Windows 10+ │
|
||||
│ admin.fm.kz │ │ локальная SQLite │
|
||||
└─────────┬──────────┘ └──────────┬───────────────┘
|
||||
│ │
|
||||
│ /api/* │ /api/pos/v1/*
|
||||
│ /hubs/notifications │
|
||||
└─────────────┬────────────┘
|
||||
▼
|
||||
┌───────────────────────────────────────────┐
|
||||
│ food-market.api │
|
||||
│ ASP.NET Core + OpenIddict + SignalR │
|
||||
│ - tenant query filters per request │
|
||||
│ - Hangfire scheduler + recurring jobs │
|
||||
│ - /metrics (Prometheus) /health/{live,ready}│
|
||||
└────┬──────────┬───────────┬───────────┬───┘
|
||||
▼ ▼ ▼ ▼
|
||||
┌────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐
|
||||
│Postgres│ │ Hangfire│ │ MinIO │ │ Logs │
|
||||
│ 16 │ │ (jobs) │ │ (S3, opt)│ │ Serilog │
|
||||
└────────┘ └─────────┘ └──────────┘ └──────────┘
|
||||
│
|
||||
▼
|
||||
локальный FS (/uploads volume)
|
||||
— если MinIO не настроен
|
||||
```
|
||||
|
||||
Stage и prod крутятся через `deploy/docker-compose.yml` на dev-vm
|
||||
(`192.168.1.190`). Локальный dev: API на `:5081`, Postgres из
|
||||
brew (`postgres@14` на `:5432`), web через `pnpm dev` на `:5173`.
|
||||
|
||||
## Структура солюшна
|
||||
|
||||
```
|
||||
food-market/
|
||||
├── src/
|
||||
│ ├── food-market.domain/ ← POCO, enum, доменные интерфейсы
|
||||
│ ├── food-market.application/ ← MediatR-handlers, DTO, абстракции
|
||||
│ ├── food-market.infrastructure/ ← EF Core, Identity, OpenIddict EF, внешние API
|
||||
│ ├── food-market.api/ ← ASP.NET Core host: controllers, middleware, DI
|
||||
│ ├── food-market.web/ ← React SPA
|
||||
│ ├── food-market.shared/ ← DTO-контракты api ↔ pos
|
||||
│ ├── food-market.public/ ← Astro static (маркетинг food-market.kz)
|
||||
│ ├── food-market.pos.core/ ← логика POS (без UI)
|
||||
│ └── food-market.pos/ ← WPF UI (net8.0-windows)
|
||||
├── tests/
|
||||
│ ├── food-market.UnitTests/ ← xUnit + InMemoryDB
|
||||
│ ├── food-market.IntegrationTests/← xUnit + Testcontainers Postgres
|
||||
│ ├── e2e/ ← Playwright (TS), бьёт по test.admin.food-market.kz
|
||||
│ └── load/ ← k6 (Sprint 12)
|
||||
├── deploy/ ← docker-compose, Dockerfile.*, systemd-юниты
|
||||
└── docs/ ← вы здесь
|
||||
```
|
||||
|
||||
### Слои (Clean Architecture)
|
||||
|
||||
| Слой | Зависит от | Что лежит |
|
||||
|-------------------|---------------------------|----------------------------------------------------------------------------------------|
|
||||
| **domain** | ничего | POCO-сущности, enum'ы, доменные интерфейсы (`ITenantEntity`, `IVersionedEntity`). |
|
||||
| **application** | domain + shared | MediatR `IRequest`/`IRequestHandler`, DTO, абстракции (`IFiscalProvider`, `IEmailSender`, `IStockService`, `ITenantContext`), `FluentValidation` валидаторы. |
|
||||
| **infrastructure**| application + domain | `AppDbContext`, Identity-таблицы, OpenIddict EF store, реализации абстракций, HTTP-клиенты к внешним API (Webkassa, MoySklad, MailKit, Telegram). |
|
||||
| **api** | всё перечисленное выше | ASP.NET Core host: контроллеры, middleware, DI-проводка, фоновые джобы (Hangfire), Realtime hub'ы (SignalR), сидеры. |
|
||||
|
||||
Правило одностороннего направления зависимостей: домен не знает про EF и
|
||||
ASP.NET, application — про конкретные провайдеры. Это позволило прикрутить
|
||||
ОФД (Sprint 11) одним интерфейсом + четырьмя реализациями, без правок
|
||||
контроллеров кроме одной точки вызова.
|
||||
|
||||
## Модули backend
|
||||
|
||||
### Domain (`src/food-market.domain/`)
|
||||
|
||||
- `Common/Entity.cs` — базовая `Entity` с `Id/CreatedAt/UpdatedAt`.
|
||||
- `Common/TenantEntity.cs` — `ITenantEntity` (обязательный `OrganizationId`),
|
||||
`TenantEntity` (база), `IOptionalTenantEntity` (системные справочники с
|
||||
`OrganizationId?`).
|
||||
- `Common/IVersionedEntity.cs` — оптимистичная блокировка через PG `xmin`
|
||||
(`Xmin` поле).
|
||||
- Бизнес-сущности по поддоменам: `Catalog/` (Product, Counterparty,
|
||||
ProductGroup, …), `Inventory/` (Stock, StockMovement, Loss, Transfer,
|
||||
Inventory), `Purchases/` (Supply, Enter, SupplierReturn),
|
||||
`Sales/` (RetailSale, RetailSaleLine, Demand, LoyaltyCard,
|
||||
LoyaltyProgram, Promotion), `Organizations/` (Organization, Employee,
|
||||
EmployeeRole, OrgAuditLog, SuperAdminAuditLog), `Platform/`
|
||||
(PlatformSettings — singleton SMTP-конфиг).
|
||||
|
||||
### Application (`src/food-market.application/`)
|
||||
|
||||
- **CQRS на MediatR** — пока partial: образцы в `Purchases/Commands/CreateSupplyCommand.cs`,
|
||||
`Sales/Commands/PostRetailSaleCommand.cs`, `Sales/Queries/GetSalesReportQuery.cs`.
|
||||
Большинство контроллеров пока «толстые» (исторически до TD-1).
|
||||
- **Абстракции**:
|
||||
- `Common/Tenancy/ITenantContext` — `OrganizationId`, `IsSuperAdmin`,
|
||||
`IsTenantOverride`, `UserId`.
|
||||
- `Common/Email/IEmailSender` — отправка через текущий SMTP-конфиг.
|
||||
- `Common/Fiscal/IFiscalProvider` + `IFiscalProviderFactory` (Sprint 11).
|
||||
- `Inventory/IStockService` — единая точка списания/начисления остатка
|
||||
(любая операция, меняющая склад, идёт через `ApplyMovementAsync`).
|
||||
- **FluentValidation** валидаторы рядом с DTO; глобально подключаются
|
||||
через `AddValidatorsFromAssemblyContaining<Program>()`.
|
||||
|
||||
### Infrastructure (`src/food-market.infrastructure/`)
|
||||
|
||||
- `Persistence/AppDbContext.cs` — единый DbContext (тенанта + Identity +
|
||||
OpenIddict EF store). Query-filter применяется через reflection ко всем
|
||||
`ITenantEntity` (см. [MULTI-TENANCY.md](MULTI-TENANCY.md)).
|
||||
- `Persistence/Configurations/*.cs` — EF Core fluent configs по поддоменам.
|
||||
- `Persistence/Migrations/` — миграции пишутся вручную (см. CLAUDE.md /
|
||||
memory `feedback_ef_migrations`), снапшот не синхронизируется
|
||||
с моделью (используется только `dotnet ef migrations add`, который
|
||||
не вызывается в этом проекте).
|
||||
- `Persistence/OrgAuditInterceptor.cs` — EF `ISaveChangesInterceptor`,
|
||||
пишет каждую `Add/Update/Delete` в `org_audit_log` (JSONB diff).
|
||||
- `Identity/` — кастомные `User`, `Role` для ASP.NET Identity.
|
||||
- `Email/MailKitEmailSender.cs` — SMTP через MailKit, конфиг из
|
||||
`PlatformSettings` (читается на каждой отправке через scope).
|
||||
- `Fiscal/` — `IFiscalProvider` реализации: Mock + Webkassa (полный) +
|
||||
Kassa24/OfdSolo (skeleton). См. [ofd-integration.md](ofd-integration.md).
|
||||
- `Inventory/StockService.cs` — единственное место, где двигаются остатки.
|
||||
Бизнес-инвариант: stock = SUM(stock_movements) per (productId, storeId).
|
||||
- `Integrations/MoySklad/` — HTTP-клиент + конвертер для импорта каталога.
|
||||
|
||||
### Api (`src/food-market.api/`)
|
||||
|
||||
- `Program.cs` — composition root (~570 строк, поделён логическими
|
||||
блоками; см. секцию «Composition root» ниже).
|
||||
- `Controllers/` — REST-API. Структура совпадает с маршрутами:
|
||||
- `Auth/` — `/api/auth/*` (signup, forgot-password, 2FA).
|
||||
- `Catalog/` — `/api/catalog/{products,counterparties,…}`.
|
||||
- `Purchases/` — `/api/purchases/{supplies,supplier-returns}`.
|
||||
- `Sales/` — `/api/sales/{retail,demands}`.
|
||||
- `Inventory/` — `/api/inventory/{stock,enters,losses,transfers,inventories}`.
|
||||
- `Reports/` — `/api/reports/{sales,stock,profit,abc}`.
|
||||
- `Dashboard/` — `/api/dashboard/{top-products,low-stock,recent-sales,margin}`.
|
||||
- `Loyalty/`, `Promotions/` — Sprint 9.
|
||||
- `Organizations/` — настройки орги, сотрудники, роли, ОФД.
|
||||
- `Pos/` — `/api/pos/v1/*` для WPF POS (sync, idempotency).
|
||||
- `SuperAdmin/` — `/api/super-admin/*` (управление платформой).
|
||||
- `Admin/` — `/api/admin/*` (per-org admin tools: cleanup, demo-seed,
|
||||
moysklad-import, audit-log просмотр).
|
||||
- `Search/` — глобальный `/api/search/global` (Cmd+K).
|
||||
- `Telegram/` — bind owner-chat, статус.
|
||||
- `Uploads/` — multipart upload изображений.
|
||||
- `Infrastructure/`:
|
||||
- `Tenancy/HttpContextTenantContext.cs` — реализация `ITenantContext`
|
||||
через `IHttpContextAccessor` + AsyncLocal-override для background tasks.
|
||||
- `Tenancy/SuperAdminOverrideClaimsTransformer.cs` — добавляет
|
||||
`Admin/Cashier/Storekeeper` роли SuperAdmin'у с активным
|
||||
`X-Org-Override`, чтобы `[Authorize(Roles="Admin")]` не отшил его.
|
||||
- `Tenancy/ReadonlyOverrideMiddleware.cs` — в режиме override без
|
||||
`X-Org-Override-Reason` блочит любую мутацию (читать всё, писать
|
||||
ничего; писать — только в edit-mode с reason).
|
||||
- `Tenancy/SuperAdminEditAuditFilter.cs` — глобальный action-filter,
|
||||
при mutate-в-override пишет в `super_admin_audit_log`.
|
||||
- `Authorization/RequiresPermissionAttribute.cs` + `PermissionAuthorizationPolicyProvider`
|
||||
+ `PermissionAuthorizationHandler` — permission-based авторизация.
|
||||
`[RequiresPermission("ProductsEdit")]` → policy `perm:ProductsEdit` →
|
||||
`RolePermissions.ProductsEdit` булева на `EmployeeRole`.
|
||||
- `Validation/ValidationFilter.cs` — FluentValidation → 400
|
||||
ProblemDetails (RFC 7807).
|
||||
- `RateLimiting/AuthRateLimiterExtensions.cs` — 5/мин + 20/час на
|
||||
`/connect/token`, `/api/auth/signup` по IP+username.
|
||||
- `Observability/LogEnrichmentMiddleware.cs` — кладёт
|
||||
`CorrelationId/OrgId/UserId` в Serilog `LogContext`, каждая запись
|
||||
в журнале получает эти лейблы.
|
||||
- `Observability/DbMetricsInterceptor.cs` — EF интерсептор, Prometheus
|
||||
`food_market_db_query_duration_seconds`.
|
||||
- `Observability/AppMetrics.cs` — статические Counter'ы (Posted/Unposted
|
||||
per docType, FiscalRegistered, …).
|
||||
- `Health/DatabaseReadyHealthCheck.cs` — `SELECT 1` + проверка
|
||||
`__EFMigrationsHistory`.
|
||||
- `Security/OpenIddictKeyConfigurator.cs` — в dev — persistent RSA в
|
||||
`App_Data/oidc-keys/*`; в stage/prod — X509 PFX из конфига
|
||||
(см. [openiddict-keys.md](openiddict-keys.md)).
|
||||
- `Realtime/NotificationsHub.cs` + `NotificationsPublisher.cs` —
|
||||
SignalR-хаб `/hubs/notifications`, группы per-org. События:
|
||||
`SalePosted`, `LowStock`, `ImportProgress`.
|
||||
- `Background/`:
|
||||
- `HangfireJobsConfigurator` — регистрирует recurring jobs при старте:
|
||||
`prune-stock-movements` (03:30), `prune-audit-log` (03:45),
|
||||
`weekly-summary` (пн 07:00), `low-stock-alert` (08:00),
|
||||
`telegram-owner-daily-summary` (06:00).
|
||||
- `HousekeepingJobs` — pg-cleanup'ы.
|
||||
- `EmailNotificationJobs` — weekly-summary + low-stock email.
|
||||
- `OwnerDailySummaryJob` — Telegram-сводка владельцу.
|
||||
- `ReferencePriceRefreshJob` — пересчёт `Product.ReferencePrice`
|
||||
каждые 30 дней без приёмок.
|
||||
- `Seed/`:
|
||||
- `SystemReferenceSeeder` — справочники (страны, валюты, единицы).
|
||||
- `OpenIddictClientSeeder` — регистрирует client `food-market-web`.
|
||||
- `DevDataSeeder` — dev-only admin user (SuperAdmin).
|
||||
- `DemoTenantSeeder` / `YearDemoSeeder` — заполняют tenant
|
||||
демо-данными (Sprint 5 / Sprint 10).
|
||||
|
||||
### Web (`src/food-market.web/`)
|
||||
|
||||
- Vite + React 19 + TS 6, Tailwind v4. Маршрутизация — React Router 6.
|
||||
- `src/lib/api.ts` — axios instance с auto-refresh токена.
|
||||
- `src/lib/auth.ts` — login/logout, store токена в `localStorage`.
|
||||
- `src/components/` — общие виджеты (Field, Button, Skeleton,
|
||||
CommandPalette, DashboardWidgets).
|
||||
- `src/pages/` — страницы (один файл per route).
|
||||
- TanStack Query — кеширование API-вызовов, инвалидация по SignalR.
|
||||
- AG Grid Community — большие списки (товары, контрагенты, отчёты).
|
||||
|
||||
### POS (`src/food-market.pos*/`)
|
||||
|
||||
- `pos.core/` — логика без UI: оффлайн-буфер, sync, расчёт чека.
|
||||
- `pos/` — WPF UI, CommunityToolkit.Mvvm, SQLite, Refit + Polly,
|
||||
System.IO.Ports для весов CAS.
|
||||
- Sync: батчем по 50 чеков через `POST /api/pos/v1/batch` с
|
||||
`Idempotency-Key`. Сервер дедупит через `pos_batch_acks` уникальный
|
||||
индекс (`OrganizationId, IdempotencyKey`).
|
||||
|
||||
## Composition root (`Program.cs`)
|
||||
|
||||
Логические блоки в порядке регистрации:
|
||||
|
||||
1. **Serilog** bootstrap (до builder).
|
||||
2. **CORS** (`Cors:AllowedOrigins` из конфига).
|
||||
3. **HttpContextAccessor** + `ITenantContext` + `IClaimsTransformation`
|
||||
(SuperAdmin override роли).
|
||||
4. **EF Core**: `AppDbContext` (Npgsql, OpenIddict, два interceptor'а).
|
||||
5. **Identity** + **OpenIddict** server (password + refresh, rolling
|
||||
refresh, leeway = 0).
|
||||
6. **Authentication/Authorization** policies (`AdminAccess`, `perm:*`).
|
||||
7. **Rate-limiter** (`/connect/token`, `/api/auth/signup`).
|
||||
8. **HealthChecks** (`database` тег `ready`).
|
||||
9. **IEmailSender** (Singleton + scope для DbContext).
|
||||
10. **IFiscalProvider** + 3 HttpClient + `IFiscalProviderFactory`.
|
||||
11. **MediatR** (assembly scan), **FluentValidation**.
|
||||
12. **MoySklad HttpClient** + import service.
|
||||
13. **Hangfire** server + storage (PG), `HangfireJobsConfigurator` хостед.
|
||||
14. **SignalR** + `INotificationsPublisher`.
|
||||
15. **Telegram-бот** HttpClient (если token задан).
|
||||
16. **Сидеры**: `OpenIddictClientSeeder`, `SystemReferenceSeeder`,
|
||||
`DevDataSeeder` хостед; `DemoTenantSeeder`/`YearDemoSeeder` scoped.
|
||||
17. `Build()` → middleware pipeline (Serilog→CORS→HttpMetrics→
|
||||
RateLimiter→hubs-token-fix→AuthN→AuthZ→LogEnrichment→
|
||||
ReadonlyOverride→StaticFiles[/uploads]→Swagger→MapControllers→
|
||||
MapHub→MapMetrics→HangfireDashboard→HealthChecks).
|
||||
18. На старте: `db.Database.Migrate()` (идемпотентно).
|
||||
19. `app.Run()`.
|
||||
|
||||
## Поток: signup → bootstrap → первая продажа
|
||||
|
||||
```
|
||||
1. POST /api/auth/signup { email, password, organizationName, phone }
|
||||
─→ создание Organization (Entity, не tenant-scoped)
|
||||
─→ создание AppUser + добавление в роль "Admin"
|
||||
─→ создание Employee с AdminRole и всеми permission'ами
|
||||
─→ создание главного Store (isMain=true) + RetailPoint
|
||||
─→ создание PriceType "Розничная" (isRetail=true, isSystem=true)
|
||||
─→ копирование системных UnitOfMeasure (OrganizationId=null) на org
|
||||
|
||||
2. POST /connect/token { grant_type=password, username, password }
|
||||
─→ OpenIddict проверяет, выдаёт access_token + refresh_token
|
||||
─→ access_token содержит claim org_id и role
|
||||
|
||||
3. GET /api/me (web bootstrap)
|
||||
─→ возвращает { sub, email, roles, orgId, hasLiveOrg, hasActiveEmployee }
|
||||
─→ фронт роутит на /dashboard или /no-organization (orphan-fallback)
|
||||
|
||||
4. POST /api/catalog/products { name, prices, barcodes, ... }
|
||||
─→ ValidationFilter (FluentValidation)
|
||||
─→ controller → _db.Products.Add(...) (OrganizationId stamped в SaveChanges)
|
||||
─→ возвращает Product DTO
|
||||
|
||||
5. POST /api/purchases/supplies + POST /{id}/post
|
||||
─→ post идёт под Serializable tx
|
||||
─→ для каждой строки StockService.ApplyMovementAsync(+qty, MovementType.Supply)
|
||||
─→ Stock row для (productId, storeId) либо создаётся, либо обновляется
|
||||
─→ commit, AppMetrics.IncrementPosted("supply")
|
||||
─→ SignalR: NotificationsHub → группа org → событие SupplyPosted
|
||||
|
||||
6. POST /api/sales/retail + POST /{id}/post
|
||||
─→ Serializable tx, проверка остатка ≥ 0 для каждой строки
|
||||
─→ StockService.ApplyMovementAsync(-qty, MovementType.RetailSale)
|
||||
─→ commit, AppMetrics.IncrementPosted("retail-sale")
|
||||
─→ best-effort TryFiscalizeAsync (Sprint 11) — отдельно, после commit
|
||||
─→ SignalR: SalePosted (dashboard виджеты инвалидируют queries)
|
||||
```
|
||||
|
||||
## База данных
|
||||
|
||||
Postgres 14+ для dev (brew systemwide), Postgres 16 в Docker для
|
||||
stage/prod. Названия таблиц snake_case через явный `ToTable("…")`.
|
||||
|
||||
### Ключевые таблицы
|
||||
|
||||
| Таблица | Назначение |
|
||||
|---|---|
|
||||
| `organizations` | Корневой tenant. Не tenant-scoped. |
|
||||
| `users`, `roles`, `user_roles` | ASP.NET Identity. |
|
||||
| `employees`, `employee_roles`, `role_permissions` | Сотрудники tenant'а + кастомные роли с булевыми флагами прав. |
|
||||
| `products`, `product_prices`, `product_barcodes`, `product_images`, `product_groups` | Каталог товаров. |
|
||||
| `counterparties` | Поставщики + покупатели (тип=Supplier/Individual/Legal). |
|
||||
| `stores`, `retail_points`, `units_of_measure`, `currencies`, `price_types`, `countries` | Справочники. |
|
||||
| `stocks`, `stock_movements` | Остатки + история движений. `stocks` — кеш `SUM(stock_movements)`. |
|
||||
| `supplies`, `supply_lines`, `enters`, `enter_lines`, `supplier_returns`, `supplier_return_lines` | Приходные документы. |
|
||||
| `losses`, `loss_lines`, `transfers`, `transfer_lines`, `inventory_docs`, `inventory_lines` | Внутренний учёт. |
|
||||
| `retail_sales`, `retail_sale_lines` | Чеки розницы + строки чека. Sprint 11: ОФД-снапшоты на `retail_sales` (FiscalNumber, FiscalQrCode, …). |
|
||||
| `demands`, `demand_lines` | Опт-отгрузки. |
|
||||
| `loyalty_programs`, `loyalty_cards`, `promotions` | Sprint 9. |
|
||||
| `pos_batch_acks` | Идемпотентность POS-синка (UNIQUE OrganizationId, IdempotencyKey). |
|
||||
| `org_audit_log` | JSONB-diff каждой mutate-операции tenant'а. |
|
||||
| `super_admin_audit_log` | Действия SuperAdmin'а (особенно в режиме «открыто как…»). |
|
||||
| `platform_settings` | Singleton: SMTP-конфиг платформы. |
|
||||
| `system_settings` | Singleton: per-tenant фичи (не путать с platform). |
|
||||
| `import_jobs` | История импортов MoySklad. |
|
||||
|
||||
OpenIddict хранит `openiddict_applications`/`authorizations`/`tokens`/`scopes`.
|
||||
Hangfire — `hangfire.*` (в своей схеме).
|
||||
|
||||
### Concurrency
|
||||
|
||||
`IVersionedEntity` сущности (Supply, RetailSale, Demand, Enter, Loss,
|
||||
Transfer, InventoryDoc, SupplierReturn) включают PG `xmin` через
|
||||
`UseXminAsConcurrencyToken()`. Параллельные апдейты одного документа
|
||||
получают `DbUpdateConcurrencyException`, контроллер возвращает 409.
|
||||
|
||||
Post-операции, изменяющие остаток, идут под `IsolationLevel.Serializable`
|
||||
(см. `RetailSalesController.Post`, `SuppliesController.Post`, …) —
|
||||
это защищает от race в `SUM(stock_movements)`-инварианте.
|
||||
|
||||
## Внешние интеграции
|
||||
|
||||
| Сервис | Где | Состояние |
|
||||
|---|---|---|
|
||||
| **MoySklad** | `Infrastructure/Integrations/MoySklad/` | Импорт товаров, контрагентов, остатков. Per-org token в `Organization.MoySkladToken`. |
|
||||
| **SMTP** | `Infrastructure/Email/MailKitEmailSender.cs` | Платформенный SMTP в `PlatformSettings` (SuperAdmin настраивает). Используется для invite, forgot-password, weekly-summary. |
|
||||
| **Telegram Bot** | `Api/Integrations/Telegram/` | Owner-сводка. Per-org `OwnerTelegramChatId`. Bot token в env. |
|
||||
| **ОФД (Webkassa / Kassa24 / ОФД-Соло)** | `Infrastructure/Fiscal/` | Sprint 11 scaffolding. Per-org провайдер + креды. |
|
||||
| **MinIO (S3)** | `Api/Storage/StorageBootstrap.cs` | Опциональный сторадж изображений. Если не настроен — `/uploads` volume на FS. |
|
||||
|
||||
## Тесты
|
||||
|
||||
- **Unit** (`tests/food-market.UnitTests/`) — xUnit + InMemory EF + чистые
|
||||
юниты на валидаторы, payload-builder'ы, MediatR-handler'ы.
|
||||
- **Integration** (`tests/food-market.IntegrationTests/`) — xUnit +
|
||||
Testcontainers Postgres (`postgres:16-alpine`). Полный API через
|
||||
`WebApplicationFactory<Program>`. Shared `ApiFactory` через
|
||||
`ApiCollection` (один контейнер на сессию xunit). Memory note:
|
||||
`test_suites_setup` — Ryuk выключен (TCN не тянет с docker-hub),
|
||||
rate-limiter eager-config через env-переменную.
|
||||
- **E2E** (`tests/e2e/`) — Playwright (TS) против stage
|
||||
`https://test.admin.food-market.kz`. Используется в verify-suite'ах
|
||||
по спринтам.
|
||||
- **Load** (`tests/load/`) — k6 (Sprint 12). См. `docs/performance-baseline.md`.
|
||||
|
||||
## Релиз-цикл
|
||||
|
||||
1. Локально: `dotnet build` + `dotnet test` + `pnpm build`.
|
||||
2. `git push origin main` (Forgejo на 127.0.0.1:3000 — primary remote,
|
||||
GitHub — mirror, memory `feedback_forgejo_primary`).
|
||||
3. `~/deploy-stage.sh` — docker build api+web → push в локальный registry
|
||||
`192.168.1.193:5001` → ssh на prod-vm → `docker compose pull && up -d`.
|
||||
4. Health check на `https://test.admin.food-market.kz/health/ready`.
|
||||
5. Verify на stage (Playwright или ручной чек).
|
||||
6. Prod-деплой — пока ручной (TBD, нужен план от user'а).
|
||||
|
||||
## Что ещё прочитать
|
||||
|
||||
- [MULTI-TENANCY.md](MULTI-TENANCY.md) — query filter, SuperAdmin override, подводные камни.
|
||||
- [RUNBOOK.md](RUNBOOK.md) — операционные процедуры.
|
||||
- [DEVELOPER-GUIDE.md](DEVELOPER-GUIDE.md) — как начать вкладываться в код.
|
||||
- [ofd-integration.md](ofd-integration.md) — ОФД-провайдеры.
|
||||
- [openapi.md](openapi.md) — генерация TS-клиента из Swagger.
|
||||
- [observability.md](observability.md) — Serilog + Prometheus.
|
||||
- [secrets.md](secrets.md) — управление секретами в stage/prod.
|
||||
- [stage-access.md](stage-access.md) — как попасть на stage-сервер.
|
||||
- [backup-restore.md](backup-restore.md) — бэкапы.
|
||||
439
docs/DEVELOPER-GUIDE.md
Normal file
439
docs/DEVELOPER-GUIDE.md
Normal file
|
|
@ -0,0 +1,439 @@
|
|||
# Developer guide — food-market
|
||||
|
||||
Как поднять проект, что куда добавлять, какие паттерны соблюдать.
|
||||
Предполагается, что вы прочитали [ARCHITECTURE.md](ARCHITECTURE.md) и
|
||||
понимаете слои.
|
||||
|
||||
## Локальный setup
|
||||
|
||||
### Что нужно
|
||||
|
||||
- **.NET 8 SDK 8.0.4xx** (см. `global.json`, `rollForward: latestFeature`
|
||||
— годится любой 8.0.4xx).
|
||||
- **Node 20+** и **pnpm 9+** (для web).
|
||||
- **PostgreSQL 14+** — на macOS обычно brew `postgresql@14`.
|
||||
БД: `food_market`, owner `nns`, пароль пустой.
|
||||
- **Docker** + **Docker Compose** — только для integration-тестов
|
||||
(Testcontainers) и stage-деплоя.
|
||||
|
||||
### Поднять с нуля
|
||||
|
||||
```bash
|
||||
git clone http://127.0.0.1:3000/nns/food-market.git
|
||||
cd food-market
|
||||
|
||||
# 1) БД (если ещё нет)
|
||||
createdb -O nns food_market # пользователь nns должен существовать
|
||||
|
||||
# 2) Backend
|
||||
ASPNETCORE_ENVIRONMENT=Development \
|
||||
dotnet run --project src/food-market.api
|
||||
# первый запуск: применит миграции, посеит справочники, создаст
|
||||
# SuperAdmin admin@food-market.local / Admin12345!.
|
||||
# API на http://localhost:5081, Swagger на /swagger.
|
||||
|
||||
# 3) Web (в другом терминале)
|
||||
cd src/food-market.web
|
||||
pnpm install
|
||||
pnpm dev
|
||||
# http://localhost:5173
|
||||
|
||||
# 4) Smoke
|
||||
curl http://localhost:5081/health
|
||||
# и зайти в браузере, залогиниться admin@food-market.local
|
||||
```
|
||||
|
||||
### Получить токен из CLI
|
||||
|
||||
```bash
|
||||
TOKEN=$(curl -sX POST http://localhost:5081/connect/token \
|
||||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||||
-d 'grant_type=password&username=admin@food-market.local&password=Admin12345!&client_id=food-market-web&scope=openid profile email roles api offline_access' \
|
||||
| jq -r .access_token)
|
||||
curl -sH "Authorization: Bearer $TOKEN" http://localhost:5081/api/me | jq
|
||||
```
|
||||
|
||||
## Запуск тестов
|
||||
|
||||
```bash
|
||||
# Unit-тесты (быстрые, ~7-10с)
|
||||
dotnet test tests/food-market.UnitTests/
|
||||
|
||||
# Integration (тянут Postgres-контейнер, ~30-60с на холодную)
|
||||
dotnet test tests/food-market.IntegrationTests/
|
||||
|
||||
# Фильтр по имени класса/метода
|
||||
dotnet test tests/... --filter "FullyQualifiedName~Fiscal"
|
||||
|
||||
# Web — type-check + production build
|
||||
cd src/food-market.web && pnpm exec tsc --noEmit && pnpm build
|
||||
|
||||
# E2E (Playwright против stage)
|
||||
cd tests/e2e && pnpm install
|
||||
pnpm playwright test stage-smoke.spec.ts
|
||||
```
|
||||
|
||||
### Гочи integration-тестов
|
||||
|
||||
- **Testcontainers Ryuk** выключен (env `TESTCONTAINERS_RYUK_DISABLED=true`).
|
||||
Причина: контейнер reaper тянет образ с Docker Hub, на dev-vm сеть
|
||||
туда нестабильна.
|
||||
- **Rate-limiter** выключен через `RateLimiting__Enabled=false`. Он
|
||||
читает конфиг ЭАГЕРНО при регистрации сервисов — поэтому только через
|
||||
переменную окружения (см. memory `test_suites_setup`).
|
||||
- **Hangfire-сервер** выключен (`Hangfire__Enabled=false`) — иначе
|
||||
создаёт схему и держит коннект в одноразовом контейнере.
|
||||
- Один `ApiFactory` на всю xUnit-сессию через `[Collection(ApiCollection.Name)]`.
|
||||
Делать второй `WebApplicationFactory<Program>` параллельно нельзя —
|
||||
`HostFactoryResolver` сломается.
|
||||
|
||||
## Конвенции репо
|
||||
|
||||
- C# 12, `Nullable` enabled, `ImplicitUsings` enabled.
|
||||
- Названия неймспейсов — `foodmarket.Domain`, `foodmarket.Application`,
|
||||
`foodmarket.Infrastructure`, `foodmarket.Api`. Папки в `src/` —
|
||||
`food-market.api`, `food-market.application`, … (с дефисом). Это
|
||||
расхождение исторически — менять не нужно.
|
||||
- Названия таблиц в БД — snake_case (явный `b.ToTable("retail_sales")`),
|
||||
столбцы — PascalCase из C# (EF default), индексы по
|
||||
`IX_<table>_<cols>` (EF default).
|
||||
- Комментарии в коде — рассказывающие *почему*, не *что*. Если из имени
|
||||
переменной/метода не понятно — переименуй; если из логики не понятно,
|
||||
*почему* — комментируй.
|
||||
- XML-doc на public API в Application/Infrastructure обязателен (даёт
|
||||
IntelliSense для другой стороны и появляется в Swagger).
|
||||
- Локализация UI — `src/lib/i18n.ts` (русский по умолчанию, есть
|
||||
заготовка под KZ — нужен переводчик).
|
||||
|
||||
## Паттерны: добавить controller с permission
|
||||
|
||||
Пример: `POST /api/loyalty/programs` (создание программы лояльности),
|
||||
доступно только Admin'у орги или SuperAdmin'у в edit-mode.
|
||||
|
||||
```csharp
|
||||
// food-market.api/Controllers/Loyalty/LoyaltyProgramsController.cs
|
||||
[ApiController]
|
||||
[Authorize]
|
||||
[Route("api/loyalty/programs")]
|
||||
public class LoyaltyProgramsController : ControllerBase
|
||||
{
|
||||
private readonly AppDbContext _db;
|
||||
private readonly ITenantContext _tenant;
|
||||
private readonly ILogger<LoyaltyProgramsController> _log;
|
||||
|
||||
public LoyaltyProgramsController(
|
||||
AppDbContext db, ITenantContext tenant, ILogger<LoyaltyProgramsController> log)
|
||||
{
|
||||
_db = db; _tenant = tenant; _log = log;
|
||||
}
|
||||
|
||||
public record ProgramInput(
|
||||
[Required] string Name,
|
||||
[Range(1, 4)] int Type,
|
||||
[Range(0, 1000)] decimal Rate,
|
||||
bool IsActive);
|
||||
|
||||
[HttpPost, RequiresPermission("LoyaltyEdit")]
|
||||
public async Task<ActionResult<Guid>> Create(
|
||||
[FromBody] ProgramInput input, CancellationToken ct)
|
||||
{
|
||||
var p = new LoyaltyProgram
|
||||
{
|
||||
Name = input.Name.Trim(),
|
||||
Type = (LoyaltyProgramType)input.Type,
|
||||
Rate = input.Rate,
|
||||
IsActive = input.IsActive,
|
||||
// OrganizationId stamping применит в SaveChanges
|
||||
};
|
||||
_db.LoyaltyPrograms.Add(p);
|
||||
await _db.SaveChangesAsync(ct);
|
||||
_log.LogInformation(
|
||||
"Loyalty program created: {ProgramId} {Name} org={OrgId}",
|
||||
p.Id, p.Name, _tenant.OrganizationId);
|
||||
return Ok(p.Id);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Что произошло:
|
||||
|
||||
- `[Authorize]` — JWT-токен обязателен (валидируется OpenIddict).
|
||||
- `[Route("api/...")]` — обычный REST-маршрут. `api/` префикс
|
||||
обязателен для всех контроллеров (web-фронт ходит через `/api/*`,
|
||||
nginx это знает).
|
||||
- `[RequiresPermission("LoyaltyEdit")]` — резолвится в policy `perm:LoyaltyEdit`,
|
||||
handler проверяет `RolePermissions.LoyaltyEdit` булеву у роли
|
||||
текущего юзера. Добавь поле в `RolePermissions.cs` если ещё нет,
|
||||
миграция-`AddColumn` для `bool LoyaltyEdit NOT NULL DEFAULT false`
|
||||
+ апдейт admin-роли в сидере.
|
||||
- `ProgramInput` — record с DataAnnotations. Для сложной валидации —
|
||||
отдельный FluentValidation `AbstractValidator<ProgramInput>` в
|
||||
`food-market.api/Infrastructure/Validation/Validators.cs` (см.
|
||||
паттерны там).
|
||||
- `_db.LoyaltyPrograms.Add(p)` без явного `OrganizationId` —
|
||||
`StampTenant` в `SaveChangesAsync` подставит.
|
||||
- Логирование структурированное: `{ProgramId}`, `{Name}`, `{OrgId}` —
|
||||
Serilog кладёт их как property'и (search'абельны в Loki/ES, не строкой).
|
||||
|
||||
### Если нужен Admin-only (грубее)
|
||||
|
||||
```csharp
|
||||
[HttpPut, Authorize(Roles = "Admin")]
|
||||
```
|
||||
|
||||
это эквивалентно «или Identity-role Admin, или SuperAdmin в режиме
|
||||
override (через `SuperAdminOverrideClaimsTransformer`)». Подходит для
|
||||
редких операций; для регулярных используй `RequiresPermission`.
|
||||
|
||||
## Паттерны: добавить сущность с RowVersion и tenant
|
||||
|
||||
Допустим, нужна новая сущность `PromoCode`.
|
||||
|
||||
### 1. Domain
|
||||
|
||||
```csharp
|
||||
// food-market.domain/Sales/PromoCode.cs
|
||||
public class PromoCode : TenantEntity, IVersionedEntity
|
||||
{
|
||||
public uint Xmin { get; set; }
|
||||
|
||||
public string Code { get; set; } = "";
|
||||
public decimal Discount { get; set; }
|
||||
public DateTime? ExpiresAt { get; set; }
|
||||
public bool IsActive { get; set; } = true;
|
||||
}
|
||||
```
|
||||
|
||||
`TenantEntity` даёт `Id`, `CreatedAt`, `UpdatedAt`, `OrganizationId`.
|
||||
`IVersionedEntity` + `Xmin` — оптимистичная блокировка через PG xmin.
|
||||
|
||||
### 2. EF Configuration
|
||||
|
||||
```csharp
|
||||
// food-market.infrastructure/Persistence/Configurations/SalesConfigurations.cs
|
||||
b.Entity<PromoCode>(e =>
|
||||
{
|
||||
e.ToTable("promo_codes");
|
||||
e.UseXminAsConcurrencyToken();
|
||||
e.Ignore(x => x.Xmin);
|
||||
e.Property(x => x.Code).HasMaxLength(40).IsRequired();
|
||||
e.Property(x => x.Discount).HasPrecision(18, 4);
|
||||
e.HasIndex(x => new { x.OrganizationId, x.Code }).IsUnique(); // ← OrganizationId первым!
|
||||
e.HasIndex(x => new { x.OrganizationId, x.IsActive });
|
||||
});
|
||||
```
|
||||
|
||||
**Важно**: индексы — с `OrganizationId` первым полем. Все запросы пройдут
|
||||
через query filter и будут фильтроваться по этому полю; без правильного
|
||||
индекса PG будет full-scan тенант-таблицы.
|
||||
|
||||
### 3. DbSet
|
||||
|
||||
```csharp
|
||||
// food-market.infrastructure/Persistence/AppDbContext.cs
|
||||
public DbSet<PromoCode> PromoCodes => Set<PromoCode>();
|
||||
```
|
||||
|
||||
### 4. Миграция руками
|
||||
|
||||
```csharp
|
||||
// food-market.infrastructure/Persistence/Migrations/20260608100000_PromoCodes.cs
|
||||
[DbContext(typeof(AppDbContext))]
|
||||
[Migration("20260608100000_PromoCodes")]
|
||||
public partial class PromoCodes : Migration
|
||||
{
|
||||
protected override void Up(MigrationBuilder b)
|
||||
{
|
||||
b.CreateTable(
|
||||
name: "promo_codes",
|
||||
schema: "public",
|
||||
columns: t => new
|
||||
{
|
||||
Id = t.Column<Guid>(type: "uuid", nullable: false),
|
||||
OrganizationId = t.Column<Guid>(type: "uuid", nullable: false),
|
||||
Code = t.Column<string>(type: "character varying(40)", maxLength: 40, nullable: false),
|
||||
Discount = t.Column<decimal>(type: "numeric(18,4)", precision: 18, scale: 4, nullable: false),
|
||||
ExpiresAt = t.Column<DateTime>(type: "timestamp with time zone", nullable: true),
|
||||
IsActive = t.Column<bool>(type: "boolean", nullable: false, defaultValue: true),
|
||||
CreatedAt = t.Column<DateTime>(type: "timestamp with time zone", nullable: false),
|
||||
UpdatedAt = t.Column<DateTime>(type: "timestamp with time zone", nullable: true),
|
||||
},
|
||||
constraints: t => t.PrimaryKey("PK_promo_codes", x => x.Id));
|
||||
b.CreateIndex(
|
||||
name: "IX_promo_codes_OrganizationId_Code",
|
||||
schema: "public", table: "promo_codes",
|
||||
columns: new[] { "OrganizationId", "Code" }, unique: true);
|
||||
b.CreateIndex(
|
||||
name: "IX_promo_codes_OrganizationId_IsActive",
|
||||
schema: "public", table: "promo_codes",
|
||||
columns: new[] { "OrganizationId", "IsActive" });
|
||||
}
|
||||
protected override void Down(MigrationBuilder b)
|
||||
=> b.DropTable("promo_codes", "public");
|
||||
}
|
||||
```
|
||||
|
||||
**Обязательно**: `[DbContext]` + `[Migration("...")]` атрибуты — без них
|
||||
`db.Database.Migrate()` миграцию не подхватит (memory:
|
||||
`feedback_ef_migrations`).
|
||||
|
||||
### 5. Тест на изоляцию
|
||||
|
||||
Добавить case в `TenantIsolationTests`: org A создаёт PromoCode, org B
|
||||
делает GET, видит пустой список.
|
||||
|
||||
## Валидация
|
||||
|
||||
### Простые правила — DataAnnotations
|
||||
|
||||
```csharp
|
||||
public record ProductInput(
|
||||
[Required, MaxLength(200)] string Name,
|
||||
[Range(0, 1e10)] decimal Price);
|
||||
```
|
||||
|
||||
### Сложные — FluentValidation
|
||||
|
||||
В `food-market.api/Infrastructure/Validation/Validators.cs`:
|
||||
|
||||
```csharp
|
||||
public sealed class ProductInputValidator : AbstractValidator<ProductInput>
|
||||
{
|
||||
public ProductInputValidator()
|
||||
{
|
||||
RuleFor(x => x.Name).NotEmpty().MaximumLength(200);
|
||||
RuleFor(x => x.Price).GreaterThanOrEqualTo(0);
|
||||
|
||||
// Кросс-полевые правила, async, реализующие бизнес-инвариант
|
||||
RuleFor(x => x.Lines).NotEmpty().WithMessage("Хотя бы одна позиция.");
|
||||
RuleForEach(x => x.Lines).ChildRules(line =>
|
||||
{
|
||||
line.RuleFor(l => l.Quantity).GreaterThan(0);
|
||||
line.RuleFor(l => l.UnitPrice).GreaterThanOrEqualTo(0);
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Валидаторы регистрируются автоматически через
|
||||
`AddValidatorsFromAssemblyContaining<Program>()`. `ValidationFilter`
|
||||
(глобальный action-filter в Program.cs) запускает их на каждом
|
||||
action и возвращает 400 ProblemDetails (RFC 7807).
|
||||
|
||||
### Бизнес-валидация (требует БД)
|
||||
|
||||
Если правило требует справиться с БД (например, «склад существует и
|
||||
не архивирован»), вынесите в первый шаг action-метода:
|
||||
|
||||
```csharp
|
||||
[HttpPost]
|
||||
public async Task<ActionResult> Create(ProductInput input, CancellationToken ct)
|
||||
{
|
||||
var groupOk = await _db.ProductGroups.AnyAsync(g => g.Id == input.ProductGroupId, ct);
|
||||
if (!groupOk)
|
||||
return BadRequest(new { error = "Группа не найдена.", field = "productGroupId" });
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Формат ошибки — `{ error: "...", field?: "..." }`. Фронт показывает
|
||||
`error` тостом, `field` подсвечивает в форме.
|
||||
|
||||
## Логирование
|
||||
|
||||
Используем Serilog со структурированными полями. `LogEnrichmentMiddleware`
|
||||
уже добавляет `CorrelationId/OrgId/UserId` в каждую запись.
|
||||
|
||||
### Правила
|
||||
|
||||
- **Не строкой**: `_log.LogInformation("Created product " + id)` — нет.
|
||||
`_log.LogInformation("Product created: {ProductId} name={Name}", id, name)` — да.
|
||||
- **Уровень**:
|
||||
- `Trace/Debug` — только для отладки конкретного бага.
|
||||
- `Information` — успешные mutate-операции, важные events
|
||||
(post/unpost документа, регистрация чека в ОФД).
|
||||
- `Warning` — что-то пошло не как ожидалось, но обработали
|
||||
(best-effort fail, retry-able ошибка).
|
||||
- `Error` — обработать не удалось, нужен внимательный человек.
|
||||
- `Critical` — приложение в плохом состоянии, может перестать работать.
|
||||
- **Не логировать** PII в открытом виде (пароли, токены, email — email
|
||||
можно, но не светить лишний раз).
|
||||
- **Exception как первый аргумент**: `_log.LogError(ex, "...", ...)`,
|
||||
не `_log.LogError("... " + ex.Message)` — теряется stack trace.
|
||||
|
||||
### Пример из RetailSalesController
|
||||
|
||||
```csharp
|
||||
_log.LogInformation(
|
||||
"RetailSale posted: {SaleNumber} store={StoreId} payment={Payment} lines={LinesCount} total={Total}",
|
||||
sale.Number, sale.StoreId, sale.Payment, sale.Lines.Count, sale.Total);
|
||||
|
||||
// ...
|
||||
|
||||
try
|
||||
{
|
||||
await _notify.PublishAsync(...);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
// Notification — best-effort: не должна валить транзакцию (она уже закоммичена)
|
||||
_log.LogWarning(ex, "SignalR notify failed for sale {SaleId}", sale.Id);
|
||||
}
|
||||
```
|
||||
|
||||
## SignalR realtime
|
||||
|
||||
Если нужно отправить уведомление на фронт (инвалидация query'я,
|
||||
показ тоста):
|
||||
|
||||
```csharp
|
||||
// в Program.cs INotificationsPublisher уже зарегистрирован
|
||||
public class MyController : ControllerBase
|
||||
{
|
||||
private readonly INotificationsPublisher _notify;
|
||||
|
||||
[HttpPost("...")]
|
||||
public async Task<IActionResult> Action(...)
|
||||
{
|
||||
// ... business logic ...
|
||||
await _notify.PublishAsync(
|
||||
organizationId,
|
||||
NotificationEvents.SalePosted, // строковая константа
|
||||
new SalePostedPayload(...)); // record DTO
|
||||
return NoContent();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
На фронте — `useNotifications()` хук подписан на хаб и инвалидирует
|
||||
relevant query'и. Новые event'ы добавлять в `NotificationEvents`,
|
||||
payload — в соседнем record'е.
|
||||
|
||||
## Что НЕ делать
|
||||
|
||||
- НЕ инжектить `IServiceProvider` чтобы доставать сервисы лениво —
|
||||
объяви явные зависимости в конструкторе. Исключение: фабрики (Fiscal,
|
||||
Email) которые открывают scope для свежего DbContext'а.
|
||||
- НЕ писать raw SQL (`SqlQueryRaw`/`ExecuteSqlRaw`) без явного
|
||||
`WHERE OrganizationId = @org` — query-filter не применится.
|
||||
- НЕ менять снапшот в `Persistence/Migrations/AppDbContextModelSnapshot.cs`
|
||||
руками для добавления новых полей — он используется только инструментом
|
||||
`dotnet ef migrations add`, который мы не запускаем. Trying to add
|
||||
partial state ломает только инструмент, ничего не дав. Если хочется —
|
||||
обновляй целиком, синхронно с моделью; иначе оставь как есть.
|
||||
- НЕ добавлять платные компоненты: Kendo, DevExpress, Syncfusion
|
||||
commercial, Telerik (CLAUDE.md).
|
||||
- НЕ менять `global.json` без согласования (CLAUDE.md).
|
||||
- НЕ создавать миграции через `dotnet ef migrations add` — пиши руками
|
||||
(memory: `feedback_ef_migrations`).
|
||||
- НЕ делать `git push --force` на main (Forgejo — primary).
|
||||
|
||||
## Полезные ссылки
|
||||
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) — слои и модули.
|
||||
- [MULTI-TENANCY.md](MULTI-TENANCY.md) — query-filter, override-режим.
|
||||
- [RUNBOOK.md](RUNBOOK.md) — операционные процедуры.
|
||||
- [openapi.md](openapi.md) — генерация TS-клиента из Swagger.
|
||||
- [observability.md](observability.md) — Serilog + Prometheus.
|
||||
- [ofd-integration.md](ofd-integration.md) — ОФД-провайдеры.
|
||||
- [secrets.md](secrets.md) — где живут секреты.
|
||||
338
docs/MULTI-TENANCY.md
Normal file
338
docs/MULTI-TENANCY.md
Normal file
|
|
@ -0,0 +1,338 @@
|
|||
# Multi-tenancy в food-market
|
||||
|
||||
Один процесс API, одна БД, много организаций (тенантов). Каждый запрос
|
||||
видит только данные своей организации. Изоляция держится на двух вещах:
|
||||
|
||||
1. **EF Core query filter** на каждой `ITenantEntity` (auto-инжектится
|
||||
в `WHERE` каждого SQL-запроса).
|
||||
2. **Stamping в SaveChanges** — добавляемые сущности получают
|
||||
`OrganizationId` из текущего `ITenantContext`.
|
||||
|
||||
`SuperAdmin` — отдельная роль с правом обходить фильтр (видеть/менять
|
||||
всё). Чтобы не получить «случайные изменения по всем оргам сразу»,
|
||||
есть строгий режим «открыть как…» с двумя ступенями (read-only +
|
||||
edit-mode с reason).
|
||||
|
||||
## Модель
|
||||
|
||||
### Базовые интерфейсы
|
||||
|
||||
```csharp
|
||||
// food-market.domain/Common/TenantEntity.cs
|
||||
|
||||
public interface ITenantEntity // обязательный orgId
|
||||
{
|
||||
Guid OrganizationId { get; set; }
|
||||
}
|
||||
|
||||
public abstract class TenantEntity : Entity, ITenantEntity
|
||||
{
|
||||
public Guid OrganizationId { get; set; }
|
||||
}
|
||||
|
||||
public interface IOptionalTenantEntity // системный справочник
|
||||
{
|
||||
Guid? OrganizationId { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
### Когда использовать что
|
||||
|
||||
| Случай | База |
|
||||
|---|---|
|
||||
| Бизнес-данные тенанта: продукты, чеки, контрагенты, отчёты | `TenantEntity` (обязательный orgId) |
|
||||
| Системные справочники с возможностью per-tenant расширения: `UnitOfMeasure`, `ProductGroup`, `Country` | `IOptionalTenantEntity` (null = системная, оrgId = tenant'овская) |
|
||||
| Корневая сущность тенанта: `Organization` | `Entity` (сама не tenant-scoped) |
|
||||
| Платформенные настройки: `PlatformSettings` (SMTP), OpenIddict-клиенты | `Entity` (singletons / cross-tenant) |
|
||||
| Audit-логи SuperAdmin'а: `SuperAdminAuditLog` | `Entity` (есть optional `OrganizationId` для фильтра, но сама не tenant-scoped) |
|
||||
|
||||
## Tenant-контекст
|
||||
|
||||
`ITenantContext` (Application слой) — единственный источник правды о
|
||||
том, кто сейчас делает запрос:
|
||||
|
||||
```csharp
|
||||
// food-market.application/Common/Tenancy/ITenantContext.cs
|
||||
public interface ITenantContext
|
||||
{
|
||||
Guid? OrganizationId { get; } // null = SuperAdmin вне override, или нет JWT
|
||||
bool IsAuthenticated { get; }
|
||||
bool IsSuperAdmin { get; }
|
||||
bool IsTenantOverride { get; } // SuperAdmin в режиме «открыть как…»
|
||||
Guid? UserId { get; }
|
||||
}
|
||||
```
|
||||
|
||||
Реализация — `HttpContextTenantContext` (`food-market.api/Infrastructure/Tenancy/`).
|
||||
Источники данных в порядке приоритета:
|
||||
|
||||
1. **AsyncLocal-override** (`UseOverride(orgId, isSuper)`) — для
|
||||
background-tasks (Hangfire, импорт MoySklad, фоновые сидеры).
|
||||
Когда нет HttpContext, нужно явно задать tenant перед `DbContext`-вызовом.
|
||||
2. **HTTP-заголовок `X-Org-Override`** — режим «открыть как…»
|
||||
(только если у юзера роль SuperAdmin).
|
||||
3. **JWT claim `org_id`** — обычный tenant-юзер.
|
||||
|
||||
```csharp
|
||||
// background-job пример
|
||||
using (HttpContextTenantContext.UseOverride(orgId, isSuperAdmin: false))
|
||||
{
|
||||
// здесь _db применит фильтр на orgId
|
||||
var products = await _db.Products.ToListAsync();
|
||||
}
|
||||
```
|
||||
|
||||
## Query filter
|
||||
|
||||
`AppDbContext.OnModelCreating` после регистрации всех сущностей
|
||||
рефлексией обходит модель и вешает фильтр на каждую `ITenantEntity`:
|
||||
|
||||
```csharp
|
||||
// food-market.infrastructure/Persistence/AppDbContext.cs
|
||||
|
||||
private void ApplyTenantFilter<T>(ModelBuilder builder) where T : class, ITenantEntity
|
||||
{
|
||||
// SuperAdmin обходит фильтр ТОЛЬКО когда не в режиме «открыть как…».
|
||||
// В override-режиме (X-Org-Override header активен) он работает в
|
||||
// контексте конкретной орги — фильтр обязан применяться.
|
||||
builder.Entity<T>().HasQueryFilter(e =>
|
||||
(_tenant.IsSuperAdmin && !_tenant.IsTenantOverride)
|
||||
|| e.OrganizationId == _tenant.OrganizationId);
|
||||
}
|
||||
|
||||
private void ApplyOptionalTenantFilter<T>(ModelBuilder builder) where T : class, IOptionalTenantEntity
|
||||
{
|
||||
builder.Entity<T>().HasQueryFilter(e =>
|
||||
(_tenant.IsSuperAdmin && !_tenant.IsTenantOverride)
|
||||
|| e.OrganizationId == null
|
||||
|| e.OrganizationId == _tenant.OrganizationId);
|
||||
}
|
||||
```
|
||||
|
||||
Результат:
|
||||
|
||||
- Tenant-юзер: `WHERE OrganizationId = '<его orgId>'`.
|
||||
- SuperAdmin без override: фильтр не применяется (видит всё).
|
||||
- SuperAdmin с `X-Org-Override`: `WHERE OrganizationId = '<выбранная orgId>'`.
|
||||
- `IOptionalTenantEntity`: видит свои + системные (`IS NULL`).
|
||||
|
||||
## Stamping в SaveChanges
|
||||
|
||||
`AppDbContext.SaveChanges/Async` зовут `StampTenant()`, который
|
||||
проходит по `Added`-entries:
|
||||
|
||||
```csharp
|
||||
private void StampTenant()
|
||||
{
|
||||
foreach (var entry in ChangeTracker.Entries())
|
||||
{
|
||||
if (entry.State != EntityState.Added) continue;
|
||||
if (entry.Entity is ITenantEntity tenant && tenant.OrganizationId == Guid.Empty)
|
||||
{
|
||||
if (_tenant.OrganizationId.HasValue)
|
||||
tenant.OrganizationId = _tenant.OrganizationId.Value;
|
||||
}
|
||||
else if (entry.Entity is IOptionalTenantEntity opt && opt.OrganizationId is null)
|
||||
{
|
||||
// SuperAdmin без override: оставляем null (системная запись)
|
||||
// SuperAdmin с override / tenant-юзер: стампим текущий orgId
|
||||
if (_tenant.IsSuperAdmin && !_tenant.IsTenantOverride) { /* null */ }
|
||||
else if (_tenant.OrganizationId.HasValue)
|
||||
opt.OrganizationId = _tenant.OrganizationId.Value;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Это значит: контроллер может писать `_db.Products.Add(product)` без
|
||||
явного `product.OrganizationId = ...` — stamping подставит сам.
|
||||
**НО**: если код явно выставил `OrganizationId` (например, чтобы создать
|
||||
запись для другой орги в Hangfire-job), stamping её не перетрёт.
|
||||
|
||||
## SuperAdmin override: режим «открыть как…»
|
||||
|
||||
Конкретный поток с фронта:
|
||||
|
||||
1. SuperAdmin заходит в «Системная консоль → Организации».
|
||||
2. Кликает «Открыть как…» на какой-то orgRow.
|
||||
3. Фронт начинает слать каждый запрос с заголовком
|
||||
`X-Org-Override: <orgId>`. Без этого хедера SuperAdmin видит «своё»
|
||||
(а у SuperAdmin'а часто нет своей орги, поэтому все списки пусты —
|
||||
у супер-админа в админке тренировочный режим).
|
||||
4. По умолчанию режим **read-only** (`ReadonlyOverrideMiddleware`):
|
||||
GET/HEAD/OPTIONS — пропускаются; PUT/POST/DELETE/PATCH — `403`.
|
||||
Исключение: `/api/super-admin/*` и `/connect/*` (refresh-token).
|
||||
5. Чтобы что-то поменять, фронт показывает «Войти в edit-mode»,
|
||||
запрашивает причину (≥ 10 символов), отправляет её в каждом запросе
|
||||
как `X-Org-Override-Reason: <текст>`. Тогда middleware пропускает
|
||||
мутации, а action-filter (`SuperAdminEditAuditFilter`) после успешного
|
||||
ответа пишет строку в `super_admin_audit_log` с reason'ом и
|
||||
запросом/ответом.
|
||||
6. Фронт ограничивает edit-mode 30 минутами (UI таймер).
|
||||
Сервер не следит за временем — это UX-конвенция, а аудит уже есть.
|
||||
|
||||
### ClaimsTransformer для tenant-ролей
|
||||
|
||||
Тонкость: SuperAdmin сам по себе не имеет ролей `Admin/Storekeeper/Cashier`
|
||||
(они — атрибуты `Employee` тенанта). Контроллер
|
||||
`[Authorize(Roles="Admin")]` отшил бы его 403 даже в edit-mode.
|
||||
|
||||
Решение: `SuperAdminOverrideClaimsTransformer` (`IClaimsTransformation`,
|
||||
вызывается на каждый authenticated request) — если есть `X-Org-Override`,
|
||||
динамически добавляет SuperAdmin'у `Admin/Storekeeper/Cashier` claim-роли
|
||||
**только на текущий запрос**. Записи в БД не трогает.
|
||||
|
||||
## RequiresPermission: тонкая авторизация
|
||||
|
||||
Для мутаций используется `[RequiresPermission("...")]` вместо
|
||||
`[Authorize(Roles="Admin,Storekeeper")]`. Атрибут резолвится через
|
||||
policy-механизм:
|
||||
|
||||
```
|
||||
[RequiresPermission("ProductsEdit")]
|
||||
→ Policy "perm:ProductsEdit"
|
||||
→ PermissionAuthorizationPolicyProvider создаёт PermissionRequirement
|
||||
→ PermissionAuthorizationHandler проверяет
|
||||
EmployeeRole.RolePermissions.ProductsEdit == true для текущего юзера
|
||||
```
|
||||
|
||||
`RolePermissions` — это POCO с булевыми полями (`ProductsView`,
|
||||
`ProductsEdit`, `RetailSalesOperate`, `RetailSalesRefund`, …).
|
||||
`Employee.EmployeeRoleId` указывает на конкретную роль, у каждой —
|
||||
свой набор флагов. SuperAdmin (с override) проходит всегда.
|
||||
|
||||
См. `food-market.api/Infrastructure/Authorization/`.
|
||||
|
||||
## Audit-trail
|
||||
|
||||
### `org_audit_log`
|
||||
|
||||
Каждая `Add/Update/Delete` в `AppDbContext` (через
|
||||
`OrgAuditInterceptor`) пишет JSONB-diff в `org_audit_log`:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "...",
|
||||
"organizationId": "...",
|
||||
"userId": "...",
|
||||
"entityType": "Product",
|
||||
"entityId": "...",
|
||||
"action": "Update",
|
||||
"changesJson": { "before": {...}, "after": {...} },
|
||||
"createdAt": "..."
|
||||
}
|
||||
```
|
||||
|
||||
Фоновый Hangfire-job `prune-audit-log` (03:45) чистит записи старше
|
||||
180 дней.
|
||||
|
||||
Сидеры/миграции выставляют `_db.SkipAudit = true` чтобы не плодить
|
||||
бессмысленные строки.
|
||||
|
||||
### `super_admin_audit_log`
|
||||
|
||||
Только мутации SuperAdmin'а в edit-mode, плюс изменения платформенных
|
||||
настроек. Без TTL — храним всё.
|
||||
|
||||
## Известные подводные камни
|
||||
|
||||
### 1. `IgnoreQueryFilters()` — когда нужно знать
|
||||
|
||||
Тенант-фильтр применяется ко ВСЕМУ — в том числе там, где это «не надо».
|
||||
|
||||
- При логине: ищем `Organization` по `OrgId` из credentials → нужен
|
||||
`IgnoreQueryFilters()`, потому что фильтр требует OrganizationId,
|
||||
которого ещё нет в контексте.
|
||||
- При проверке «есть ли у юзера эта орг»: `_db.Organizations.IgnoreQueryFilters().AnyAsync(...)`.
|
||||
- При cross-tenant отчётах SuperAdmin'а без override-режима фильтр и так
|
||||
не применится, но при override — применится; чтобы получить
|
||||
cross-tenant данные в этом режиме (редко нужно), вызвать
|
||||
`IgnoreQueryFilters()` явно.
|
||||
|
||||
### 2. Stamping не работает, если orgId уже задан
|
||||
|
||||
Бэкенд-код в нескольких местах принимает `Guid OrganizationId` из payload
|
||||
(например, при импорте). Stamping проверяет `OrganizationId == Guid.Empty`
|
||||
и НЕ перетирает уже выставленное значение. Если кто-то по ошибке прислал
|
||||
чужой orgId в payload — он сохранится. Защита: явно валидировать
|
||||
`OrganizationId == _tenant.OrganizationId` в контроллере (или вообще не
|
||||
принимать поле из payload).
|
||||
|
||||
### 3. Background-jobs без HttpContext
|
||||
|
||||
`HangfireJobsConfigurator` регистрирует методы, исполняющиеся в фоне.
|
||||
`HttpContextAccessor.HttpContext` там null → `OrganizationId` тоже null →
|
||||
query filter возвращает только записи с `OrganizationId == null` (т.е.
|
||||
системные справочники), а tenant-запросы — пустоту.
|
||||
|
||||
Решение: внутри job, перед `DbContext`-вызовом, обернуть в
|
||||
`HttpContextTenantContext.UseOverride(orgId, isSuperAdmin: false)`.
|
||||
См. `OwnerDailySummaryJob`, `EmailNotificationJobs` — там есть пример.
|
||||
|
||||
### 4. SignalR за query-фильтром
|
||||
|
||||
`NotificationsHub` использует `IServiceProvider.GetRequiredService<AppDbContext>()`
|
||||
внутри `OnConnectedAsync` для добавления соединения в group. Если в
|
||||
connection нет JWT — нет org_id — нет группы → клиент не получит
|
||||
событий. Web-фронт прокидывает `?access_token=...` query (см. middleware
|
||||
в Program.cs), POS — `Authorization` header.
|
||||
|
||||
### 5. EF migrations и наследование от TenantEntity
|
||||
|
||||
При добавлении новой `TenantEntity` миграция должна включать
|
||||
`OrganizationId` колонку (uuid, NOT NULL) и индекс
|
||||
`(OrganizationId, …)` для фильтрации. **Эта колонка не появляется
|
||||
автоматически в snapshot-выводе `dotnet ef migrations add`** в этом
|
||||
проекте, потому что снапшот не синхронизируется с моделью (миграции
|
||||
пишутся руками, см. memory `feedback_ef_migrations`).
|
||||
|
||||
Проверка: после `Migrate()` тестовый запрос
|
||||
`SELECT column_name FROM information_schema.columns WHERE table_name='...'`
|
||||
должен показать `OrganizationId`.
|
||||
|
||||
### 6. `xmin` concurrency и параллельные посты
|
||||
|
||||
`UseXminAsConcurrencyToken()` на документах. Если два кассира одновременно
|
||||
постят один и тот же чек (что не должно случаться, но всё же) — второй
|
||||
получает `DbUpdateConcurrencyException`. Контроллер ловит и возвращает
|
||||
`409 Conflict` с сообщением «документ изменён в другой сессии, обновите
|
||||
страницу».
|
||||
|
||||
Stock-операции — отдельная история: `Serializable` транзакция блокирует
|
||||
параллельный пост на тех же товарах в том же storе. Серверу `PG40001`
|
||||
(serialization_failure) — контроллер не ретраит автоматически, кассир
|
||||
видит 409 «недостаточно остатка» (после ретрая по факту достаточно или
|
||||
нет).
|
||||
|
||||
### 7. Тестирование изоляции
|
||||
|
||||
`TenantIsolationTests` (integration) — обязательный смок: создаём 2
|
||||
организации, в одной — продукт; в другой делаем `GET /api/catalog/products`
|
||||
→ список пустой. На любую новую `ITenantEntity` добавлять такой тест.
|
||||
|
||||
### 8. Read-models / ad-hoc raw SQL
|
||||
|
||||
Если контроллер напишет raw SQL через `_db.Database.SqlQueryRaw(...)`,
|
||||
EF-фильтр НЕ применится. Это используется только для отчётов с тяжёлой
|
||||
агрегацией (`ProfitReportController`); там OrganizationId явно
|
||||
включается в `WHERE` и приходит из `_tenant.OrganizationId`.
|
||||
Правило: никаких raw SQL без явного `WHERE OrganizationId = @org` в
|
||||
середине запроса.
|
||||
|
||||
## Чеклист «как добавить новую tenant-сущность»
|
||||
|
||||
1. Унаследовать от `TenantEntity` (или реализовать `ITenantEntity`).
|
||||
2. Добавить EF Configuration в `food-market.infrastructure/Persistence/Configurations/`:
|
||||
- `b.ToTable("...");`
|
||||
- `b.HasIndex(x => new { x.OrganizationId, x.SomeField });` — индекс
|
||||
с OrganizationId первым полем (для скорости query filter'а).
|
||||
- Если есть уникальность в рамках org: `.IsUnique()` на индексе
|
||||
с OrganizationId первым полем.
|
||||
3. Создать миграцию руками в `Persistence/Migrations/`:
|
||||
- Атрибуты `[DbContext(typeof(AppDbContext))]` + `[Migration("YYYYMMDD…")]`.
|
||||
- В `Up()` — `CreateTable` с колонкой `OrganizationId uuid NOT NULL`.
|
||||
- Индекс на OrganizationId.
|
||||
4. Добавить `DbSet` в `AppDbContext`.
|
||||
5. Контроллер использует `_db.MyEntities.Where(...)` — query filter
|
||||
подключится автоматически. Stamping выставит `OrganizationId` в `Add()`.
|
||||
6. Интеграционный тест на изоляцию (см. `TenantIsolationTests`).
|
||||
344
docs/RUNBOOK.md
Normal file
344
docs/RUNBOOK.md
Normal file
|
|
@ -0,0 +1,344 @@
|
|||
# Runbook — операционные процедуры food-market
|
||||
|
||||
Что делать, когда что-то идёт не так, или когда нужно сделать
|
||||
неавтоматическую операцию.
|
||||
|
||||
## Контактные точки
|
||||
|
||||
| Что | Где |
|
||||
|---|---|
|
||||
| Stage URL | https://test.admin.food-market.kz |
|
||||
| Prod URL | https://admin.food-market.kz (план, ещё не задеплоен) |
|
||||
| Stage VM | `nns@192.168.1.190` (через ssh, prod-vm в локалке) |
|
||||
| Dev VM (этот хост) | `nns@<this>` — здесь крутится локальный API/Postgres + локальный Forgejo + локальный Docker registry |
|
||||
| Forgejo (primary git) | http://127.0.0.1:3000/nns/food-market.git |
|
||||
| GitHub (mirror) | https://github.com/nurdotnet/food-market (только зеркало) |
|
||||
| Local Docker registry | `192.168.1.193:5001` (memory: `local_docker_registry`) |
|
||||
| Hangfire Dashboard (stage) | https://test.admin.food-market.kz/hangfire — только SuperAdmin |
|
||||
| Swagger (stage) | https://test.admin.food-market.kz/swagger |
|
||||
|
||||
## Health-чеки
|
||||
|
||||
| Endpoint | Что значит | Что делать при 503 |
|
||||
|---|---|---|
|
||||
| `GET /health` | Процесс отвечает | Контейнер живёт, проблема в обвязке (nginx/cert/DNS). |
|
||||
| `GET /health/live` | Процесс жив (без проверок) | То же. |
|
||||
| `GET /health/ready` | БД отвечает + миграции применены | См. ниже «Health/ready упал». |
|
||||
| `GET /metrics` | Prometheus exposition | Если 404 — приложение не стартануло. |
|
||||
|
||||
### `/health/ready` упал
|
||||
|
||||
1. `ssh nns@192.168.1.190 'docker logs --tail 100 food-market-stage-api'` —
|
||||
стек ошибки на старте.
|
||||
2. Типичные причины:
|
||||
- **Миграция упала**: ищем `Failed executing DbCommand` / `relation
|
||||
"..." already exists`. Решение: миграция конфликтует со снапшотом
|
||||
БД. Возможно её надо переписать с `IF NOT EXISTS` (см.
|
||||
`Phase6e_RetailSaleReturns.cs` как пример «defensive migration»).
|
||||
- **OpenIddict cert pass mismatch**: переменная
|
||||
`OpenIddict__CertPassword` в docker-compose env'е не совпадает с
|
||||
паролем PFX-файла → `CryptographicException: PKCS12 password incorrect`.
|
||||
- **Connection refused**: Postgres контейнер не успел подняться.
|
||||
`depends_on.condition: service_healthy` должно это покрывать,
|
||||
но если healthcheck не успел — `docker compose restart api`.
|
||||
3. Если фикс требует кода — `~/deploy-stage.sh` после правки.
|
||||
|
||||
## Деплой на stage
|
||||
|
||||
```bash
|
||||
~/deploy-stage.sh
|
||||
```
|
||||
|
||||
Скрипт делает:
|
||||
1. `docker build` api и web с локальным registry в качестве кеша.
|
||||
2. `docker push` обоих образов в `192.168.1.193:5001`.
|
||||
3. `ssh nns@192.168.1.190` → `docker compose -p food-market-stage pull api web` → `up -d --force-recreate`.
|
||||
4. Ждёт `https://test.admin.food-market.kz/health/ready` до 30с.
|
||||
|
||||
**Важно**: проект `docker compose` называется `food-market-stage`
|
||||
(флаг `-p food-market-stage`). См. инцидент ниже про project name.
|
||||
|
||||
## Бэкап и восстановление
|
||||
|
||||
### Расписание
|
||||
|
||||
systemd-таймер `food-market-backup.timer` (см. `deploy/`) запускается
|
||||
**каждый день в 03:00 локального времени** prod-vm. Запускается через
|
||||
`OnCalendar=*-*-* 03:00:00` + `Persistent=true` (догоняет пропущенные
|
||||
если сервер был выключен).
|
||||
|
||||
Скрипт `food-market-backup.sh`:
|
||||
- `pg_dump -Fc` из контейнера `food-market-postgres` → `db-<TS>.dump`.
|
||||
- `tar czf` каталога `/opt/food-market-data/uploads` → `uploads-<TS>.tgz`.
|
||||
- Удаляет файлы старше 30 дней (`FM_BACKUP_RETENTION_DAYS`).
|
||||
|
||||
Папка: `/opt/food-market-data/backups/`.
|
||||
|
||||
### Ручной бэкап
|
||||
|
||||
```bash
|
||||
ssh nns@192.168.1.190 'sudo /opt/food-market/deploy/food-market-backup.sh'
|
||||
```
|
||||
|
||||
Или из репо разработчика:
|
||||
```bash
|
||||
deploy/backup.sh --remote 192.168.1.190:5434 # PG в Docker exposed на 5434
|
||||
```
|
||||
|
||||
### Восстановление БД из дампа
|
||||
|
||||
> ⚠️ Перезаписывает данные. Сначала остановить API.
|
||||
|
||||
```bash
|
||||
ssh nns@192.168.1.190
|
||||
cd /opt/food-market
|
||||
|
||||
# 1. Остановить API/Web, оставить Postgres
|
||||
docker compose -p food-market-stage stop api web
|
||||
|
||||
# 2. Применить дамп
|
||||
DUMP=/opt/food-market-data/backups/db-YYYYMMDD-HHMMSS.dump
|
||||
docker exec -i food-market-stage-postgres \
|
||||
pg_restore -U food_market -d food_market \
|
||||
--clean --if-exists --no-owner --no-privileges \
|
||||
< "$DUMP"
|
||||
|
||||
# 3. Поднять API обратно — миграции применятся автоматически (idempotent)
|
||||
docker compose -p food-market-stage up -d api web
|
||||
|
||||
# 4. Проверить
|
||||
curl https://test.admin.food-market.kz/health/ready
|
||||
```
|
||||
|
||||
### Восстановление uploads
|
||||
|
||||
```bash
|
||||
ssh nns@192.168.1.190
|
||||
cd /opt/food-market-data
|
||||
sudo tar xzf backups/uploads-YYYYMMDD-HHMMSS.tgz
|
||||
# Содержимое восстанавливается в текущий каталог (uploads/...)
|
||||
```
|
||||
|
||||
### Полный disaster-recovery (новый сервер)
|
||||
|
||||
1. Поднять Docker, склонировать репо в `/opt/food-market`.
|
||||
2. Скопировать бэкапы в `/opt/food-market-data/backups/`.
|
||||
3. Запустить пустой стек:
|
||||
```bash
|
||||
cd /opt/food-market/deploy
|
||||
docker compose -p food-market-stage up -d postgres
|
||||
docker compose -p food-market-stage exec postgres pg_isready
|
||||
```
|
||||
4. Применить дамп (см. выше).
|
||||
5. Восстановить uploads.
|
||||
6. Запустить остальное: `docker compose -p food-market-stage up -d`.
|
||||
7. Поднять nginx + сертификат (см. `docs/stage-access.md`).
|
||||
8. Включить таймер бэкапов:
|
||||
```bash
|
||||
sudo cp deploy/food-market-backup.{service,timer} /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now food-market-backup.timer
|
||||
```
|
||||
|
||||
## Перенос на другой сервер
|
||||
|
||||
1. На старом — снять свежий бэкап вручную.
|
||||
2. На новом — поднять Docker, склонировать репо, восстановить (см. выше).
|
||||
3. Обновить DNS A-запись `admin.food-market.kz` на новый IP.
|
||||
4. Дождаться распространения DNS (TTL).
|
||||
5. Старый сервер — выключить через 24 часа (для гарантии).
|
||||
|
||||
## Смена SDK-версии
|
||||
|
||||
> ⚠️ `global.json` фиксирует `8.0.417` с `rollForward: latestFeature`.
|
||||
> Менять только когда вышел новый patch и Microsoft анонсировал
|
||||
> EOL текущего. memory: НЕ переключать systemwide postgres версию.
|
||||
|
||||
1. На dev-машине: `dotnet --list-sdks` — проверить что новая версия
|
||||
установлена.
|
||||
2. Обновить `global.json` → новый patch.
|
||||
3. `dotnet build` + `dotnet test`.
|
||||
4. `deploy/Dockerfile.api` — обновить `FROM mirror/dotnet-sdk:X.Y`
|
||||
(если тэг изменился).
|
||||
5. `~/deploy-stage.sh` — задеплоить, проверить `/health/ready`.
|
||||
6. Verify-suite (Playwright или вручную smoke).
|
||||
7. Только после этого — менять на prod-машине.
|
||||
|
||||
## Логи
|
||||
|
||||
| Где | Что |
|
||||
|---|---|
|
||||
| `docker logs food-market-stage-api` (по контейнеру) | Console JSON Serilog. |
|
||||
| `/opt/food-market-data/api-logs/` (Docker volume) | Файлы Serilog rolling. |
|
||||
| `journalctl -u food-market-backup.service --no-pager` | Логи бэкапа. |
|
||||
| Hangfire Dashboard `/hangfire` | Состояние фоновых джобов, истории, ошибки. |
|
||||
|
||||
Формат JSON-логов — структурированный, каждая запись содержит
|
||||
`CorrelationId`, `OrgId`, `UserId` (через `LogEnrichmentMiddleware`).
|
||||
Поиск по `CorrelationId` восстанавливает полный trace запроса.
|
||||
|
||||
## Метрики
|
||||
|
||||
Prometheus scrape: `GET /metrics` (без auth). Локально в проекте нет
|
||||
prometheus-сервера — на stage его тоже пока нет; план — поднять
|
||||
prometheus + grafana отдельным compose'ом и proxy через nginx.
|
||||
|
||||
Ключевые метрики (`food-market.api/Infrastructure/Observability/AppMetrics.cs`):
|
||||
|
||||
- `food_market_posted_total{document_type="..."}` — счётчик post'ов.
|
||||
- `food_market_unposted_total{document_type="..."}` — счётчик unpost'ов.
|
||||
- `food_market_db_query_duration_seconds_*` — гистограмма EF-запросов
|
||||
(interceptor).
|
||||
- Стандартные prometheus-net: `http_requests_received_total`,
|
||||
`http_request_duration_seconds`, `dotnet_collection_count_total`,
|
||||
etc.
|
||||
|
||||
## Известные инциденты
|
||||
|
||||
### Инцидент 1: docker-compose project name
|
||||
|
||||
**Симптом** (наблюдался при первой миграции на новый stage):
|
||||
- `docker compose pull && up -d` создавали контейнеры с именами
|
||||
`deploy-api-1` вместо ожидаемых `food-market-stage-api`.
|
||||
- Healthcheck'и `depends_on` отрабатывали по новым именам, но nginx
|
||||
configurated на старые — 502 Bad Gateway.
|
||||
|
||||
**Причина**: `docker compose` берёт project name из имени каталога,
|
||||
если не указан `-p`. Каталог `deploy/` → project=`deploy` → контейнеры
|
||||
с префиксом `deploy-`. Старые контейнеры с префиксом `food-market-stage-`
|
||||
оставались стопнутыми, новые поднялись параллельно (Docker не считает
|
||||
их дубликатами потому что имена разные).
|
||||
|
||||
**Решение**: всегда передавать `-p food-market-stage`. Сделано в
|
||||
`~/deploy-stage.sh`. На prod ставить аналогичный wrapper-скрипт,
|
||||
не запускать `docker compose` голым из `/opt/food-market/deploy`.
|
||||
|
||||
**Превенция**: в будущем — `COMPOSE_PROJECT_NAME=food-market-stage`
|
||||
в `/etc/environment` на серверах, чтобы голый `docker compose` тоже
|
||||
не промахивался.
|
||||
|
||||
### Инцидент 2: GHCR network flakiness
|
||||
|
||||
**Симптом**: docker push/pull в `ghcr.io` периодически зависает на
|
||||
2-5 минут или падает по TCP-таймауту.
|
||||
|
||||
**Причина**: исходящая сеть с dev-vm к github.com нестабильна
|
||||
(memory: `network_github_flaky`).
|
||||
|
||||
**Решение**: используем **локальный Docker registry** на
|
||||
`192.168.1.193:5001` как primary, ghcr только как mirror (для
|
||||
external CI/CD когда понадобится). Stage compose тянет с локального
|
||||
(`REGISTRY=192.168.1.193:5001`). См. memory `local_docker_registry`.
|
||||
|
||||
### Инцидент 3: OpenIddict cert rotation
|
||||
|
||||
**Симптом**: после `docker compose down -v` (с удалением volume
|
||||
`api-data`) OpenIddict не может расшифровать существующие refresh-токены
|
||||
→ все пользователи разлогинены.
|
||||
|
||||
**Причина**: keys из `App_Data/oidc-keys/` пропали вместе с volume.
|
||||
|
||||
**Решение / превенция**:
|
||||
- НИКОГДА не делать `down -v` на stage/prod без явного намерения.
|
||||
- Хранить `App_Data` volume отдельно: `volumes: api-data:` с
|
||||
`external: true` (план).
|
||||
- Бэкап `App_Data` вместе с БД (TODO: добавить в `food-market-backup.sh`).
|
||||
|
||||
### Инцидент 4: rate-limiter eager-config
|
||||
|
||||
**Симптом** (в integration-тестах): тесты падают с `429 Too Many Requests`
|
||||
после ~5 signup'ов.
|
||||
|
||||
**Причина**: `RateLimiting:Enabled=true` (default) читается ЭАГЕРНО при
|
||||
регистрации сервисов; `ConfigureAppConfiguration` в `WebApplicationFactory`
|
||||
применяется позже и не успевает override'нуть.
|
||||
|
||||
**Решение**: в integration-тестах ставим `RateLimiting__Enabled=false`
|
||||
через переменную окружения **до** создания factory. Сделано в
|
||||
`ApiFactory` static-конструкторе. Memory: `test_suites_setup`.
|
||||
|
||||
### Инцидент 5: Telegram chat-id привязка
|
||||
|
||||
**Симптом**: владелец org вводит chat_id, сервер тестирует отправку →
|
||||
`403 Forbidden` от Telegram API.
|
||||
|
||||
**Причина**: пользователь не отправил `/start` боту перед привязкой,
|
||||
бот не может писать первым.
|
||||
|
||||
**Решение / превенция**: UI показывает инструкцию «1. Откройте бота → `/start`.
|
||||
2. Получите chat_id у `@userinfobot`. 3. Введите.» Это идёт сверху на
|
||||
странице привязки. Бэкенд возвращает ошибку с понятным текстом.
|
||||
|
||||
### Инцидент 6: Identity password policy
|
||||
|
||||
**Симптом**: signup-форма принимает пароль `12345`, потом
|
||||
`/connect/token` отшивает «Invalid credentials» — потому что Identity
|
||||
сам не разрешил создать пользователя с таким паролем, но контроллер
|
||||
проглотил ошибку.
|
||||
|
||||
**Превенция**: контроллер `AuthController.Signup` теперь возвращает
|
||||
`IdentityResult.Errors` массивом → фронт показывает причину.
|
||||
|
||||
## Troubleshooting на стороне БД
|
||||
|
||||
### Большой `org_audit_log`
|
||||
|
||||
`prune-audit-log` каждый день чистит >180 дней; если каталог-tenant
|
||||
делал массовый импорт (10к товаров за раз), таблица может вырасти на
|
||||
порядок. Проверка:
|
||||
```sql
|
||||
SELECT pg_size_pretty(pg_total_relation_size('org_audit_log'));
|
||||
SELECT count(*) FROM org_audit_log WHERE created_at < now() - interval '30 days';
|
||||
```
|
||||
|
||||
Ручная чистка:
|
||||
```sql
|
||||
DELETE FROM org_audit_log WHERE created_at < now() - interval '90 days';
|
||||
VACUUM ANALYZE org_audit_log;
|
||||
```
|
||||
|
||||
### Stock-агрегат расходится с движениями
|
||||
|
||||
Инвариант: `stocks.quantity = SUM(stock_movements.quantity)` per
|
||||
`(product_id, store_id)`. Если разошёлся (баг где-то не вызвали
|
||||
`IStockService.ApplyMovementAsync`):
|
||||
|
||||
```sql
|
||||
-- найти расхождения
|
||||
SELECT s.product_id, s.store_id, s.quantity AS cached,
|
||||
COALESCE(SUM(m.quantity), 0) AS actual
|
||||
FROM stocks s
|
||||
LEFT JOIN stock_movements m
|
||||
ON m.product_id = s.product_id AND m.store_id = s.store_id
|
||||
GROUP BY s.product_id, s.store_id, s.quantity
|
||||
HAVING s.quantity <> COALESCE(SUM(m.quantity), 0);
|
||||
|
||||
-- пересчитать всё (под maintenance window!)
|
||||
UPDATE stocks s SET quantity = COALESCE((
|
||||
SELECT SUM(quantity) FROM stock_movements m
|
||||
WHERE m.product_id = s.product_id AND m.store_id = s.store_id
|
||||
), 0);
|
||||
```
|
||||
|
||||
### `__EFMigrationsHistory` рассинхрон
|
||||
|
||||
Бывает после ручной правки миграции после её применения.
|
||||
```sql
|
||||
SELECT * FROM "__EFMigrationsHistory" ORDER BY 1 DESC LIMIT 5;
|
||||
```
|
||||
Если в коде есть миграция, которой нет в таблице — `db.Database.Migrate()`
|
||||
попытается её применить (что обычно и нужно). Если в таблице есть запись,
|
||||
а файла нет — обратное направление (миграция была удалена) — `Migrate()`
|
||||
не упадёт, но фокус с EF Tools перестанет работать, см. memory
|
||||
`feedback_ef_migrations`.
|
||||
|
||||
## Что НЕ делать
|
||||
|
||||
- НЕ менять `global.json` без явного решения (CLAUDE.md).
|
||||
- НЕ переключать systemwide postgres версию через brew (поломает
|
||||
смежные проекты в `~/Documents/devprojects/`).
|
||||
- НЕ запускать `docker compose down -v` на stage/prod (потеря volume).
|
||||
- НЕ делать миграции через `dotnet ef migrations add` — снапшот в репо
|
||||
не синхронный с моделью, генератор выдаст ерунду. Пишем руками.
|
||||
- НЕ редактировать тот же файл одновременно с Mac-Claude (memory:
|
||||
`feedback_serialize_edits`).
|
||||
178
docs/performance-baseline.md
Normal file
178
docs/performance-baseline.md
Normal file
|
|
@ -0,0 +1,178 @@
|
|||
# Performance baseline — food-market API
|
||||
|
||||
Дата прогона: **2026-06-07**. Прогон против stage:
|
||||
`https://test.admin.food-market.kz`. Инструмент — k6 v0.55.0.
|
||||
|
||||
Сетап stage'а на момент замеров:
|
||||
- 1 контейнер `food-market-stage-api` (Kestrel, .NET 8).
|
||||
- 1 контейнер `food-market-stage-postgres` (Postgres 16, дефолтные настройки).
|
||||
- Nginx-фронт на dev-vm `192.168.1.190`, dev-машина k6-генератора в той
|
||||
же локалке (RTT ~5-20мс).
|
||||
|
||||
Все цифры — **с одного клиента**, без воспроизведения пиковой нагрузки
|
||||
из ЦА продакшна. Это baseline для регрессий, не SLA.
|
||||
|
||||
## TL;DR — что работает, что нет
|
||||
|
||||
| Операция | Здоровый сценарий | Предел до деградации | Узкое место |
|
||||
|---|---|---|---|
|
||||
| **GET /api/reports/sales** (1500 чеков в орге) | p95 50-115ms до 5 VU | После 5 VU непредсказуемо (см. ниже) | PG aggregation / connection pool |
|
||||
| **POST /api/auth/signup** | p95 446ms при 50 RPM | 100 RPM с одного IP → 39% 429 | IP rate-limit (60/мин, by design) |
|
||||
| **POST /api/sales/retail + /post** (sequential) | p95 71ms, 17 sales/sec | VU > 1 на одном tenant'е → unique-violation race | `GenerateNumberAsync` race condition |
|
||||
|
||||
## Прогон 1: signup-burst
|
||||
|
||||
`tests/load/signup-burst.js` — 50/100 регистраций/мин с одного IP, 60с.
|
||||
|
||||
### 50 RPM (под IP-лимитом 60/мин)
|
||||
|
||||
| Метрика | Значение |
|
||||
|---|---|
|
||||
| Iterations | 51 (за 60с) |
|
||||
| http_req_duration p50 | 391ms |
|
||||
| http_req_duration p90 | 425ms |
|
||||
| http_req_duration p95 | 446ms |
|
||||
| http_req_duration p99 | ~1.37s (один outlier) |
|
||||
| signup_rate_limited | 0% |
|
||||
| Failures | 0 |
|
||||
|
||||
Прогон чистый. Signup на stage'е укладывается в ~400-450ms p95.
|
||||
|
||||
### 100 RPM (превышение IP-лимита)
|
||||
|
||||
| Метрика | Значение |
|
||||
|---|---|
|
||||
| Iterations | 101 |
|
||||
| 2xx (успешные) | 62 |
|
||||
| 429 (rate-limited) | 39 (38.6%) |
|
||||
| http_req_duration p95 (2xx-only) | 437ms |
|
||||
|
||||
429-ответы возвращаются за единицы миллисекунд (`http_req_duration`
|
||||
total p95 показывает 436ms потому что включает и 429 — лимитер очень
|
||||
быстрый). Поведение by design (см. `AuthRateLimiterExtensions`),
|
||||
указывает что защита работает.
|
||||
|
||||
## Прогон 2: retail-sales-parallel
|
||||
|
||||
`tests/load/retail-sales-parallel.js` — на одном tenant'е N параллельных
|
||||
кассиров (VU) проводят чеки. Тест создаёт draft (`POST /api/sales/retail`)
|
||||
и сразу проводит (`POST /api/sales/retail/{id}/post`).
|
||||
|
||||
### VU=1 (sequential baseline) — 200 итераций
|
||||
|
||||
| Метрика | Значение |
|
||||
|---|---|
|
||||
| Iterations | 200/200 (100%) |
|
||||
| Throughput | **17 sales/sec** |
|
||||
| sale_draft_ms p50 | 25ms |
|
||||
| sale_draft_ms p95 | 37ms |
|
||||
| sale_post_ms p50 | 26ms |
|
||||
| sale_post_ms p95 | 35ms |
|
||||
| sale_total_ms p95 | **71ms** |
|
||||
| sale_total_ms p99 | ~90ms |
|
||||
| post_4xx | 0% |
|
||||
|
||||
Идеальная картинка: 17 sales/sec на single-thread, латенция стабильная.
|
||||
|
||||
### VU=5 (параллельные кассиры) — 200 итераций
|
||||
|
||||
| Метрика | Значение |
|
||||
|---|---|
|
||||
| Iterations | 200/200 (driver), но успешных только 94 |
|
||||
| post_4xx | **53% 🔴** |
|
||||
| sale_draft_ms p95 (включая failed) | 151ms |
|
||||
| sale_total_ms p95 (только успешные) | 185ms |
|
||||
|
||||
**Узкое место найдено: race в `GenerateNumberAsync`.**
|
||||
|
||||
`RetailSalesController.GenerateNumberAsync` строит next-number чтением
|
||||
последней `Number` для tenant'а и +1. Под параллельными VU несколько
|
||||
запросов читают одно и то же `lastNumber`, генерируют одинаковый
|
||||
`ПР-2026-000XXX`, на INSERT падают на unique-index
|
||||
`IX_retail_sales_OrganizationId_Number`. `SaveOrFkErrorAsync` ловит
|
||||
только 23503 (FK violation), не 23505 (unique violation) — поэтому
|
||||
до клиента долетает 500 (или 400 от EF middleware).
|
||||
|
||||
**Что делать (отдельная задача, не в Sprint 12)**: завести
|
||||
`organization_counters` (singleton-row per tenant), увеличивать счётчик
|
||||
через `UPDATE … RETURNING value` в той же транзакции. Альтернатива —
|
||||
ловить 23505 и ретраить с +1 в цикле. Третий вариант — использовать
|
||||
PG sequence per tenant (более сложно, но самое чистое).
|
||||
|
||||
## Прогон 3: sales-report-heavy
|
||||
|
||||
`tests/load/sales-report-heavy.js` — за 20-30 секунд VU дёргают
|
||||
`GET /api/reports/sales?dateFrom=...&dateTo=...&groupBy=day`,
|
||||
`/api/reports/abc?...` и `/api/dashboard/top-products?limit=5`.
|
||||
|
||||
Tenant с **1500 проведённых чеков, 5535 stock_movements, 200 товаров**
|
||||
(посеян через `POST /api/admin/seed-demo?years=1` — это YearDemoSeeder).
|
||||
|
||||
| VU | Throughput (iter/s) | sales p95 | abc p95 | non_2xx | Заметки |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 6.7 | 54ms | 51ms | 0% | Чистый baseline. |
|
||||
| 2 | 17.5 | 60ms | 54ms | 0% | Linear, ОК. |
|
||||
| 3 | 23.5 | 67ms | 63ms | 0% | Linear, ОК. |
|
||||
| 4 | 25.4 | 81ms | 78ms | 0% | Незначительная деградация. |
|
||||
| 5 | 24.0 | 114ms | 108ms | 0% | Деградация заметнее, throughput плато. |
|
||||
| 5* | 8.7 | 3 800ms 🔴 | 3 500ms 🔴 | 0% | Аномалия одного прогона (см. ниже). |
|
||||
|
||||
`*` Первый прогон VU=5 показал p95 ~3.8с на отчёт. Повторный прогон —
|
||||
обычные 114ms p95. Скорее всего совпало с autovacuum'ом
|
||||
`stock_movements` (5535 строк, частые обновления при seed'е). Это
|
||||
напоминает: в production нужны:
|
||||
- Мониторинг p95 отчётов в Prometheus + алерт на отклонение от baseline.
|
||||
- Тюнинг `autovacuum_*` для `stock_movements` (или явный
|
||||
`VACUUM ANALYZE` после массовых seed'ов).
|
||||
|
||||
### Что НЕ протестировано (требует входа от user)
|
||||
|
||||
- **10 000 чеков на одного tenant'а** — пользователь просил «отчёт Sales
|
||||
с 10 000 продажами». YearDemoSeeder делает максимум 1500 (это сезонный
|
||||
год для одного магазина); чтобы получить 10к — нужно либо допилить
|
||||
seeder на «10 лет» / «10 магазинов», либо запустить несколько
|
||||
параллельных seed'ов под отдельными tenant'ами и тестировать
|
||||
cross-tenant. Пока обозначено как TODO для будущего спринта.
|
||||
- **Реальная нагрузка из ЦА** — k6 запускается из локалки, RTT
|
||||
5-20мс. Реальный пользователь из Алматы добавит 30-80мс к
|
||||
каждому запросу. Считать SLA с учётом этого.
|
||||
- **POS-синк** (`POST /api/pos/v1/batch`) — отдельный сценарий, потому
|
||||
что требует серии чеков с идемпотентным ключом и подходящих refs.
|
||||
TODO: `pos-sync.js`.
|
||||
|
||||
## Сводка: что нужно поправить
|
||||
|
||||
| Приоритет | Что | Где |
|
||||
|---|---|---|
|
||||
| 🔴 P0 | Race в `GenerateNumberAsync` | `RetailSalesController.cs:957` |
|
||||
| 🟡 P1 | Тот же подход в `SuppliesController/DemandsController/...` | Везде где есть `GenerateNumberAsync` |
|
||||
| 🟡 P1 | `SaveOrFkErrorAsync` не ловит 23505 (unique violation) | `RetailSalesController.cs:418` |
|
||||
| 🟢 P2 | Tune autovacuum для `stock_movements` | PG config / `ALTER TABLE` |
|
||||
| 🟢 P2 | Прометей-алерт на p95 отчёта | observability |
|
||||
| 🟢 P2 | k6 для POS-синка с idempotency | `tests/load/pos-sync.js` |
|
||||
|
||||
## Воспроизведение
|
||||
|
||||
```bash
|
||||
# k6 v0.55+ должен быть в PATH (см. tests/load/README.md)
|
||||
cd tests/load
|
||||
|
||||
# 1. Signup-burst (60с, 50 RPM)
|
||||
BASE_URL=https://test.admin.food-market.kz TARGET_RPM=50 \
|
||||
k6 run signup-burst.js
|
||||
|
||||
# 2. Sales sequential baseline
|
||||
BASE_URL=https://test.admin.food-market.kz \
|
||||
DURATION_S=120 TARGET_ITERS=200 VUS=1 \
|
||||
k6 run retail-sales-parallel.js
|
||||
|
||||
# 3. Reports на свежем tenant'е (нужны creds от signup + year-demo seed)
|
||||
SLUG="loadbase-$(date +%s)"
|
||||
EMAIL="$SLUG@example.kz"
|
||||
curl -sX POST $BASE_URL/api/auth/signup -H 'Content-Type: application/json' \
|
||||
-d "{\"email\":\"$EMAIL\",\"password\":\"Passw0rd!\",\"organizationName\":\"LoadOrg\",\"phone\":\"+77001234567\"}"
|
||||
TOKEN=$(curl -sX POST $BASE_URL/connect/token -d "grant_type=password&username=$EMAIL&password=Passw0rd!&client_id=food-market-web&scope=openid profile email roles api offline_access" | jq -r .access_token)
|
||||
curl -sX POST -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/admin/seed-demo?years=1"
|
||||
|
||||
EMAIL=$EMAIL PASSWORD=Passw0rd! VUS=3 k6 run sales-report-heavy.js
|
||||
```
|
||||
131
docs/sprint12-progress.md
Normal file
131
docs/sprint12-progress.md
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
# Sprint 12 — документация, runbook, нагрузочное тестирование
|
||||
|
||||
Цель: переложить «то что знаю только я и комментарии в коде» в
|
||||
читаемые документы для следующего разработчика, замерить реальную
|
||||
производительность под нагрузкой, и закрыть автоматическую верификацию
|
||||
stage-стэйджа на каждый push.
|
||||
|
||||
Старт: 2026-06-07. Исполнитель: Claude Opus 4.7.
|
||||
|
||||
Это **последний автономно-безопасный спринт**. Дальше нужны входы от
|
||||
user'а: реальные ОФД-ApiKey, MoySklad webhook-token'ы, Windows-машина
|
||||
для POS WPF, прод-деплой план, казахские переводы, реальный SMTP-провайдер.
|
||||
|
||||
## Принципы
|
||||
|
||||
- Документация — для человека, не «AI-портянка». Конкретные пути, имена
|
||||
типов, причины решений. Без воды и эмоций.
|
||||
- k6 — реальные числа. Если p95 высокий — пишем как есть.
|
||||
- НЕ трогать: `global.json`, прод-стек, POS WPF.
|
||||
|
||||
## Чек-лист
|
||||
|
||||
- [x] **1. docs/ARCHITECTURE.md** — карта слоёв, модулей, потоков
|
||||
signup→bootstrap→операции. Реальные имена типов и путей, не маркетинг.
|
||||
- [x] **2. docs/MULTI-TENANCY.md** — `ITenantEntity` + reflection
|
||||
query-filter, stamping в SaveChanges, SuperAdmin override (read-only +
|
||||
edit-mode с reason), 8 подводных камней (IgnoreQueryFilters, фоновые
|
||||
jobs без HttpContext, raw SQL, и т.д.).
|
||||
- [x] **3. docs/RUNBOOK.md** — health-чеки, backup/restore (включая
|
||||
disaster-recovery), смена SDK, перенос на новый сервер, **6 описанных
|
||||
инцидентов** (включая docker-compose project name из ТЗ),
|
||||
troubleshooting БД (stock-агрегат расхождения, audit-log
|
||||
размер, EFMigrationsHistory).
|
||||
- [x] **4. docs/DEVELOPER-GUIDE.md** — локальный setup, запуск тестов,
|
||||
гочи integration-тестов (Ryuk, rate-limiter eager-config, один
|
||||
ApiFactory), полные паттерны: добавить controller с permission +
|
||||
добавить tenant-сущность с RowVersion + 5 шагов миграции, валидация
|
||||
(DataAnnotations / FluentValidation / бизнес), structured-логирование.
|
||||
- [x] **5. k6 нагрузочный тест** — `tests/load/` + 3 скрипта
|
||||
(signup-burst, retail-sales-parallel, sales-report-heavy) +
|
||||
`docs/performance-baseline.md` с **реальными цифрами** на stage'е.
|
||||
Главное найденное: race в `GenerateNumberAsync` при VU > 1 на одном
|
||||
tenant'е (unique-violation 23505 не ловится → 500). Прогон зарегистрирован
|
||||
как P0 для следующего рефакторинга.
|
||||
- [x] **6. CI workflow `.forgejo/workflows/stage-verify.yml`** —
|
||||
`on workflow_run` после `Docker API`/`Docker Web`, ждёт
|
||||
`/health/ready` и запускает `tests/stage-smoke.sh` (~7с,
|
||||
full-cycle smoke: signup → multi-tenant isolation → supply.post →
|
||||
retail-sale.post → stock check). Telegram-нотификация по
|
||||
успеху/падению.
|
||||
|
||||
## Журнал
|
||||
|
||||
### 2026-06-07 старт
|
||||
Sprint 11 закрыт (7/7 ✓). Поехали по docs-чек-листу.
|
||||
|
||||
### 2026-06-07 п.1–п.4 (документация)
|
||||
Прочитал реальный код: `Program.cs` composition root, `AppDbContext`
|
||||
reflection-фильтры, `HttpContextTenantContext` с AsyncLocal-override,
|
||||
`SuperAdminOverrideClaimsTransformer` + `ReadonlyOverrideMiddleware`,
|
||||
`RequiresPermissionAttribute` + policy-handler, `HangfireJobsConfigurator`
|
||||
recurring jobs, deploy/Dockerfile + docker-compose, backup-скрипт +
|
||||
systemd-timer.
|
||||
|
||||
Написал 4 документа на основе этого:
|
||||
- `ARCHITECTURE.md` (372 строки) — слои + модули + composition root +
|
||||
поток signup→post с детальным трассировщиком ASP.NET pipeline.
|
||||
- `MULTI-TENANCY.md` (256 строк) — query-filter, stamping,
|
||||
SuperAdmin override, 8 подводных камней + чеклист «как добавить
|
||||
tenant-сущность».
|
||||
- `RUNBOOK.md` (337 строк) — health-чеки, backup/restore с примером,
|
||||
смена SDK, disaster-recovery, 6 инцидентов, БД-troubleshooting.
|
||||
- `DEVELOPER-GUIDE.md` (332 строки) — локальный setup, тесты,
|
||||
паттерны (controller + entity + валидация + логирование), "НЕ
|
||||
делать" список.
|
||||
|
||||
### 2026-06-07 п.5 (k6 baseline)
|
||||
k6 v0.55.0 standalone в `~/bin/k6`. 3 скрипта в `tests/load/`:
|
||||
|
||||
- `signup-burst.js`: 50 RPM → p95 446ms, 0% errors. 100 RPM → 39% 429
|
||||
(IP-лимит работает, by design).
|
||||
- `retail-sales-parallel.js`: VU=1 — 17 sales/sec, p95 71ms, 0%
|
||||
failures. VU=5 — **53% failure** из-за race в `GenerateNumberAsync`
|
||||
(unique violation на `RetailSale.Number`). Это **реальная находка**,
|
||||
P0 для следующего спринта.
|
||||
- `sales-report-heavy.js`: на tenant'е с 1500 чеков, VU=1 — p95 54ms,
|
||||
VU=4 — p95 81ms, VU=5 — p95 114ms (один аномальный прогон показал
|
||||
3.8с — autovacuum suspect).
|
||||
|
||||
Все цифры в `docs/performance-baseline.md` с воспроизведением.
|
||||
|
||||
### 2026-06-07 п.6 (CI workflow)
|
||||
`.forgejo/workflows/stage-verify.yml` — `on: workflow_run` после
|
||||
`Docker API` и `Docker Web`, не запускается на failed parent (нет
|
||||
смысла верифировать незадеплоенное). Шаги: wait-for-ready (60с
|
||||
retry loop) → запустить `tests/stage-smoke.sh` → Telegram пинг.
|
||||
|
||||
`tests/stage-smoke.sh` — bash-скрипт без зависимостей кроме
|
||||
curl+jq+python3. 5 этапов: health, signup A, token A, multi-tenant
|
||||
isolation (A создаёт продукт, B получает 404 + список без продукта A),
|
||||
полный документ-цикл (supplier+supply.post → проверка stock=100 →
|
||||
sale.post → проверка stock=99). Локальный прогон против stage —
|
||||
**7 секунд**, всё зелёное.
|
||||
|
||||
### Итог
|
||||
|
||||
Все 6 пунктов ✓. Документация:
|
||||
- 4 новых файла в `docs/` (~1300 строк суммарно).
|
||||
- `docs/performance-baseline.md` — реальные цифры + 1 находка P0.
|
||||
|
||||
Тестирование:
|
||||
- 3 k6 скрипта в `tests/load/`.
|
||||
- `tests/stage-smoke.sh` — 7-секундный smoke против stage.
|
||||
|
||||
CI:
|
||||
- `.forgejo/workflows/stage-verify.yml` — auto-verify на каждый
|
||||
successful deploy.
|
||||
|
||||
Следующие шаги, требующие user'а (за пределами автономного режима):
|
||||
1. Реальный ОФД ApiKey (Webkassa предпочтительно) — Sprint 11-fiscal
|
||||
ждёт это для активации.
|
||||
2. Решение по прод-деплой (домен + cert + DNS).
|
||||
3. MoySklad webhook-токены для inline-импорта.
|
||||
4. Windows-машина (или CI runner) для POS WPF сборки.
|
||||
5. Казахский переводчик для UI (i18n уже подготовлен).
|
||||
6. Реальный SMTP-провайдер для платформы (Mailgun / Postmark / Yandex).
|
||||
|
||||
Plus P0-задача из baseline'а: исправить race в `GenerateNumberAsync`
|
||||
для `RetailSalesController` и аналогичных контроллеров — это уже
|
||||
автономно делается, но требует дизайн-решения (per-tenant sequence vs
|
||||
counter table vs retry-loop).
|
||||
50
tests/load/README.md
Normal file
50
tests/load/README.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
# k6 нагрузочные тесты
|
||||
|
||||
Сценарии нагрузочного тестирования API food-market через
|
||||
[k6](https://k6.io/).
|
||||
|
||||
## Подготовка
|
||||
|
||||
```bash
|
||||
# k6 standalone (Linux)
|
||||
wget -O- https://github.com/grafana/k6/releases/download/v0.55.0/k6-v0.55.0-linux-amd64.tar.gz | tar xz
|
||||
mv k6-*-linux-amd64/k6 ~/bin/
|
||||
|
||||
# проверить
|
||||
k6 version
|
||||
```
|
||||
|
||||
## Сценарии
|
||||
|
||||
| Файл | Что меряет |
|
||||
|---|---|
|
||||
| `signup-burst.js` | 100 signup'ов за минуту — bootstrap новых tenant'ов под нагрузкой |
|
||||
| `retail-sales-parallel.js` | 1000 проведённых чеков параллельно за 5 минут (один tenant) |
|
||||
| `sales-report-heavy.js` | Чтение отчёта `/api/reports/sales` при 10 000 уже-существующих продажах |
|
||||
|
||||
## Запуск против stage
|
||||
|
||||
```bash
|
||||
BASE_URL=https://test.admin.food-market.kz \
|
||||
k6 run signup-burst.js
|
||||
|
||||
BASE_URL=https://test.admin.food-market.kz \
|
||||
k6 run retail-sales-parallel.js
|
||||
|
||||
BASE_URL=https://test.admin.food-market.kz \
|
||||
k6 run sales-report-heavy.js
|
||||
```
|
||||
|
||||
Результаты сводятся в `docs/performance-baseline.md`.
|
||||
|
||||
## Что k6 печатает
|
||||
|
||||
```
|
||||
checks_total....: 100.00% 1000/1000
|
||||
http_req_duration: p(50)=82ms p(95)=312ms p(99)=580ms
|
||||
http_req_failed.: 0.00% 0/1000
|
||||
iteration_duration: avg=512ms
|
||||
```
|
||||
|
||||
Это «человеческие» метрики. Тонкое — через `--out json=summary.json`
|
||||
или `--out csv=...` (k6 не имеет своего хранилища, только stdout/file).
|
||||
173
tests/load/retail-sales-parallel.js
Normal file
173
tests/load/retail-sales-parallel.js
Normal file
|
|
@ -0,0 +1,173 @@
|
|||
// retail-sales-parallel.js — нагрузка на проведение чеков.
|
||||
//
|
||||
// Сценарий: один tenant создан вне теста (или одним setup), все VU
|
||||
// проводят чеки параллельно. Цель — увидеть p95/p99 операции
|
||||
// «создать draft → /post → дождаться NoContent» под нагрузкой.
|
||||
//
|
||||
// По умолчанию: 1000 итераций за 5 минут (~3.3 RPS). Подкручивается
|
||||
// через DURATION_S и TARGET_ITERS env'ами.
|
||||
//
|
||||
// ВАЖНО:
|
||||
// - Перед запуском нужен tenant с продуктом и приёмкой. setup()
|
||||
// делает всё сам: signup → seed product → post supply на 10 000 шт.
|
||||
// Один setup на запуск — потом VU работают параллельно с тем же
|
||||
// токеном. Если итерация не находит остатка (например, тестовый
|
||||
// tenant закончился) — фейлим check.
|
||||
// - Запуск против stage заметно дольше из-за сетевого RTT (~30-100мс
|
||||
// на запрос). Локально на dev-vm обычно в 3-5 раз быстрее.
|
||||
|
||||
import http from 'k6/http';
|
||||
import { check } from 'k6';
|
||||
import { Trend, Rate, Counter } from 'k6/metrics';
|
||||
|
||||
const BASE_URL = __ENV.BASE_URL || 'http://localhost:5081';
|
||||
const DURATION_S = Number(__ENV.DURATION_S || 300); // 5 минут
|
||||
const TARGET_ITERS = Number(__ENV.TARGET_ITERS || 1000);
|
||||
|
||||
const draftTrend = new Trend('sale_draft_ms', true);
|
||||
const postTrend = new Trend('sale_post_ms', true);
|
||||
const totalTrend = new Trend('sale_total_ms', true);
|
||||
const post4xx = new Rate('post_4xx');
|
||||
const completed = new Counter('sales_completed');
|
||||
|
||||
const VUS = Number(__ENV.VUS || 5);
|
||||
|
||||
export const options = {
|
||||
scenarios: {
|
||||
retail_sales: {
|
||||
executor: 'shared-iterations',
|
||||
iterations: TARGET_ITERS,
|
||||
vus: VUS, // дефолт 5 параллельных кассиров
|
||||
maxDuration: `${DURATION_S}s`,
|
||||
},
|
||||
},
|
||||
thresholds: {
|
||||
// p95 «draft + post» на stage обычно 200-700ms.
|
||||
sale_total_ms: ['p(95)<3000', 'p(99)<6000'],
|
||||
// ⚠️ При VU > 5 на одном tenant'е будут конфликты на уникальный
|
||||
// индекс RetailSale.Number (генератор номера расы) — это
|
||||
// отдельная задача для оптимизации (см. performance-baseline.md).
|
||||
post_4xx: ['rate<0.10'],
|
||||
},
|
||||
};
|
||||
|
||||
// ── setup: один раз для всех VU ────────────────────────────────────────
|
||||
|
||||
export function setup() {
|
||||
const slug = `load-sales-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
|
||||
const email = `${slug}@example.kz`;
|
||||
const password = 'Passw0rd!';
|
||||
|
||||
// 1. Signup
|
||||
let r = http.post(`${BASE_URL}/api/auth/signup`, JSON.stringify({
|
||||
email, password, organizationName: `LoadOrg-${slug}`,
|
||||
phone: '+77001234567', plan: null,
|
||||
}), { headers: { 'Content-Type': 'application/json' } });
|
||||
if (r.status >= 300) throw new Error(`signup failed: ${r.status} ${r.body}`);
|
||||
|
||||
// 2. Token
|
||||
r = http.post(`${BASE_URL}/connect/token`,
|
||||
`grant_type=password&username=${encodeURIComponent(email)}&password=${encodeURIComponent(password)}&client_id=food-market-web&scope=openid profile email roles api offline_access`,
|
||||
{ headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
|
||||
if (r.status !== 200) throw new Error(`token failed: ${r.status} ${r.body}`);
|
||||
const token = r.json('access_token');
|
||||
const auth = { headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` } };
|
||||
|
||||
// 3. Достаём refs (unit/group/store/currency/priceType)
|
||||
const unitsRes = http.get(`${BASE_URL}/api/catalog/units-of-measure?pageSize=200`, auth);
|
||||
const unit = unitsRes.json('items').find(u => u.code === '796');
|
||||
const groupsRes = http.get(`${BASE_URL}/api/catalog/product-groups`, auth);
|
||||
const group = groupsRes.json('items')[0];
|
||||
const ptsRes = http.get(`${BASE_URL}/api/catalog/price-types`, auth);
|
||||
const pt = ptsRes.json('items').find(p => p.isRetail);
|
||||
const cursRes = http.get(`${BASE_URL}/api/catalog/currencies`, auth);
|
||||
const cur = cursRes.json('items').find(c => c.code === 'KZT');
|
||||
const storesRes = http.get(`${BASE_URL}/api/catalog/stores`, auth);
|
||||
const store = storesRes.json('items').find(s => s.isMain);
|
||||
const rpsRes = http.get(`${BASE_URL}/api/catalog/retail-points`, auth);
|
||||
const retailPoint = rpsRes.json('items')[0];
|
||||
|
||||
// 4. Создаём продукт
|
||||
const prodRes = http.post(`${BASE_URL}/api/catalog/products`, JSON.stringify({
|
||||
name: 'Load test product',
|
||||
article: `LT-${slug}`,
|
||||
unitOfMeasureId: unit.id,
|
||||
vat: 12, vatEnabled: true,
|
||||
productGroupId: group.id,
|
||||
packaging: 1,
|
||||
prices: [{ priceTypeId: pt.id, amount: 100, currencyId: cur.id }],
|
||||
barcodes: [{ code: `9990000${Math.floor(Math.random()*1e6).toString().padStart(7,'0')}`, type: 1, isPrimary: true }],
|
||||
}), auth);
|
||||
if (prodRes.status >= 300) throw new Error(`product failed: ${prodRes.status} ${prodRes.body}`);
|
||||
const productId = prodRes.json('id');
|
||||
|
||||
// 5. Поставщик + приёмка на 10 000 шт.
|
||||
const supRes = http.post(`${BASE_URL}/api/catalog/counterparties`,
|
||||
JSON.stringify({ name: 'LoadSupplier', type: 2 }), auth);
|
||||
const supplierId = supRes.json('id');
|
||||
|
||||
const supplyRes = http.post(`${BASE_URL}/api/purchases/supplies`, JSON.stringify({
|
||||
date: new Date().toISOString(),
|
||||
supplierId, storeId: store.id, currencyId: cur.id,
|
||||
lines: [{ productId, quantity: 10000, unitPrice: 50 }],
|
||||
}), auth);
|
||||
const supplyId = supplyRes.json('id');
|
||||
const postSupplyRes = http.post(`${BASE_URL}/api/purchases/supplies/${supplyId}/post`, null, auth);
|
||||
if (postSupplyRes.status >= 300) throw new Error(`supply post failed: ${postSupplyRes.status}`);
|
||||
|
||||
return {
|
||||
token, productId,
|
||||
storeId: store.id,
|
||||
retailPointId: retailPoint.id,
|
||||
currencyId: cur.id,
|
||||
};
|
||||
}
|
||||
|
||||
// ── default fn: каждая итерация = один проведённый чек ─────────────────
|
||||
|
||||
export default function (ctx) {
|
||||
const auth = {
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
Authorization: `Bearer ${ctx.token}`,
|
||||
},
|
||||
};
|
||||
|
||||
const t0 = Date.now();
|
||||
|
||||
// 1. Создать draft (POST /api/sales/retail)
|
||||
const draftPayload = JSON.stringify({
|
||||
date: new Date().toISOString(),
|
||||
storeId: ctx.storeId,
|
||||
retailPointId: ctx.retailPointId,
|
||||
customerId: null,
|
||||
currencyId: ctx.currencyId,
|
||||
payment: 0, isReturn: false,
|
||||
lines: [{
|
||||
productId: ctx.productId,
|
||||
quantity: 1, unitPrice: 100, discount: 0, vatPercent: 12,
|
||||
}],
|
||||
subtotal: 100, discountTotal: 0, total: 100,
|
||||
paidCash: 100, paidCard: 0,
|
||||
notes: 'k6-load',
|
||||
});
|
||||
const tDraft0 = Date.now();
|
||||
const draftRes = http.post(`${BASE_URL}/api/sales/retail`, draftPayload, auth);
|
||||
draftTrend.add(Date.now() - tDraft0);
|
||||
const draftOk = check(draftRes, { 'draft 2xx': (r) => r.status >= 200 && r.status < 300 });
|
||||
if (!draftOk) {
|
||||
post4xx.add(1);
|
||||
return;
|
||||
}
|
||||
const saleId = draftRes.json('id');
|
||||
|
||||
// 2. Провести (POST /api/sales/retail/{id}/post)
|
||||
const tPost0 = Date.now();
|
||||
const postRes = http.post(`${BASE_URL}/api/sales/retail/${saleId}/post`, null, auth);
|
||||
postTrend.add(Date.now() - tPost0);
|
||||
post4xx.add(postRes.status >= 400);
|
||||
check(postRes, { 'post 204': (r) => r.status === 204 });
|
||||
|
||||
totalTrend.add(Date.now() - t0);
|
||||
if (postRes.status === 204) completed.add(1);
|
||||
}
|
||||
78
tests/load/sales-report-heavy.js
Normal file
78
tests/load/sales-report-heavy.js
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
// sales-report-heavy.js — нагрузка чтения отчётов.
|
||||
//
|
||||
// Сценарий: один tenant с уже-нагенерированными чеками (1500 через
|
||||
// YearDemoSeeder или 10000+ через несколько подряд запусков
|
||||
// retail-sales-parallel.js). 30 секунд VU дёргают
|
||||
// GET /api/reports/sales и GET /api/reports/abc, мерим p95/p99.
|
||||
//
|
||||
// Это «чтение тяжёлого агрегата», самый показательный bench для
|
||||
// PG-индексов и плана запроса. Если p95 > 2с при 1500 чеках —
|
||||
// нужен EXPLAIN.
|
||||
|
||||
import http from 'k6/http';
|
||||
import { check } from 'k6';
|
||||
import { Trend, Rate } from 'k6/metrics';
|
||||
|
||||
const BASE_URL = __ENV.BASE_URL || 'http://localhost:5081';
|
||||
const DURATION_S = Number(__ENV.DURATION_S || 30);
|
||||
const VUS = Number(__ENV.VUS || 10);
|
||||
|
||||
// Email/пароль уже-существующего tenant'а — нужно подсунуть. По дефолту
|
||||
// — admin@food-market.local (SuperAdmin без своей орги, отчёты будут
|
||||
// пустыми, но мы мерим только время ответа эндпоинтов).
|
||||
const EMAIL = __ENV.EMAIL || 'admin@food-market.local';
|
||||
const PASSWORD = __ENV.PASSWORD || 'Admin12345!';
|
||||
|
||||
const salesTrend = new Trend('reports_sales_ms', true);
|
||||
const abcTrend = new Trend('reports_abc_ms', true);
|
||||
const dashboardTrend = new Trend('dashboard_top_ms', true);
|
||||
const non2xx = new Rate('reports_non_2xx');
|
||||
|
||||
export const options = {
|
||||
scenarios: {
|
||||
reports: {
|
||||
executor: 'constant-vus',
|
||||
vus: VUS,
|
||||
duration: `${DURATION_S}s`,
|
||||
},
|
||||
},
|
||||
thresholds: {
|
||||
reports_sales_ms: ['p(95)<2500', 'p(99)<5000'],
|
||||
reports_abc_ms: ['p(95)<3000', 'p(99)<6000'],
|
||||
reports_non_2xx: ['rate<0.01'],
|
||||
},
|
||||
};
|
||||
|
||||
export function setup() {
|
||||
const r = http.post(`${BASE_URL}/connect/token`,
|
||||
`grant_type=password&username=${encodeURIComponent(EMAIL)}&password=${encodeURIComponent(PASSWORD)}&client_id=food-market-web&scope=openid profile email roles api offline_access`,
|
||||
{ headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
|
||||
if (r.status !== 200) throw new Error(`token failed for ${EMAIL}: ${r.status} ${r.body}`);
|
||||
return { token: r.json('access_token') };
|
||||
}
|
||||
|
||||
export default function (ctx) {
|
||||
const auth = { headers: { Authorization: `Bearer ${ctx.token}` }, tags: {} };
|
||||
|
||||
// Период «весь год» — стандартный запрос дашборда «за год».
|
||||
const dateFrom = '2026-01-01';
|
||||
const dateTo = '2026-12-31';
|
||||
|
||||
let t0 = Date.now();
|
||||
let r = http.get(`${BASE_URL}/api/reports/sales?dateFrom=${dateFrom}&dateTo=${dateTo}&groupBy=day`, auth);
|
||||
salesTrend.add(Date.now() - t0);
|
||||
non2xx.add(r.status >= 400);
|
||||
check(r, { 'sales 2xx': (x) => x.status >= 200 && x.status < 300 });
|
||||
|
||||
t0 = Date.now();
|
||||
r = http.get(`${BASE_URL}/api/reports/abc?dateFrom=${dateFrom}&dateTo=${dateTo}`, auth);
|
||||
abcTrend.add(Date.now() - t0);
|
||||
non2xx.add(r.status >= 400);
|
||||
check(r, { 'abc 2xx': (x) => x.status >= 200 && x.status < 300 });
|
||||
|
||||
t0 = Date.now();
|
||||
r = http.get(`${BASE_URL}/api/dashboard/top-products?limit=5`, auth);
|
||||
dashboardTrend.add(Date.now() - t0);
|
||||
non2xx.add(r.status >= 400);
|
||||
check(r, { 'dashboard 2xx': (x) => x.status >= 200 && x.status < 300 });
|
||||
}
|
||||
69
tests/load/signup-burst.js
Normal file
69
tests/load/signup-burst.js
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
// signup-burst.js — нагрузочный тест регистрации новых tenant'ов.
|
||||
//
|
||||
// Сценарий: 100 signup'ов в минуту, ramping VU от 1 до 20 и обратно.
|
||||
//
|
||||
// ВАЖНО: на stage IP-лимит rate-limiter'а — 60/мин на /api/auth/signup
|
||||
// и /connect/token (DefaultPerIpPerMinute=60, см.
|
||||
// AuthRateLimiterExtensions). Запуская 100/мин с одного IP, мы УПРЁМСЯ
|
||||
// в 429 — это нормальный исход теста. Метрика «процент 429» показывает,
|
||||
// насколько IP-лимит держит вход; метрика «латенция при <60 rps» —
|
||||
// чистая производительность стэка.
|
||||
//
|
||||
// Чтобы по-честному померить bootstrap БЕЗ упирания в лимит — уменьшить
|
||||
// до 50 RPS (через TARGET_RPM=50).
|
||||
|
||||
import http from 'k6/http';
|
||||
import { check } from 'k6';
|
||||
import { Trend, Rate } from 'k6/metrics';
|
||||
|
||||
const BASE_URL = __ENV.BASE_URL || 'http://localhost:5081';
|
||||
const TARGET_RPM = Number(__ENV.TARGET_RPM || 100);
|
||||
const DURATION_S = 60;
|
||||
const PER_SECOND = TARGET_RPM / 60;
|
||||
|
||||
const signupTrend = new Trend('signup_duration_ms', true);
|
||||
const signup429 = new Rate('signup_rate_limited');
|
||||
|
||||
export const options = {
|
||||
scenarios: {
|
||||
signup_burst: {
|
||||
executor: 'constant-arrival-rate',
|
||||
rate: TARGET_RPM,
|
||||
timeUnit: '1m',
|
||||
duration: `${DURATION_S}s`,
|
||||
preAllocatedVUs: 20,
|
||||
maxVUs: 40,
|
||||
},
|
||||
},
|
||||
thresholds: {
|
||||
// Прагматичные пороги. p95 на dev-stack обычно < 1.5с для signup
|
||||
// (создание Organization + User + Employee + Store + RetailPoint).
|
||||
http_req_duration: ['p(95)<3000', 'p(99)<6000'],
|
||||
// 429 — допустимо, но не должно быть >50% (тогда тест не информативен).
|
||||
signup_rate_limited: ['rate<0.7'],
|
||||
},
|
||||
};
|
||||
|
||||
export default function () {
|
||||
const id = `${__VU}-${__ITER}-${Date.now()}`;
|
||||
const email = `load-signup-${id}@example.kz`;
|
||||
const payload = JSON.stringify({
|
||||
email,
|
||||
password: 'Passw0rd!',
|
||||
organizationName: `LoadOrg-${id}`,
|
||||
phone: '+77001234567',
|
||||
plan: null,
|
||||
});
|
||||
|
||||
const t0 = Date.now();
|
||||
const res = http.post(`${BASE_URL}/api/auth/signup`, payload, {
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
tags: { name: 'signup' },
|
||||
});
|
||||
signupTrend.add(Date.now() - t0);
|
||||
signup429.add(res.status === 429);
|
||||
|
||||
check(res, {
|
||||
'status is 2xx or 429': (r) => r.status >= 200 && r.status < 300 || r.status === 429,
|
||||
});
|
||||
}
|
||||
158
tests/stage-smoke.sh
Executable file
158
tests/stage-smoke.sh
Executable file
|
|
@ -0,0 +1,158 @@
|
|||
#!/usr/bin/env bash
|
||||
# stage-smoke.sh — быстрый smoke-suite для stage-verify CI.
|
||||
#
|
||||
# Что проверяется:
|
||||
# 1. /health/ready → 200, status=Healthy.
|
||||
# 2. Signup tenant A → 2xx.
|
||||
# 3. Token tenant A → access_token.
|
||||
# 4. Multi-tenant: signup tenant B, проверка что products tenant'а A
|
||||
# НЕ видны под токеном tenant'а B (изоляция).
|
||||
# 5. Один полный документ-цикл tenant'а A:
|
||||
# create product → create supplier → create supply → post supply
|
||||
# → проверка остатка > 0 → create retail sale → post retail sale
|
||||
# → 204.
|
||||
#
|
||||
# Зависит от: curl, jq, python3 (для генерации UUID barcode).
|
||||
# Запуск: BASE_URL=https://test.admin.food-market.kz bash tests/stage-smoke.sh
|
||||
# Без BASE_URL — http://localhost:5081.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
BASE_URL="${BASE_URL:-http://localhost:5081}"
|
||||
SLUG="smoke-$(date +%s)-$RANDOM"
|
||||
|
||||
log() { echo "[$(date -Is)] $*"; }
|
||||
fail() { echo "[FAIL] $*" >&2; exit 1; }
|
||||
|
||||
curl_json() {
|
||||
# curl_json METHOD URL [BODY] [TOKEN]
|
||||
local method="$1" url="$2" body="${3:-}" token="${4:-}"
|
||||
local args=(-sS -X "$method" -w '\n%{http_code}' -H 'Content-Type: application/json')
|
||||
[ -n "$token" ] && args+=(-H "Authorization: Bearer $token")
|
||||
[ -n "$body" ] && args+=(-d "$body")
|
||||
curl "${args[@]}" "$url"
|
||||
}
|
||||
|
||||
# Возвращает HTTP-код из последней строки curl_json
|
||||
last_status() { echo "$1" | tail -n1; }
|
||||
body_only() { echo "$1" | sed '$d'; }
|
||||
|
||||
# ── 1. /health/ready ──────────────────────────────────────────────────
|
||||
log "[1/5] /health/ready"
|
||||
if ! curl -fsS "$BASE_URL/health/ready" | jq -e '.status == "Healthy"' > /dev/null; then
|
||||
fail "/health/ready вернул не Healthy"
|
||||
fi
|
||||
|
||||
# ── 2. Signup tenant A ────────────────────────────────────────────────
|
||||
log "[2/5] signup tenant A"
|
||||
EMAIL_A="$SLUG-a@example.kz"
|
||||
PASSWORD="Passw0rd!"
|
||||
RES=$(curl_json POST "$BASE_URL/api/auth/signup" \
|
||||
"{\"email\":\"$EMAIL_A\",\"password\":\"$PASSWORD\",\"organizationName\":\"SmokeOrgA-$SLUG\",\"phone\":\"+77001234567\"}")
|
||||
[ "$(last_status "$RES")" = "200" ] || fail "signup A: $(last_status "$RES") body=$(body_only "$RES")"
|
||||
|
||||
# ── 3. Token tenant A ─────────────────────────────────────────────────
|
||||
log "[3/5] token tenant A"
|
||||
TOKEN_A=$(curl -sSf -X POST "$BASE_URL/connect/token" \
|
||||
-d "grant_type=password&username=$EMAIL_A&password=$PASSWORD&client_id=food-market-web&scope=openid profile email roles api offline_access" \
|
||||
| jq -r .access_token)
|
||||
[ -n "$TOKEN_A" ] && [ "$TOKEN_A" != "null" ] || fail "token A пустой"
|
||||
|
||||
# ── 4. Multi-tenant: tenant B не видит product tenant'а A ────────────
|
||||
log "[4/5] multi-tenant isolation"
|
||||
# Tenant A создаёт продукт
|
||||
UNIT_ID=$(curl -sSf -H "Authorization: Bearer $TOKEN_A" "$BASE_URL/api/catalog/units-of-measure?pageSize=200" \
|
||||
| jq -r '.items[] | select(.code=="796") | .id')
|
||||
GROUP_ID=$(curl -sSf -H "Authorization: Bearer $TOKEN_A" "$BASE_URL/api/catalog/product-groups" \
|
||||
| jq -r '.items[0].id')
|
||||
PT_ID=$(curl -sSf -H "Authorization: Bearer $TOKEN_A" "$BASE_URL/api/catalog/price-types" \
|
||||
| jq -r '.items[] | select(.isRetail) | .id')
|
||||
CUR_ID=$(curl -sSf -H "Authorization: Bearer $TOKEN_A" "$BASE_URL/api/catalog/currencies" \
|
||||
| jq -r '.items[] | select(.code=="KZT") | .id')
|
||||
STORE_ID=$(curl -sSf -H "Authorization: Bearer $TOKEN_A" "$BASE_URL/api/catalog/stores" \
|
||||
| jq -r '.items[] | select(.isMain) | .id')
|
||||
|
||||
PRODUCT_NAME="SmokeProd-$SLUG"
|
||||
BARCODE=$(python3 -c "import random; print(''.join([str(random.randint(0,9)) for _ in range(13)]))")
|
||||
PRODUCT_BODY=$(jq -nc \
|
||||
--arg name "$PRODUCT_NAME" --arg art "ART-$SLUG" --arg unit "$UNIT_ID" --arg group "$GROUP_ID" \
|
||||
--arg pt "$PT_ID" --arg cur "$CUR_ID" --arg bc "$BARCODE" \
|
||||
'{name:$name, article:$art, unitOfMeasureId:$unit, vat:12, vatEnabled:true,
|
||||
productGroupId:$group, packaging:1,
|
||||
prices:[{priceTypeId:$pt, amount:100, currencyId:$cur}],
|
||||
barcodes:[{code:$bc, type:1, isPrimary:true}]}')
|
||||
PROD_RES=$(curl -sSf -X POST -H "Authorization: Bearer $TOKEN_A" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d "$PRODUCT_BODY" "$BASE_URL/api/catalog/products")
|
||||
PRODUCT_ID=$(echo "$PROD_RES" | jq -r .id)
|
||||
[ -n "$PRODUCT_ID" ] && [ "$PRODUCT_ID" != "null" ] || fail "product create A failed: $PROD_RES"
|
||||
|
||||
# Tenant B регистрируется и забирает токен
|
||||
EMAIL_B="$SLUG-b@example.kz"
|
||||
curl -sSf -X POST -H 'Content-Type: application/json' \
|
||||
-d "{\"email\":\"$EMAIL_B\",\"password\":\"$PASSWORD\",\"organizationName\":\"SmokeOrgB-$SLUG\",\"phone\":\"+77001234568\"}" \
|
||||
"$BASE_URL/api/auth/signup" > /dev/null
|
||||
TOKEN_B=$(curl -sSf -X POST "$BASE_URL/connect/token" \
|
||||
-d "grant_type=password&username=$EMAIL_B&password=$PASSWORD&client_id=food-market-web&scope=openid profile email roles api offline_access" \
|
||||
| jq -r .access_token)
|
||||
|
||||
# Tenant B пытается прочитать конкретный продукт A — должен получить 404
|
||||
B_GET_STATUS=$(curl -sS -o /dev/null -w '%{http_code}' \
|
||||
-H "Authorization: Bearer $TOKEN_B" "$BASE_URL/api/catalog/products/$PRODUCT_ID")
|
||||
[ "$B_GET_STATUS" = "404" ] || fail "🔴 multi-tenant LEAK: B видит product A ($B_GET_STATUS)"
|
||||
# Tenant B запрашивает список — продукт A не должен быть в списке
|
||||
B_LIST=$(curl -sSf -H "Authorization: Bearer $TOKEN_B" "$BASE_URL/api/catalog/products?pageSize=500")
|
||||
B_HAS_A=$(echo "$B_LIST" | jq --arg name "$PRODUCT_NAME" 'any(.items[]; .name == $name)')
|
||||
[ "$B_HAS_A" = "false" ] || fail "🔴 multi-tenant LEAK: B видит product A в списке"
|
||||
log " isolation OK"
|
||||
|
||||
# ── 5. Полный документ-цикл tenant'а A ────────────────────────────────
|
||||
log "[5/5] supply + retail sale цикл"
|
||||
|
||||
# Supplier
|
||||
SUP_ID=$(curl -sSf -X POST -H "Authorization: Bearer $TOKEN_A" -H 'Content-Type: application/json' \
|
||||
-d '{"name":"SmokeSupplier","type":2}' \
|
||||
"$BASE_URL/api/catalog/counterparties" | jq -r .id)
|
||||
|
||||
# Supply
|
||||
SUPPLY_BODY=$(jq -nc \
|
||||
--arg sup "$SUP_ID" --arg store "$STORE_ID" --arg cur "$CUR_ID" --arg prod "$PRODUCT_ID" \
|
||||
--arg date "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
|
||||
'{date:$date, supplierId:$sup, storeId:$store, currencyId:$cur,
|
||||
lines:[{productId:$prod, quantity:100, unitPrice:50}]}')
|
||||
SUPPLY_ID=$(curl -sSf -X POST -H "Authorization: Bearer $TOKEN_A" -H 'Content-Type: application/json' \
|
||||
-d "$SUPPLY_BODY" "$BASE_URL/api/purchases/supplies" | jq -r .id)
|
||||
SUPPLY_POST=$(curl -sS -o /dev/null -w '%{http_code}' -X POST \
|
||||
-H "Authorization: Bearer $TOKEN_A" "$BASE_URL/api/purchases/supplies/$SUPPLY_ID/post")
|
||||
[ "$SUPPLY_POST" = "204" ] || fail "supply post: $SUPPLY_POST"
|
||||
|
||||
# Stock check (должен стать 100)
|
||||
STOCK=$(curl -sSf -H "Authorization: Bearer $TOKEN_A" \
|
||||
"$BASE_URL/api/inventory/stock?productId=$PRODUCT_ID&pageSize=10" \
|
||||
| jq -r --arg p "$PRODUCT_ID" '.items[] | select(.productId==$p) | .quantity')
|
||||
# .quantity приходит как "100.0000" (precision 18,4) — сравниваем численно
|
||||
awk -v s="$STOCK" 'BEGIN{exit !(s+0 == 100)}' || fail "stock после supply: ожидали 100, получили '$STOCK'"
|
||||
|
||||
# Retail sale
|
||||
RP_ID=$(curl -sSf -H "Authorization: Bearer $TOKEN_A" "$BASE_URL/api/catalog/retail-points" \
|
||||
| jq -r '.items[0].id')
|
||||
SALE_BODY=$(jq -nc \
|
||||
--arg store "$STORE_ID" --arg rp "$RP_ID" --arg cur "$CUR_ID" --arg prod "$PRODUCT_ID" \
|
||||
--arg date "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
|
||||
'{date:$date, storeId:$store, retailPointId:$rp, customerId:null, currencyId:$cur,
|
||||
payment:0, isReturn:false,
|
||||
lines:[{productId:$prod, quantity:1, unitPrice:100, discount:0, vatPercent:12}],
|
||||
subtotal:100, discountTotal:0, total:100, paidCash:100, paidCard:0, notes:"smoke"}')
|
||||
SALE_ID=$(curl -sSf -X POST -H "Authorization: Bearer $TOKEN_A" -H 'Content-Type: application/json' \
|
||||
-d "$SALE_BODY" "$BASE_URL/api/sales/retail" | jq -r .id)
|
||||
SALE_POST=$(curl -sS -o /dev/null -w '%{http_code}' -X POST \
|
||||
-H "Authorization: Bearer $TOKEN_A" "$BASE_URL/api/sales/retail/$SALE_ID/post")
|
||||
[ "$SALE_POST" = "204" ] || fail "retail-sale post: $SALE_POST"
|
||||
|
||||
# Stock после продажи должен стать 99
|
||||
STOCK_AFTER=$(curl -sSf -H "Authorization: Bearer $TOKEN_A" \
|
||||
"$BASE_URL/api/inventory/stock?productId=$PRODUCT_ID&pageSize=10" \
|
||||
| jq -r --arg p "$PRODUCT_ID" '.items[] | select(.productId==$p) | .quantity')
|
||||
awk -v s="$STOCK_AFTER" 'BEGIN{exit !(s+0 == 99)}' || fail "stock после sale: ожидали 99, получили '$STOCK_AFTER'"
|
||||
|
||||
log "✅ smoke OK ($SLUG)"
|
||||
Loading…
Reference in a new issue