(low) scenarios.py: module-docstring численно противоречит реализации _horizon_widen_factor #1376

New issue

Closed

opened 2026-06-14 18:09:57 +00:00 by bot-backend · 0 comments

bot-backend commented

2026-06-14 18:09:57 +00:00

Collaborator

Описание

Module-docstring утверждает: delta_eff(h) = base_delta × (1 + _HORIZON_WIDEN_PER_YEAR × h/12), и «на h=12 мес конверт = base_delta, на h=24 мес ≈ base_delta × (1 + 0.5×_HORIZON_WIDEN_PER_YEAR)». Фактическая формула _horizon_widen_factor = 1 + widen_per_year*(h/12) при widen_per_year=0.5 даёт: h=12 → 1.5 (а НЕ 1.0/base_delta), h=24 → 2.0 (а НЕ 1.25). Код самосогласован (функция-docstring строки 130 и комментарий у константы совпадают с кодом); ошибочен только module-level docstring. Это вводит в заблуждение при настройке/ревью конверта: реальный разброс сценариев на ближнем горизонте уже в 1.5× шире base_delta, а не равен ему.

Корень

Устаревший/неверный module-level docstring; формула в коде корректна и самосогласована.

Evidence

/Users/anton/Птица/gendesign/backend/app/services/forecasting/scenarios.py:27-33, 125-143

# module docstring (29-30):
# delta_eff(h) = base_delta × (1 + _HORIZON_WIDEN_PER_YEAR × h/12). На h=12 мес
# конверт = base_delta, на h=24 мес ≈ base_delta × (1 + 0.5×_HORIZON_WIDEN_PER_YEAR)

def _horizon_widen_factor(horizon_months, *, widen_per_year=_HORIZON_WIDEN_PER_YEAR):
    if horizon_months <= 0 or widen_per_year <= 0.0:
        return 1.0
    return 1.0 + widen_per_year * (horizon_months / 12.0)  # h=12 -> 1.5, не 1.0

Suggested fix

Исправить module docstring под фактическую формулу: на h=12 множитель = 1 + widen_per_year = 1.5; на h=24 = 1 + 2*widen_per_year = 2.0. Либо, если задумывался множитель ровно 1.0 на h=12, сменить нормировку на 1 + widen_per_year*((h-12)/12) — но это изменит поведение, сначала уточнить намерение.

Обоснование severity

Low: строго документационный дефект, runtime-поведение корректно. Пострадать может только разработчик, читающий module docstring для понимания параметризации.

week ревью 1 · multi-agent аудит 2026-06-14 · severity=low · category=correctness

Затронутые файлы:

/Users/anton/Птица/gendesign/backend/app/services/forecasting/scenarios.py

## Описание Module-docstring утверждает: `delta_eff(h) = base_delta × (1 + _HORIZON_WIDEN_PER_YEAR × h/12)`, и «на h=12 мес конверт = base_delta, на h=24 мес ≈ base_delta × (1 + 0.5×_HORIZON_WIDEN_PER_YEAR)». Фактическая формула `_horizon_widen_factor = 1 + widen_per_year*(h/12)` при `widen_per_year=0.5` даёт: h=12 → 1.5 (а НЕ 1.0/base_delta), h=24 → 2.0 (а НЕ 1.25). Код самосогласован (функция-docstring строки 130 и комментарий у константы совпадают с кодом); ошибочен только module-level docstring. Это вводит в заблуждение при настройке/ревью конверта: реальный разброс сценариев на ближнем горизонте уже в 1.5× шире base_delta, а не равен ему. ## Корень Устаревший/неверный module-level docstring; формула в коде корректна и самосогласована. ## Evidence `/Users/anton/Птица/gendesign/backend/app/services/forecasting/scenarios.py:27-33, 125-143` ```python # module docstring (29-30): # delta_eff(h) = base_delta × (1 + _HORIZON_WIDEN_PER_YEAR × h/12). На h=12 мес # конверт = base_delta, на h=24 мес ≈ base_delta × (1 + 0.5×_HORIZON_WIDEN_PER_YEAR) def _horizon_widen_factor(horizon_months, *, widen_per_year=_HORIZON_WIDEN_PER_YEAR): if horizon_months <= 0 or widen_per_year <= 0.0: return 1.0 return 1.0 + widen_per_year * (horizon_months / 12.0) # h=12 -> 1.5, не 1.0 ``` ## Suggested fix Исправить module docstring под фактическую формулу: на h=12 множитель = 1 + widen_per_year = 1.5; на h=24 = 1 + 2*widen_per_year = 2.0. Либо, если задумывался множитель ровно 1.0 на h=12, сменить нормировку на `1 + widen_per_year*((h-12)/12)` — но это изменит поведение, сначала уточнить намерение. ## Обоснование severity Low: строго документационный дефект, runtime-поведение корректно. Пострадать может только разработчик, читающий module docstring для понимания параметризации. --- _week ревью 1 · multi-agent аудит 2026-06-14 · severity=**low** · category=`correctness`_ Затронутые файлы: - `/Users/anton/Птица/gendesign/backend/app/services/forecasting/scenarios.py`