js/types.js - master - Starolat/DeepDive

js/types.js
2 382 строки142 KB
Starolat Sergei
feat: модальное окно «Работы 4 уровня» для гамаков в Анализе отклонений
02 авг 2026, 12:48
02 авг 2026, 12:48edc77bf
// @ts-check
/**
 * @fileoverview JSDoc Type Definitions for DeepDive Analytics
 * Single Source of Truth for all data contracts
 * @version 1.4.0
 */

// ============================================================================
// Domain Models - Primavera P6 Entities
// ============================================================================

/**
 * Проект (график работ)
 * @typedef {Object} Project
 * @property {string} projectId - Уникальный ID проекта (например, "PRJ-001")
 * @property {string} name - Название проекта
 * @property {string} [description] - Описание проекта
 * @property {string} startDate - Дата начала проекта (ISO 8601)
 * @property {string} endDate - Дата окончания проекта (ISO 8601)
 * @property {'active'|'closed'|'template'} status - Статус проекта
 * @property {string} [dataDate] - Дата актуализации графика (Data Date / LAST_RECALC_DATE из Primavera)
 */

/**
 * WBS (Work Breakdown Structure) - иерархическое разбиение работ
 * @typedef {Object} WBS
 * @property {number} wbsId - Уникальный ID WBS узла (Oracle NUMBER)
 * @property {number} projectId - Ссылка на проект (PROJ_ID)
 * @property {number} [parentId] - ID родительского узла (NULL для корня)
 * @property {string} code - Код WBS (например, "1.2.3")
 * @property {string} name - Название узла
 * @property {number} [seqNum] - Порядковый номер (SEQ_NUM из PROJWBS)
 * @property {number} [level] - Уровень в иерархии
 * @property {'current'|'target'} [scheduleType] - Тип графика (текущий/целевой)
 * @property {string} [startDate] - Агрегированная дата начала (минимальная по поддереву)
 * @property {string} [endDate] - Агрегированная дата окончания (максимальная по поддереву)
 */

/**
 * Работа графика (Activity/Task)
 * @typedef {Object} Activity
 * @property {number} id - Уникальный ID работы (TASK_ID)
 * @property {'current'|'target'} [scheduleType] - Тип графика (текущий/целевой)
 * @property {string} taskName - Название работы
 * @property {string} startDate - Дата начала (YYYY-MM-DD)
 * @property {string} endDate - Дата окончания (YYYY-MM-DD)
 * @property {string} [actualStartDate] - Фактическая дата начала (YYYY-MM-DD)
 * @property {string} [actualEndDate] - Фактическая дата окончания (YYYY-MM-DD)
 * @property {number} [duration] - Длительность в днях
 * @property {number} [totalFloat] - Общий резерв (дней)
 * @property {number} [freeFloat] - Свободный резерв (дней)
 * @property {string} [taskType] - Тип задачи (TASK_TYPE из Primavera, например "TT_LOE")
 * @property {string} [cstrType] - Тип первого ограничения (CSTR_TYPE)
 * @property {string} [cstrDate] - Дата первого ограничения (YYYY-MM-DD)
 * @property {string} [cstrType2] - Тип второго ограничения (CSTR_TYPE2)
 * @property {string} [cstrDate2] - Дата второго ограничения (YYYY-MM-DD)
 * @property {string} [responsible] - Ответственный
 * @property {number} [wbsId] - Ссылка на WBS (WBS_ID)
 * @property {number} [projectId] - Ссылка на проект (PROJ_ID)
 * @property {number} [calendarId] - Ссылка на рабочий календарь (CLNDR_ID, SYS-025)
 * @property {string} [activityCode] - Код работы в проекте (TASK_CODE)
 * @property {number} [totalManhours] - Общие трудозатраты (labor): сумма actual + remaining units
 * @property {number} [actualManhours] - Фактические трудозатраты (labor): сумма actual units
 * @property {number} [remainingManhours] - Оставшиеся трудозатраты (labor): сумма remaining units
 * @property {number} [currentTotalManhours] - Общие трудозатраты текущего графика по activityCode (cross-schedule baseline)
 * @property {number} [targetTotalManhours] - Общие трудозатраты целевого графика по activityCode (cross-schedule baseline)
 * @property {number} [cumulativeCurrentTotalManhours] - Накопительные трудозатраты текущего графика (из TimeLinePanel)
 * @property {number} [cumulativeTargetTotalManhours] - Накопительные трудозатраты целевого графика (из TimeLinePanel)
 * @property {number} [cumulativeCurrentPercent] - Процент накопительных трудозатрат текущего графика относительно ВСЕГО ТРЗ текущего
 * @property {number} [cumulativeTargetPercent] - Процент накопительных трудозатрат целевого графика относительно ВСЕГО ТРЗ целевого
 */

/**
 * Ресурс (человек, механизм, материал)
 * @typedef {Object} Resource
 * @property {number} resourceId - Уникальный ID ресурса (RSRC_ID)
 * @property {string} name - Название ресурса
 * @property {'labor'|'nonlabor'|'material'} type - Тип ресурса
 * @property {string} [unit] - Единица измерения
 * @property {number} [unitId] - ID единицы измерения
 * @property {number} [parentId] - ID родительского ресурса
 * @property {boolean} [isActive] - Активен ли ресурс
 */

/**
 * Назначение ресурса на работу
 * @typedef {Object} ResourceAssignment
 * @property {number} assignmentId - Уникальный ID назначения (TASKRSRC_ID)
 * @property {number} activityId - Ссылка на работу (TASK_ID)
 * @property {number} [resourceId] - Ссылка на ресурс (RSRC_ID)
 * @property {string} [resourceType] - Тип ресурса (RSRC_TYPE из TASKRSRC)
 * @property {number} [roleId] - ID роли
 * @property {number} [targetUnits] - Целевое количество единиц
 * @property {number} [actualUnits] - Фактическое количество
 * @property {number} [remainingUnits] - Оставшееся количество
 * @property {number} [targetCost] - Целевая стоимость
 * @property {number} [actualCost] - Фактическая стоимость
 * @property {number} [remainingCost] - Оставшаяся стоимость
 * @property {number} [costPerUnit] - Стоимость за единицу
 * @property {string} [startDate] - Дата начала (YYYY-MM-DD)
 * @property {string} [endDate] - Дата окончания (YYYY-MM-DD)
 */

/**
 * Период распределения ресурса (неделя/месяц)
 * @typedef {Object} ResourceAssignmentSpreadPeriod
 * @property {string} startDate - Дата начала периода (ISO 8601)
 * @property {string} endDate - Дата окончания периода (ISO 8601)
 * @property {number} [actualUnits] - Фактические единицы за период
 * @property {number} [remainingUnits] - Оставшиеся единицы за период
 * @property {number} [targetUnits] - Целевые единицы за период
 */

/**
 * Распределение ресурса по периодам (ответ от API)
 * @typedef {Object} ResourceAssignmentSpread
 * @property {number} resourceAssignmentObjectId - ID назначения ресурса (TASKRSRC_ID). API Primavera возвращает поле ResourceAssignmentObjectId.
 * @property {ResourceAssignmentSpreadPeriod[]} periods - Массив периодов
 */

// ============================================================================
// JS Data Engine Types (SYS-014, SYS-015, SYS-016)
// ============================================================================

/**
 * Рабочий календарь Primavera P6 (SYS-025).
 * Хранятся только рабочие дни; отсутствие ключа = нерабочий день.
 * @typedef {Object} WorkCalendar
 * @property {number} calendarId - Уникальный ID календаря (CLNDR_ID)
 * @property {string} name - Название календаря (CLNDR_NAME)
 * @property {number} dayHrCnt - Часов в рабочем дне (DAY_HR_CNT)
 * @property {Map<number, number>} workHoursByDay - days since epoch → рабочие часы; нет ключа = нерабочий день
 */

/**
 * Колоночное хранение spread-данных в DataIndexer.
 * @typedef {Object} SpreadColumnarData
 * @property {Int32Array} assignmentIds - ID назначений ресурсов
 * @property {Int32Array} weekIndices - Индексы недель
 * @property {Float64Array} targetUnits - Целевые единицы
 * @property {Float64Array} actualUnits - Фактические единицы
 * @property {Float64Array} remainingUnits - Оставшиеся единицы
 */

/**
 * In-memory индексы базы данных (DataIndexer, SYS-014).
 * @typedef {Object} DatabaseIndexes
 * @property {string} databaseId - Уникальный ID базы
 * @property {string} name - Отображаемое имя
 * @property {'api'|'file'} source - Источник данных
 * @property {string} createdAt - ISO-8601 timestamp создания
 * @property {Map<number, Project>} projectsById - Проекты по ID
 * @property {Map<number, WBS>} wbsById - WBS по ID
 * @property {Map<number, Activity>} activitiesById - Все работы по ID
 * @property {Map<'current'|'target', Map<number, Activity>>} activitiesBySchedule - Работы по типу графика
 * @property {Int32Array} allActivityIds - Все ID работ
 * @property {Map<number, CodeType>} codeTypeById - Типы кодов по ID
 * @property {Map<number, CodeValue>} codeValueById - Значения кодов по ID
 * @property {Map<number, Map<number, CodeValue>>} codeValuesByType - Значения по typeId
 * @property {Map<number, Set<number>>} activitiesByCodeValue - Работы по valueId
 * @property {Map<number, Map<number, number>>} activityCodesByType - activityId -> {typeId -> valueId}
 * @property {Map<number, Resource>} resourcesById - Ресурсы по ID
 * @property {Map<number, ResourceAssignment>} assignmentsById - Назначения по ID
 * @property {Map<number, ResourceAssignment[]>} assignmentsByActivity - Назначения по работе
 * @property {Map<number, ResourceAssignment[]>} assignmentsByResource - Назначения по ресурсу
 * @property {Map<string, MaterialDelivery>} materialDeliveriesById - Поставки материалов по ID
 * @property {Map<string, MaterialDeliverySource>} materialDeliverySourcesById - Источники реестров поставок по ID
 * @property {Map<number, MaterialDelivery[]>} materialDeliveriesByActivity - Поставки по работе
 * @property {Map<number, MaterialDelivery[]>} materialDeliveriesByResource - Поставки по ресурсу
 * @property {Map<string, MaterialDelivery[]>} materialDeliveriesByMaterialCode - Поставки по коду МТР
 * @property {Map<string, MaterialDelivery[]>} materialDeliveriesBySource - Поставки по источнику реестра
 * @property {Map<number, number>} materialDeliveryQtyByWeek - Суммарные поставки по неделям (weekIndex -> qty)
 * @property {Map<string, Map<number, number>>} materialDeliveryQtyByMaterialWeek - Поставки по материалу и неделе
 * @property {SpreadColumnarData} spread - Колоночные spread-данные
 * @property {Map<number, {start: number, end: number}>} spreadIndexByAssignment - Диапазон spread по назначению (spread отсортирован по assignmentId)
 * @property {Map<number, number[]>} spreadIndexByWeek - Индексы строк spread по неделе
 * @property {WeekInfo[]} weeks - Все недели проекта
 * @property {number} minWeekIndex - Минимальный weekIndex
 * @property {number} maxWeekIndex - Максимальный weekIndex
 * @property {Map<number, Set<number>>} wbsTree - WBS дерево: wbsId -> Set<childWbsId>
 * @property {Map<number, Set<number>>} activitiesByWbs - Работы по WBS: wbsId -> Set<activityId>
 * @property {Map<number, Set<number>>} wbsDescendantsCache - Кэш потомков WBS
 * @property {GanttRelationship[]} [relationships] - Связи работ (опционально)
 * @property {Map<number, WorkCalendar>} calendarsById - Рабочие календари по ID (SYS-025)
 */

/**
 * Распарсенные данные .dddb файла (BinaryDeserializer, SYS-016).
 * @typedef {Object} ParsedDDDB
 * @property {DDDHeader} header - Заголовок файла
 * @property {Project[]} projects - Проекты
 * @property {WBS[]} wbs - WBS узлы
 * @property {CodeType[]} codeTypes - Типы кодов
 * @property {CodeValue[]} codeValues - Значения кодов
 * @property {Activity[]} activities - Работы
 * @property {CodeAssignment[]} codeAssignments - Назначения кодов
 * @property {Resource[]} resources - Ресурсы
 * @property {ResourceAssignment[]} resourceAssignments - Назначения ресурсов
 * @property {SpreadColumnarData} spread - Spread-строки (колоночные массивы)
 * @property {MaterialDeliverySource[]} [materialDeliverySources] - Источники реестров поставок материалов
 * @property {MaterialDelivery[]} [materialDeliveries] - Поставки материалов
 * @property {GanttRelationship[]} [relationships] - Связи работ
 * @property {WorkCalendar[]} [calendars] - Рабочие календари (v2.7.0+, опционально; undefined если таблица 9 отсутствует)
 * @property {string} [name] - Имя базы
 */

// ============================================================================
// Project Compare Types (COMP-034)
// ============================================================================

/**
 * Источник данных одной стороны сравнения.
 * @typedef {Object} CompareSide
 * @property {'active'|'file'} origin - 'active' = активная БД приложения, 'file' = загруженный в модалке файл
 * @property {string} name - Имя файла / БД
 * @property {ParsedDDDB} data - Распарсенные данные проекта
 * @property {string|null} loadedAt - ISO-дата загрузки
 */

/**
 * Режим сравнения: какие графики сопоставляются.
 * 'current' — текущие графики обоих файлов; 'target' — целевые планы обоих файлов.
 * @typedef {'current'|'target'} CompareScheduleMode
 */

/**
 * Разрез сравнения ресурсов.
 * 'labor' — трудозатраты (Resource.type = 'labor'|'nonlabor'),
 * 'material' — физобъёмы (Resource.type = 'material').
 * @typedef {'labor'|'material'} CompareResourceKind
 */

/**
 * Строка результата сравнения: назначение ресурса на работу, сматченное между файлами.
 * @typedef {Object} AssignmentDiffRow
 * @property {string} activityCode - Код работы (ключ матчинга)
 * @property {string} activityName - Наименование работы
 * @property {string} resourceKey - Ключ ресурса (resourceName, т.к. id между файлами нестабилен)
 * @property {string} resourceName
 * @property {CompareResourceKind} kind
 * @property {number|null} unitsA - Количество в Проекте 1 (null — назначения нет)
 * @property {number|null} unitsB - Количество в Проекте 2 (null — назначения нет)
 * @property {number} delta - unitsB - unitsA (null трактуется как 0)
 * @property {number|null} deltaPercent - Δ в % от unitsA (null если unitsA = 0/null)
 * @property {'added'|'removed'|'changed'|'same'} changeType
 */

