feat(financial): levered (equity) IRR — capstone финмодели #1881 #1900

Merged

bot-backend merged 2 commits from feat/levered-equity-irr into main

2026-06-25 09:06:46 +00:00

bot-backend commented

2026-06-25 08:25:52 +00:00

Collaborator

Что

Последняя крупная финметрика Excel-эталона «Авангардная 13» — IRR на собственные средства (levered/equity). Раньше финансирование (#1895) считало только агрегаты (пиковый долг, проценты, прибыль после финанс.), но не доходность на equity.

Как

_compute_financing уже проходит помесячный график долга (банк покрывает LTC 70% оттока, проценты капитализируются, притоки гасят долг). Из того же прохода эмитим денежный поток собственника:

отток: equity вносит (1−LTC) долю → cf·(1−ltc)
приток: остаток после обслуживания долга → cf − min(cf, debt)

levered_irr = _irr_monthly(equity_cf) (annualized), с тем же roi-proxy fallback и флагом levered_irr_is_proxy, что и unlevered IRR.

Честность (важно)

Levered IRR может быть выше ИЛИ ниже проектной IRR. При проектной доходности > 15% (стоимость долга) — положительный леверидж (выше). При marginal-проекте (проектная IRR < 15%) — отрицательный леверидж (ниже, вплоть до минуса). Показываем со знаком (Unicode «−»), не маскируем.
Вырожденные случаи (LTC≥1, нет equity под риском) → 0.0 + proxy-флаг, никогда не выдуманная доходность.
isReal = financing_enabled && !levered_irr_is_proxy.

Числа (LTC 70%)

Проект	unlevered IRR	levered IRR	леверидж
business/spot (проект > 15%)	0.201	0.288	положительный
comfort/mid_rise (проект ~4.6%)	0.046	−0.116	отрицательный (честно)

Корректность

Инвариант Σ equity_cf == net_profit_after_financing держится точно (банковский принципал нетится в ноль, проценты — единственная утечка). Тест проверяет на реальной модели.
Unlevered NPV/IRR/PBP и Σ cashflow == net_profit НЕ затронуты — levered чисто additive.
Deep-review независимо перепроверил equity-cashflow математику (hand-worked example), инвариант, edge-cases, codegen byte-identical.

Изменения

financial.py — _FinancingResult dataclass (+ equity_cashflow), levered IRR в compute_financial.
concept.py — additive levered_irr / levered_irr_is_proxy (defaults, back-compat).
api-types.ts — регенерён точной CI-цепочкой (app.openapi() → openapi-typescript → prettier); diff = только 2 поля, без мусора → openapi-codegen-check пройдёт.
ptica-adapt.ts + ConceptVariantsResult.tsx — строка «IRR на собственные средства» (drawer/каскад, не above-the-fold KPI), proxy/negative честно.
+8 backend тестов, +4 honesty-теста. Backend 51 passed, frontend 23 passed, mypy+ruff clean.

Refs #1881

## Что Последняя крупная финметрика Excel-эталона «Авангардная 13» — **IRR на собственные средства (levered/equity)**. Раньше финансирование (#1895) считало только агрегаты (пиковый долг, проценты, прибыль после финанс.), но не доходность на equity. ## Как `_compute_financing` уже проходит помесячный график долга (банк покрывает LTC 70% оттока, проценты капитализируются, притоки гасят долг). Из того же прохода эмитим **денежный поток собственника**: - отток: equity вносит `(1−LTC)` долю → `cf·(1−ltc)` - приток: остаток после обслуживания долга → `cf − min(cf, debt)` `levered_irr = _irr_monthly(equity_cf)` (annualized), с тем же roi-proxy fallback и флагом `levered_irr_is_proxy`, что и unlevered IRR. ## Честность (важно) - Levered IRR **может быть выше ИЛИ ниже** проектной IRR. При проектной доходности > 15% (стоимость долга) — положительный леверидж (выше). При marginal-проекте (проектная IRR < 15%) — **отрицательный леверидж** (ниже, вплоть до минуса). Показываем со знаком (Unicode «−»), не маскируем. - Вырожденные случаи (LTC≥1, нет equity под риском) → `0.0` + proxy-флаг, никогда не выдуманная доходность. - `isReal = financing_enabled && !levered_irr_is_proxy`. ## Числа (LTC 70%) | Проект | unlevered IRR | levered IRR | леверидж | |---|---|---|---| | business/spot (проект > 15%) | 0.201 | **0.288** | положительный | | comfort/mid_rise (проект ~4.6%) | 0.046 | **−0.116** | отрицательный (честно) | ## Корректность - **Инвариант `Σ equity_cf == net_profit_after_financing` держится точно** (банковский принципал нетится в ноль, проценты — единственная утечка). Тест проверяет на реальной модели. - **Unlevered NPV/IRR/PBP и `Σ cashflow == net_profit` НЕ затронуты** — levered чисто additive. - Deep-review независимо перепроверил equity-cashflow математику (hand-worked example), инвариант, edge-cases, codegen byte-identical. ## Изменения - `financial.py` — `_FinancingResult` dataclass (+ `equity_cashflow`), levered IRR в `compute_financial`. - `concept.py` — additive `levered_irr` / `levered_irr_is_proxy` (defaults, back-compat). - `api-types.ts` — регенерён **точной CI-цепочкой** (`app.openapi()` → openapi-typescript → prettier); diff = только 2 поля, без мусора → openapi-codegen-check пройдёт. - `ptica-adapt.ts` + `ConceptVariantsResult.tsx` — строка «IRR на собственные средства» (drawer/каскад, не above-the-fold KPI), proxy/negative честно. - +8 backend тестов, +4 honesty-теста. Backend 51 passed, frontend 23 passed, mypy+ruff clean. Refs #1881

bot-backend added 1 commit 2026-06-25 08:25:52 +00:00

feat(financial): levered (equity) IRR for the developer financial model

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

Details

CI / backend-tests (pull_request) Failing after 11m33s

Details

CI / changes (pull_request) Successful in 6s

Details

CI / frontend-tests (pull_request) Successful in 54s

Details

1ae8ae3ca0

Walk the existing debt schedule to emit the equity holder's monthly cashflow
((1−LTC) share of outflows; residual inflow after debt service) and run the
same DCF IRR + roi-proxy fallback over it. Degenerate cases (LTC≥1, no equity
at risk) → 0.0 / proxy, never a fabricated return. Levered IRR можно выше или
НИЖЕ проектной (отрицательный леверидж, если проект не покрывает стоимость долга
15%) — показываем честно, со знаком (Unicode «−»).

Инвариант Σ equity_cf == net_profit_after_financing держится точно. Unlevered
NPV/IRR/PBP и Σ cashflow == net_profit НЕ затронуты (levered чисто additive).

Schema: additive levered_irr / levered_irr_is_proxy на FinancialModel
(api-types.ts регенерён точной CI-цепочкой openapi-typescript+prettier).
Frontend: строка «IRR на собственные средства» в finance-drawer кокпита +
concept-каскаде (drawer-only — не раздуваем above-the-fold KPI), proxy/negative
помечаются честно. Завершает паритет с Excel-эталоном «Авангардная 13» (IRR).

Deep-review ✅ (equity-cashflow математика независимо перепроверена, инвариант,
codegen byte-identical, blast radius contained).

Refs #1881

Light1YT added 1 commit 2026-06-25 08:54:26 +00:00

test(concepts): add levered_irr keys to FinancialModel contract-key assertion

CI / changes (pull_request) Successful in 7s

Details

CI / frontend-tests (pull_request) Successful in 59s

Details

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

Details

CI / backend-tests (pull_request) Successful in 11m43s

Details

5de5367fab

test_concepts_response_matches_contract_keys pins the exact financial key
set; the two additive levered IRR fields broke it (full-suite-only test,
outside test_financial_dcf.py). Refs #1881