food-market/docs/sprint12-progress.md

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.

Чек-лист

• 1. docs/ARCHITECTURE.md — карта слоёв, модулей, потоков signup→bootstrap→операции. Реальные имена типов и путей, не маркетинг.
• 2. docs/MULTI-TENANCY.md — ITenantEntity + reflection query-filter, stamping в SaveChanges, SuperAdmin override (read-only + edit-mode с reason), 8 подводных камней (IgnoreQueryFilters, фоновые jobs без HttpContext, raw SQL, и т.д.).
• 3. docs/RUNBOOK.md — health-чеки, backup/restore (включая disaster-recovery), смена SDK, перенос на новый сервер, 6 описанных инцидентов (включая docker-compose project name из ТЗ), troubleshooting БД (stock-агрегат расхождения, audit-log размер, EFMigrationsHistory).
• 4. docs/DEVELOPER-GUIDE.md — локальный setup, запуск тестов, гочи integration-тестов (Ryuk, rate-limiter eager-config, один ApiFactory), полные паттерны: добавить controller с permission + добавить tenant-сущность с RowVersion + 5 шагов миграции, валидация (DataAnnotations / FluentValidation / бизнес), structured-логирование.
• 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 для следующего рефакторинга.
• 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).