/**
 * Строка diff состава работ.
 * @typedef {Object} ActivityDiffRow
 * @property {string} activityCode
 * @property {string} activityName - Из того файла, где работа присутствует
 * @property {'added'|'removed'} changeType - added = только в П2, removed = только в П1
 */

/**
 * Сводка сравнения.
 * @typedef {Object} CompareSummary
 * @property {number} activitiesAdded - Работ добавлено в П2 (в выбранном режиме)
 * @property {number} activitiesRemoved - Работ удалено из П1 (в выбранном режиме)
 * @property {number} activitiesChanged - Работ с хотя бы одним изменённым назначением
 * @property {number} assignmentsAdded
 * @property {number} assignmentsRemoved
 * @property {number} assignmentsChanged
 * @property {number} totalDelta - ΣΔ по текущему разрезу
 */

/**
 * Результат сравнения двух версий проекта (ProjectCompareService.computeProjectDiff).
 * @typedef {Object} ProjectCompareResult
 * @property {ActivityDiffRow[]} activityDiffRows - Diff состава работ выбранного режима
 * @property {AssignmentDiffRow[]} rows - Diff назначений ресурсов
 * @property {CompareSummary} summary - Сводка
 */

/**
 * Заголовок .dddb файла.
 * @typedef {Object} DDDHeader
 * @property {string} magic - "DDDB"
 * @property {number} version - uint32, encoded major/minor/patch
 * @property {number} flags - uint32
 * @property {number} createdAt - uint64 timestamp ms
 * @property {number} tableCount - uint32
 */

/**
 * Запись директории таблиц .dddb.
 * @typedef {Object} DDDTableDirectoryEntry
 * @property {number} tableId - uint32
 * @property {number} offset - uint64
 * @property {number} length - uint64
 */

/**
 * Опции построения индексов (DataIndexer, SYS-014).
 * @typedef {Object} BuildIndexesOptions
 * @property {'current'|'target'} [scheduleType] - Тип загружаемого графика
 * @property {string} [existingDatabaseId] - Добавить в существующую БД (current+target)
 */

/**
 * Опции сериализации .dddb (BinarySerializer, SYS-015).
 * @typedef {Object} SerializerOptions
 * @property {number} [version] - Целевая версия формата
 * @property {boolean} [includeRelationships] - Включить связи работ
 * @property {boolean} [includeCalendars] - Включить рабочие календари (SYS-025, default: true)
 */

/**
 * Опции десериализации .dddb (BinaryDeserializer, SYS-016).
 * @typedef {Object} DeserializerOptions
 * @property {string} [name] - Имя базы (если не в файле)
 */

// ============================================================================
// Activity Codes - Глобальные справочники
// ============================================================================

/**
 * Тип кода (справочник)
 * @typedef {Object} CodeType
 * @property {number} typeId - ID справочника (ACTV_CODE_TYPE_ID)
 * @property {string} name - Название (например, "Территориальная зона")
 * @property {number} [maxLength] - Максимальная длина значения
 * @property {boolean} [isRequired] - Обязательность заполнения
 * @property {'AS_Global'|'AS_EPS'|'AS_Project'} [scope] - Область видимости
 * @property {number} [projectId] - ID проекта для project-scoped
 * @property {'current'|'target'} [scheduleType] - Тип графика
 */

/**
 * Значение кода
 * @typedef {Object} CodeValue
 * @property {number} valueId - ID значения (ACTV_CODE_ID)
 * @property {number} typeId - Ссылка на справочник (ACTV_CODE_TYPE_ID)
 * @property {string} shortName - Короткое имя (код)
 * @property {string} description - Текст (например, "Зона А (Север)")
 * @property {string} [color] - HEX цвет для графиков (например, "#FF6B6B")
 * @property {number} [sortOrder] - Порядок сортировки
 * @property {number} [parentId] - ID родительского значения
 * @property {'current'|'target'} [scheduleType] - Тип графика
 */

/**
 * Назначение кода на работу
 * @typedef {Object} CodeAssignment
 * @property {number} activityId - Ссылка на работу (TASK_ID)
 * @property {number} codeTypeId - Ссылка на тип кода (ACTV_CODE_TYPE_ID)
 * @property {number} codeValueId - Ссылка на значение кода (ACTV_CODE_ID)
 * @property {number} [projectId] - ID проекта
 */

/**
 * Выбранное значение внутри фильтра по Activity Code (FEAT-004)
 * @typedef {Object} CodeFilterValueItem
 * @property {number} valueId - ID значения (ACTV_CODE_ID)
 * @property {string} valueName - Название значения
 * @property {string} [color] - HEX цвет значения
 */

/**
 * Активный фильтр по коду работы (COMP-003, FEAT-004)
 * @typedef {Object} CodeFilterItem
 * @property {string} id - Уникальный ID фильтра (`filter-${codeTypeId}`)
 * @property {number} codeTypeId - ID справочника (ACTV_CODE_TYPE_ID)
 * @property {string} codeTypeName - Название справочника
 * @property {number[]} codeValueIds - IDs активных (включённых) значений (ACTV_CODE_ID)
 * @property {number[]} disabledCodeValueIds - IDs выключенных, но не удалённых значений
 * @property {CodeFilterValueItem[]} codeValues - Полные данные всех выбранных значений (active + disabled)
 * @property {boolean} enabled - Включён ли фильтр
 * @property {'user'|'level'|'mixed'} [source] - Источник фильтра: user (ручной), level (scope уровня), mixed (объединённый)
 * @property {number} [codeValueId] - DEPRECATED: ID первого выбранного значения (для backward compat)
 * @property {string} [codeValueName] - DEPRECATED: название первого значения
 * @property {string} [color] - DEPRECATED: HEX цвет первого значения
 */

/**
 * Доступный справочник для фильтрации с развёрнутым списком значений (COMP-003)
 * @typedef {Object} AvailableCodeType
 * @property {number} typeId - ID справочника
 * @property {string} name - Название справочника
 * @property {CodeValue[]} values - Доступные значения кодов
 * @property {boolean} expanded - Развёрнут ли список значений
 * @property {boolean} isLoading - Загружаются ли значения
 */

/**
 * Доступный справочник с развёрнутыми значениями (COMP-018)
 * @typedef {Object} CodePickerItem
 * @property {number|string} typeId - ID справочника либо строковый ID псевдо-справочника (например, 'resource')
 * @property {string} name - Название справочника
 * @property {CodeValue[]} values - Доступные значения
 * @property {boolean} isLoading - Загружаются ли значения
 * @property {boolean} [isPseudo] - Является ли псевдо-справочником (например, ресурс)
 */

/**
 * Состояние выбора в режиме value (COMP-018, FEAT-004)
 * @typedef {Object} CodePickerSelection
 * @property {number|string} typeId
 * @property {string} typeName
 * @property {number} valueId
 * @property {string} valueName
 * @property {string} [color]
 * @property {boolean} ctrlKey - Выбрано с удержанием Ctrl/Cmd (множественный выбор)
 */

/**
 * Состояние панели фильтров (COMP-003)
 * @typedef {Object} FilterPanelState
 * @property {CodeFilterItem[]} activeFilters - Активные фильтры
 * @property {AvailableCodeType[]} availableTypes - Доступные справочники
 * @property {boolean} isLoading - Загрузка данных
 */

/**
 * Информация о загруженной базе данных
 * @typedef {Object} DatabaseInfo
 * @property {string} id - ID базы
 * @property {string} name - Отображаемое имя
 * @property {'memory'|'file'} source - Источник
 * @property {string} [createdAt] - Дата создания
 * @property {string} [projectName] - Имя проекта
 */

/**
 * Метаданные базы данных
 * @typedef {Object} DatabaseMetadata
 * @property {string} schemaVersion - Версия схемы
 * @property {string} createdAt - Дата создания
 * @property {string} application - Название приложения
 * @property {string} [projectName] - Имя проекта Primavera
 * @property {number} [activityCount] - Количество работ
 * @property {number} [projectCount] - Количество проектов
 */

/**
 * Статистика загруженного проекта в разрезе одного графика (current/target).
 * @typedef {Object} ProjectScheduleStats
 * @property {number} wbsCount - Количество позиций WBS
 * @property {number} activityCount - Количество работ
 * @property {number} codeAssignmentCount - Количество назначенных кодов работ
 * @property {number} resourceAssignmentCount - Количество назначенных ресурсов
 */

/**
 * Статистика по одному проекту.
 * @typedef {Object} ProjectStatsItem
 * @property {string} projectId - Идентификатор проекта
 * @property {string} name - Название проекта
 * @property {ProjectScheduleStats} current - Статистика текущего графика
 * @property {ProjectScheduleStats} target - Статистика целевого графика
 */

/**
 * Результат запроса статистики по загруженному проекту.
 * @typedef {Object} ProjectStatsResult
 * @property {string} databaseName - Имя базы данных
 * @property {ProjectStatsItem[]} projects - Статистика по проектам
 * @property {ProjectScheduleStats} total - Итоговая статистика по всем проектам
 */

/**
 * Результат сравнения баз данных
 * @typedef {Object} ComparisonResult
 * @property {string} databaseId - ID базы
 * @property {string} name - Имя базы
 * @property {number} totalActivities - Всего работ
 * @property {number} completedActivities - Завершено
 * @property {number} inProgressActivities - В работе
 * @property {number} pendingActivities - В ожидании
 * @property {number} avgProgress - Средний прогресс (%)
 * @property {number} [overdueActivities] - Просрочено
 */

/**
 * Результат сравнения current vs target
 * @typedef {Object} CurrentVsTargetComparison
 * @property {string} activityCode - Код работы
 * @property {string} taskName - Название работы
 * @property {number} currentDuration - Длительность в текущем
 * @property {number} targetDuration - Длительность в целевом
 * @property {string} currentStartDate - Дата начала в текущем
 * @property {string} targetStartDate - Дата начала в целевом
 * @property {string} currentEndDate - Дата окончания в текущем
 * @property {string} targetEndDate - Дата окончания в целевом
 * @property {number} currentFloat - Общий резерв в текущем
 * @property {number} targetFloat - Общий резерв в целевом
 * @property {number} currentFreeFloat - Свободный резерв в текущем
 * @property {number} targetFreeFloat - Свободный резерв в целевом
 * @property {number} hasDifferences - Есть ли различия (1/0)
 */

/**
 * Параметры инициализации DataService
 * @typedef {Object} InitConfig
 * @property {string} [cdnUrl] - URL для загрузки внешних скриптов (deprecated, не используется в JS Data Engine)
 * @property {boolean} [useLocalStorage] - Использовать ли localStorage для кэша
 */

/**
 * Метрика для сравнения баз данных
 * @typedef {'progress'|'duration'|'count'|'overdue'} ComparisonMetric
 */

// ============================================================================
// COMP-009 Extension: Database Mappings and Load Sessions
// ============================================================================

/**
 * Маппинг проекта на базу данных (database_mappings row)
 * @typedef {Object} DatabaseMapping
 * @property {string} mappingId - UUID записи
 * @property {string} projectId - ID проекта DeepDive
 * @property {string} pairId - ID пары
 * @property {'current'|'target'} scheduleType - Тип графика
 * @property {string} databaseId - ID загруженной базы данных
 * @property {string} shortName - KSG ID (= short_name Primavera)
 * @property {string} loadedAt - ISO 8601
 * @property {number} [activityCount] - Количество загруженных работ
 * @property {'pending'|'loading'|'completed'|'error'|'unloaded'} status - Статус
 * @property {string} [errorMessage] - Сообщение об ошибке
 */

/**
 * Сессия загрузки (load_sessions row)
 * @typedef {Object} LoadSession
 * @property {string} sessionId - UUID сессии
 * @property {string} startedAt - ISO 8601
 * @property {string} [completedAt] - ISO 8601
 * @property {number} totalOperations - Всего операций
 * @property {number} successfulOperations - Успешно
 * @property {number} failedOperations - Ошибок
 * @property {number} cancelledOperations - Отменено
 * @property {string} [configSnapshot] - JSON с конфигурацией
 * @property {string} [authTokenHash] - Хеш токена авторизации
 */

// ============================================================================
// UI/Application Types
// ============================================================================

/**
 * Фильтр данных
 * @typedef {Object} Filter
 * @property {string} field - Поле для фильтрации (например, "status")
 * @property {string} condition - Условие ("Равно", "Не равно", "Содержит", "Начинается с", "Заканчивается на", "Больше", "Больше или равно", "Меньше", "Меньше или равно", "Между")
 * @property {string|string[]} value - Значение для фильтрации (для "Между" - массив [min, max])
 * @property {string} [id] - Уникальный ID фильтра (для удаления)
 */

/**
 * Определение столбца таблицы (data-grid)
 * @typedef {Object} TableColumn
 * @property {string} id - Уникальный идентификатор столбца
 * @property {string} header - Заголовок для отображения
 * @property {string} field - Поле в объекте данных строки
 * @property {'text'|'number'|'date'|'percent'|'wbs'} type - Тип данных
 * @property {number} width - Ширина столбца в px
 * @property {boolean} visible - Видимость столбца
 * @property {boolean} sortable - Можно ли сортировать
 * @property {boolean} filterable - Можно ли фильтровать
 * @property {Function} [formatter] - Функция форматирования значения
 * @property {string|function(Object): string} [cellClass] - CSS-класс ячейки (строка или функция от data)
 * @property {string|function(Object): string} [cellStyle] - Inline-стили ячейки (строка или функция от data)
 * @property {boolean} [isTreeColumn=false] - Колонка отрисовывается как дерево (indent + expand)
 * @property {function(Object): boolean} [dimmer] - Функция затемнения ячейки
 */

/**
 * Элемент данных таблицы (data-grid)
 * @typedef {Object} TableRow
 * @property {string} type - Тип строки (произвольный идентификатор домена)
 * @property {string} id - Уникальный ID
 * @property {number} level - Уровень вложенности
 * @property {boolean} hasChildren - Есть ли дочерние элементы
 * @property {Object} data - Исходные данные строки
 * @property {string} displayName - Отображаемое имя
 * @property {string} [parentId] - ID родительской строки (для flat tree)
 */

/**
 * Автофильтр для столбца (Excel-like)
 * @typedef {Object} AutoFilter
 * @property {string} columnId - ID столбца
 * @property {string} field - Поле данных
 * @property {'equals'|'notEquals'|'contains'|'startsWith'|'endsWith'|'greaterThan'|'greaterOrEqual'|'lessThan'|'lessOrEqual'|'between'} operator - Оператор
 * @property {string|number|Date|Array<string|number>} value - Значение фильтра
 * @property {boolean} isActive - Активен ли фильтр
 */

/**
 * Правило сортировки таблицы
 * @typedef {Object} SortRule
 * @property {string} columnId - ID столбца
 * @property {'asc'|'desc'} direction - Направление сортировки
 */

