Черновик спецификации: адресуемые данные проекта для документов

Актуально на: 2026-07-09

Статус: draft для обсуждения.

1. Задача

Нужно уметь получить из проекта любое пользовательское или расчетное значение и вставить его в Word, PowerPoint или другой документ по специальному символическому обозначению.

Документ должен обновляться без ручной правки цифр: если проект изменился, генератор заново разрешает все символы и подставляет актуальные значения.

2. Текущее состояние в проекте

2.1. Что уже хранится в БД

В Prisma уже есть нормализованные таблицы для большой части вводимых данных:

Важно: ProjectWorkspaceState.state остается fallback/legacy-источником. Новая система подстановок не должна напрямую зависеть от UI-state, но должна уметь читать legacy-поля, пока не все области нормализованы.

2.2. Что уже рассчитывается в коде

Расчетные величины сейчас собираются не в БД, а в моделях:

Вывод: для документов нужен единый расчетный слой, который повторяет серверно тот же pipeline, что и экран workspace.

3. Базовый принцип

Любое значение должно иметь стабильный ключ:

domain.metric[selector].property@period | format

Для документов предлагается использовать двойные фигурные скобки:

{{ pf:project.title }}
{{ pf:cashflow.balance_end@2026-08 | money }}
{{ pf:investment.npv[mode=real,scope=before_financing] | money }}

Префикс pf: нужен, чтобы отличать наши токены от обычного текста и от возможных полей Word.

4. Периоды

Значения можно запрашивать тремя способами:

Если период не указан:

• для scalar-полей возвращается само поле;
• для рядов ошибка PERIOD_REQUIRED, кроме метрик, где есть естественный агрегат за весь проект.

5. Форматы

Формат указывается после |.

Дополнительные параметры формата:

{{ pf:investment.npv[mode=real] | money:currency=RUB,decimals=0 }}
{{ pf:investment.irr | percent:decimals=1 }}

6. Селекторы

Селекторы идут в квадратных скобках.

{{ pf:sales.revenue[product=product-id]@2026-08 | money }}
{{ pf:cashflow.row[row=28]@p6 | money }}
{{ pf:investment.npv[scope=before_financing,mode=real] | money }}

Общие селекторы:

7. Первый каталог ключей

Это не полный каталог, а стартовый набор для обсуждения.

7.1. Проект

7.2. Настройки расчета

7.3. Продажи

7.4. Cash-flow

7.5. P&L

7.6. Эффективность инвестиций

7.7. Финансирование

8. Требования к реализации

Нужны три слоя.

8.1. ProjectDataResolver

Серверный модуль:

resolveProjectValue({
  projectId,
  token: "pf:investment.npv[mode=real,scope=before_financing]",
  period: "2026-08",
  format: "money",
})

Должен возвращать:

{
  ok: true,
  value: 3472508.12,
  formatted: "3 472 508 RUB",
  meta: {
    source: "calculated",
    period: "2026-08",
    dependencies: ["cashflow", "projectCalc"]
  }
}

Ошибки:

8.2. ProjectDataRegistry

Каталог всех ключей:

{
  key: "investment.npv",
  title: "NPV проекта",
  type: "money",
  source: "calculated",
  periodMode: "aggregate",
  selectors: ["mode", "scope"],
  resolver: resolveInvestmentNpv,
}

Этот каталог нужен для:

• автодополнения токенов;
• проверки шаблонов перед генерацией;
• документации;
• миграции ключей без поломки старых документов.

8.3. ProjectSnapshot

Один объект, который собирает:

• вводимые данные из БД;
• legacy fallback из ProjectWorkspaceState;
• расчетные модели cash-flow, P&L, налоги, займы, капитал, эффективность;
• карту периодов проекта.

Документ не должен сам собирать расчеты. Он должен только спрашивать resolver.

9. Проверка доступности данных

Для каждого ключа в registry нужны тесты:

10. Важные решения для обсуждения

1. Синтаксис токенов: оставить {{ pf:... }} или выбрать другой.
2. Периоды: использовать @p7, @2026-08, @last, @all.
3. Нужно ли разрешать русские алиасы, например {{ ПФ:NPV }}, или держать только стабильные английские ключи.
4. Нужно ли сохранять рассчитанные snapshots в БД для аудита, или всегда пересчитывать live.
5. Как версионировать ключи, если формула поменялась.

11. Предлагаемый следующий шаг

1. Создать lib/project-data/registry.ts с первым набором ключей.
2. Создать lib/project-data/resolver.ts.
3. Вынести server-safe сборку расчетного ProjectSnapshot из текущих UI-хуков.
4. Добавить API:

POST /api/projects/:projectId/resolve-values

Тело:

{
  "tokens": [
    "{{ pf:project.title }}",
    "{{ pf:investment.npv[mode=real,scope=before_financing] | money }}",
    "{{ pf:cashflow.balance_end@2026-08 | money }}"
  ]
}

Ответ:

{
  "{{ pf:project.title }}": "Магазин ...",
  "{{ pf:investment.npv[mode=real,scope=before_financing] | money }}": "3 472 508 RUB",
  "{{ pf:cashflow.balance_end@2026-08 | money }}": "..."
}