---

[I128-2826] Расширить Help для документации задач, API и эксплуатационных runbook

---

НАЧАЛО >> Оглавление >> Общее описание >> История изменений >> Что нового в проекте I128 >> Версия 2026.3 >> [I128-2826] Расширить Help для документации задач, API и эксплуатационных runbook📄 Скачать в DOCX

---

Тип	Версия	Статус	Приоритет	Исполнитель
⚙️ Новые возможности	2026.3	🔘 Завершено	Средний	Ilya Mikhaylenko

Компоненты: ИРБИС 128. Модуль Help - Помощь

Завершено: 08.09.2026 11:54

1. Цель

Нужно расширить Help как штатное место хранения и публикации документации по задачам, workflow-проектам, API, эксплуатационным runbook, known limitations, troubleshooting и материалам базы знаний.

Tasks и другие доменные модули не должны становиться собственными хранилищами документации. Они подготавливают доменное содержимое и ссылки на исходные объекты, а опубликованный материал и его lifecycle принадлежат Help.

1. Состав работ

• Поддержать типы материалов: руководство пользователя, руководство администратора, руководство разработчика, API/SDK examples, эксплуатационный runbook, playbook, known limitations, troubleshooting, changelog/release notes и knowledge article.

• Для материала хранить версию, язык, аудиторию, owner module, source object, source version, дату пересмотра, статус актуальности, права видимости и связи с исходными record-based объектами.

• Поддержать публикацию candidate solution и knowledge article из решенной задачи: Tasks готовит доменный текст и readiness-признаки, Help хранит опубликованный материал.

• Поддержать context help для WorkflowView/WorkflowScreen/Tasks, чтобы UI мог показать релевантную подсказку без локальной логики документации.

• Добавить HealthCheck-проверки битых ссылок, просроченных runbook, отсутствующих обязательных разделов и устаревших API examples.

• Обеспечить права на просмотр, публикацию, снятие с публикации, ревизию и архивирование материалов через Security.

  1. Границы ответственности

• Help владеет опубликованными материалами, версиями, навигацией документации, context help, lifecycle документа и связями на source objects.

• Tasks владеет task-specific содержанием, readiness rules и действием подготовки публикации.

• WorkflowView/WorkflowScreen показывают ссылки и подсказки, HealthCheck диагностирует актуальность, TestA проверяет сценарии публикации.

  1. Критерии приемки

• Документация пользователя, администратора, разработчика и эксплуатации может храниться и публиковаться в Help.

• Опубликованный материал из задачи хранится в Help и связан с исходной задачей стандартной связью.

• Права видимости и публикации проверяются через Security.

• Context help доступен из WorkflowView/WorkflowScreen без копирования текста в эти модули.

• HealthCheck находит битые ссылки и устаревшие материалы.

  1. TestA и Help

• TestA должен покрыть публикацию материала, связь с задачей, доступность context help, права, устаревание, HealthCheck и отсутствие скрытого контекста в UI.

• Help должен содержать собственный раздел о правилах ведения документации, версионировании и ревизии.

-

I128-2826: реализован первый кодовый срез Help для промышленного жизненного цикла справочных материалов, контекстной помощи и диагностируемого системного реестра. PR не переносит в Help доменную логику Tasks, TaskPortal, Workflow* или HealthCheck: модуль владеет только опубликованными материалами, их метаданными, контекстными ссылками и локальной диагностикой собственного контракта.

Куда смотреть:

• В интерфейсе: ?id=Help/Show&m=Help/DocumentationLifecycle - новая страница с правилами жизненного цикла документации, системного реестра, контекстной помощи, диагностики и TestA-проверки.
• Техническая точка: новые публичные функции Help реализованы в __call: чтение системного JSON, нормализация материала, построение реестра, подбор контекстной помощи и локальная диагностика Help-контракта.
• Настройки: в редакторе модуля Help добавлены параметры DOCXэкспорта, файла реестра материалов, аудитории контекстной помощи и режима диагностики Helpссылок.
• Для PRволны: ветка `feature/I1282826helpdoc-lifecycleсоздана от актуальногоdevelop; PR направлен вdevelop`.

Изменения по файлам:

modules/Help/api.php

• Оставлены только системные функции модуля и настройки по умолчанию.
• Добавлен PHPDoc @method для публичных __call функций Help, включая новый контракт материалов.

modules/Help/__call/*.inc

• Добавлены GetSystemMaterialDefinitions, NormalizeMaterialDefinition, BuildMaterialRegistry, ResolveContextHelp, HealthCheckDefinition.
• Код операций находится в __call, без переноса тела функций в api.php.
• Variables дополнена GetParamInfo и настройками DOCX/реестра/контекстной помощи.

modules/Help/system/help*material*contract.json

• Новый системный JSON-контракт: типы материалов, статусы жизненного цикла, аудитории, типы source object, обязательные разделы, context help и системные материалы первого промышленного контура.

modules/Help/Help/*.md

• Добавлена страница Help/DocumentationLifecycle.
• Корневое оглавление и Help/HelpDoc дополнены ссылкой на новый контракт.

modules/Help/Tests/Module.inc

• Новый TestA saferead тест `Help.module.materialregistry`.
• Проверяются наличие обязательных файлов, чтение JSON, индексы, context help, HealthCheckDefinition и отсутствие прямой зависимости Help от Tasks, TaskPortal, HealthCheck в новом контракте.

Проверки:

• PHP lint: modules/Help/api.php, новые и измененные modules/Help/__call/*.inc, modules/Help/Tests/Module.inc - без syntax errors.
• JSON: modules/Help/system/help*material*contract.json успешно разбирается через ConvertFrom-Json.
• TestA: Help.module.material~~registry passed 1/1, safe~~read, без failed/skipped/warning.
• Chrome: http://irbis128.local/?id=Help/Show&m=Help/DocumentationLifecycle возвращает 200, заголовок отображается, console errors нет.

1. Связанные задачи

1.1. 🔗 blocks: I128-2802

1.2. 🔗 blocks: I128-2838

1.3. 🔗 blocks: I128-2839

1.4. 🔗 blocks: I128-2840

1.5. 🔗 blocks: I128-2791

1.6. 🔗 blocks: I128-2797

1.7. 🔗 blocks: I128-2798

1.8. 🔗 blocks: I128-2799