/**
 * Опции копирования таблицы в буфер обмена
 * @typedef {Object} CopyOptions
 * @property {boolean} [includeHeaders=true] - Включать ли заголовки
 * @property {boolean} [expandedOnly=false] - Только развёрнутые узлы
 * @property {string} [delimiter='\t'] - Разделитель
 * @property {'tsv'|'csv'} [format='tsv'] - Формат
 * @property {string[]} [columns] - Конкретные столбцы
 */

/**
 * Группировка данных (v2.1.0)
 * @typedef {Object} Grouping
 * @property {'code'|'resource'} kind - Тип группировки (code — по Activity Code, resource — по материальному ресурсу)
 * @property {string} field - Поле/идентификатор для группировки (строковый alias typeId для code, 'resource' для resource)
 * @property {string} displayName - Отображаемое название
 * @property {number} level - Уровень группировки (1-based)
 * @property {number} [typeId] - ID справочника (ACTV_CODE_TYPE_ID), только для kind='code'
 * @property {boolean} enabled - Включена ли группировка
 */

/**
 * Сегмент пути группировки для построения иерархии
 * @typedef {Object} GroupingPathSegment
 * @property {string} key - Уникальный ключ сегмента
 * @property {string} displayName - Отображаемое название
 * @property {number|null} [codeValueId] - ID значения кода (только для kind='code')
 * @property {number|null} [resourceId] - ID ресурса (только для kind='resource')
 * @property {string} [color] - HEX цвет для визуализации
 */

/**
 * Результат группировки
 * @typedef {Object} GroupedResult
 * @property {string} key - Ключ группы
 * @property {string} displayName - Отображаемое название
 * @property {number} count - Количество элементов
 * @property {Activity[]} items - Элементы группы
 * @property {Object} [aggregates] - Агрегированные значения
 */

/**
 * Метрика для auto-уровня (единый GROUP BY по code_values)
 * @typedef {Object} AutoLevelMetric
 * @property {number} valueId - ID значения справочника
 * @property {string} shortName - Короткое имя (код)
 * @property {string} description - Описание
 * @property {string} color - HEX цвет
 * @property {number} sortOrder - Порядок сортировки
 * @property {number} count - Количество работ
 * @property {number} planManhours - Суммарные плановые трудозатраты
 * @property {number} factManhours - Суммарные фактические трудозатраты
 * @property {number} remainingManhours - Оставшиеся трудозатраты
 * @property {number} avgPercentComplete - Средний процент выполнения
 * @property {number} completedCount - Количество завершённых работ (только current)
 * @property {number} notStartedCount - Количество не начатых работ (только current)
 * @property {number} inProgressCount - Количество работ в процессе (только current)
 * @property {string|null} earliestStart - Минимальная дата начала (current)
 * @property {string|null} latestEnd - Максимальная дата окончания (current)
 * @property {string|null} targetEarliestStart - Минимальная дата начала (target)
 * @property {string|null} targetLatestEnd - Максимальная дата окончания (target)
 * @property {number} cumPlan - Накопленный план на дату отчёта (трудозатраты)
 * @property {number} cumFact - Накопленный факт на дату отчёта (трудозатраты)
 * @property {number} totalPlan - Общий план baseline (трудозатраты)
 * @property {number} totalFact - Общий план current (трудозатраты)
 * @property {Array<{weekIndex: number, weekStartDate?: string, weekEndDate?: string, planUnits: number, actualUnits: number, remainingUnits: number}>} [weeklyData] - Недельные данные по трудозатратам
 * @property {number} [planQty] - Плановое количество материала / объём (для material-домена)
 * @property {number} [actualQty] - Фактическое количество материала / объём (для material-домена)
 * @property {string} [unitName] - Единица измерения материала (для material-домена)
 * @property {number} [activityCount] - Количество работ (алиас для count, удобен для material-домена)
 */

/**
 * KPI метрика
 * @typedef {Object} KPIData
 * @property {number} total - Всего работ
 * @property {number} completed - Завершено
 * @property {number} inProgress - В работе
 * @property {number} pending - В ожидании
 * @property {number} overdue - Просрочено
 */

/**
 * Конфигурация модуля (панели)
 * @typedef {Object} ModuleConfig
 * @property {string} id - ID модуля
 * @property {string} title - Заголовок модуля
 * @property {boolean} [isCollapsed] - Свернут ли модуль
 * @property {boolean} [isDockedOut] - Откреплен ли модуль
 * @property {{x: number, y: number}} [position] - Позиция (для открепленных)
 * @property {{width: number, height: number}} [size] - Размер (для открепленных)
 */

/**
 * Макет (Layout) - сохраненная конфигурация UI
 * @typedef {Object} Layout
 * @property {string} name - Название макета
 * @property {LayoutConfig} config - Конфигурация
 * @property {string} createdAt - Дата создания (ISO 8601)
 */

/**
 * Конфигурация макета
 * @typedef {Object} LayoutConfig
 * @property {ModuleConfig[]} modules - Конфигурации модулей
 * @property {boolean} sidebarVisible - Видимость сайдбара
 * @property {string} timestamp - Временная метка
 */

/**
 * Состояние приложения
 * @typedef {Object} AppState
 * @property {string} [currentProjectId] - ID текущего проекта
 * @property {string} [targetProjectId] - ID целевого проекта
 * @property {Filter[]} filters - Активные фильтры
 * @property {Grouping[]} groupings - Активные группировки
 * @property {Activity[]} data - Текущие данные
 */

// ============================================================================
// Event Detail Types
// ============================================================================

/**
 * Детали события обновления данных
 * @typedef {Object} DataUpdatedDetail
 * @property {Activity[]} data - Обновленные данные
 * @property {number} timestamp - Время обновления
 * @property {string} [databaseId] - ID базы данных
 */

/**
 * Детали события изменения фильтра
 * @typedef {Object} FilterChangeDetail
 * @property {Filter[]} filters - Список активных фильтров
 * @property {'add'|'remove'|'set'|'clear'} action - Действие
 * @property {Filter} [changedFilter] - Измененный фильтр
 * @property {number} [index] - Индекс удаленного фильтра
 */

/**
 * Детали события изменения группировки
 * @typedef {Object} GroupingChangeDetail
 * @property {Grouping[]} groupings - Список активных группировок
 * @property {'add'|'remove'|'toggle'|'move'|'set'|'clear'} action - Действие
 * @property {Grouping} [grouping] - Измененная группировка
 * @property {number} [fromIndex] - Исходный индекс при action='move'
 * @property {number} [toIndex] - Целевой индекс при action='move'
 */

/**
 * Детали события готовности базы данных
 * @typedef {Object} DatabaseReadyDetail
 * @property {string} databaseId - ID базы данных
 * @property {string} name - Имя базы
 * @property {'memory'|'file'|'api'} source - Источник (memory=из API, file=из файла, api=legacy)
 * @property {string} [projectName] - Имя проекта (только при source='memory')
 */

/**
 * Детали события изменения активной базы данных
 * @typedef {Object} DatabaseChangedDetail
 * @property {string} databaseId - ID новой активной базы
 * @property {string} [previousDatabaseId] - ID предыдущей базы
 */

/**
 * Детали события изменения макета
 * @typedef {Object} LayoutChangeDetail
 * @property {'save'|'load'|'delete'|'toggle'} action - Действие
 * @property {Layout} [layout] - Макет (при save/load)
 * @property {string} [name] - Имя макета (при delete)
 * @property {boolean} [visible] - Видимость (при toggle)
 */

/**
 * Детали события загрузки проектов
 * @typedef {Object} LoadingCompleteDetail
 * @property {string[]} projectIds - ID загруженных проектов
 * @property {number} durationMs - Длительность загрузки (мс)
 * @property {number} [successfulCount] - Количество успешных
 * @property {number} [failedCount] - Количество неудачных
 */

/**
 * Детали события изменения статуса КСГ
 * @typedef {Object} KsgStatusChangeDetail
 * @property {string} projectId - ID проекта
 * @property {string} pairId - ID пары
 * @property {'current'|'target'} type - Тип графика
 * @property {boolean} loaded - Загружен ли
 */

/**
 * Узел дерева WBS для отображения в фильтре (COMP-015)
 * @typedef {Object} WbsTreeNode
 * @property {number} wbsId - Уникальный ID WBS узла
 * @property {number} [parentId] - ID родительского узла (NULL для корня)
 * @property {string} code - Код WBS (например, "1.2.3")
 * @property {string} name - Название узла
 * @property {number} level - Уровень в иерархии (0 = корень)
 * @property {number} [seqNum] - Порядковый номер для сортировки
 * @property {WbsTreeNode[]} children - Дочерние узлы
 * @property {boolean} expanded - Развёрнут ли узел
 * @property {boolean} selected - Выбран ли узел
 * @property {number} [activityCount] - Количество работ в поддереве
 */

/**
 * Детали события изменения WBS-фильтра (COMP-015)
 * @typedef {Object} WbsFilterChangeDetail
 * @property {number[]} selectedWbsIds - IDs выбранных WBS узлов (после дедупликации)
 * @property {number[]} effectiveWbsIds - Эффективные IDs после "поглощения" родителями
 * @property {'add'|'remove'|'clear'} action - Действие
 * @property {number} [changedWbsId] - ID изменённого узла
 */

/**
 * Элемент списка ресурсов для отображения в фильтре (COMP-026)
 * @typedef {Object} ResourceFilterItem
 * @property {number} resourceId - Уникальный ID ресурса (RSRC_ID)
 * @property {string} name - Название ресурса
 * @property {string} [shortName] - Короткое имя/код ресурса
 * @property {string} [unitName] - Единица измерения
 * @property {number} targetUnits - Сумма target_units назначений ресурса на работы current (с учётом глобальных фильтров)
 * @property {number} actualUnits - Сумма actual_units назначений ресурса на работы current (с учётом глобальных фильтров)
 */

/**
 * Детали события изменения фильтра по ресурсам (COMP-026)
 * @typedef {Object} ResourceFilterChangeDetail
 * @property {number[]} resourceFilterIds - IDs выбранных ресурсов
 * @property {'set'|'add'|'remove'|'toggle'|'clear'} action - Действие
 */

// ============================================================================
// Week Index Types (Вариант В: Precomputed Slices)
// ============================================================================

/**
 * Информация о недельном срезе
 * @typedef {Object} WeekInfo
 * @property {number} weekIndex — Глобальный индекс недели (разница в неделях от 1970-01-05)
 * @property {number} weekNumber — ISO номер недели в году (1–53)
 * @property {number} year — Год (по воскресенью недели)
 * @property {string} weekStart — Дата понедельника (YYYY-MM-DD)
 * @property {string} weekEnd — Дата воскресенья (YYYY-MM-DD)
 * @property {boolean} isPast — true если неделя полностью до data_date
 */

/**
 * Диапазон недель (фильтр)
 * @typedef {Object} WeekRange
 * @property {number|null} startIdx — Начальный weekIndex (null = без ограничения)
 * @property {number|null} endIdx — Конечный weekIndex (null = без ограничения)
 */

/**
 * Единый Data Date от FilterStateManager (mode decides source).
 * @typedef {Object} EffectiveDataDate
 * @property {'timeline'|'range'} mode — Источник даты: timeline (бегунок) или range (фильтр периода)
 * @property {number} [weekIdx] — weekIndex для mode='timeline'
 * @property {string} [weekEnd] — Дата воскресенья (YYYY-MM-DD) для mode='timeline'
 * @property {number|null} [startIdx] — Начальный weekIndex для mode='range' (null = от начала проекта)
 * @property {number|null} [endIdx] — Конечный weekIndex для mode='range' (null = до конца проекта)
 */

/**
 * Детали события изменения недельного диапазона
 * @typedef {Object} WeekRangeFilter
 * @property {number|null} startIdx — Начальный weekIndex
 * @property {number|null} endIdx — Конечный weekIndex
 * @property {string|null} startMonday — Дата начала диапазона (YYYY-MM-DD)
 * @property {string|null} endSunday — Дата окончания диапазона (YYYY-MM-DD)
 */

// ============================================================================
// SYS-006: FilterStateManager Types
// ============================================================================

/**
 * Полное сериализуемое состояние фильтров (SYS-006).
 * @typedef {Object} FilterState
 * @property {CodeFilterItem[]} codeFilters - Пользовательские фильтры по Activity Codes (включая disabled)
 * @property {CodeFilterItem[]} levelCodeFilters - Фильтры активного уровня (baseFilters, включая disabled)
 * @property {number[]} wbsFilterIds - IDs выбранных WBS узлов (после дедупликации)
 * @property {number[]} resourceFilterIds - IDs включённых материальных ресурсов (RSRC_ID, тип 'material')
 * @property {number[]} selectedResourceFilterIds - IDs всех выбранных ресурсов (включая disabled)
 * @property {number[]} disabledResourceFilterIds - IDs выбранных, но отключённых ресурсов
 * @property {boolean} showCurrent - Показывать текущий график (ТГ)
 * @property {boolean} showTarget - Показывать целевой график (ЦП)
 * @property {WeekRange} weekRange - Диапазон недель (startIdx/endIdx) или оба null
 * @property {boolean} weekRangeEnabled - Активен ли выбранный диапазон недель
 * @property {Grouping[]} groupings - Активные группировки (включая disabled)
 * @property {boolean} levelFiltersActive - Активны ли уровневые фильтры (true после setLevelCodeFilters)
 */

/**
 * Детали события filter-state-change (SYS-006).
 * @typedef {Object} FilterStateChangeDetail
 * @property {string} action - Тип действия:
 *   'code-filter-set' | 'code-filter-remove' | 'code-filter-toggle' | 'code-filter-clear' | 'code-filter-replace' |
 *   'level-filter-change' |
 *   'wbs-filter-change' | 'resource-filter-change' | 'schedule-mode-change' | 'grouping-change' | 'week-filter-change'
 * @property {FilterState} state - Полный текущий snapshot (сериализованный)
 * @property {CodeFilterItem} [filter] - Изменённый/добавленный/удалённый фильтр (для code-* actions)
 * @property {number[]} [ids] - Новые WBS IDs (для wbs-filter-change)
 * @property {number[]} [resourceIds] - Новые Resource IDs (для resource-filter-change)
 * @property {boolean} [showCurrent] - Новое значение (для schedule-mode-change)
 * @property {boolean} [showTarget] - Новое значение (для schedule-mode-change)
 * @property {Grouping[]} [groupings] - Новые группировки (для grouping-change)
 * @property {number|null} [startIdx] - Начальный weekIndex (для week-filter-change)
 * @property {number|null} [endIdx] - Конечный weekIndex (для week-filter-change)
 * @property {string|null} [startMonday] - Дата начала диапазона (для week-filter-change)
 * @property {string|null} [endSunday] - Дата окончания диапазона (для week-filter-change)
 * @property {string|null} [weekEnd] - Legacy: неделя воскресенья (для week-filter-change, backward compat)
 */

