---

[I128-2817] Реализовать общесистемные рабочие календари WorkCalendar

---

НАЧАЛО >> Оглавление >> Общее описание >> История изменений >> Что нового в проекте I128 >> Версия 2026.3 >> [I128-2817] Реализовать общесистемные рабочие календари WorkCalendar📄 Скачать в DOCX

---

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

Компоненты: Нет

Завершено: 08.09.2026 12:27

1. Цель

Нужно реализовать общесистемный модуль WorkCalendar для ИРБИС 128. Модуль должен хранить рабочие календари и выполнять воспроизводимый расчет рабочего времени для задач, согласований, фоновых расписаний, SLA/OLA, дежурств, окон изменений и будущих workflow-процессов.

WorkCalendar должен быть владельцем календарных правил и временной доступности. Предметные модули должны выбирать календарь, передавать правила расчета и сохранять рассчитанный результат, но не должны реализовывать собственную логику рабочих дней, праздников, смен, timezone и исключений.

1. Контекст

В промышленном контуре ИРБИС 128 сроки реакции, сроки выполнения, напоминания, фоновые задания, approval deadlines, дежурства и окна изменений должны рассчитываться одинаково для разных модулей. Если такие правила хранить отдельно в Tasks, WorkflowCalendar, WorkflowApproval или Queue, система получит несколько несовместимых реализаций праздников, переносов, смен, часовых поясов и пересчета сроков.

WorkCalendar должен стать общим системным сервисом расчета времени. Первый важный потребитель - модуль Tasks: он использует календарь для SLA, OLA, командных очередей, ранжирования, просрочек, напоминаний и пересчета сроков. Но модуль не должен быть частной частью Tasks и должен быть применим к другим workflow-проектам.

1. Что Нужно Сделать

Нужно реализовать модель календарей:

• WorkCalendar: стабильный ключ, название, описание, timezone, статус активности, признак системности, версия и audit изменений.
• WorkCalendarPeriod: регулярные рабочие периоды по дням недели, сменам и временным интервалам.
• WorkCalendarException: праздник, перенос, сокращенный день, внеплановая смена, нерабочий период или разовое исключение.
• WorkCalendarHolidayPack: версионированный набор праздников и переносов для страны, региона или организации.
• WorkCalendarRule: правила расчета, округления, начала рабочего дня, учета праздников, пауз и границ интервала.
• WorkCalendarCalculation: сохраненный результат расчета с calendar key, calendar version, входными параметрами, итоговой абсолютной датой и диагностикой.
• WorkCalendarProfile: профиль выбора календаря для проекта, организации, host, типа записи или SLA-правила.

Нужно реализовать модель доступности ресурсов:

• WorkCalendarResourceAvailability: временной overlay доступности пользователя, группы, подразделения или ресурса.
• WorkCalendarOnCallSchedule: график дежурств с основным и резервным исполнителем, сменами, timezone и исключениями.
• WorkCalendarChangeWindow: разрешенное окно изменений или freeze-период с областью действия и условиями обхода.
• WorkCalendarImpactReport: dryrun отчет влияния изменения календаря, holiday pack, availability, oncall или change window на объекты потребителей.

Нужно поддержать календарные правила:

• рабочие и нерабочие дни;
• несколько рабочих периодов в одном дне;
• смены и круглосуточные режимы;
• праздники, переносы, сокращенные дни и внеплановые рабочие дни;
• timezone и переходы времени, включая DST там, где он есть;
• нейтральный системный календарь 5/2 без жесткой привязки к производственному календарю РФ;
• отдельные JSON definitions для holiday packs РФ, регионов и организаций.

Нужно реализовать API расчета:

• проверить, является ли момент рабочим временем;
• найти ближайшее рабочее время после заданной даты;
• прибавить рабочую длительность к дате и вернуть абсолютный срок;
• посчитать рабочую длительность между двумя датами;
• рассчитать deadline по SLA/OLA-правилу;
• вернуть диагностический trace расчета для администратора;
• вернуть доступность пользователя, группы, подразделения или ресурса в заданный период;
• вернуть текущего on-call кандидата и резервного кандидата для заданного контекста;
• проверить попадание действия в разрешенное окно изменений или freeze-период;
• вернуть результат в машинно читаемом виде с calendar key, version, input, output, rounding, warnings и trace id.

Нужно реализовать версионирование и изменение календарей:

• каждое изменение календаря, holiday pack, availability, on-call schedule и change window должно фиксировать автора, дату, комментарий и затронутый период;
• результат расчета должен хранить версию календаря, по которой он был получен;
• уже сохраненные absolute deadlines по умолчанию не должны меняться автоматически после изменения календаря;
• изменение календаря должно уметь формировать dry-run impact report по открытым объектам потребителей;
• массовый пересчет должен выполняться только после явного apply и через Queue;
• rollback или отмена изменения должны быть диагностируемыми и не должны молча переписывать сроки.

