Аудит contextual help и ролей¶
Результат¶
Product help links ведут каждую project role на публичную bilingual page, которая описывает разрешённую задачу или явно задаёт permission boundary и safe handoff. Public product никогда не ссылается на protected Operator Runbook.
Проверено: 22 октября 2026 года по apps/web/src/lib/docs.ts, settings tab
visibility, текущему EN/RU source tree и web link tests.
Проверенные ссылки¶
| Product surface | Видимая аудитория | Documentation target | Аудитория target | Результат |
|---|---|---|---|---|
| Dashboard activation checklist | Все project roles | Getting started | Все project roles | Safe read/action path |
| Approvals page | Все project roles | Approvals | Все project roles; resolve явно требует admin/owner |
При отсутствии controls есть safe administrator handoff |
| Reports page | Все project roles | Reports and Graph Health | Все project roles | Safe read path |
| Dashboard Graph Health card | Все project roles | Reports and Graph Health | Все project roles | Safe read path |
| Connectors header | Все roles, которые могут открыть screen | Connection setup | admin/owner |
Required role указана до setup; остальным предписан handoff без передачи credentials |
| Connector failure banner | Все roles с доступом к status | Troubleshooting | Все project roles | Symptom-first, без privileged workaround |
| Settings → MCP | Все project roles | MCP setup | Все project roles; API-key creation передаётся administrator | Viewer read-only boundary указана явно |
| Settings → Members | Все project roles | Role permissions | Все project roles | Read-only role table без invitation instruction для member/viewer |
| Меню Help в шапке → Documentation | Все project roles | Главная документации | Все project roles | Публичная стартовая страница; меню скрыто, если origin документации недоступен |
| Меню Help в шапке → Merge request review guide | Все project roles | Ревью merge request | Все project roles; изменение настроек — admin |
Read-путь; таблица настроек называет границу admin |
| Меню Help в шапке → First review in five minutes | Все project roles | Первое ревью за пять минут | admin/owner |
Страница называет нужную роль до настройки и отправляет остальные роли к администратору без передачи credentials |
Application использует English canonical path. Material language switcher
открывает соответствующую Russian page. Для каждого target из DOCS_PATHS есть
.md и .ru.md source.
Operator boundary¶
Operator pages содержат deployment, migration, backup, incident и protected
environment procedures. Они исключены из public MkDocs config и public
container. Ни одно значение DOCS_PATHS не может начинаться с operator/;
docsUrl() также отклоняет такой target после unsafe cast.
Operators открывают эти pages только через authenticated internal documentation build. Product roles никогда не направляются из public UI на GitLab Pages access control.
Что должно быть в safe target¶
Если action доступно не всем viewers исходного screen, target page должна указывать:
- minimum role до первого action;
- что lower role может безопасно проверить;
- кому передать задачу и какие сведения нужны;
- запрет на передачу sessions, tokens и connector credentials;
- non-privileged verification или troubleshooting path, где возможно.
Link неприемлем, если он dead, открывает Operator content, предполагает hidden controls или предлагает lower role обойти authorization.
Автоматические проверки¶
Web test проверяет, что каждый contextual target:
- находится вне
operator/; - имеет English и Russian source;
- имеет explicit audience entry;
- открывается с safe external-link attributes.
Запуск:
npm --prefix apps/web test -- docs-link.test.tsx
make docs-build
make docs-build-internal
Strict MkDocs builds проверяют links внутри target pages. При добавлении
contextual help обновляйте DOCS_PATHS, DOCS_AUDIENCES, эту таблицу и обе
language versions в одном merge request.