/**
 * Идентификатор вкладки в <filter-resource-tabs> (COMP-027).
 * @typedef {'filters'|'resources'} FilterResourceTabId
 */

/**
 * Конфигурация компонента <filter-resource-tabs> (COMP-027).
 * @typedef {Object} FilterResourceTabsConfig
 * @property {FilterResourceTabId} activeTab - Активная вкладка ('filters' = Коды, 'resources' = Ресурсы)
 */

/**
 * Chip активного фильтра по материальному ресурсу в <filter-resource-tabs> (COMP-027).
 * @typedef {Object} ActiveResourceFilterChip
 * @property {number} resourceId - ID ресурса (RSRC_ID)
 * @property {string} name - Отображаемое название ресурса
 * @property {string} [shortName] - Короткое название ресурса
 */

/**
 * Детали события изменения единого Data Date (data-date-change).
 * @typedef {Object} DataDateChangeDetail
 * @property {EffectiveDataDate} dataDate - Новый единый Data Date
 * @property {EffectiveDataDate} [previousDataDate] - Предыдущий Data Date (для diff)
 * @property {'timeline'|'range'|'timeline-init'|'range-reset'} reason - Причина изменения: timeline (движение бегунка), range (установка фильтра), timeline-init (инициализация при загрузке БД), range-reset (сброс фильтра)
 */

/**
 * Payload для установки фильтра по Activity Code (SYS-006).
 * @typedef {Object} CodeFilterPayload
 * @property {number} typeId - ID справочника (ACTV_CODE_TYPE_ID)
 * @property {string} typeName - Название справочника
 * @property {number} valueId - ID значения (ACTV_CODE_ID)
 * @property {string} valueName - Название значения
 * @property {string} [color] - HEX цвет значения
 */

// ============================================================================
// AppSettingsModal Types (COMP-008)
// ============================================================================

/**
 * Проект Primavera из API
 * @typedef {Object} PrimaveraProject
 * @property {string} projectId - Уникальный ID проекта (например, "PRJ-001")
 * @property {string} name - Название проекта
 * @property {string} [description] - Описание проекта
 * @property {string} lastUpdated - Дата последнего обновления (ISO 8601)
 * @property {'active'|'closed'|'template'} status - Статус проекта
 * @property {number} [activityCount] - Количество работ
 */

/**
 * График (Schedule) проекта Primavera
 * @typedef {Object} Schedule
 * @property {string} scheduleId - Уникальный ID графика
 * @property {string} projectId - Ссылка на проект
 * @property {string} shortName - Короткое имя/код графика в Primavera (например, "Current_May2024")
 * @property {string} [fullName] - Полное название графика
 * @property {'current'|'target'} type - Тип графика: текущий или целевой (базовый)
 * @property {string} [dataDate] - Дата актуальности данных (Data Date)
 * @property {'pending'|'loading'|'completed'|'error'} status - Статус загрузки
 * @property {string} [databaseId] - ID созданной БД в JS Data Engine (после загрузки)
 */

/**
 * Пара графиков КСГ (Schedule Pair) - v0.7.0+
 * @typedef {Object} SchedulePair
 * @property {string} pairId - Уникальный ID пары (uuid)
 * @property {string} projectId - Ссылка на проект DeepDive
 * @property {string} currentScheduleId - Идентификатор текущего графика (= KSG ID = short_name Primavera)
 * @property {string} [targetScheduleId] - Идентификатор целевого графика (= KSG ID = short_name Primavera)
 * @property {string} [currentDescription] - Описание текущего графика
 * @property {string} [targetDescription] - Описание целевого графика
 * @property {boolean} currentKsgLoaded - Загружен ли КСГ для текущего графика
 * @property {boolean} targetKsgLoaded - Загружен ли КСГ для целевого графика
 * @property {string} [currentDataDate] - Дата актуальности текущего графика
 * @property {string} [targetDataDate] - Дата актуальности целевого графика
 * @property {'pending'|'loading'|'completed'|'error'|'cancelled'|'unloaded'} status - Статус загрузки пары
 * @property {string} [errorMessage] - Сообщение об ошибке загрузки
 * @property {boolean} isValid - Валидна ли пара (has targetScheduleId)
 */

/**
 * Проект DeepDive (пользовательская сущность)
 * @typedef {Object} DeepDiveProject
 * @property {string} projectId - Уникальный внутренний ID проекта (uuid)
 * @property {string} name - Название проекта
 * @property {SchedulePair[]} schedulePairs - Пары графиков КСГ
 * @property {boolean} expanded - Развёрнута ли карточка проекта
 * @property {string} createdAt - Дата создания (ISO 8601)
 * @property {string} [updatedAt] - Дата последнего обновления
 */

/**
 * Снимок проекта (Snapshot)
 * @typedef {Object} ProjectSnapshot
 * @property {string} snapshotId - Уникальный ID снимка
 * @property {string} projectId - Ссылка на проект
 * @property {string} scheduleId - Ссылка на график (Schedule)
 * @property {string} name - Отображаемое имя снимка
 * @property {string} createdAt - Дата создания снимка (ISO 8601)
 * @property {string} [description] - Описание снимка
 * @property {'pending'|'loading'|'completed'|'error'} status - Статус снимка
 * @property {string} [errorMessage] - Сообщение об ошибке
 * @property {string} [databaseId] - ID созданной БД в JS Data Engine
 */

/**
 * Состояние загрузки проектов
 * @typedef {Object} LoadingState
 * @property {boolean} isLoading - Идёт ли загрузка
 * @property {string[]} selectedProjectIds - Выбранные проекты
 * @property {string} [currentProjectId] - Текущий загружаемый проект
 * @property {string} [currentPairId] - Текущая загружаемая пара
 * @property {number} overallProgress - Общий прогресс (0-100)
 * @property {'idle'|'loading'|'completed'|'error'|'cancelled'} phase - Фаза загрузки
 * @property {string} [errorMessage] - Сообщение об ошибке
 * @property {Object.<string, ValidationError[]>} [validationErrors] - Ошибки валидации
 */

/**
 * Ошибка валидации
 * @typedef {Object} ValidationError
 * @property {string} code - Код ошибки
 * @property {string} message - Описание ошибки
 * @property {string} [pairId] - ID пары (если ошибка связана с парой)
 */

/**
 * Параметры сохранения файлов
 * @typedef {Object} SaveOptions
 * @property {string} filename - Имя файла
 * @property {string} [projectId] - ID проекта
 * @property {boolean} [asZip] - Сохранить как ZIP
 * @property {string} [zipFilename] - Имя ZIP файла
 */

/**
 * Настройки приложения (для экспорта/импорта)
 * @typedef {Object} AppSettings
 * @property {string} version - Версия формата настроек
 * @property {string} exportedAt - Дата экспорта (ISO 8601)
 * @property {string} [applicationVersion] - Версия приложения
 * @property {AppSettingsData} data - Данные настроек
 */

/**
 * Данные настроек приложения
 * @typedef {Object} AppSettingsData
 * @property {DeepDiveProject[]} projects - Список проектов DeepDive
 * @property {Schedule[]} [schedules] - Графики проектов (legacy)
 * @property {ProjectSnapshot[]} [snapshots] - Снимки проектов
 * @property {Filter[]} [filters] - Сохранённые фильтры
 * @property {Grouping[]} [groupings] - Сохранённые группировки
 * @property {UISettings} [ui] - Настройки UI
 * @property {ConnectionSettings} [connections] - Настройки подключений
 */

/**
 * Настройки UI
 * @typedef {Object} UISettings
 * @property {string} [theme] - Тема оформления
 * @property {Object} [layout] - Настройки layout
 */

/**
 * Настройки подключений
 * @typedef {Object} ConnectionSettings
 * @property {string} [primaveraApiUrl] - URL API Primavera
 * @property {string} [authToken] - Токен авторизации (encrypted)
 */

/**
 * Результат импорта настроек
 * @typedef {Object} SettingsImportResult
 * @property {boolean} success - Успешно ли импортировано
 * @property {string} [error] - Сообщение об ошибке
 * @property {number} importedProjects - Количество импортированных проектов
 * @property {number} importedPairs - Количество импортированных пар
 * @property {string[]} warnings - Предупреждения при импорте
 */

// ============================================================================
// COMP-009: PrimaveraDataLoader Types
// ============================================================================

/**
 * Конфигурация загрузки (UI options)
 * @typedef {Object} LoaderConfig
 * @property {string[]} shortNames - short_name проектов Primavera для загрузки
 * @property {string} authToken - Токен авторизации Primavera
 * @property {boolean} [autoSave=true] - Автоматически сохранять в файл
 * @property {string} [filenamePattern] - Шаблон для имени файла
 * @property {number} [parallelLoad=1] - Количество параллельных загрузок (1-3)
 * @property {boolean} [continueOnError=true] - Продолжать при ошибке
 */

/**
 * Операция загрузки одного графика
 * @typedef {Object} LoadOperation
 * @property {string} operationId - UUID операции
 * @property {string} projectId - ID проекта DeepDive
 * @property {string} projectName - Название проекта
 * @property {string} pairId - ID пары
 * @property {'current'|'target'} scheduleType - Тип графика
 * @property {string} shortName - KSG ID = short_name Primavera
 * @property {'pending'|'loading'|'completed'|'error'|'cancelled'} status
 * @property {number} progress - Прогресс 0-100
 * @property {string} [databaseId] - ID созданной БД
 * @property {number} [activityCount] - Количество загруженных работ
 * @property {string} [errorMessage] - Сообщение об ошибке
 * @property {AbortController} [abortController] - Для отмены операции
 */

/**
 * Результат batch загрузки
 * @typedef {Object} BatchLoadResult
 * @property {boolean} success - Успешна ли загрузка
 * @property {number} totalOperations - Всего операций
 * @property {number} successfulLoads - Успешно загружено
 * @property {number} failedLoads - Ошибок
 * @property {number} cancelledLoads - Отменено
 * @property {LoadOperation[]} operations - Детали по каждой операции
 * @property {string} [sessionId] - ID сессии
 * @property {number} totalDurationMs - Общая длительность
 */

/**
 * Прогресс загрузки для UI
 * @typedef {Object} LoadingProgress
 * @property {number} overallPercent - Общий прогресс (0-100)
 * @property {LoadOperation[]} operations - Все операции
 * @property {LoadingProgressSummary} summary - Сводка
 * @property {string} [currentPhase] - Текущая фаза
 */

/**
 * Сводка прогресса загрузки
 * @typedef {Object} LoadingProgressSummary
 * @property {number} total - Всего операций
 * @property {number} completed - Завершено
 * @property {number} loading - В процессе
 * @property {number} pending - В очереди
 * @property {number} failed - Ошибок
 */

// ============================================================================
// COMP-020: ProjectSummaryPanel Types
// ============================================================================

/**
 * Данные вехи для Summary-панели
 * @typedef {Object} MilestoneData
 * @property {string} name - Название вехи
 * @property {string|null} baselineFinishDate - Плановая дата окончания (YYYY-MM-DD)
 * @property {string|null} finishDate - Фактическая дата окончания (YYYY-MM-DD)
 * @property {string} objectId - Уникальный ID вехи
 */

/**
 * Прогресс по категории (Общий, ПИР, МТО, СМР, ПНР)
 * @typedef {Object} ProgressCategory
 * @property {number} accumulatedPlanPrevWeek - Накопленный план до отчётной даты (%)
 * @property {number} accumulatedFactPrevWeek - Накопленный факт до отчётной даты (%)
 * @property {number} periodPlanPrevWeek - План за отчётный период (%)
 * @property {number} periodFactPrevWeek - Факт за отчётный период (%)
 * @property {number} cumulativePlanCurrentWeek - Накопленный план текущей недели (%)
 * @property {number} cumulativeFactCurrentWeek - Накопленный факт текущей недели (%)
 * @property {number} delta - Отклонение факт от план (%)
 * @property {number|null} trend - Изменение дельты относительно предыдущего периода — null в MVP
 * @property {number} totalPlan - Общий плановый объём (трудозатраты)
 * @property {number} totalFact - Общий фактический объём (трудозатраты)
 * @property {string|null} startDate - Самое раннее начало работ (DD.MM.YYYY)
 * @property {string|null} endDate - Самое позднее окончание работ (DD.MM.YYYY)
 * @property {Array<{weekStartDate: string, weekEndDate: string, planUnits: number, actualUnits: number, remainingUnits: number}>} [weeklyDataTable] - Детализация по неделям
 * @property {number} [planQty] - Плановое количество материала / объём (для material-домена)
 * @property {number} [actualQty] - Фактическое количество материала / объём (для material-домена)
 * @property {string} [unitName] - Единица измерения материала (для material-домена)
 */

/**
 * Данные S-кривой
 * @typedef {Object} SCurveData
 * @property {string[]} xAxis - Метки оси X (недели, формат "DD.MM.YY" — понедельник недели)
 * @property {number[]} baseline - Базовый план (накопительные трудозатраты)
 * @property {(number|null)[]} actual - Факт (накопительные трудозатраты)
 * @property {(number|null)[]} forecast - Прогноз (факт + остаток)
 * @property {(number|null)[]} [trend] - LOESS-сглаженный тренд фактической кривой (%)
 * @property {(number|null)[]} [trendForecast] - Theil-Sen экстраполяция от последнего факта (%)
 * @property {boolean[]} [outliers] - Флаги выбросов по периодным трудозатратам (MAD)
 * @property {(number|null)[]} [confidenceUpper] - Верхняя граница доверительного интервала LOESS (%)
 * @property {(number|null)[]} [confidenceLower] - Нижняя граница доверительного интервала LOESS (%)
 * @property {{slope: number, intercept: number, estimatedFinishWeekIndex: number|null, estimatedFinishXIndex: number|null}} [theilSen] - Параметры регрессии и прогноз finish (xIndex — позиция в xAxis)
 * @property {'mixed'|'baseline'|'current'|'absolute'} [normalizationMode] - Применённый режим нормировки
 * @property {string} [reportDate] - Дата отчёта (YYYY-MM-DD), используется для отметки отчётной недели
 * @property {number} [reportWeekIdx] - Индекс недели даты отчёта (effectiveWeekIdx), используется для точного позиционирования markLine
 */

/**
 * Полный контракт данных для ProjectSummaryPanel
 * @typedef {Object} SummaryWidgetData
 * @property {string} projectName - Название проекта
 * @property {MilestoneData} techLaunchMilestone - Веха "Техзапуск"
 * @property {MilestoneData} smrMilestone - Контрольная веха (обычно "ВехаСМР")
 * @property {MilestoneData} [customMilestone] - Дополнительная веха из настроек
 * @property {{overall: ProgressCategory, pir: ProgressCategory, mto: ProgressCategory, smr: ProgressCategory, pnr: ProgressCategory}} progress - Прогресс по категориям
 * @property {SCurveData} sCurve - Данные S-кривой
 * @property {string} [reportDate] - Дата отчёта (YYYY-MM-DD), используется для отметки отчётной недели
 */

