Контракт:
сводные таблицы (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. События обновления
- Источник изменился → окно (S4) помечает сводные этого источника
«устарели»; пересчёт — только по «Обновить» / «Обновить все» (как в
Excel) или при открытии файла с
refreshOnLoad="1". - «Обновить» =
refresh→ окно пишет ячейки одной операцией отмены, вызываетset_pivots, затем пересчёт книги.
6. Проверка
cargo test -p meridian-pivot— расчёт, итоги, сортировка, фильтр, раскладка.cargo test -p meridian-calc-xlsx --test pivot_corpus— корпусqa/pivot-corpus(≥ 100 книг): 0 паник, после «Обновить» значения = кэш Excel у 100 % простого подмножества; квитанцияqa/evidence/pivot-corpus-<sha>-<дата>.json.cargo test -p meridian-calc --lib pivot— GETPIVOTDATA на построенной сводной (поиск, итоги, фильтр,#REF!, русское имя);cargo test -p meridian-calc-xlsx --test pivot_getpivotdata— против значений, сохранённых Excel (формулы книг корпуса и формула на каждую ячейку данных простых сводных).cargo test -p meridian-calc-xlsx --test pivot_write— запись новой сводной, чтение обратно, «Обновить».
Изменения
- 19.10.2026 — 0.1, черновик: слои, модель, файлы, формула, события (S4p, первый коммит дорожки).
- 19.10.2026 — 0.2: сигнатуры
pivot_ioпо сделанному (B1–B3), правила Excel из корпуса (пустые значения → пустая ячейка, Σ текста → 0, даты кэша до секунды, «столбцы целиком» + одна пустая запись), подмодулиpivot_io/.