request-portal/.claude/skills/sp-query/SKILL.md

---

name: sp-query description: Спросить у SharePoint-тенанта реальные данные портала заявок через tools/sp — что отдаёт поисковый индекс (managed properties, Retrievable), сколько партиций и элементов в списках, произвольный KQL или REST. Использовать, когда ответ зависит от состояния тенанта, а не выводится из кода: «отдаётся ли поле через Search», «сколько на самом деле партиций», «почему запрос возвращает пусто», «проверь на живых данных». Не использовать для правки данных.

Запросы к SharePoint портала заявок

Когда это нужно

Рассуждать по коду можно долго и неправильно. Есть класс вопросов, где ответ живёт только в тенанте:

• отдаёт ли индекс конкретное поле (Retrievable) — от этого зависит, можно ли заменить REST-дочитывание на SelectProperties;
• сколько на самом деле партиций у типа заявки и сколько в них элементов (это переменная P во всех оценках числа запросов);
• почему KQL возвращает пусто — не то имя managed property, не тот Path, нет прав;
• как выглядит реальное значение поля (AuthorOWSUSER — не почта, а почта | ФИО).

Если вопрос из этого списка — не гадай и не проси пользователя лезть в консоль браузера. Спроси тенант.

Порядок действий

cd tools/sp
node sp.mjs status          # сначала: есть ли вход вообще

Logged out → нужен вход. Он интерактивный: команда печатает код, который пользователь вводит в браузере сам. Запускать login в фоне бессмысленно — попроси пользователя выполнить его и вернуться.

node sp.mjs login

Если ругается на SP_APP_ID — регистрация приложения не сделана, отправь пользователя в tools/sp/README.md, раздел «Разовая подготовка» (это разовая задача с admin consent, сам её не закроешь).

Дальше:

команда	что отвечает
node sp.mjs props	отдаёт ли индекс поля заявки; <нет в ответе> / <null> = не Retrievable
node sp.mjs lists	портальные списки, их адреса и размеры — реальное число партиций
node sp.mjs search "<KQL>" --select a,b --rows N	тот же запрос, что шлёт портал
node sp.mjs get "/_api/web/..."	произвольный GET

Что нельзя

• Не вводить пароли и секреты. Вход только device code: код вводит пользователь. Если предлагаешь --authType password или --secret — ты делаешь неправильно.
• Не писать данные. Инструмент читающий. Любая правка списков — отдельный разговор с пользователем, а не побочный эффект разбора.
• Не заводить app-only доступ по сертификату ради Search. Он для этого не годится: /_api/search/query под app-only-токеном обычно не отдаёт ничего, поиску нужен пользовательский контекст.

Грабли

Queryable ≠ Retrievable. Разные флаги managed property. То, по чему получается фильтровать, не обязано приходить в ответе — и наоборот. Доказав одно, не считай доказанным другое: в этом проекте на этом уже спотыкались.

Имена managed properties нестандартные. Суффикс по типу колонки: OWSTEXT (Text), OWSCHCS (Choice), OWSUSER (Person/Group). У колонок из группы колонок сайта добавляется префикс группы — поэтому существует TansuSiteApproverOWSUSER, а «ожидаемого» ApproverOWSUSER в схеме нет вовсе. Прежде чем сочинять имя, посмотри константы MP_* в src/webparts/requestPortal/features/myRequests/myRequests.service.ts.

Пустой результат ≠ свойство не работает. Сначала проверь Path (адрес сайта, слеш на конце, регистр) и права — в этом проекте вывод «managed property сломана» однажды оказался артефактом задвоенного сегмента в тестовом Path.

Замер портала — это другое. tools/sp отвечает на вопросы о данных. Чтобы понять, куда уходит время в самом портале, есть встроенный замер: window.rpPerf = true в консоли страницы (см. src/webparts/requestPortal/shared/perfTrace.ts), детали — window.rpPerfDetail().