/**
 * Опции построения сводки
 * @typedef {Object} SummaryBuildOptions
 * @property {string} [reportDate] - Дата отчёта (YYYY-MM-DD), по умолчанию dataDate проекта
 * @property {string} [controlMilestone='ВехаСМР'] - Код контрольной вехи
 * @property {boolean} [isAdditionalStatus=false] - Дополнительный статус (Phase 2)
 * @property {string} [databaseId] - ID базы данных (если не активная)
 * @property {CodeFilterItem[]} [codeFilters] - Активные фильтры по Activity Codes (применяются ко всем виджетам)
 * @property {number[]} [wbsFilterIds] - IDs выбранных WBS узлов (включая потомков через RECURSIVE CTE)
 * @property {number[]} [resourceFilterIds] - IDs выбранных материальных ресурсов (RSRC_ID, тип 'material'). Применяется только к виджетам объёмов, НЕ к трудозатратам.
 * @property {WeekRange} [weekRange] - Диапазон недель (фильтрация через activity_weeks)
 * @property {'slice'|'range'} [calcMode] - Режим расчёта: slice=накоплено к дате (<= weekIdx), range=сумма внутри диапазона (BETWEEN startIdx AND endIdx)
 * @property {number} [dataDateWeekIdx] - weekIndex, используемый как Data Date при calcMode='slice' (обычно позиция бегунка timeline)
 * @property {'mixed'|'baseline'|'current'|'absolute'} [normalizationMode] - Режим нормировки S-кривой и прогресса: mixed=план от baseline, факт от current, baseline=всё от baseline total, current=всё от current total, absolute=абсолютные трудозатраты. По умолчанию берётся из config.DEFAULT_NORMALIZATION_MODE
 * @property {LevelContext} [levelContext] - Контекст уровня для drill-down (фильтр-стек + метаданные)
 * @property {Filter[]} [privateFilters] - Приватные фильтры виджета (применяются только к этому виджету)
 * @property {Filter[]} [filters] - Generic фильтры (drill-down stack, объединяются с codeFilters/wbsFilterIds/levelContext/privateFilters)
 * @property {'manhours'|'material'} [dataDomain='manhours'] - Домен данных виджета/уровня
 * @property {Filter[]} [baseFilters] - Implicit/base фильтры уровня (применяются после глобальных фильтров)
 */

// ============================================================================
// Level-Based Drill-Down Architecture Types (v1.3.0)
// ============================================================================

/**
 * Контекст уровня — передаётся виджетам для self-fetch
 * @typedef {Object} LevelContext
 * @property {number} levelIndex - Индекс уровня в стеке (0 = корень)
 * @property {string} levelId - Уникальный ID уровня (UUID)
 * @property {string} levelName - Отображаемое название уровня
 * @property {Filter[]} inheritedFilters - Фильтры, унаследованные от предыдущих уровней
 * @property {Filter[]} levelFilters - Фильтры, добавленные на этом уровне (privateFilters + mapFilters)
 * @property {string} [groupByField] - Поле группировки текущего уровня (если задано)
 * @property {string} [groupByDisplayName] - Отображаемое название группировки
 * @property {number|null} [parentWbsId] - ID родительского WBS для WBS-based drill-down
 * @property {string} [reportDate] - Дата отчёта (YYYY-MM-DD) для S-curve расчётов
 * @property {WeekRange} [weekRange] - Диапазон недель (фильтрация)
 * @property {'manhours'|'material'} [dataDomain='manhours'] - Домен данных уровня
 * @property {Filter[]} [baseFilters] - Implicit/base фильтры уровня
 */

/**
 * Конфигурация виджета-экземпляра в LevelLayoutPanel
 * @typedef {Object} WidgetInstanceConfig
 * @property {string} id - Уникальный ID экземпляра (UUID)
 * @property {string} componentTag - Tag веб-компонента (например, "summary-s-curve-widget")
 * @property {string} [title] - Заголовок виджета (переопределяет дефолтный)
 * @property {{x: number, y: number}} position - Позиция в CSS Grid (column / row)
 * @property {{width: number, height: number}} size - Размер в grid cells (colspan / rowspan)
 * @property {Object} [props] - Публичные свойства для передачи в виджет (например, { chartType: 'cumulative'|'weekly' } для summary-progress-widget)
 * @property {Filter[]} [privateFilters] - Фильтры, применяемые только к этому виджету
 * @property {boolean} [allowDrillDown=true] - Можно ли кликать для drill-down
 * @property {string} [drillDownTargetLevelId] - ID целевого уровня (если не следующий по порядку)
 * @property {'manhours'|'material'} [dataDomain='manhours'] - Домен данных виджета (runtime-производное, определяется по componentTag)
 */

/**
 * Правило перехода при drill-down
 * @typedef {Object} TransitionRule
 * @property {string} id - Уникальный ID правила (UUID)
 * @property {string} [fromWidgetId] - ID виджета-источника (WidgetInstanceConfig.id). Для авто-уровня может отсутствовать.
 * @property {string} [fromLevelId] - ID уровня-источника (опционально, для точности)
 * @property {string} toLevelId - ID целевого уровня
 * @property {string} [matchField] - Поле для exact match (например, "codeValueId")
 * @property {string} [matchValue] - Конкретное значение для match (если правило для одного значения)
 * @property {Filter[]} [mapFilters] - Дополнительные фильтры для применения на целевом уровне
 * @property {string} [mapGroupBy] - Поле группировки для целевого уровня (переопределяет default)
 * @property {'default'|'success'|'error'|'dashed'} [status='default'] - Визуальный статус связи (влияет на стиль линии)
 */

/**
 * Конфигурация уровня (LevelLayoutPanel)
 * @typedef {Object} LevelConfig
 * @property {string} id - Уникальный ID уровня (UUID)
 * @property {string} name - Отображаемое название
 * @property {number} order - Порядковый номер (0, 1, 2...)
 * @property {number} [x] - Canvas-координата X (сохраняется из PresetBuilderCanvas)
 * @property {number} [y] - Canvas-координата Y (сохраняется из PresetBuilderCanvas)
 * @property {number} [width] - Ширина карточки уровня на canvas
 * @property {number} [height] - Высота карточки уровня на canvas
 * @property {{columns: number, rows: number, gap: number}} grid - CSS Grid параметры
 * @property {WidgetInstanceConfig[]} widgets - Виджеты на уровне
 * @property {string} [defaultGroupBy] - Поле группировки по умолчанию для этого уровня
 * @property {boolean} [autoInheritFilters=true] - Автоматически наследовать privateFilters + mapFilters
 * @property {'manual'|'auto'} [generationMode='manual'] - Режим генерации содержимого уровня
 * @property {string} [autoCodeType] - Название справочника для авто-генерации виджетов
 * @property {string} [autoWidgetType] - Тип виджета для авто-генерации (componentTag)
 * @property {'labor'|'nonlabor'|'material'} [autoResourceType='labor'] - Тип ресурса для авто-уровня
 * @property {'codeOrder'|'deviation'|'actual'|'plan'} [autoSortBy='codeOrder'] - Поле сортировки авто-виджетов
 * @property {'asc'|'desc'} [autoSortDir='asc'] - Направление сортировки авто-виджетов
 * @property {'manhours'|'material'} [dataDomain='manhours'] - Домен данных уровня
 * @property {Filter[]} [baseFilters] - Implicit/base фильтры, применяемые ко всем виджетам уровня
 * @property {Object<string, Object>} [widgetSettings] - Runtime-настройки авто-виджетов по их id (`auto-<levelId>-<valueId>`), например { chartType }
 */

/**
 * Пресет уровней (сохраняемая конфигурация)
 * @typedef {Object} LevelPreset
 * @property {string} presetId - Уникальный ID пресета (UUID)
 * @property {string} name - Название пресета
 * @property {string} [description] - Описание
 * @property {string} version - Версия формата (например, "2.0.0")
 * @property {LevelConfig[]} levels - Определения уровней
 * @property {TransitionRule[]} transitions - Правила переходов
 * @property {string} [defaultLevelId] - ID уровня по умолчанию при открытии
 * @property {string} createdAt - Дата создания (ISO 8601)
 * @property {string} [updatedAt] - Дата обновления (ISO 8601)
 * @property {boolean} [isBuiltIn=false] - Встроенный пресет (не удаляется)
 * @property {number} [canvasScale] - Последний масштаб canvas (PresetBuilderCanvas)
 * @property {number} [canvasPanX] - Последний сдвиг canvas по X
 * @property {number} [canvasPanY] - Последний сдвиг canvas по Y
 */

/**
 * Данные bar-диаграммы (plan/fact по категориям)
 * @typedef {Object} BarChartData
 * @property {string[]} categories - Названия категорий (например, ["ПИР", "МТО", "СМР", "ПНР"])
 * @property {(number|null)[]} plan - Плановые значения по категориям (null для не соответствующей категории)
 * @property {(number|null)[]} fact - Фактические значения по категориям (null для не соответствующей категории)
 * @property {number} total - Общая сумма (для отображения в заголовке)
 * @property {boolean} [isFrozen] - Заморожены ли данные
 */

/**
 * JSON-схема пресета макетов уровней (Layout Preset Schema v2)
 * @typedef {Object} LayoutPresetSchema
 * @property {string} [$schema] - Идентификатор схемы (например, "deepdive-layout/v2")
 * @property {string} version - Версия формата (например, "2.0.0")
 * @property {string} name - Название пресета
 * @property {string} [description] - Описание
 * @property {LevelConfig[]} levels - Определения уровней
 * @property {TransitionRule[]} transitions - Правила переходов
 * @property {string} [defaultLevelId] - ID уровня по умолчанию при открытии
 * @property {string} createdAt - Дата создания (ISO 8601)
 * @property {string} [updatedAt] - Дата обновления (ISO 8601)
 * @property {boolean} [isBuiltIn=false] - Встроенный пресет (не удаляется)
 */

/**
 * Событие навигации между уровнями
 * @typedef {Object} LevelNavigateDetail
 * @property {string} fromLevelId - ID уровня-источника
 * @property {string} toLevelId - ID целевого уровня
 * @property {string} fromWidgetId - ID виджета-источника
 * @property {Filter[]} nextLevelFilters - Суммарные фильтры для целевого уровня
 * @property {string} [clickedValue] - Значение, по которому кликнули (для отображения)
 * @property {string} [clickedDisplayName] - Отображаемое название значения
 */

/**
 * Событие обновления контекста уровня
 * @typedef {Object} LevelContextUpdateDetail
 * @property {string} levelId - ID уровня
 * @property {LevelContext} context - Новый контекст
 * @property {Filter[]} [previousFilters] - Предыдущие фильтры (для diff)
 */

// ============================================================================
// API Types
// ============================================================================

/**
 * Параметры запроса данных
 * @typedef {Object} FetchDataParams
 * @property {Filter[]} [filters] - Фильтры для применения
 * @property {string} [groupBy] - Поле для группировки
 * @property {string} [sortBy] - Поле для сортировки
 * @property {'asc'|'desc'} [sortOrder] - Направление сортировки
 */

// ============================================================================
// COMP-016: FocusedGantt Types
// ============================================================================

/**
 * Элемент данных для отрисовки в FocusedGantt.
 * @typedef {Object} GanttActivity
 * @property {number} id - TASK_ID
 * @property {string} taskName - Название работы
 * @property {string} startDate - YYYY-MM-DD
 * @property {string} endDate - YYYY-MM-DD
 * @property {number} duration - Длительность в днях
 * @property {number} [totalFloat] - Общий резерв (для крит. пути)
 * @property {number} [freeFloat] - Свободный резерв
 * @property {number} [calendarId] - CLNDR_ID календаря работы (SYS-025)
 * @property {string} [activityCode] - Код работы в Primavera
 * @property {string} [color] - HEX цвет бара (из CodeValue или статуса)
 * @property {boolean} [isMilestone] - true для вех (duration = 0)
 * @property {boolean} [isCritical] - true если total_float === 0
 */

/**
 * Связь между работами (календарно-сетевая модель).
 * @typedef {Object} GanttRelationship
 * @property {number} relationshipId - ID связи (TASK_PRED_ID)
 * @property {number} predecessorId - ID предшественника (PRED_TASK_ID)
 * @property {number} successorId - ID последователя (TASK_ID)
 * @property {'FS'|'SS'|'FF'|'SF'} type - Тип связи
 * @property {number} [lagDays] - Лаг в днях (может быть отрицательным — lead)
 * @property {boolean} [isCritical] - true если обе работы на крит. пути
 */

/**
 * Детали события клика по бару работы
 * @typedef {Object} GanttBarClickDetail
 * @property {number} activityId - ID работы
 * @property {GanttActivity} activity - Полные данные работы
 */

/**
 * Конфигурация отображаемых полей рядом с баром
 * @typedef {Object} GanttLabelConfig
 * @property {boolean} showDates - Показывать start–end
 * @property {boolean} showPercent - Показывать % complete
 * @property {boolean} showStatus - Показывать статус
 * @property {'left'|'right'|'auto'} position - Положение меток
 */

// ============================================================================
// COMP-022: ActivityChainPanel Types
// ============================================================================

/**
 * Элемент цепочки работ (Activity Chain Item).
 * @typedef {Object} ActivityChainItem
 * @property {number} id - TASK_ID работы
 * @property {string} activityCode - Код работы (TASK_CODE)
 * @property {string} taskName - Название работы
 * @property {string} startDate - Дата начала (YYYY-MM-DD)
 * @property {string} endDate - Дата окончания (YYYY-MM-DD)
 * @property {string} [actualEndDate] - Фактическая дата окончания (null = не завершена)
 * @property {number} freeFloat - Свободный резерв (дней)
 * @property {number} level - Уровень в цепочке (0 = корень, N = выделенная работа)
 * @property {boolean} isSelected - true для выделенной работы (последний элемент)
 * @property {boolean} isRoot - true для первого элемента цепочки
 * @property {number} [relationshipId] - ID связи (TASK_PRED_ID)
 * @property {number} [lagDays] - Лаг связи в днях
 * @property {'FS'|'SS'|'FF'|'SF'} [relationshipType] - Тип связи с последующей работой
 * @property {{code: string, description: string}} [gpPosition] - Позиция ГП из справочника "Позиция_ГП_МСГ"
 * @property {{code: string, description: string}} [drawingMark] - Марка чертежа из справочника "!Марка чертежа (Основной)"
 */