Нужно реализовать системные и пользовательские definitions:

• системные календари и holiday packs должны поставляться через JSON/system definitions;
• системные записи не должны редактироваться штатным администратором напрямую, кроме разрешенного режима разработки системных definitions;
• пользовательская настройка должна выполняться через копию системного календаря или явное наследование с overrides;
• импорт holiday pack должен поддерживать dry-run, conflict report, версию и rollback;
• экспорт проекта или workflow package должен включать календарные ссылки и необходимые definitions, если проект на них опирается.

Нужно реализовать права и безопасность:

• права на просмотр, создание, редактирование, копирование, публикацию, удаление, импорт, экспорт и запуск пересчета календарей должны проверяться через Security;
• причины отсутствия или недоступности должны маскироваться через Security: пользователь без права видит только факт недоступности или безопасную формулировку;
• dry-run reports, impact reports и диагностический trace расчета должны показываться только пользователям с соответствующими правами;
• системные definitions должны быть защищены от случайного изменения.

Нужно реализовать интеграции:

• Tasks выбирает календарь проекта, задает task-specific SLA/date rules, хранит absolute deadline, calendar key, calendar version и исходное правило расчета.

• Tasks выполняет доменные реакции на пересчет: изменение признака просрочки, перестановка в очереди, эскалация, уведомление или ручное подтверждение.

• WorkflowCalendar использует WorkCalendar для рабочих и нерабочих интервалов, capacity и availability, но не хранит правила рабочего времени.

• WorkflowApproval использует WorkCalendar для сроков согласования и эскалаций, но не переносит approval policy в WorkCalendar.

• Queue выполняет тяжелый пересчет, delayed jobs и scheduled jobs по рабочему времени, но не хранит календарную семантику.

• Users/Organisations предоставляет пользователей, группы, подразделения и organization context для availability и on-call, но не хранит календарные правила.

• HealthCheck проверяет корректность календарей, ссылок, timezone, пересечений, conflicts и readiness system definitions.

• Observability получает сигналы о latency расчета, ошибках timezone, количестве пересчитанных объектов и длительности Queue-заданий.

• TestA проверяет расчет, системные definitions, права, dryrun/apply, Queueпересчет и интеграционные сценарии.

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

WorkCalendar владеет календарями, рабочими периодами, праздниками, сменами, timezone, исключениями, availability overlays, отсутствиями, замещениями, on-call schedules, change/freeze windows, API расчета, версиями и impact reports.

WorkCalendar не должен владеть задачами, SLAполитиками задач, назначением ответственного, ранжированием очереди задач, approvalпроцессом, визуальными календарными представлениями, runtime Queue, справочником пользователей, правами доменных действий, коммуникациями и историей действий задачи.

Решение о назначении задачи, эскалации, обходе freezeпериода или изменении workflowсостояния принимает модуль-потребитель через свои правила, Workflow и Security. WorkCalendar только рассчитывает временную доступность, рабочие интервалы, сроки и диагностируемый результат.

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

Администратор может создать календарь, настроить рабочие периоды, смены, timezone и исключения, а также скопировать системный календарь для пользовательской настройки.

Системный нейтральный календарь 5/2 и примеры holiday packs поставляются через JSON/system definitions и воспроизводимо синхронизируются при setup/update.

API корректно определяет рабочее время, ближайшее рабочее время, прибавление рабочей длительности и рабочую длительность между датами с учетом timezone, праздников, сокращенных дней, смен и исключений.

Результат расчета содержит calendar key, calendar version, входные параметры, итоговую абсолютную дату, признаки округления, warnings и диагностический trace.

Изменение опубликованного календаря не меняет старые deadlines автоматически. Система формирует impact report, а массовый пересчет выполняется только через явный apply и Queue.

Availability, absence, delegation, on-call и change/freeze windows доступны через API для потребляющих модулей, но не приводят к автоматическому назначению задачи внутри WorkCalendar.

Причины отсутствия и диагностические данные маскируются с учетом прав. Пользователь без права не видит скрытые персональные детали.

HealthCheck находит отсутствующие календарные ссылки, пустое расписание, некорректную timezone, конфликтующие исключения, пересечения availability, битые ссылки на пользователей/группы и устаревшие system definitions.

WorkCalendar можно использовать не только для Tasks, но и для WorkflowCalendar, WorkflowApproval, Queue schedules и будущих workflow-процессов без изменения ядра модуля.

1. Проверки И Документация

Нужно подготовить TestA-сценарии для:

