MOffice

Контракт: сводные таблицы (meridian-pivot, pivot_io, GETPIVOTDATA)

Владелец S4p «Сводные» (docs/sessions/OWNERS.toml)
Версия 0.2 (черновик) — 19.10.2026, пакеты B1–B3 сделаны; до входа S4 в окно (08.12) меняется владельцем
Потребители S4 «Sheets» (окно: диалог «Сводная таблица», панель «Поля сводной», «Обновить»; после беты 07.12); meridian-calc (функция GETPIVOTDATA); meridian-calc-xlsx (pivot_io.rs — чтение и запись pivot-частей); позже S4b (сводные диаграммы, 1.5)
Как менять совместимое добавление — новая версия 0.x в этой шапке и строка в «Изменениях» коммитом S4p; ломающее — сначала запись в журнал S4 (docs/sessions/lanes/S4.md, «Следующей сессии»), согласие S4, затем правка. До версии 1 (вход S4 в окно, 08.12) меняется владельцем свободно, но каждое изменение — строкой ниже.

Бриф: plan/competitors-20261019/brief-sheets-charts-pivots-1.0.md, разделы 2.2, 4 (пакеты B1–B3), 6. Вне 1.0: срезы, временные шкалы, вычисляемые поля и объекты, группировка дат и чисел, сводные диаграммы, OLAP, ODS.

1. Слои и направление зависимостей

meridian-pivot          (только std: модель, кэш, расчёт, раскладка — чистые функции, без файлов и окна)
   ▲
meridian-calc-xlsx::pivot_io   (XLSX ⇄ модель: pivotCacheDefinition, pivotCacheRecords, pivotTable)
   │                            └─ строит meridian_calc::pivot::PivotIndex для GETPIVOTDATA
   ▼
meridian-calc           (GETPIVOTDATA читает реестр PivotIndex книги; от meridian-pivot НЕ зависит)
   ▲
ui/meridian-sheets      (S4: диалоги, панель полей; вызывает pivot_io и meridian-pivot)

meridian-calc не зависит от meridian-pivot: реестр сводных для формул — собственный тип движка (meridian_calc::pivot::PivotIndex), его заполняет pivot_io при открытии книги и окно после «Обновить».

2. Модель (meridian_pivot)

Тип Смысл
Item значение элемента кэша: Blank, Number(f64), Date(f64) (серийный номер), Text, Bool, Error(String)
Cache столбцовый кэш: поля CacheField { name, items, codes }; items — уникальные значения (общие элементы файла — первыми, в их порядке), codes[r] — номер элемента записи r. Текст сравнивается без учёта регистра (как в Excel), Number и Date с одним серийным номером — один элемент
Cache::from_rows(headers, rows) кэш из диапазона или «умной таблицы»: первая строка — имена полей, пустое имя → Столбец N
PivotDef раскладка: rows (до 2 полей в 1.0), cols (до 1), values (DataField { field, agg, name }, несколько), filter (один фильтр отчёта: выбранный элемент или «все»), values_axis (место псевдополя «Σ Значения»), общие итоги по строкам и столбцам, промежуточные итоги по первому полю строк
Agg Sum, Count (непустые, как «Количество» Excel), Average, Min, Max; прочие функции файла читаются как Other(имя) и при «Обновить» не пересчитываются (значение файла остаётся)
AxisField поле оси: field, sort (Source — порядок элементов, Asc/Desc по подписи, ByValue { data, desc }), скрытые элементы, промежуточный итог вкл/выкл
Pivot = compute(&Cache, &PivotDef) чистая функция: деревья осей (строки, столбцы), значения в узлах (листья, промежуточные, общие итоги). Ошибки источника — первой ошибкой агрегата (как Excel)
Grid = render(&Pivot, &PivotDef, &Cache, &RenderOptions) раскладка в ячейки (компактная форма Excel 2007+, итоги сверху): относительные координаты, значение, роль ячейки (Header, RowLabel, ColLabel, Data, Subtotal, Grand, PageField), first_data_row/col, размер. Подписи («Названия строк», «Общий итог», «Сумма по полю …») — по языку RenderOptions::lang (ru/en)

