Жизненный цикл документации Help

НАЧАЛО >> Оглавление >> Жизненный цикл документации Help📄 Скачать в DOCX

Модуль Help является владельцем опубликованных справочных материалов системы: руководств, API-примеров, эксплуатационных инструкций, известных ограничений, статей базы знаний и материалов для устранения неисправностей. Доменные модули готовят содержание и определяют, какие действия пользователя требуют справки, но опубликованный материал, его статус и контекстные ссылки ведутся через Help.

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

Системный реестр находится в modules/Help/system/help_material_contract.json. В нем фиксируются:

типы материалов;
статусы жизненного цикла;
аудитории;
типы исходных объектов;
обязательные разделы документации;
связи контекстов интерфейса с Help-материалами;
перечень системных материалов первого промышленного контура.

Ключ материала должен быть стабильным. Help-путь задает страницу, открываемую через ?id=Help/Show&m=<путь>. Один материал может относиться к нескольким аудиториям и нескольким контекстам интерфейса.

2. Статусы жизненного цикла

Черновик используется для материала, который еще не должен попадать в пользовательскую навигацию. Статус проверки означает, что материал готовится к публикации. Опубликованный материал может отображаться в дереве Help и контекстных ссылках. Устаревший материал сохраняется для истории, но не должен предлагаться как основной ответ. Архивный материал не используется в текущем интерфейсе.

Дата пересмотра нужна для эксплуатационной дисциплины: опубликованный материал не должен оставаться без проверки после изменения связанного модуля, API, workflow-проекта или runbook.

3. Контекстная помощь

Контекстная помощь подбирается функцией Help/ResolveContextHelp. На вход передаются имя модуля, ключ контекста и аудитория. Функция не загружает доменный модуль и не исполняет его бизнес-логику: она работает только с реестром Help-материалов.

Такой подход позволяет WorkflowView, WorkflowScreen, API-страницам и административным формам показывать ссылки на справку единообразно. Если точный контекст не найден, допускается fallback к материалам модуля-владельца.

4. Диагностика

Функция Help/HealthCheckDefinition проверяет системный реестр:

JSON-файл доступен и корректно разбирается;
ключи материалов, типов и статусов не дублируются;
типы, статусы и аудитории материалов существуют в справочниках;
обязательные Help-страницы реально существуют;
опубликованные материалы имеют актуальную дату пересмотра.

Эта функция является контрактом для будущей интеграции с общесистемным HealthCheck. Сам модуль Help не должен зависеть от доменной логики Tasks, TaskPortal или Workflow-проектов: он только проверяет собственный реестр и доступность Help-страниц.

5. TestA