# MVP-3 «Маржа, НЗП, актирование» — Design Draft

| | |
|---|---|
| Дата | 2026-05-13 |
| Статус | **Draft — фиксация обсуждённого, требует доработки после MVP-2** |
| Зависимости | MVP-1 + MVP-2 (есть core.employee, core.project, core.stage, core.work_log) |
| Срок | 2-3 недели после MVP-2 |

> **Назначение этого документа:** зафиксировать то, что уже обсудили по MVP-3, чтобы не вспоминать заново. Это **набросок**, не финальная спека.

## Цели MVP-3

Финансовая аналитика по проектам: маржа план/факт, незавершёнка (НЗП), прогноз актирования следующего месяца, контроль подписания результирующих документов.

### Главные бизнес-вопросы

- Какая маржа по проектам (план/факт)?
- Сколько НЗП (незавершёнки) на каждом активном проекте?
- Сколько денег будем актировать в следующем месяце?
- Где отстаём по срокам подписания актов?
- Какая общая себестоимость и себестоимость по закрытым актам?

## Что добавляем к MVP-1/2

### Расширение core

```sql
core.project_finance (
    id bigserial PRIMARY KEY,
    project_id bigint REFERENCES core.project,
    stage_id bigint REFERENCES core.stage,
    scenario_code text,             -- план | факт | прогноз (из Catalog.СценарииПланирования BIT.RA)
    analytics_type text,            -- ВидАналитики из BIT.RA (рассмотреть в core или хранить как есть)
    employee_id bigint REFERENCES core.employee,
    period_date date,               -- дата движения
    sum_total decimal(15,2),        -- Сумма (плановая/фактическая)
    sum_acted decimal(15,2),        -- СуммаАкт
    sum_expense decimal(15,2),      -- СуммаРасход
    source_doc_id text              -- ссылка на Document.ПланФактПроектныхПоказателей_v2
)

-- Возможно понадобится:
core.stage_act (
    id bigserial PRIMARY KEY,
    stage_id bigint REFERENCES core.stage,
    plan_act_date date,             -- плановая дата акта (из Catalog.ЭтапыПроектов.ДатаОкончания)
    actual_act_date date,           -- фактическая дата подписания (если известно)
    is_signed boolean,
    sum_planned decimal(15,2),
    sum_actual decimal(15,2)
)
```

### Новые витрины

```
mart.project_margin            — маржа план/факт по проекту: (Сумма_план - СуммаРасход_план) / Сумма_план и аналогично для факта
mart.wip                       — НЗП = Σ(часы × ставка) - актированная_выручка по проекту/этапу
mart.actuation_forecast        — прогноз актирования: открытые этапы с ДатаОкончания в следующем месяце и Σ их Сумма
mart.deadline_risks_financial  — риски по подписанию документов (расширение mart.deadline_risks из MVP-2 на финансовую сторону)
mart.cost_summary              — общая себестоимость и себестоимость по закрытым (АктПодписан=true) этапам
```

### Источники данных (помимо MVP-1/2)

- **BIT.RA эндпоинт `/api/project_register`** — `AccumulationRegister.ОборотыПроектныхПоказателей_v2` с инкрементом (измерения Сценарий+Проект+Этап+ВидАналитики+Исполнитель → ресурсы Сумма+СуммаАкт+СуммаРасход).
- **BIT.RA эндпоинт `/api/plan_fact_v2`** — `Document.ПланФактПроектныхПоказателей_v2`. **ValueStorage поле `ХранилищеДерева` не тянем** (по [identity-and-scope](../../memory/feedback_identity_and_scope.md)).
- **BIT.RA эндпоинт `/api/lurv`** — `Document.ЛУРВ` для понимания фактически выписанных листов учёта результатов выполнения.

### Дашборд (расширение)

Новый дашборд «Финансы проектов» в Metabase:
- Плитка «Общая НЗП» (сумма по всем активным проектам).
- Плитка «Прогноз актирования за следующий месяц».
- Таблица «Маржинальность проектов» — проект, план-маржа, факт-маржа, отклонение, цвет светофор.
- Таблица «Этапы к актированию в этом/следующем месяце» — этап, плановая дата, сумма, готовность.
- График «Динамика НЗП по проектам» за 12 месяцев.

## Open questions (для финализации перед стартом MVP-3)

- **Что считать НЗП именно?** Текущая идея — `Σ(core.work_log.hours × core.employee.rate) − Σ(core.project_finance где сценарий=факт-акт)`. Но если расход в `ОборотыПроектныхПоказателей_v2.СуммаРасход` уже считается по факту работ — это будет двойной счёт. Уточнить семантику регистра.
- **Сценарии (`Catalog.СценарииПланирования` BIT.RA)** — какие реально используются? План, факт, прогноз? Нужно понять словарь.
- **`ВидАналитики` в регистре** — что это за измерение, какие значения? Возможно нужно тянуть `Catalog.ВидыАналитикиПроектныхПоказателей` (или подобное).
- **Связь с финрезом подразделений (MVP-4)** — финрез считается из выручки и расходов, маржа проектов — тоже. Не дублируем ли мы расчёты? Возможно MVP-3 и MVP-4 нужно объединить или строго разграничить (MVP-3 = разрез по проектам, MVP-4 = разрез по подразделениям).
- **Контроль подписания документов** — нужны ли дополнительные сущности (Договоры, ДополнительныеСоглашения)? Они есть в BIT.RA `Catalog.Договоры` и в ТЧ `Проекты.ДокументыЭтапов`.

## Зависимости от MVP-2

MVP-3 стартует когда:
- ✅ MVP-2 работает (есть core.stage, deadline-логика).
- ✅ Identity-map проектов BIT.RA ↔ EVA стабильна.
- Полезно но не обязательно: восстановлена обработка `СинхронизацияДанныхEVA_РА` (для стабильного маппинга проектов).