Initial spec: MVP-1 workload + drafts for MVP-2/3/4 + Subsystem D

2026-05-13 19:42:17 +05:00
commit 76f9a1ccfa
7 changed files with 979 additions and 0 deletions
@@ -0,0 +1,93 @@
+# 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_РА` (для стабильного маппинга проектов).