lekss361/gendesign

Fork 0

docs(ptica): шесть мест, где документация расходилась с кодом (#2464) #2968

Merged

bot-backend merged 1 commit from fix/2464-docs-vs-code into main

2026-08-20 10:25:23 +00:00

bot-backend commented

2026-08-20 10:02:50 +00:00

Collaborator

Шесть пунктов эпика #2464 про расхождение документации с кодом. Каждый проверен против кода или прод-данных, а не переписан по впечатлению.

1. `macro_coefficient.py:99` — сумма backed-весов

Комментарий обещал 0.45. С #946 inflation стал backed-каналом с весом 0.08:

0.18 + 0.12 + 0.10 + 0.05 + 0.08 = 0.53

Сумму тогда не обновили.

2–3. `macro_series.py:305`, `sales_series.py:496` — недостижимое поведение

Оба обещали пустой результат «при months_back < 0». Код клампит через max(0, months_back), поэтому сетка всегда содержит текущий месяц. Проверено прогоном:

months_back=-5 → сетка из 1 месяца
months_back=-1 → сетка из 1 месяца

Документировалось поведение, которого нет.

4. `analytics_queries._velocity_baseline` — ложное про словарь районов

Утверждалось: objective_corpus_room_month.district matches domrf_kn_objects.district_name. Соседний _elasticity_coef описывает ту же колонку правильно — это МИКРО-вокабуляр.

Замер прода:

district (микро)      Академический, ВИЗ, Юго-Западный, Уктус, Втузгородок, …
district_name (админ) Академический, Чкаловский, Верх-Исетский, Ленинский, …

Из 8 админ-имён в микро-колонке встречаются 4, и с заметно меньшим объёмом: Ленинский 55 точек против 621 у Академического, Чкаловский и Верх-Исетский — ноль. Вызывающий передаёт сюда именно админ-имя.

Резолв admin→micros здесь не делаю — это отдельная задача с изменением живых показателей. Docstring лишь перестаёт утверждать обратное.

5. `nspd_denorm.denorm_dump` — контракт транзакции

Docstring: «Caller отвечает за commit/close». Код на строке 373 вызывает db.commit() сам. Вызывающий, понадеявшийся обернуть это в свою транзакцию, получил бы уже зафиксированные строки.

6. `nspd_client.search_by_quarter` — смета запросов занижена в 25–42 раза

	docstring	фактически
core	6 запросов / ~3.6 с	150 / ~90 с
+ЗОУИТ	11 / ~6.6 с	395 / ~237 с
всё	22 / ~13 с	934 / ~560 с

Три из пяти core-слоёв (territorial_zones, red_lines, engineering_structures) и все zouit/risk идут get_features_in_bbox_grid при grid_n=7 — по 49 запросов каждый.

Это не безобидно: по оценке «22 запроса, 13 секунд» слои включают не задумываясь, а объём запросов здесь — прямой фактор WAF-риска. Ср. #2956, где НСПД сейчас отдаёт 403 на IP VPS.

Гейт на два проверяемых числа

Прозаические пункты гейтом не закроешь, а два числа — да. test_2464_docs_match_code.py сверяет написанное с вычисленным из констант.

мутация	результат
вернуть `0.45` в комментарий	1 failed
изменить вес канала, не тронув комментарий	1 failed
вернуть `6/11/22` в смету	1 failed
контроль	3 passed, rc=0

Плюс контроль на сам гейт: если _GRID_WALK_LAYERS опустеет, расчёт совпал бы с любой мелкой цифрой тавтологически — тест это ловит.

Прогоны

tests/services   3116 passed   rc=0

Шесть пунктов эпика #2464 про расхождение документации с кодом. Каждый **проверен** против кода или прод-данных, а не переписан по впечатлению. ## 1. `macro_coefficient.py:99` — сумма backed-весов Комментарий обещал `0.45`. С #946 `inflation` стал backed-каналом с весом 0.08: ``` 0.18 + 0.12 + 0.10 + 0.05 + 0.08 = 0.53 ``` Сумму тогда не обновили. ## 2–3. `macro_series.py:305`, `sales_series.py:496` — недостижимое поведение Оба обещали пустой результат «при `months_back < 0`». Код клампит через `max(0, months_back)`, поэтому сетка всегда содержит текущий месяц. Проверено прогоном: ``` months_back=-5 → сетка из 1 месяца months_back=-1 → сетка из 1 месяца ``` Документировалось поведение, которого нет. ## 4. `analytics_queries._velocity_baseline` — ложное про словарь районов Утверждалось: `objective_corpus_room_month.district` **matches** `domrf_kn_objects.district_name`. Соседний `_elasticity_coef` описывает ту же колонку правильно — это МИКРО-вокабуляр. Замер прода: ``` district (микро) Академический, ВИЗ, Юго-Западный, Уктус, Втузгородок, … district_name (админ) Академический, Чкаловский, Верх-Исетский, Ленинский, … ``` Из 8 админ-имён в микро-колонке встречаются 4, и с заметно меньшим объёмом: Ленинский 55 точек против 621 у Академического, Чкаловский и Верх-Исетский — ноль. Вызывающий передаёт сюда именно **админ-имя**. Резолв admin→micros здесь **не делаю** — это отдельная задача с изменением живых показателей. Docstring лишь перестаёт утверждать обратное. ## 5. `nspd_denorm.denorm_dump` — контракт транзакции Docstring: «Caller отвечает за commit/close». Код на строке 373 вызывает `db.commit()` сам. Вызывающий, понадеявшийся обернуть это в свою транзакцию, получил бы уже зафиксированные строки. ## 6. `nspd_client.search_by_quarter` — смета запросов занижена в 25–42 раза | | docstring | фактически | |---|---|---| | core | 6 запросов / ~3.6 с | **150 / ~90 с** | | +ЗОУИТ | 11 / ~6.6 с | **395 / ~237 с** | | всё | 22 / ~13 с | **934 / ~560 с** | Три из пяти core-слоёв (`territorial_zones`, `red_lines`, `engineering_structures`) и **все** zouit/risk идут `get_features_in_bbox_grid` при `grid_n=7` — по 49 запросов каждый. Это не безобидно: по оценке «22 запроса, 13 секунд» слои включают не задумываясь, а объём запросов здесь — прямой фактор WAF-риска. Ср. #2956, где НСПД сейчас отдаёт 403 на IP VPS. ## Гейт на два проверяемых числа Прозаические пункты гейтом не закроешь, а два числа — да. `test_2464_docs_match_code.py` сверяет **написанное** с **вычисленным из констант**. | мутация | результат | |---|---| | вернуть `0.45` в комментарий | 1 failed | | изменить вес канала, не тронув комментарий | 1 failed | | вернуть `6/11/22` в смету | 1 failed | | контроль | 3 passed, rc=0 | Плюс контроль на сам гейт: если `_GRID_WALK_LAYERS` опустеет, расчёт совпал бы с любой мелкой цифрой тавтологически — тест это ловит. ## Прогоны ``` tests/services 3116 passed rc=0 ```

bot-backend added 1 commit 2026-08-20 10:02:51 +00:00

docs(ptica): шесть мест, где документация расходилась с кодом (#2464 )

CI Trade-In / changes (pull_request) Successful in 8s

Details

CI / changes (pull_request) Successful in 10s

Details

CI Trade-In / backend-tests (pull_request) Has been skipped

Details

CI Trade-In / browser-tests (pull_request) Has been skipped

Details

CI Trade-In / frontend-checks (pull_request) Has been skipped

Details

CI / frontend-tests (pull_request) Has been skipped

Details

CI / openapi-codegen-check (pull_request) Successful in 1m53s

Details

CI / backend-tests (pull_request) Successful in 17m21s

Details

e7c79c9646

Каждое проверено против кода или прод-данных, а не переписано по впечатлению.

1. macro_coefficient:99 — «СУММА backed-весов = 0.45». С #946 inflation стал
   backed-каналом с весом 0.08: 0.18+0.12+0.10+0.05+0.08 = 0.53. Сумму не
   обновили.

2. macro_series:305 и 3. sales_series:496 — оба обещали пустой результат «при
   months_back < 0». Код клампит через max(0, months_back), поэтому сетка всегда
   содержит текущий месяц. Проверено прогоном: months_back=-5 → 1 месяц.
   Документировалось поведение, которого нет.

4. analytics_queries._velocity_baseline — «objective_corpus_room_month.district
   matches domrf_kn_objects.district_name». Неверно, и соседний _elasticity_coef
   описывает ту же колонку правильно (МИКРО-вокабуляр). Замер прода:

     district (микро)      Академический, ВИЗ, Юго-Западный, Уктус, Втузгородок…
     district_name (админ) Академический, Чкаловский, Верх-Исетский, Ленинский…

   Из 8 админ-имён в микро-колонке встречаются 4, и с меньшим объёмом (Ленинский
   55 точек против 621 у Академического; Чкаловский и Верх-Исетский — ноль).
   Вызывающий передаёт админ-имя. Резолв admin→micros тут НЕ делаю — это
   отдельная задача; docstring лишь перестаёт утверждать обратное.

5. nspd_denorm.denorm_dump — «Caller отвечает за commit/close», при том что
   функция сама вызывает db.commit() на 373. Вызывающий, понадеявшийся обернуть
   это в свою транзакцию, получил бы уже зафиксированные строки.

6. nspd_client.search_by_quarter — смета «6/11/22 запроса, ~3.6с/~6.6с/~13с».
   Фактически три из пяти core-слоёв и ВСЕ zouit/risk идут grid-walk'ом по 49
   запросов: 150/395/934 запроса, ~90с/~237с/~560с. Занижение в 25-42 раза, и
   это не безобидно: по такой оценке слои включают не задумываясь, а объём
   запросов здесь — прямой фактор WAF-риска (ср. #2956, где НСПД сейчас отдаёт
   403 на IP VPS).

Два из шести чисел проверяемы автоматически, и на них поставлен гейт: сумма
backed-весов сверяется с константами, смета запросов — с _GRID_WALK_LAYERS.
Мутационно проверен: вернуть 0.45 → красный, изменить вес канала не тронув
комментарий → красный, вернуть 6/11/22 → красный, контроль → 3 passed rc=0.
Плюс контроль на сам гейт: если _GRID_WALK_LAYERS опустеет, расчёт совпал бы с
любой мелкой цифрой тавтологически.

Прогоны: tests/services — 3116 passed rc=0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>