/**
 * Связь работы с предшественником (используется для построения цепочки).
 * @typedef {Object} ActivityPredecessorLink
 * @property {number} relationshipId - TASK_PRED_ID
 * @property {number} successorId - ID последующей работы (TASK_ID)
 * @property {number} predecessorId - ID предшествующей работы (PRED_TASK_ID)
 * @property {'FS'|'SS'|'FF'|'SF'} type - Тип связи
 * @property {number} [lagDays] - Лаг в днях
 * @property {boolean} isDriving - true если связь ведущая (driving)
 */

// ============================================================================
// Global Declarations (for TypeScript checking)
// ============================================================================

// ============================================================================
// Layout Persistence Types
// ============================================================================

/**
 * Конфигурация одного модуля в макете.
 * @typedef {Object} ModuleLayoutConfig
 * @property {string} id - DOM id модуля
 * @property {string} container - ID родительского контейнера
 * @property {string|null} nextSiblingId - ID следующего модуля в DOM (null если последний)
 * @property {boolean} dockedOut - Откреплён ли модуль
 * @property {boolean} collapsed - Свёрнут ли модуль
 * @property {number} xOffset - Смещение по X (для откреплённых)
 * @property {number} yOffset - Смещение по Y (для откреплённых)
 * @property {string} width - inline width
 * @property {string} height - inline height
 * @property {string} flex - inline flex
 */

/**
 * Snapshot состояния dockable layout (из js/ui.js).
 * @typedef {Object} DockableLayoutSnapshot
 * @property {string} gridColumns - grid-template-columns дашборда
 * @property {boolean} leftSidebarVisible - Видима ли левая панель
 * @property {boolean} zenMode - Включён ли дзен-режим
 * @property {ModuleLayoutConfig[]} modules - Массив конфигураций модулей
 */

/**
 * Полный экспортируемый макет рабочего пространства.
 * @typedef {Object} WorkspaceLayout
 * @property {string} schemaVersion - Версия схемы (например "1.0")
 * @property {string} appVersion - Версия приложения
 * @property {string} name - Название макета
 * @property {string} description - Описание макета
 * @property {string} exportedAt - ISO дата экспорта
 * @property {DockableLayoutSnapshot} layout - Состояние dockable layout
 * @property {FilterState} [filters] - Состояние фильтров
 * @property {Object} [timeline] - Состояние таймлайна
 * @property {Object} [mainContent] - Состояние основного контента
 * @property {string|null} [activePresetId] - ID активного пресета аналитики
 */

// ============================================================================
// COMP-024: ScheduleDeviationAnalyzer Types
// ============================================================================

/**
 * Тип причины отклонения
 * @typedef {'late_start' |
 *           'insufficient_output' |
 *           'late_start_and_insufficient_output' |
 *           'predecessor_delay' |
 *           'constraint_delay' |
 *           'removed_from_current' |
 *           'on_track' |
 *           'unknown'
 * } DeviationCauseType
 */

/**
 * Элемент цепочки предшественников
 * @typedef {Object} PredecessorChainItem
 * @property {number} activityId
 * @property {string} activityCode
 * @property {string} taskName
 * @property {string} [relationshipType] — FS / SS / FF / SF
 * @property {number} [lagDays]
 * @property {boolean} isDriving — free_float <= 0
 * @property {string} [startDate] — start_date в ТГ
 * @property {string} [endDate] — end_date (projected) в ТГ
 * @property {string} [actualStartDate] — actual_start_date в ТГ
 * @property {string} [actualEndDate] — actual_end_date в ТГ
 * @property {string} [targetStartDate] — start_date в ЦП
 * @property {string} [targetEndDate] — end_date в ЦП
 * @property {string} [impactDate] — дата влияния (ISO) с учётом связи и lag
 * @property {string} [taskType] — task_type из activities (TT_LOE и т.д.)
 */

/**
 * Работа, являющаяся корневой причиной отклонения
 * @typedef {Object} RootCauseActivity
 * @property {number} activityId
 * @property {string} activityCode
 * @property {string} taskName
 */

/**
 * Результат анализа одной работы
 * @typedef {Object} DeviationItem
 * @property {number} activityId — ID работы в ТГ
 * @property {string} activityCode — TASK_CODE
 * @property {string} taskName
 * @property {string} [taskType] — task_type ТГ (например, "TT_LOE" для гамаков)
 * @property {string} [gpPosition] — Позиция генплана (из справочника Позиция_ГП_МСГ)
 * @property {string} [gpPositionDescription] — Описание позиции генплана
 * @property {string} [drawingMark] — Марка чертежа (из справочника Марка чертежа (Основной))
 * @property {string} [drawingMarkDescription] — Описание марки чертежа
 * @property {string} [workType] — Вид работ (из справочника ЦПС_Вид работ для отчета)
 * @property {string} [workTypeDescription] — Описание вида работ
 * @property {string} [targetStartDate] — start_date ЦП
 * @property {string} [targetEndDate] — end_date ЦП
 * @property {string} [currentActualStart] — actual_start_date ТГ
 * @property {string} [currentProjectedEnd] — end_date ТГ (или dataDate если не завершена)
 * @property {DeviationCauseType} causeType
 * @property {string} causeDescription — человекочитаемое описание причины
 * @property {PredecessorChainItem[]} [predecessorChain] — цепочка от текущей работы до корневой
 * @property {RootCauseActivity} rootCauseActivity — работа-причина (сама работа или предшественник)
 * @property {string} [constraintType] — cstr_type ТГ (если causeType === 'constraint_delay')
 * @property {string} [constraintDate] — cstr_date ТГ
 * @property {number} [targetManhours] — Накопленные трудозатраты ЦП к дате отчёта (plan to date)
 * @property {number} [targetTotalManhours] — Общие трудозатраты ЦП работы (actual + remaining за весь период)
 * @property {number} [currentManhours] — Накопленные трудозатраты ТГ к дате отчёта (actual + remaining to date)
 * @property {number} [currentTotalManhours] — Общие трудозатраты ТГ работы (actual + remaining за весь период)
 * @property {number} [currentActualToDate] — Фактические трудозатраты ТГ к дате отчёта
 * @property {number} [manhoursDelta] — Дельта трудозатрат (ТГ − ЦП)
 */

/**
 * Параметры запуска анализа
 * @typedef {Object} AnalysisOptions
 * @property {string} databaseId — ID базы данных
 * @property {string} dataDate — Дата актуализации ТГ (YYYY-MM-DD)
 * @property {CodeFilterItem[]} [codeFilters] — Глобальные фильтры по Activity Codes
 * @property {number[]} [wbsFilterIds] — Фильтр по WBS
 * @property {WeekRange} [weekRange] — Диапазон недель
 */

// ============================================================================
// SYS-010: DeviationNarrativeService Types
// ============================================================================

/**
 * Контекст генерации нарратива по работе. Дополняет DeviationItem вычисленными метриками.
 * @typedef {Object} NarrativeContext
 * @property {number} startDelayDays — Сдвиг начала (факт − план, 0 если нет)
 * @property {number} endDelayDays — Сдвиг окончания (проектив − план, 0 если нет)
 * @property {number} targetManhours — Трудозатраты ЦП
 * @property {number} currentManhours — Трудозатраты ТГ
 * @property {boolean} isCompleted — Работа имеет actual_end_date
 * @property {boolean} [hasActualStart] — Работа имеет actual_start_date (старт уже произошёл)
 * @property {string} [dataDate] — Дата актуализации (YYYY-MM-DD)
 * @property {string} [lang] — Код языка ('ru' по умолчанию)
 */

/**
 * Результат генерации нарратива по работе.
 * @typedef {Object} NarrativeResult
 * @property {string} headline — Заголовок для сводки (1 строка)
 * @property {string} narrative — Развёрнутое описание (1–3 предложения)
 * @property {string} recommendation — Рекомендация по действию
 * @property {'critical'|'warning'|'info'} severity — Уровень критичности
 * @property {string[]} tags — Активные модификаторы (для фильтрации/тестов)
 */

/**
 * Позиция оборудования в отчёте.
 * @typedef {Object} EquipmentItem
 * @property {string} name — Наименование (например, "Установка компрессорная азотная АГС-1890.0")
 * @property {string} [forecastDeliveryDate] — Прогнозная дата поставки
 * @property {number} [deviationFromTargetDays] — Отклонение от ЦП, дни
 * @property {number} [reserveDays] — Резерв, дни (отрицательный = дефицит)
 * @property {string} [contractStatus] — Статус договора
 * @property {string} [contractDeliveryDate] — Срок по договору
 * @property {string} [requiredDate] — Требуемая дата поставки
 * @property {string} [measures] — Предусмотренные мероприятия
 */

/**
 * Позиция МТР в отчёте.
 * @typedef {Object} MtrItem
 * @property {string} name — Наименование / подрядчик
 * @property {string} [items] — Перечень позиций (например, "23 шт. ЗРА (D219-1400)")
 * @property {boolean} affectsLaunch — Влияет ли на срок запуска
 * @property {string} [dynamicVsLastWeek] — Динамика за неделю
 * @property {string} [recommendation] — Рекомендация ("Требуется оптимизация сроков поставки")
 */

/**
 * Метрики по виду работ (табличные данные для отчёта).
 * @typedef {Object} WorkTypeMetrics
 * @property {string} workType — Вид работ (например, "монтаж ЗРА")
 * @property {string} unit — Единица измерения (шт, м, усл.ст)
 * @property {number} accumulatedBacklog — Накопленное отставание
 * @property {number} backlogPercent — Отставание от общего объёма, %
 * @property {number} planPerDay — План в сутки
 * @property {number} actualPerDay — Факт в сутки
 */

/**
 * Информация по мобилизации персонала.
 * @typedef {Object} ManpowerInfo
 * @property {number} plan — План мобилизации, чел
 * @property {number} actual — Факт, чел
 * @property {number} deficitPercent — Дефицит / превышение, %
 * @property {boolean} isPlanFulfilled — План исполняется?
 * @property {string} [narrative] — Пояснение
 */

/**
 * Раздел ПИР в отчёте по объекту.
 * @typedef {Object} BlockSectionPir
 * @property {'completed'|'on_track'|'deviation_off_path'|'deviation_on_path'} status
 * @property {string} [narrative] — Уже сформированный текст (если есть)
 * @property {DeviationItem[]} [deviations] — Отклонения в ПИР
 */

/**
 * Раздел МТО в отчёте по объекту.
 * @typedef {Object} BlockSectionMto
 * @property {'no_deviation'|'off_path'|'on_path'} status
 * @property {EquipmentItem[]} [equipment] — Оборудование с отклонениями
 * @property {MtrItem[]} [mtr] — МТР с отклонениями
 * @property {string} [narrative] — Уже сформированный текст
 */

/**
 * Раздел СМР в отчёте по объекту.
 * @typedef {Object} BlockSectionSmr
 * @property {'on_track'|'deviation_off_path'|'deviation_on_path'} status
 * @property {number} [totalDeviationPercent] — Суммарное отклонение СМР от плана, %
 * @property {number} [weeklyDynamicPercent] — Динамика за неделю, %
 * @property {WorkTypeMetrics[]} [workTypes] — Метрики по видам работ
 * @property {ManpowerInfo} [manpower] — Информация по мобилизации МСГ
 * @property {string} [narrative] — Уже сформированный текст
 * @property {DeviationItem[]} [deviations] — Отклонения в СМР
 */

/**
 * Прогноз по ключевой вехе проекта.
 * @typedef {Object} ForecastResult
 * @property {string} milestoneName — Название вехи
 * @property {string} targetDate — Целевая дата
 * @property {string} [forecastDate] — Прогнозная дата
 * @property {number} [deviationDays] — Отклонение, дни
 * @property {number} [probabilityPercent] — Вероятность прогноза, %
 * @property {string} [basis] — Обоснование прогноза
 */

/**
 * Данные для формирования отчёта по объекту / WBS-блоку.
 * @typedef {Object} BlockReportData
 * @property {string} blockName — Название объекта
 * @property {string} [blockCode] — Код объекта
 * @property {number} [launchDeviationDays] — Отклонение тех.запуска от ЦП (отрицательное = задержка)
 * @property {boolean} isOnCriticalPath — Есть ли отклонения на критическом пути
 * @property {BlockSectionPir} pir — Раздел ПИР
 * @property {BlockSectionMto} mto — Раздел МТО
 * @property {BlockSectionSmr} smr — Раздел СМР
 * @property {DeviationItem[]} [criticalDeviations] — Ключевые отклонения работ объекта
 * @property {ForecastResult[]} [forecasts] — Прогнозы по вехам объекта
 * @property {string} [dataDate] — Дата актуализации
 */

/**
 * Секция внутри BlockReportResult.
 * @typedef {Object} BlockReportSection
 * @property {'launch'|'pir'|'mto'|'smr'|'forecast'|'status'} sectionType
 * @property {string} headline — Заголовок секции
 * @property {string} narrative — Текст секции
 * @property {string} [recommendation] — Рекомендация по секции
 * @property {'critical'|'warning'|'info'} severity
 */

/**
 * Результат генерации отчёта по объекту.
 * @typedef {Object} BlockReportResult
 * @property {string} blockName — Название объекта
 * @property {string} summaryText — Агрегированный текстовый нарратив всего объекта
 * @property {BlockReportSection[]} sections — Разделы отчёта
 * @property {WorkTypeMetrics[][]} [tables] — Таблицы метрик (для вставки в DOCX)
 * @property {'critical'|'warning'|'info'} severity — Итоговая критичность объекта
 * @property {string[]} tags — Активные признаки
 */

/**
 * Контекст для прогнозной секции отчёта.
 * @typedef {Object} ProjectForecastContext
 * @property {ForecastResult[]} forecasts — Массив прогнозов по ключевым вехам
 * @property {string} [basis] — Общее обоснование прогноза
 */

// ============================================================================
// FLOW-006: Material Volume Analytics Types
// ============================================================================

/**
 * Элемент данных по физическому объёму (материал) на уровне назначения ресурса.
 * Агрегация идёт на уровне ResourceAssignment, а не Activity, т.к. на одной работе
 * могут быть разные материалы с разными единицами измерения.
 * @typedef {Object} MaterialVolumeItem
 * @property {number} activityId - ID работы (TASK_ID)
 * @property {number} resourceId - ID ресурса (RSRC_ID)
 * @property {string} resourceName - Название ресурса
 * @property {string} unitName - Единица измерения (шт, м³, т и т.д.)
 * @property {number} planQty - Плановое количество (target_units)
 * @property {number} actualQty - Фактическое количество (actual_units)
 * @property {number} remainingQty - Оставшееся количество (remaining_units)
 * @property {number} percentComplete - Процент выполнения (0-100)
 * @property {string} startDate - Дата начала работы (YYYY-MM-DD)
 * @property {string} endDate - Дата окончания работы (YYYY-MM-DD)
 * @property {'current'|'target'} scheduleType - Тип графика
 * @property {number} wbsId - ID WBS узла
 * @property {string} [wbsCode] - Код WBS (например, "1.2.3")
 * @property {string} [wbsName] - Название WBS узла
 * @property {string} activityCode - Код работы (TASK_CODE)
 * @property {string} taskName - Название работы
 * @property {number} [planTargetQty] - Плановое количество по целевому графику (ЦП), сопоставленное по activityCode+resourceId
 * @property {number} [cumulativeCurrentQty] - Накопленный физический объём текущего графика (по неделе/диапазону)
 * @property {number} [cumulativeTargetQty] - Накопленный физический объём целевого графика (по неделе/диапазону)
 * @property {number} [cumulativeDeltaQty] - Дельта накопленных объёмов (ТГ − ЦП)
 */