Ограничения 1.0 проверяются PivotDef::check_1_0() (окно не даёт собрать больше); расчёт и раскладка работают и с большим числом полей — так читаются чужие файлы.

Скорость: compute + render по 100 000 строк источника ≤ 300 мс (медиана, эталонный ПК R2) — бенчмарк cargo bench -p meridian-pivot (benches/pivot_100k.rs), квитанция в qa/evidence/.

3. Файлы: meridian_calc_xlsx::pivot_io

Чтение и запись — только в pivot_io.rs (разбор и сверка) с подмодулями pivot_io/write.rs (запись, «Обновить») и pivot_io/index.rs (реестр GETPIVOTDATA); в lib.rs — регистрация модуля и вызов set_pivots (коммиты [касание S4]). Части сводных по-прежнему лежат побайтно в SheetLayout::pivots (пакет частей листа) и XlsxBook::pivot_caches: то, что pivot_io не понимает, пишется как было.

Функция Что делает
read_pivots(&XlsxBook) -> Vec<FilePivot>, FilePivot::def(), check, stale разбор каждой сводной: лист, имя, location (область, firstDataRow/Col), поля осей и значений, rowItems/colItems (сохранённая раскладка), кэш (Cache из pivotCacheRecords, источник — лист и область или имя таблицы), признак «простая» (без вычисляемых полей, группировки, OLAP)
refresh(&XlsxBook, &FilePivot, Lang) -> Refresh, apply_refresh «Обновить»: кэш из источника по значениям ячеек книги → compute. Элементы те же — новые значения пишутся в ячейки сохранённой раскладки, pivotTable не трогается; появились или исчезли — раскладка строится заново (relaid). Записи кэша заменяются, определению ставится refreshOnLoad="1"
new_pivot(&XlsxBook, &Source, &Cache, &PivotDef, лист, строка, столбец, имя, Lang) -> NewPivot, attach_parts новая сводная: ячейки раскладки + пакет частей (pivotTable, pivotCacheDefinition с refreshOnLoad="1", pivotCacheRecords, связи, типы содержимого) для SheetLayout::pivots и строка pivot_caches; кэш источника — source_cache_of(&XlsxBook, &Source)
pivot_index(&XlsxBook) -> Vec<meridian_calc::pivot::PivotIndex> реестр для GETPIVOTDATA по сохранённой раскладке

Записанный файл открывается в Excel 365 и LibreOffice без «восстановления»; проверка LibreOffice — в корпусе (qa/pivot-corpus), Excel — на Windows-ПК владельца (и Excel для Mac, где есть).

4. Формула: GETPIVOTDATA / ПОЛУЧИТЬ.ДАННЫЕ.СВОДНОЙ.ТАБЛИЦЫ

GETPIVOTDATA(поле_данных; сводная; [поле1; элемент1]; …). сводная — любая ячейка внутри области сводной. Поле данных — подпись поля значений («Сумма по полю Выручка») или имя поля источника («Выручка»), без учёта регистра. Пары «поле — элемент» в любом порядке; элемент сравнивается как в Excel (текст без регистра, число и дата по значению). Возвращает значение показанной ячейки сводной; комбинация, которой нет на листе (скрытый итог, неизвестный элемент, поле не на оси), — #REF!; ссылка не на сводную — #REF!.

Реестр: Workbook::set_pivots(Vec<PivotIndex>) (meridian_calc::pivot): PivotIndex { sheet, area, data_fields, fields, cells } — для каждой ячейки данных: номер поля данных, набор пар (поле, элемент) и координаты ячейки. Функция читает текущее значение ячейки, поэтому после «Обновить» окно заменяет значения ячеек и реестр (set_pivots помечает формулы к пересчёту).

5. События обновления

6. Проверка

Изменения