• базового календаря 5/2;
• праздников, переносов, сокращенных дней и внеплановых рабочих дней;
• нескольких рабочих интервалов в одном дне;
• смен и круглосуточного режима;
• timezone и DST edge cases;
• прибавления рабочего времени и расчета длительности между датами;
• сохранения calendar version в результате расчета;
• dryrun impact report и Queuebased recalculation apply;
• прав просмотра, редактирования, импорта, пересчета и masking absence reasons;
• absence, delegation, on-call primary/backup, отсутствия доступного дежурного;
• change window и freeze-period;
• OLA calculation отдельно от внешнего SLA заявителя;
• HealthCheck provider checks и system JSON definitions.

В Help должны быть подготовлены:

• руководство администратора по настройке календарей, holidays, смен, exceptions, availability, on-call и change windows;
• руководство разработчика по API расчета и интеграции модулей-потребителей;
• эксплуатационный runbook по dryrun, impact report, Queueпересчету, rollback, диагностике timezone и ошибкам system definitions.

-

I1282817: добавлен первый кодовый срез общесистемного модуля WorkCalendar. PR вводит календарный runtime для расчета рабочего времени, доступности ресурсов и окон изменений; доменные SLAправила, назначение задач, workflowпереходы и фоновые пересчеты остаются в модуляхпотребителях.

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

• В интерфейсе изменений не видно. Техническая точка: модуль WorkCalendar, его __call API, system JSON definitions, Help и TestA. Эффект: Tasks, Queue, WorkflowCalendar, WorkflowApproval и другие потребители смогут ссылаться на общий рабочий календарь и получать объяснимые результаты расчета времени без собственной реализации календарной логики.
• Chrome: не подтверждалось, потому что PR добавляет системный контракт и вычислительный API без самостоятельной пользовательской страницы. Help можно открыть через ?id=Help/Show&m=WorkCalendar/Root, ?id=Help/Show&m=WorkCalendar/Purpose и ?id=Help/Show&m=WorkCalendar/AdminGuide.
• Настройки для сценария: отдельная настройка стенда не требуется; базовые системные definitions находятся в modules/WorkCalendar/system/work_calendars.json.
• Help: добавлены корневая, функциональная и администраторская страницы WorkCalendar.
• Для PRволны: ветка `feature/I1282817workcalendarbusinesstimeсоздана отdevelop; PR направлен вdevelop`.

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

modules/WorkCalendar/api.php

• Новый системный класс модуля WorkCalendar.
• В Init задаются тип записи WORKCALENDAR, настройки администраторского списка и поисковые префиксы WCALKEY, WCALTITLE, WCALTIMEZONE.
• Добавлены PHPDoc @method для публичных __call функций.
• OnBeforeSave нормализует запись календаря и обновляет индексные поля перед сохранением.

modules/WorkCalendar/__call/*.inc

• Основной код функций размещен в __call, а не в api.php.
• Добавлены чтение системных definitions, нормализация и валидация календаря, расчет рабочих окон, проверка рабочего момента, поиск следующего рабочего времени, прибавление рабочей длительности и расчет рабочей длительности между датами.
• Добавлены resolver доступности ресурсов, dry-run impact report, HealthCheck definition, преобразование записи в definition, обновление индексов записи и описание переменных редактора.

modules/WorkCalendar/system/work_calendars.json

• Новый системный JSON с календарями DEFAULT~~5X2 и ALWAYS~~24X7.
• Описаны пример holiday pack и профили потребителей TASKS~~DEFAULT, QUEUE~~24X7.

modules/WorkCalendar/Tests/Module.inc

• Новый TestA safe-read тест модуля.
• Проверяются нормализация расписания, рабочие и нерабочие интервалы, перенос срока через выходные, расчет рабочей длительности, исключения, masked availability, impact report, HealthCheck, системный fallback GetCalendarByKey, чтение in-memory записи и обновление индексных полей.

modules/WorkCalendar/Help/Root.md modules/WorkCalendar/Help/Purpose.md modules/WorkCalendar/Help/AdminGuide.md

• Новые Help-страницы для назначения модуля, границ ответственности и администрирования календарей.
• Описаны базовые правила настройки календаря, исключений, availability overlays, on-call и change/freeze windows.

modules/WorkCalendar/Formats/brief.pft128

• Новый краткий формат заголовка записи календаря: выводит название календаря, а при его отсутствии ключ.

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

1.1. 🔗 blocks: I128-2805

1.2. 🔗 blocks: I128-2822

1.3. 🔗 blocks: I128-2839

1.4. 🔗 blocks: I128-2793

1.5. 🔗 blocks: I128-2795

1.6. 🔗 blocks: I128-2797

1.7. 🔗 blocks: I128-2798

1.8. 🔗 blocks: I128-2799

1.9. 🔗 blocks: I128-2813

1.10. 🔗 blocks: I128-2818