/**
 * Материальный ресурс для фильтра (из таблицы resources типа 'material').
 * @typedef {Object} MaterialResourceItem
 * @property {number} resourceId - ID ресурса
 * @property {string} name - Название ресурса
 * @property {string} shortName - Короткое название
 * @property {string} unitName - Единица измерения
 */

/**
 * Элемент прогресса по материалу (для VolumeProgressWidget).
 * @typedef {Object} VolumeProgressItem
 * @property {number} resourceId - ID ресурса
 * @property {string} resourceName - Название ресурса
 * @property {string} unitName - Единица измерения
 * @property {number} planQty - Плановое количество
 * @property {number} actualQty - Фактическое количество
 * @property {number} remainingQty - Оставшееся количество
 * @property {number} percentComplete - Процент выполнения (0-100)
 * @property {number} activityCount - Количество работ с этим материалом
 */

/**
 * Агрегированные данные по материалу (для табличного отображения / сводки).
 * @typedef {Object} MaterialVolumeAggregate
 * @property {number} resourceId - ID ресурса
 * @property {string} resourceName - Название ресурса
 * @property {string} unitName - Единица измерения
 * @property {number} totalPlanQty - Общий плановый объём
 * @property {number} totalActualQty - Общий фактический объём
 * @property {number} totalRemainingQty - Общий оставшийся объём
 * @property {number} percentComplete - Процент выполнения (0-100)
 * @property {number} activityCount - Количество работ с этим материалом
 * @property {string|null} earliestStart - Самая ранняя дата начала (YYYY-MM-DD)
 * @property {string|null} latestEnd - Самая поздняя дата окончания (YYYY-MM-DD)
 */

/**
 * Данные виджета прогресса по физическим объёмам (volumeProgress).
 * @typedef {Object} VolumeProgressData
 * @property {number} totalPlan - Общий плановый объём
 * @property {number} totalActual - Общий фактический объём
 * @property {number} totalRemaining - Общий оставшийся объём
 * @property {number} percentComplete - Общий процент выполнения (0-100)
 * @property {VolumeProgressItem[]} items - Разбивка по ресурсам (alias для byResource)
 * @property {number} totalMaterials - Количество материалов
 * @property {number} totalActivities - Общее количество работ с материалами
 * @property {boolean} hasMixedUnits - true если агрегированы разные единицы измерения
 */

/**
 * Категория (ресурс) в S-кривой физических объёмов.
 * @typedef {Object} VolumeSCurveCategory
 * @property {string} name - Название ресурса/категории
 * @property {string} color - Цвет серии в HEX
 * @property {number[]} periodPlanPct - Периодный план, % от общего плана
 * @property {number[]} periodActualPct - Периодный факт, % от общего текущего объёма
 * @property {(number|null)[]} cumActualPct - Накопленный факт, % от общего текущего объёма
 * @property {(number|null)[]} cumForecastPct - Накопленный прогноз, % от общего текущего объёма
 * @property {number} totalPlan - Суммарный план ресурса (абсолютные единицы)
 * @property {number} totalActual - Суммарный факт ресурса (абсолютные единицы)
 * @property {number} totalRemaining - Суммарный остаток ресурса (абсолютные единицы)
 */

/**
 * Данные S-кривой по физическим объёмам (volumeSCurve).
 * Разбивка по ресурсам в виде stacked bars + линия итогового прогресса.
 * @typedef {Object} VolumeSCurveData
 * @property {string[]} xAxis - Метки оси X (недели, формат "DD.MM.YY")
 * @property {VolumeSCurveCategory[]} categories - Ресурсы/категории
 * @property {number[]} totalPlanPct - Накопленный итог плана, % от общего плана
 * @property {(number|null)[]} totalActualPct - Накопленный итог факта, % от общего текущего объёма
 * @property {(number|null)[]} totalForecastPct - Накопленный итог прогноза, % от общего текущего объёма
 * @property {number} totalPlanSum - Общий плановый объём (для tooltip)
 * @property {number} totalActualSum - Общий фактический объём (для tooltip)
 * @property {number} totalForecastSum - Общий прогнозный объём (для tooltip)
 * @property {boolean} hasMixedUnits - Предупреждение: агрегация разных единиц
 * @property {string} [unitName] - Единица измерения (если все ресурсы одного типа)
 * @property {string} [reportDate] - Дата отчёта (YYYY-MM-DD) для markLine
 * @property {number} [reportWeekIdx] - Индекс недели отчёта
 * @property {number} [reportAxisIndex] - Позиция reportWeekIdx в массиве xAxis
 */

/**
 * Строка таблицы физических объёмов (volumeTable).
 * @typedef {Object} VolumeTableRow
 * @property {number} activityId - ID работы
 * @property {string} activityCode - Код работы
 * @property {string} taskName - Название работы
 * @property {number} resourceId - ID ресурса
 * @property {string} resourceName - Название ресурса
 * @property {string} unitName - Единица измерения
 * @property {number} planQty - План
 * @property {number} actualQty - Факт
 * @property {number} remainingQty - Остаток
 * @property {number} percentComplete - Процент выполнения
 * @property {string} startDate - Дата начала
 * @property {string} endDate - Дата окончания
 * @property {'current'|'target'} scheduleType
 * @property {string} [wbsCode] - Код WBS (например, "1.2.3")
 * @property {string} [wbsName] - Название WBS узла
 * @property {string} wbsPath - Путь WBS (например, "1.2.3") — legacy alias для wbsCode
 * @property {number} [cumulativeCurrentQty] - Накопленный физический объём текущего графика
 * @property {number} [cumulativeTargetQty] - Накопленный физический объём целевого графика
 */

/**
 * Опции запроса материальных объёмов.
 * @typedef {Object} MaterialVolumeQueryOptions
 * @property {'current'|'target'|'both'} [scheduleType='current'] - Тип графика
 * @property {CodeFilterItem[]} [codeFilters] - Активные фильтры по Activity Codes
 * @property {number[]} [resourceFilterIds] - IDs выбранных материальных ресурсов
 * @property {number[]} [wbsFilterIds] - IDs выбранных WBS узлов
 * @property {WeekRange} [weekRange] - Диапазон недель
 * @property {'activity'|'material'} [groupBy='activity'] - Группировка результатов
 * @property {boolean} [includeNonSmr=false] - Включить работы без кода СМР (по умолчанию только СМР)
 * @property {Filter[]} [baseFilters] - Базовые фильтры уровня
 * @property {Filter[]} [privateFilters] - Приватные фильтры виджета
 */

// ============================================================================
// Material Delivery Types (SYS-018)
// ============================================================================

/**
 * Источник реестра поставок материалов (загруженный Excel-файл).
 * @typedef {Object} MaterialDeliverySource
 * @property {string} sourceId - Уникальный ID источника (uuid)
 * @property {string} fileName - Оригинальное имя файла
 * @property {string} [reportDate] - Дата реестра из имени/содержимого (YYYY-MM-DD)
 * @property {string} uploadedAt - ISO-8601 timestamp загрузки
 * @property {number} rowCount - Количество строк в Excel
 * @property {number} importedCount - Сколько удалось импортировать
 * @property {number} unmatchedCount - Сколько не сопоставилось
 * @property {string} [hash] - Hash содержимого файла
 * @property {'draft'|'imported'|'failed'} [status='imported'] - Статус импорта
 */

/**
 * Поставка материала (строка реестра МТР).
 * Атомарная запись о планируемой/фактической поставке материала
 * с привязкой к работе графика.
 * @typedef {Object} MaterialDelivery
 * @property {string} deliveryId - Уникальный ID поставки (uuid или автоинкремент)
 * @property {string} [sourceId] - Ссылка на источник реестра (MaterialDeliverySource)
 * @property {string} [materialCodeInitial] - Код МТР (первоначальный) из SAP до контрактования поставщика (столбец Z реестра)
 * @property {string} [materialCodeFinal] - Код МТР (итоговый) из SAP после определения поставщика (столбец AA реестра)
 * @property {string} materialCode - DEPRECATED: alias для materialCodeFinal. Оставлен для обратной совместимости.
 * @property {string} materialName - Материал Имя
 * @property {string} [materialType] - Вид МТР (столбец T реестра)
 * @property {string} [activityCode] - ID Раб. из реестра
 * @property {number} [activityId] - TASK_ID после сопоставления с Activity
 * @property {number} [resourceId] - RSRC_ID после сопоставления с Resource
 * @property {number} quantity - Количество (всего / поставлено / оприходовано)
 * @property {string} unit - Единица измерения
 * @property {'basis1'|'basis2'|'object'|'warehouse'|string} [deliveryStage] - Этап поставки
 * @property {string} [deliveryDate] - Фактическая дата поставки (YYYY-MM-DD)
 * @property {string} [contractDate] - Срок поставки по договору (YYYY-MM-DD)
 * @property {string} [forecastDate] - Прогноз срока поставки (YYYY-MM-DD)
 * @property {string} [sourceDocument] - ДП / приложение / ТН / счёт-фактура
 * @property {string} [status] - Статус поставки
 * @property {string} [supplier] - Поставщик
 * @property {boolean} [matched=false] - Успешно ли сопоставлена с Activity/Resource
 * @property {string[]} [matchWarnings] - Предупреждения при маппинге
 */

/**
 * Фактическая партия поставки на конкретном этапе.
 * Одна строка реестра может порождать несколько партий
 * (базис 1, базис 2, объект).
 * @typedef {Object} MaterialDeliveryReceipt
 * @property {string} receiptId - Уникальный ID партии
 * @property {string} deliveryId - Ссылка на MaterialDelivery
 * @property {'basis1'|'basis2'|'object'|string} stage - Этап поставки
 * @property {number} quantity - Количество
 * @property {string} [date] - Дата поставки (YYYY-MM-DD)
 * @property {string} [document] - Транспортный/товарный документ
 */

/**
 * Опции импорта поставок материалов из Excel.
 * @typedef {Object} MaterialDeliveryImportOptions
 * @property {string} [sheetName='РЕЕСТР'] - Имя листа Excel
 * @property {number} [headerRow=3] - Номер строки с заголовками (1-based)
 * @property {boolean} [skipUnmatched=true] - Пропускать строки без сопоставления
 * @property {boolean} [matchByName=true] - Сопоставлять материал по имени
 * @property {boolean} [matchByNameFuzzy=true] - Разрешить нечёткое совпадение по имени (подстрока)
 * @property {boolean} [matchByCode=false] - Сопоставлять материал по коду МТР
 * @property {number} [tolerancePercent=0] - Допуск расхождения количества с targetUnits (%)
 * @property {string} [sourceId] - ID существующего источника для обновления (иначе генерируется новый)
 * @property {string} [fileName] - Имя загружаемого файла (по умолчанию из File.name)
 * @property {string} [reportDate] - Дата реестра (YYYY-MM-DD)
 * @property {boolean} [replaceExisting=true] - Полностью заменять поставки источника при повторной загрузке
 */

/**
 * Результат сопоставления одной строки реестра.
 * @typedef {Object} MaterialDeliveryMapping
 * @property {number} rowIndex - Индекс строки в Excel (1-based)
 * @property {MaterialDelivery} delivery - Сформированная поставка
 * @property {boolean} matched - Успешно ли сопоставлено
 * @property {string} [unmatchedReason] - Причина несопоставления
 */

/**
 * Результат импорта поставок материалов из Excel.
 * @typedef {Object} MaterialDeliveryImportResult
 * @property {string} [sourceId] - ID созданного/обновлённого источника реестра
 * @property {number} totalRows - Всего обработано строк
 * @property {number} importedCount - Импортировано (сопоставлено) строк
 * @property {number} skippedCount - Пропущено строк
 * @property {MaterialDeliveryMapping[]} mappings - Полный список маппингов
 * @property {MaterialDeliveryMapping[]} unmatched - Строки без сопоставления
 */

/**
 * Runtime derived-индексы поставок материалов.
 * @typedef {Object} MaterialDeliveryIndexes
 * @property {Map<string, MaterialDelivery>} deliveriesById - Поставки по ID
 * @property {Map<number, MaterialDelivery[]>} deliveriesByActivity - Поставки по работе
 * @property {Map<number, MaterialDelivery[]>} deliveriesByResource - Поставки по ресурсу
 * @property {Map<string, MaterialDelivery[]>} deliveriesByMaterialCode - Поставки по коду МТР
 * @property {Map<number, number>} deliveryQtyByWeek - Суммарные поставки по неделям
 * @property {Map<string, Map<number, number>>} deliveryQtyByMaterialWeek - Поставки по материалу и неделе
 */

// ============================================================================
// SYS-005 / SYS-007: Project Report Types
// ============================================================================

/**
 * Вариант значения launchDeviationDays
 * @typedef {number|null} LaunchDeviation
 */

/**
 * Позиция оборудования (альтернативное определение для BlockReportData)
 * @typedef {Object} BlockEquipmentItem
 * @property {string} name
 * @property {string} [status]
 * @property {number} [deviationDays]
 */

/**
 * Позиция МТР (альтернативное определение для BlockReportData)
 * @typedef {Object} BlockMtrItem
 * @property {string} name
 * @property {string} [status]
 * @property {number} [deviationDays]
 */

/**
 * Раздел техзапуска в BlockReportData
 * @typedef {Object} BlockSectionLaunch
 * @property {number|null} deviationDays — Отклонение в днях
 * @property {boolean} isOnCriticalPath
 * @property {string|null} targetDate — ISO date
 * @property {string|null} forecastDate — ISO date
 */

/**
 * Расширенный раздел ПИР для BlockReportData (SYS-005)
 * @typedef {Object} BlockReportSectionPir
 * @property {'deviation_on_path'|'deviation_off_path'|'no_deviation'} status
 * @property {DeviationItem[]} deviations
 * @property {null} equipment — Заглушка (нет в схеме БД)
 * @property {null} mtr — Заглушка
 */

