lekss361/gendesign

Fork 0

docs(ptica): две докстроки обещали то, чего в коде нет (#2464) #3002

Merged

bot-backend merged 1 commit from fix/2464-two-docstrings into main

2026-08-20 19:08:33 +00:00

bot-backend commented

2026-08-20 18:44:40 +00:00

Collaborator

Два расхождения документации с кодом одним PR — тот же класс, что #2968.

1. `QuarterDump` (nspd_client)

Докстрока класса:

Default = только core, чтобы не сжигать rate-limit на 17 запросов.

Фактическая сигнатура, 600 строк ниже:

def search_by_quarter(self, quarter_cad, *, include_zouit: bool = True, ...)

Неверно вдвойне:

дефолт — include_zouit=True, 5 ЗОУИТ-слоёв входят в дефолтный вызов;
число — territorial_zones / red_lines / engineering и все ЗОУИТ идут через grid-walk при grid_n=7, то есть по 49 запросов каждый. Дефолтный дамп — сотни запросов, а не 17. Экономит rate-limit только include_risks=False.

Докстрока самого метода при этом говорит верно: «Default True». Правильный образец лежал рядом с дефектом — как и в нескольких других находках этого эпика.

2. `find_active_on_demand_job` (cadastre_fetch)

Если в БД есть FAILED on-demand за последние 60 секунд — тоже None (чтобы повторно пробовать).

В запросе нет ни слова failed, ни какого-либо временного фильтра:

WHERE j.source_kind = :src
  AND j.status IN ('queued', 'running', 'paused')

Обещание вдвойне вредно: оно подразумевало, что неуспешная джоба старше минуты вернётся как активная (не вернётся), и отправляло отлаживающего искать окно, которого нет.

Гейты сверяют утверждение с кодом

Не читаемость текста, а согласованность:

обещание «только core» → требует include_zouit=False в сигнатуре;
обещание минутного окна → требует временного фильтра в теле функции.

Два подводных камня, на которые я наступил — и оставил от них защиту

Гейт по тексту не отличает цитату от утверждения. Первая редакция докстрок цитировала старые обещания, чтобы объяснить, что именно было не так, — и гейты покраснели на моём же объяснении. Формулировки пересказаны, а не процитированы; это оговорено прямо в тексте докстроки, чтобы следующий не повторил.

Тело функции нельзя брать как последний кусок разбиения по тройным кавычкам. SQL внутри сам обёрнут в них, поэтому «тело» оказывалось огрызком после запроса, и один гейт проходил по случайности. Вынесен хелпер _body, отбрасывающий ровно первую докстроку.

Как проверено

Двусторонне: против origin/main три гейта красные с конкретными сообщениями («докстрока QuarterDump обещает «Default = только core», а include_zouit по умолчанию True»; «в докстроке осталось число 17»; «докстрока обещает окно «за последние 60 секунд», а в SQL нет ни временного фильтра, ни статуса failed»).
Контроли зелёные с обеих сторон: характеризующий фиксирует фактические три статуса в SQL; test_docstrings_state_the_actual_behaviour ловит «починку» через вычёркивание неудобной фразы — молчание читается как «всё хорошо».
pytest backend/tests/services/ — 3199 passed, 14 skipped.

Часть эпика #2464.

Два расхождения документации с кодом одним PR — тот же класс, что #2968. ## 1. `QuarterDump` (nspd_client) Докстрока класса: > Default = только core, чтобы не сжигать rate-limit на **17 запросов**. Фактическая сигнатура, 600 строк ниже: ```python def search_by_quarter(self, quarter_cad, *, include_zouit: bool = True, ...) ``` Неверно вдвойне: - **дефолт** — `include_zouit=True`, 5 ЗОУИТ-слоёв входят в дефолтный вызов; - **число** — `territorial_zones` / `red_lines` / `engineering` и все ЗОУИТ идут через grid-walk при `grid_n=7`, то есть по **49 запросов каждый**. Дефолтный дамп — сотни запросов, а не 17. Экономит rate-limit только `include_risks=False`. Докстрока самого метода при этом говорит верно: «Default True». Правильный образец лежал рядом с дефектом — как и в нескольких других находках этого эпика. ## 2. `find_active_on_demand_job` (cadastre_fetch) > Если в БД есть FAILED on-demand **за последние 60 секунд** — тоже None (чтобы повторно пробовать). В запросе нет ни слова `failed`, ни какого-либо временного фильтра: ```sql WHERE j.source_kind = :src AND j.status IN ('queued', 'running', 'paused') ``` Обещание вдвойне вредно: оно подразумевало, что неуспешная джоба **старше** минуты вернётся как активная (не вернётся), и отправляло отлаживающего искать окно, которого нет. ## Гейты сверяют утверждение с кодом Не читаемость текста, а согласованность: - обещание «только core» → требует `include_zouit=False` в сигнатуре; - обещание минутного окна → требует временного фильтра в теле функции. ## Два подводных камня, на которые я наступил — и оставил от них защиту **Гейт по тексту не отличает цитату от утверждения.** Первая редакция докстрок цитировала старые обещания, чтобы объяснить, что именно было не так, — и гейты покраснели на моём же объяснении. Формулировки пересказаны, а не процитированы; это оговорено прямо в тексте докстроки, чтобы следующий не повторил. **Тело функции нельзя брать как последний кусок разбиения по тройным кавычкам.** SQL внутри сам обёрнут в них, поэтому «тело» оказывалось огрызком после запроса, и один гейт проходил **по случайности**. Вынесен хелпер `_body`, отбрасывающий ровно первую докстроку. ## Как проверено - **Двусторонне:** против `origin/main` три гейта красные с конкретными сообщениями («докстрока QuarterDump обещает «Default = только core», а include_zouit по умолчанию True»; «в докстроке осталось число 17»; «докстрока обещает окно «за последние 60 секунд», а в SQL нет ни временного фильтра, ни статуса failed»). - **Контроли зелёные с обеих сторон:** характеризующий фиксирует фактические три статуса в SQL; `test_docstrings_state_the_actual_behaviour` ловит «починку» через вычёркивание неудобной фразы — молчание читается как «всё хорошо». - `pytest backend/tests/services/` — 3199 passed, 14 skipped. Часть эпика #2464.

bot-backend added 1 commit 2026-08-20 18:44:41 +00:00

docs(ptica): две докстроки обещали то, чего в коде нет (#2464 )

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

Details

CI / changes (pull_request) Successful in 9s

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 2m4s

Details

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

Details

c3c8674b3c

1. `QuarterDump` (nspd_client): «Default = только core, чтобы не сжигать
rate-limit на 17 запросов». Фактический дефолт `search_by_quarter` —
`include_zouit=True`, то есть 5 ЗОУИТ-слоёв входят в дефолтный вызов.
Числа 17 тоже нет: territorial_zones/red_lines/engineering и все ЗОУИТ
идут через grid-walk при grid_n=7, по 49 запросов КАЖДЫЙ — дефолтный
дамп это сотни запросов. Экономит rate-limit только include_risks=False.
Докстрока самого метода 640 строками ниже говорит верно («Default
True») — правильный образец лежал рядом с дефектом.

2. `find_active_on_demand_job` (cadastre_fetch): «Если в БД есть FAILED
on-demand за последние 60 секунд — тоже None». В SQL нет ни слова
'failed', ни какого-либо временного фильтра. Обещание вдвойне вредно:
подразумевало, что неуспешная джоба СТАРШЕ минуты вернётся как
активная (не вернётся), и отправляло отлаживающего искать окно,
которого нет.

Гейты сверяют утверждение докстроки с кодом, а не читаемость текста:
обещание «только core» требует `include_zouit=False` в сигнатуре;
обещание минутного окна требует временного фильтра в теле.

Двусторонне: против origin/main три гейта красные с конкретными
сообщениями. Контроли зелёные с обеих сторон — характеризующий фиксирует
фактические три статуса в SQL, а test_docstrings_state_the_actual_behaviour
ловит «починку» через вычёркивание неудобной фразы.

Два подводных камня, на которые наступил и оставил защиту:
- гейт ищет обещание по тексту, поэтому старые формулировки в докстроках
ПЕРЕСКАЗАНЫ, а не процитированы — иначе он не отличает цитату от
утверждения (оговорено прямо в тексте докстроки);
- тело функции нельзя брать как последний кусок разбиения по тройным
кавычкам: SQL сам в них обёрнут, и проверка шла бы по огрызку после
запроса. Из-за этого один гейт проходил по случайности. Вынесен
хелпер `_body`.

pytest backend/tests/services/ — 3199 passed.

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