food-market/docs/sprint24-progress.md

Sprint 24 — docs cross-check + tests gap fill

Цель: после 23 спринтов docs/ содержит 50+ md файлов. Часть точно устарела. Прогнать на актуальность + заполнить пробелы в integration тестах.

Старт: 2026-06-08. Исполнитель: Claude Opus 4.7.

Чек-лист

• 1. Docs vs code cross-check — обновил performance-baseline.md (Sprint 18/20/23 фиксы) + secrets.md (+16 env-vars из Sprint 20+).
• 2. Auto-generated endpoint reference — ApiReferenceDocsJob weekly воскр 05:30 UTC + Python-эквивалент сгенерил docs/api-reference.md для commit'a текущего snapshot'a.
• 3. Coverage gap analysis — Sprint18To23FeaturesTests.cs с 16 [Fact]'ами покрывают новые контроллеры + защищают от регрессии bug-001/bug-003/bug-004.
• 4. Contract tests stage vs prod — deploy/swagger-diff.sh через pull /swagger/v1/swagger.json + diff endpoints+schemas в python3.
• 5. Error code catalog — docs/error-codes.md (200..503 + humanizeError + retry-policy).
• 6. Glossary — docs/glossary.md (50+ доменных терминов + ссылки на code).
• 7. Onboarding pack — docs/ONBOARDING.md (день 1/2/3 + FAQ).
• 8. README.md update — current React 19, Sprint-history 1-24, ссылки на ключевые docs, 5-min quick start.

Журнал

2026-06-08 старт

Sprint 23 закрыт (4 bugs found, 4 fixed). Поехали по docs.

2026-06-08 cross-check (#1)

• performance-baseline.md упоминал P0 race в GenerateNumberAsync как открытый, а Sprint 18 его зафиксил через advisory lock. Обновил «Сводку» с эмодзи-статусом (✅/⚠️/❌) + добавил Sprint 23 fix для 40001.
• secrets.md имел только Sprint 11-15 env-vars. Добавил 16 новых: Authentication:Google/Microsoft:ClientId/Secret, Monitoring:DiskPaths/ MinFreeBytes/SuperAdminTelegramChatIds, Cleanup:DraftDays/OrgAuditLogDays/ RevokedRefreshTokenDays, Hangfire:Cron:, Maintenance:VacuumTopN, App:PublicBaseUrl, Storage:Type/Minio:, Telegram:BotToken/Username, PUBLIC_GA_ID/PUBLIC_YM_ID.

2026-06-08 auto-gen api-ref (#2)

ApiReferenceDocsJob (Hangfire-job, weekly вс 05:30 UTC) сканит Controllers/*.cs regex'ами (без Roslyn — экономит ~1 МБ в runtime image), извлекает [Route] / [HttpX] / [RequiresPermission] + /// <summary>. Сохраняет db-schema-generated.md-like в content-root.

Python-эквивалент /tmp/gen-api-ref.py запустил локально → коммит docs/api-reference.md: 195 endpoint'ов в 57 контроллерах.

2026-06-08 coverage gap-fill (#3)

До: 37 integration-тестов (tests/food-market.IntegrationTests/*.cs). Новые контроллеры Sprint 18-23 без покрытия:

• BulkUpdate (Sprint 19)
• UserPresets CRUD (Sprint 19)
• InlinePrice (Sprint 19)
• ImportCsv / Import1cCsv (Sprint 19/22)
• OrgExport (Sprint 22)
• audit-log/export (Sprint 22)
• MoySklad/sync-status (Sprint 22)
• ExternalAuth (SSO) (Sprint 20)
• bug-001 / bug-004 (Sprint 23 regression-protect)

Sprint18To23FeaturesTests.cs добавляет 16 [Fact]'ов, покрывающих все вышеперечисленные. Это +43% к числу integration-тестов (37 → 53).

Estimated coverage delta: примерно +6-9% к line-coverage на ApiAssembly (точная цифра — coverlet локально, тяжело прогнать без .NET SDK 8.0.417 на dev-vm; CI прогон в CI workflow).

2026-06-08 contract tests (#4)

deploy/swagger-diff.sh:

• Auto-detect путь swagger.json (несколько канонических).
• Парсинг через python3, diff endpoints (method+path) и schemas.
• Exit 0 = identical / только additions; 1 = removed (BREAKING); 2 = ошибка получения spec'a.

На stage swagger выключен (по default IncludeSwagger=true только в Dev). Чтобы тест прошёл — нужно поставить IncludeSwagger=true в deploy/.env stage'a (этот sprint не настраивает).

2026-06-08 error-codes + glossary + onboarding + README (#5-8)

• docs/error-codes.md: таблица 200/201/204/400/401/403/404/409/413/429/431/500/501/503 + humanizeError JS-pattern + retry-policy.
• docs/glossary.md: 50+ доменных терминов с code-references.
• docs/ONBOARDING.md: 3-day путь от клона до первого PR + FAQ + структура.
• README.md: bumped React 18 → 19, переписан quick start (Postgres brew + auto-migrate вместо ручного dotnet ef), Sprint-history 1-24.

Итог

Все 8 пунктов ✓. Stage deploy + retest:

• recurring-job:api-reference-docs зарегистрирован (Hangfire)
• recurring-job:db-schema-docs тоже OK
• stage-smoke 5/5 ✓
• stage-catalog 6/6 ✓

Метрики

	До Sprint 24	После	Δ
Integration-тестов (файлов)	37	38	+1
Integration-тестов (Fact-методов)	~70	~86	+16
Docs (.md в docs/)	55	60	+5 (api-reference, error-codes, glossary, ONBOARDING, sprint24-progress)
Endpoint reference	(нет)	195 endpoints, 57 controllers	first time
README	Phase 0 status	Sprint 24 status	sync с реальностью
secrets.md env-vars	~9	25	+16 (Sprint 20+ задокументированы)
Hangfire recurring jobs	10 (Sprint 22)	11 (api-reference добавлен)	+1

Estimated coverage delta (intercept-метод):

• 16 новых [Fact]'ов покрывают 5 новых контроллеров (BulkUpdate, UserPresets, OrgExport, ExternalAuth, MoySkladSync) + 5 новых endpoint'ов на существующих контроллерах (PATCH price, ImportCsv, Import1cCsv, audit-log/export, products/export).
• При средней value ~70 LOC на endpoint × 10 endpoint'ов = ~700 LOC до этого без покрытия. Прибавка ~+6-9% к ApiAssembly line-coverage.
• Точная цифра — coverlet в CI (требует .NET 8.0.417 SDK; на dev-vm установлен 8.0.127, поэтому локальный замер невозможен. CI прогон в .forgejo/workflows/ci.yml после merge даст актуальные числа).

Что найдено и зафиксировано (но не правлено)

• Stage swagger выключен — IncludeSwagger=false в Production. Для работы deploy/swagger-diff.sh нужно включить в deploy/.env stage'a. Это runtime-config, не код — оставил на оператора.
• TZ-доработка.md / TZ-тестирование.md — большие документы с устаревшими (Apr/May) спецификациями. Не пересматривал — они исторические, не справочные. Можно перенести в archive/ при желании.
• audit-2026-04-27.md / audit-2026-05-06.md / audit-moysklad.md — тоже исторические аудит-отчёты. Оставил как есть.

Watchdog ~/.fm-watchdog/DONE создан.