/**
 * Расширенный раздел МТО для BlockReportData (SYS-005)
 * @typedef {Object} BlockReportSectionMto
 * @property {null} equipment — Заглушка
 * @property {null} mtr — Заглушка
 * @property {'no_deviation'} status — Заглушка (MVP: только 'no_deviation')
 * @property {DeviationItem[]} deviations — Заглушка (пустой массив)
 */

/**
 * Расширенный раздел СМР для BlockReportData (SYS-005)
 * @typedef {Object} BlockReportSectionSmr
 * @property {'on_track'|'deviation_off_path'|'deviation_on_path'} status
 * @property {number} totalDeviationPercent — Суммарное отклонение СМР (%)
 * @property {WorkTypeMetrics[]} workTypes — Топ-5 видов работ по отставанию
 * @property {null} manpower — Заглушка
 * @property {DeviationItem[]} deviations
 */

/**
 * Прогнозируемая веха в BlockReportData (SYS-005)
 * @typedef {Object} BlockForecastItem
 * @property {string} milestoneName
 * @property {string} targetDate — ISO
 * @property {string} forecastDate — ISO
 * @property {number} deviationDays
 */

/**
 * Данные для построения block-level отчёта (SYS-005).
 * Расширяет существующий BlockReportData конкретными полями агрегатора.
 * @typedef {Object} BlockReportData
 * @property {string} blockName — Название WBS-узла (объекта)
 * @property {string} blockId — wbsId
 * @property {number|null} launchDeviationDays — Отклонение техзапуска (дни). Отрицательное = задержка, положительное = опережение. null если нет вехи
 * @property {boolean} isOnCriticalPath — Есть ли отклонения на КП
 * @property {'critical'|'warning'|'on_track'} status — Общий статус блока
 * @property {BlockSectionLaunch} launch
 * @property {BlockReportSectionPir} pir
 * @property {BlockReportSectionMto} mto
 * @property {BlockReportSectionSmr} smr
 * @property {BlockForecastItem[]} forecasts
 * @property {DeviationItem[]} [deviations] — Все отклонения блока (для narrative)
 * @property {string} dataDate — Дата отчёта
 */

/**
 * Опции сборки BlockReportData (SYS-005)
 * @typedef {Object} BuildBlockReportDataOptions
 * @property {DeviationItem[]} [deviations] — Отклонения работ этого блока
 * @property {string} [dataDate] — Дата отчёта (ISO), по умолчанию new Date().toISOString()
 * @property {number} [minSignificantDeviationDays=1] — Минимальное отклонение в днях для включения в отчёт
 */

/**
 * Топ-риск проекта (SYS-007)
 * @typedef {Object} ProjectTopRisk
 * @property {string} blockName
 * @property {'critical'|'warning'|'info'} severity
 * @property {string} summaryText — краткое описание из BlockReportResult.summaryText
 * @property {number|null} launchDeviationDays
 * @property {string[]} tags
 */

/**
 * Результат построения отчёта по проекту (SYS-007)
 * @typedef {Object} ProjectReportResult
 * @property {string} projectName
 * @property {string} dataDate — ISO
 * @property {string} headline
 * @property {string} overview — 2-3 предложения обобщения
 * @property {ProjectTopRisk[]} topRisks — топ объекты с отклонениями
 * @property {BlockReportResult[]} blocks — отчёты по объектам
 * @property {{headline:string,narrative:string,severity:string}} [forecast] — прогнозная секция
 * @property {'critical'|'warning'|'info'} severity — max по блокам
 * @property {string[]} tags — агрегация тегов
 * @property {number} totalBlocks — всего объектов с отклонениями
 * @property {number} criticalCount
 * @property {number} warningCount
 */

/**
 * Опции построения project-отчёта (SYS-007)
 * @typedef {Object} BuildProjectReportOptions
 * @property {string} [dataDate] — Дата отчёта (ISO), по умолчанию new Date().toISOString()
 * @property {number} [maxBlocks=50] — Макс. количество блоков в отчёте
 * @property {DeviationItem[]} [deviations] — Предрассчитанные отклонения (опционально)
 * @property {number} [minBlockSeverity=1] — 0=все, 1=warning+, 2=critical only
 */

/**
 * Состояние модального окна ProjectReportModal (COMP-016)
 * @typedef {Object} ProjectReportModalState
 * @property {'init'|'loading'|'data'|'empty'|'error'} status — Состояние компонента
 * @property {ProjectReportResult|null} report — Текущий отчёт
 * @property {string|null} error — Сообщение об ошибке
 * @property {Set<string>} expandedBlocks — ID раскрытых блоков
 * @property {boolean} isOpen — Флаг открытия модалки
 */

// ============================================================================
// SYS-013: UserSettingsService Types
// ============================================================================

/**
 * Статус синхронизации UserSettingsService.
 * @typedef {'idle'|'syncing'|'pending'|'error'} UserSettingsSyncStatusName
 */

/**
 * Статус синхронизации UserSettingsService (подробный).
 * @typedef {Object} UserSettingsSyncStatus
 * @property {UserSettingsSyncStatusName} status — Текущий статус
 * @property {number} pendingCount — Количество изменений в offline-очереди
 * @property {string|null} lastSyncedAt — ISO 8601 последней успешной синхронизации
 * @property {string|null} error — Последнее сообщение об ошибке
 */

/**
 * Источник, из которого были загружены настройки.
 * @typedef {'server'|'cache'|'fallback'} UserSettingsLoadSource
 */

/**
 * Зашифрованный авторизационный токен.
 * @typedef {Object} EncryptedAuthToken
 * @property {string} iv — Base64 initialization vector
 * @property {string} ciphertext — Base64 encrypted token
 * @property {string} tag — Base64 auth tag (AES-GCM)
 * @property {number} createdAt — timestamp создания
 */

/**
 * Полный набор пользовательских настроек DeepDive.
 * @typedef {Object} UserSettingsData
 * @property {DeepDiveProject[]} projects — Проекты DeepDive (COMP-008)
 * @property {LevelPreset[]} presets — Пользовательские пресеты уровней (SYS-008)
 * @property {string|null} activePresetId — ID активного пресета
 * @property {WorkspaceLayout|null} layoutState — Состояние макета рабочего стола (SYS-009)
 * @property {Array<Object>} sidebarLayouts — Пользовательские макеты боковой панели (COMP-005)
 * @property {string} theme — ID темы: 'consta-light' | 'consta-dark'
 * @property {LoadSession[]} loadHistory — История сессий загрузки (COMP-009)
 * @property {EncryptedAuthToken|null} authToken — Зашифрованный токен Primavera
 */

/**
 * Контейнер настроек DeepDive внутри CustomSettingsDocument.
 * @typedef {Object} DeepDiveSettingsContainer
 * @property {string} version — Версия формата (например "1.0.0")
 * @property {string} updatedAt — ISO 8601 последнего изменения
 * @property {UserSettingsData} data — Сами настройки приложения
 */

/**
 * Общий документ настроек, который возвращает/принимает корпоративный сервис.
 * Ключ deepDive принадлежит приложению DeepDive Analytics.
 * @typedef {Object} CustomSettingsDocument
 * @property {Object} [tableValue] — Пример чужой настройки (не трогать)
 * @property {DeepDiveSettingsContainer} [deepDive] — Настройки DeepDive Analytics
 */

/**
 * Информация о конфликте настроек.
 * @typedef {Object} UserSettingsConflictInfo
 * @property {boolean} detected — Обнаружен ли конфликт
 * @property {string} serverUpdatedAt — ISO 8601 серверной версии
 * @property {string} clientUpdatedAt — ISO 8601 клиентской версии
 * @property {'server'|'client'|'manual'} resolution — Выбранное разрешение
 */

/**
 * Результат миграции из localStorage/IndexedDB.
 * @typedef {Object} UserSettingsMigrationResult
 * @property {boolean} migrated — Была ли выполнена миграция
 * @property {string[]} migratedKeys — Какие ключи мигрировали
 * @property {string[]} warnings — Предупреждения
 * @property {string|null} error — Ошибка, если миграция частично провалилась
 */

/**
 * Детали события user-settings-changed.
 * @typedef {Object} UserSettingsChangeDetail
 * @property {string} [path] — Путь изменённого раздела (для одиночного set), например "projects" или "theme"
 * @property {any} [value] — Новое значение (для одиночного set)
 * @property {any} [previousValue] — Предыдущее значение (для одиночного set)
 * @property {Array<{path: string, value: any, previousValue?: any}>} [updates] — Массовое обновление (для setMultiple)
 * @property {boolean} synced — Уже синхронизировано с сервером
 */

/**
 * Детали события user-settings-error.
 * @typedef {Object} UserSettingsErrorDetail
 * @property {'load'|'save'|'sync'|'migrate'|'token'} phase — Фаза, на которой произошла ошибка
 * @property {Error|string} error — Ошибка
 */

/**
 * Опции инициализации UserSettingsService.
 * @typedef {Object} UserSettingsServiceConfig
 * @property {string} [apiUrl] — Базовый URL внешнего API настроек
 * @property {number} [syncDebounceMs=1000] — Debounce перед синхронизацией
 * @property {() => Promise<CryptoKey>} [encryptionKeyFn] — Функция получения ключа шифрования
 * @property {boolean} [debug=false] — Логирование
 */

// ============================================================================
// SYS-024: LocalCriticalPathService Types
// ============================================================================

/**
 * Опции расчёта локального критического пути.
 * @typedef {Object} LocalCPOptions
 * @property {string} databaseId - ID базы данных
 * @property {number} targetId - ID целевой работы/вехи (activityId)
 * @property {'current'|'target'} [scheduleType='current'] - График для расчёта
 * @property {string} [deadlineDate] - Ручной дедлайн якоря (YYYY-MM-DD), перекрывает остальные источники
 * @property {number} [criticalThreshold=0] - Порог критичности: TF <= порога → critical
 * @property {number} [nearCriticalThreshold=5] - Порог близкого резерва (рабочие дни)
 */

/**
 * Источник якоря обратного прохода.
 * @typedef {'manual'|'constraint'|'planned'} LocalCPAnchorSource
 */

/**
 * Финишное ограничение цели (если установлено планировщиком).
 * @typedef {Object} LocalCPTargetConstraint
 * @property {string} type - CSTR_TYPE ('CS_MANDFIN' | 'CS_MEO' | 'CS_MEOB')
 * @property {number} dateDays - Дата ограничения (days since epoch)
 */

/**
 * Результат по одной работе контура.
 * @typedef {Object} LocalFloatResult
 * @property {number} lateStartDays - Поздний старт (days since epoch)
 * @property {number} lateFinishDays - Поздний финиш (days since epoch)
 * @property {number} totalFloatLocal - Локальный полный резерв (рабочие дни календаря работы; знаковый)
 * @property {'critical'|'near'|'normal'} criticality - Зона критичности
 * @property {boolean} isCritical - true если totalFloatLocal <= criticalThreshold
 */

/**
 * Результат расчёта локального критического пути (SYS-024).
 * @typedef {Object} LocalCPResult
 * @property {number} targetId - Целевая работа
 * @property {number} anchorDateDays - Дата якоря (days since epoch)
 * @property {LocalCPAnchorSource} anchorSource - Откуда взят якорь (определяет семантику резервов)
 * @property {LocalCPTargetConstraint} [targetConstraint] - Финишное ограничение цели, если установлено
 * @property {'working'|'calendar'} calendarMode - Режим единиц: рабочие дни (есть календари) / календарные дни (fallback)
 * @property {Map<number, LocalFloatResult>} results - Результаты по работам контура (только незавершённые, влияющие на цель)
 * @property {number[]} drivingChain - Локальная критическая цепочка от цели назад (activityId[], порядок: от цели к началу)
 * @property {number[]} cycleNodes - Работы, попавшие в петли логики (исключены из расчёта)
 * @property {string[]} warnings - Диагностика ('calendar-missing', 'calendar-extrapolated', 'target-completed', ...)
 * @property {number} durationMs - Время расчёта
 */

// ============================================================================
// COMP-033: LocalCPReserveOverlay Types (LocalCPStateService)
// ============================================================================

/**
 * Состояние анализа ЛКП (per databaseId).
 * @typedef {Object} LocalCPUIState
 * @property {number} targetId - Целевая работа/веха (activityId текущего графика)
 * @property {string} [deadlineDate] - Ручной дедлайн (YYYY-MM-DD), optional
 * @property {number} criticalThreshold - Порог критичности (раб. дни), default 0
 * @property {number} nearCriticalThreshold - Порог близкой зоны (раб. дни), default 5
 */

/**
 * Детали события local-cp-change (document, bubbles+composed).
 * @typedef {Object} LocalCPChangeDetail
 * @property {string} databaseId
 * @property {LocalCPUIState|null} state - null при сбросе/выгрузке БД
 * @property {LocalCPResult|null} result - Результат расчёта (null без цели)
 */

/**
 * Состояние отображения колонки для одной строки.
 * @typedef {Object} LocalCPCellValue
 * @property {number|null} value - Резерв в рабочих днях (null = вне контура/нет анализа)
 * @property {'critical'|'near'|'normal'|null} criticality
 */

/**
 * Элемент списка селектора цели.
 * @typedef {Object} LocalCPTargetOption
 * @property {number} activityId
 * @property {string} activityCode - Код работы (TASK_CODE)
 * @property {string} taskName
 * @property {boolean} isMilestone - true для вех (нулевая длительность)
 * @property {boolean} [isKeyMilestone] - true для работ с кодом «Техзапуск»/«ВехаСМР» справочника «ЦПС_Отчетность»
 * @property {string} [startDate] - Плановое/фактическое начало (YYYY-MM-DD)
 * @property {string} [endDate] - Плановое/фактическое окончание (YYYY-MM-DD)
 */

/**
 * Префиксный индекс рабочего календаря (CalendarMath, SYS-024 H.8).
 * Материализуется один раз; горячий путь — O(1)/O(log D).
 * @typedef {Object} CalendarIndex
 * @property {number} calendarId - CLNDR_ID исходного календаря
 * @property {Uint32Array} workingDays - Отсортированные рабочие дни (days since epoch, ASC)
 * @property {Int32Array} prefixCount - prefixCount[day - rangeStart] = число рабочих дней в [rangeStart..day]
 * @property {number} rangeStart - Первый день покрытия (int days)
 * @property {number} rangeEnd - Последний день покрытия (int days)
 * @property {number} firstRealDay - Первый день фактических данных календаря
 * @property {number} lastRealDay - Последний день фактических данных календаря
 * @property {Uint8Array} headPattern - Недельный паттерн (7 дней, 0=вс) из первых 28 дней данных
 * @property {Uint8Array} tailPattern - Недельный паттерн из последних 28 дней данных
 * @property {boolean} extrapolatedUsed - Флаг: был факт использования экстраполированной зоны
 */

// Экспорт для использования в других модулях
export {};