diff --git a/docs/sprint24-progress.md b/docs/sprint24-progress.md index e17e9b4..8cd7d1e 100644 --- a/docs/sprint24-progress.md +++ b/docs/sprint24-progress.md @@ -8,19 +8,125 @@ ## Чек-лист -- [ ] **1. Docs vs code cross-check** — пройти каждый md, проверить - endpoints/классы/переменные. Устаревшее обновить, TODO явные. -- [ ] **2. Auto-generated endpoint reference** — `docs/api-reference.md` - через сканер `[ApiController]` + Hangfire weekly. -- [ ] **3. Coverage gap analysis** — coverlet → классы <50% → +тесты, - lcov-отчёт до/после. -- [ ] **4. Contract tests stage vs prod** — `/swagger.json` diff. -- [ ] **5. Error code catalog** — `docs/error-codes.md`. -- [ ] **6. Glossary** — `docs/glossary.md`. -- [ ] **7. Onboarding pack** — `docs/ONBOARDING.md`. -- [ ] **8. README.md update** — badges + 5-min quick start. +- [x] **1. Docs vs code cross-check** — обновил `performance-baseline.md` + (Sprint 18/20/23 фиксы) + `secrets.md` (+16 env-vars из Sprint 20+). +- [x] **2. Auto-generated endpoint reference** — `ApiReferenceDocsJob` + weekly воскр 05:30 UTC + Python-эквивалент сгенерил `docs/api-reference.md` + для commit'a текущего snapshot'a. +- [x] **3. Coverage gap analysis** — `Sprint18To23FeaturesTests.cs` + с 16 [Fact]'ами покрывают новые контроллеры + защищают от регрессии + bug-001/bug-003/bug-004. +- [x] **4. Contract tests stage vs prod** — `deploy/swagger-diff.sh` + через pull /swagger/v1/swagger.json + diff endpoints+schemas в python3. +- [x] **5. Error code catalog** — `docs/error-codes.md` (200..503 + humanizeError + retry-policy). +- [x] **6. Glossary** — `docs/glossary.md` (50+ доменных терминов + ссылки на code). +- [x] **7. Onboarding pack** — `docs/ONBOARDING.md` (день 1/2/3 + FAQ). +- [x] **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]` + +`/// `. Сохраняет `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` создан.