service/docs/CONTEXT.md

Словарь предметной области

Редакция 13.10.2026 по дополнению NEW-01–09 и реализации прототипа 5213150. Расчётное поведение ниже принято для прототипа; архитектура рабочего сервиса утверждена 15.10.2026, живые подключения ждут ответов open-questions.md. Общая QA всех NEW ещё предстоит. Расчётный контракт, матрица покрытия.

Источник названий — ТЗ v1.7 §1 с приоритетным дополнением 13.10; расчётная база — prototype-v2 5213150. Имена ниже — единые имена будущих контрактов и кода; UI использует русский термин. role без уточнения не применять: ресурсная роль не даёт прав доступа.

Единицы и совместимость

Дата бизнеса — календарная дата Europe/Moscow; timestamp журнала — UTC instant. День изменения включён в новый период. Статус участия ended вычисляется по Clock, не хранится cron-обновлением.

Часы/FTE/ставки — точные десятичные значения; деньги — копейки или decimal. Формулы не округляют промежуточные результаты. Предложение: rates numeric(18,2), FTE numeric(12,8), hours numeric(20,8), денежный результат decimal с округлением до копейки при представлении; утверждение масштаба и округления — Q-11. JSON decimal передаётся строкой, домен не вычисляет деньги через JS float.

Неизвестно — null плюс причина missing/stale/unmapped, а не 0. В существующей месячной planSummary пустая выборка → 0%; кольца utilizationIndicators и процент периода при N=0 → неизвестно. Hкал остаётся видимой при неизвестной H. Подробнее — calculation-contract.md.

Адаптация прототипа: RequestItem → Request; Line → ResourceLine; targetId+lineIndex → assignmentId с таблицей соответствий при импорте; имена project/manager → projectId/managerId; months[].rate → взвешенная incomeRate. days сохраняется. Демо seed.js остаётся источником сценариев, не справочником рабочего сервиса.

Словарь будущего сервиса использует стабильные ID и Decimal; прототип остаётся на JS Number и именах проектов, localStorage/revision. Эти проектируемые изменения не реализованы документальной редакцией.

service/docs/addendum-coverage.md

Прослеживаемость NEW-01–09

Редакция по дополнению 13.10.2026 и фактическому prototype-v2 5213150. Все девять реализованы принятыми пакетами; эта матрица связывает требования с существующими файлами/проверками, но не объявляет общую QA и риск-ревью завершёнными. Исходный v1.7 и старые картинки сохранены как история. Расчётный контракт, спецификация, проверки, будущий сервис.

Все пути к реализации и тестам ниже — относительно prototype-v2, документы — относительно service/docs. Unit — Node npm test; browser-файлы — функции для Playwright на опубликованной странице. Проектируемые L1–L5/HTTP-интеграции сервиса не считаются этими тестами выполненными.

Отдельный принятый старый дефект: ЦФО/подразделение и CSV — js/views/reports.js, tests/distribution.test.js, tests/browser-addendum.js, REQ-020. Это не десятое требование дополнения.

Следующая общая QA

Повторить все связанные browser-сценарии на одном опубликованном состоянии, РМ/РП и 1440/320/375/390 px; сверить все NEW, отсутствие JS-ошибок, скролл таблиц, полноту/нули и денежные представления. Результаты прежних пакетов и количество unit-тестов не подменяют эту приёмку. Документы service описывают будущие подключения и авторизацию, а не готовый рабочий сервис.

service/docs/adr/0001-data-master.md

ADR-0001: Мастер заявок и назначений

Статус: утверждено 15.10.2026 (Евгений); предложено 13.10.2026. Живые подключения — после ответов на относящиеся Q.

Контекст

INT 03 не определяет мастер. Два независимых writer создадут конфликт между локальной транзакцией, историей и сущностью Bitrix.

Решение

Предложить локальный Postgres как единственный мастер Request/Assignment/DecisionLog. Сфера мастер справочников, Time мастер импортированного факта, 1С календаря/ставок после Q. Живой запуск этой модели требует Q-02.

Последствия

Атомарное решение и журнал доступны без сети. Источники связаны ExternalIdentity; ручные дополнения отдельно. Если нужен Bitrix-master, заменить persistence port недостаточно: пересмотреть транзакции/компенсации и spec. Для копии в Bitrix возможен отдельный outbox, сейчас не реализуется.

Отвергнутые варианты

Dual-write без outbox теряет согласованность; хранить всё одной JSON State блокирует независимые записи; Bitrix-master не выбран без реестра и утверждённой модели.

Дополнение 15.10.2026

Мастер справочника проектов может смениться со Сферы на Контур (ADR-0007): это смена адаптера ProjectCatalog и ExternalIdentity, а не мастера заявок и назначений. Мастером Request/Assignment/DecisionLog остаётся сервис; Контур получает их только лентой событий, без записи в его таблицы.

service/docs/adr/0002-sync-worker.md

ADR-0002: Явный синк и отдельный worker

Статус: утверждено 15.10.2026 (Евгений); предложено 13.10.2026. Живые подключения — после ответов на относящиеся Q.

Контекст

INT 02/04 требуют повторяемого синка и сохранения истории при сбоях. задача №215 задаёт SphereClient и ручной/15-минутный запуск. Nitro tasks остаются experimental.

Решение

Один модуль DirectorySync.run для теста/ручного вызова/worker. Production: отдельный процесс того же Node-релиза (NestFactory.createApplicationContext, без HTTP; ADR-0005), задания/lease/fencing в Postgres, 15 минут как предложение. Локальная PGlite: единственный процесс с ручным runner, cron выключен.

Последствия

HTTP не держится на долгом импорте; ошибки/повторы/полнота наблюдаемы. Нужно эксплуатировать второй процесс и задания; раздельных бизнес-сервисов и очереди Redis нет. Порт источника не знает scheduler; replay и crash проверяются.

Отвергнутые варианты

Nitro scheduledTasks проще, но привязаны к платформе/экспериментальному API и жизненному циклу web; in-memory cron теряет задание; отдельные микросервисы/брокер пока не оправданы. Пересмотр допустим при стабильном Nitro scheduler, сохраняющем тот же run.

service/docs/adr/0003-secrets.md

ADR-0003: Серверные секреты интеграций

Статус: утверждено 15.10.2026 (Евгений); предложено 13.10.2026. Живые подключения — после ответов на относящиеся Q.

Контекст

INT 04: URL входящего webhook сам является секретом, scope зависит от прав его владельца. Клиентский config и логи не могут его раскрывать.

Решение

Private runtimeConfig получает secrets из env секретного хранилища среды. В репо только .env.example с пустыми значениями. Для sync — отдельный служебный read-only аккаунт/приложение с минимальными scopes; transport allowlist методов чтения как дополнительный барьер. OAuth client secret и session key отдельно; refresh tokens при хранении шифруются ключом вне БД.

Последствия

Ротация требует обновления secrets/restart и проверки read smoke. Редактировать scope и выдавать credentials может оператор по регламенту; бухгалтерские ставки не загружаются целиком без необходимости. Структурные логи/Sentry удаляют headers, query tokens, webhook paths, тела профилей/ставок. Тесты проверяют отсутствие утечек.

Отвергнутые варианты

Токены в public runtimeConfig/браузере/коммитах запрещены; один админский webhook на все интеграции избыточен; шифрование ключом из той же таблицы БД не защищает backup.

service/docs/adr/0004-identity-access.md

ADR-0004: Идентификация отдельно от прав

Статус: утверждено 15.10.2026 (Евгений); предложено 13.10.2026. Живые подключения — после ответов на относящиеся Q.

Контекст

NFR 01 и задача №215 используют вход Сферы; возможен корпоративный SSO. Владение группой/должность не доказывают роль РМ.

Решение

Рекомендовать Bitrix OAuth code flow через IdentityProvider; корпоративный OIDC — альтернативный adapter после Q-08. VerifiedIdentity связывается по issuer+subject/portal+userId, далее серверные AccessGrant и opaque session cookie. viewCost отдельно, по умолчанию deny.

Последствия

Нужно согласовать grant/revoke/TTL/freshness и перенос портфеля. Проверка scope до запросов/агрегаций/CSV, revoke при деактивации. Test identity только NODE_ENV=test; production-negative тест обязателен, SPHERE_FAKE не открывает вход.

Отвергнутые варианты

Имена/email и client mode=rm не идентификация. Sync webhook не логин пользователя. Копировать default member и fake auth задача №215 без усиления нельзя: другая матрица прав и требование test-only.

Дополнение 15.10.2026

Третий IdentityProvider — доверенный шлюз платформы Контур (ADR-0007): личность из подписанного заголовка или токена, проверка подписи на сервере. Роли платформы переводятся в AccessGrant версионируемой RoleMapping (Q-14); роль из запроса клиента, как и раньше, не доверяется.

service/docs/adr/0005-stack-modules.md

ADR-0005: Стек и глубокие модули

Статус: утверждено 15.10.2026 (Евгений); предложено 13.10.2026, пересмотрено 15.10.2026 (UI — микрофронтенд на Vue + Vite вместо Nuxt; API — NestJS вместо Nitro).

Контекст

Нужна ручная поддержка и близость к задача №215 (Nuxt 4/Nitro, Drizzle, zod); UI прототипа — vanilla mock, ТЗ описывает ещё более раннюю Cloudflare-версию. Сервис делается standalone, но потом встраивается в платформу Контур как микрофронтенд (ADR-0007); механизм встраивания и стек хоста не известны (Q-12). Компонент Nuxt живёт только внутри Nuxt-приложения — useNuxtApp, роутер, плагины, runtimeConfig и автоимпорты в чужом хосте отсутствуют; SSR внутреннему инструменту не нужен. Для API нужен фреймворк, на котором сервис смогут поддерживать бэкендеры со стороны; DI нужен самой архитектуре — порты с fake и живыми адаптерами выбираются в composition root.

Решение

TypeScript strict, Node 22 LTS, pnpm-монорепо, zod/shared DTO, Postgres/Drizzle, PGlite локально/тесты, Vitest/fast-check/Playwright. Шесть глубоких модулей из architecture.md, чистый Calculations и заменяемые ports.

• API — NestJS 12 (ESM, платформа Express). Глубокий модуль architecture.md = Nest-модуль, наружу экспортирует только свой фасад; порты — injection tokens, адаптеры fake/живые выбирает AppModule по конфигурации. Контроллеры тонкие: zod-DTO через nestjs-zod (createZodDto, глобальный ZodValidationPipe), OpenAPI — @nestjs/swagger + cleanupOpenApiDoc из тех же zod-схем; class-validator не используется. Access — guard, создающий ActorContext; DomainError → общий формат ошибки — exception filter. Конфигурация — @nestjs/config с проверкой env схемой zod.
• Домен без Nest. domain/ и packages/calculations — чистый TypeScript без декораторов и @Injectable; Nest-провайдеры оборачивают их через useFactory в server/. Декораторы живут только в server/.
• Worker — тот же релиз, отдельный процесс NestFactory.createApplicationContext(WorkerModule) без HTTP (ADR-0002); расписание только создаёт задания в Postgres.
• UI — Vue 3 + Vite + vue-router, SPA без SSR, собирается как микрофронтенд. Единственный вход — mount(el, ctx), возвращающий unmount(); ctx даёт apiBase, способ авторизации запросов, режим роутера (history с basePath или memory), язык и обработчик навигации наружу. Каждое монтирование создаёт свой экземпляр Vue-приложения, роутера и состояния; глобальных переменных, слушателей вне корня и стилей вне корня нет.
• Standalone — тонкая оболочка над тем же mount: шапка, вход через Access, history-роутер. Отдельной сборки экранов для standalone нет.
• Встраивание — Module Federation (решено 15.10.2026). ui/ собирается remote через @module-federation/vite: remoteEntry.js отдаёт модуль ./mount; Vue объявлен shared singleton — если хост на Vue, берётся его копия, иначе своя из сборки. Standalone-оболочка грузит тот же mount напрямую. Стек хоста (Q-12) меняет только настройки shared, домен, API и экраны не меняются.

Последствия

Один язык и репозиторий; перенос смысла calc.js без seed globals; стандартный для рынка Node-бэкенд, понятный без знания Nuxt; Postgres concurrency тесты отдельно от embedded БД. Без Nuxt нет автоимпортов, file-based routing и useFetch: роуты, API-клиент и обработка ошибок описываются явно — это плата за переносимость. Стили изолируются корневым классом и @layer; шрифты AeonikPro коммерческие и подключаются только оболочкой, а не микрофронтендом. Vitest не выпускает метаданные декораторов через esbuild: тестам Nest нужен SWC-плагин (unplugin-swc) — настраивается в П1. Nest 12 — только ESM: зависимости и конфиги проверяются на ESM в П1. Патч-версии фиксировать в П1 с lockfile.

Отвергнутые варианты

Nuxt 4 UI+Nitro (редакция 13.10.2026) — удобен standalone, но не встраивается в хост на другом фреймворке без iframe. Nitro без Nuxt (промежуточная редакция 15.10.2026) — легче, ближе к задача №215, но ниша: порты и composition root пришлось бы собирать руками, а поддержку искать среди знающих Nuxt. Fastify-платформа Nest — быстрее, но меньше готовых middleware для cookie/CSRF; переход возможен без изменения модулей. Web component и iframe как механизм встраивания — отвергнуты решением 15.10.2026 в пользу Module Federation; iframe остаётся только запасным вариантом отладки. Микросервисы усложнят транзакции и диагностику; generic слои репозиториев раздувают интерфейсы; повтор Cloudflare D1/State main и переключателя ролей не соответствует рабочему контуру.

service/docs/adr/0006-versioned-data.md

ADR-0006: Снимки решений, календаря и факта

Статус: утверждено 15.10.2026 (Евгений); предложено 13.10.2026. Живые подключения — после ответов на относящиеся Q.

Контекст

NFR 02 требует исходных и согласованных значений. Справочники/календари меняются, Time исправляет часы; повторная сумма приводит к дрейфу отчётов.

Решение

Формулы дополнения приняты: H = календарь минус объединённые рабочие часы отпуска/больничного, P=FTE×H, N=ΣH; отдельной нормы продажи нет. Расчётный контракт фиксирует полноту и допущения actuals/отсутствий прототипа 5213150.

Рабочая архитектура (утверждена 15.10.2026): исходный Request, версии Assignment и append-only DecisionLog сохраняются транзакционно; CostRateSnapshot при решении; CalendarVersion и AbsenceSnapshot/Coverage — явные входы расчёта. Time entries upsert по ID/version с coverage, без повторного сложения; Decimal вместо JS Number. В текущем прототипе этих серверных таблиц/транзакций нет.

Последствия

Даты отсутствий объединяются до норм; нет двойного вычета. Обе записи vacation/sick обязательны для известной H, пусто не 0. Сводные рабочие часы без пересечений распределяются по календарю пропорционально только в демо; точные дни задаются dates. Реальная схема/полнота источника — Q-06.

Изменение текущих введённых отсутствий в прототипе меняет P и деньги уже согласованной заявки. Новая политика исторического пересчёта, замораживания денег или пересогласования рабочего сервиса этим ADR не утверждается и не реализуется. Срок хранения/удаления — Q-09. Исходные месячные ставки сохраняются в дневных изменениях; их миграция рабочего сервиса возможна лишь отдельным принятым импортом.

Отвергнутые варианты

Чтение текущей C для всех прошлых решений меняет историю; округление до суммирования и замена unknown на 0 дают неверные итоги; event sourcing всего приложения избыточен — достаточно версий агрегатов и журнала решений.

service/docs/adr/0007-contour-context.md

ADR-0007: Сервис как ограниченный контекст Контура

Статус: утверждено 15.10.2026 (Евгений). Интеграция с Контуром отложена; сейчас реализуются только заделы — API-first, ProjectCatalog и тип объекта (REQ-039, REQ-040, REQ-047). Остальное решение — ориентир границы, а не работа текущих пакетов.

Контекст

Ресурсное планирование станет этапом 04 «Команда и ресурсы» платформы Контур (прототип процесса: https://commercial-resource-contour.jammyglade1.chatgpt.site/). Контур ведёт сквозной процесс лид → сделка → договор → проект/продукт/сервис → план работ → команда → бюджет → трекинг → P&L → изменения → приёмка → закрытие и восемь ролей. Карточку проекта создаёт договор, а не Сфера; заявку на ресурс открывают из карточки проекта; бюджет берёт плановые FTE из согласованных назначений, фактические — из внесённых часов; изменения согласуют несколько ролей; после приёмки руководитель практики освобождает команду. Стек и способ встраивания Контура не определены (Q-12).

Решение

Сервис остаётся самостоятельным модульным монолитом (ADR-0005), но его граница с платформой задаётся портами и API, а не общими таблицами или UI:

• API-first. Всё, что делает UI, доступно через /api/v1 с OpenAPI, сгенерированным из zod-контрактов. domain/ и server/ не импортируют ui/ и Vue. UI — микрофронтенд с mount(el, ctx) (ADR-0005): Контур монтирует те же экраны, что и standalone-оболочка. Calculations публикуется отдельным пакетом без зависимостей от Vue, Nitro, БД и DOM.
• ProjectCatalog вместо прямой зависимости от Сферы: адаптер Сферы сейчас, адаптер Контура потом. Проект несёт kind = project|product|service и внешнюю ссылку; локальный projectId не меняется при смене источника.
• ActualsSource вместо TimeSource в домене: Time сейчас, трекинг Контура потом; правила полноты и идемпотентности одни.
• Права от платформы. Access принимает проверенную личность от IdentityProvider: Bitrix OAuth или доверенный шлюз платформы. Роли Контура сопоставляются с AccessGrant конфигурацией (Q-14); домен знает только pm, rm, viewCost и read-only scope отчётов.
• DecisionPolicy. Решение по заявке и изменению проходит через политику: по умолчанию достаточно решения РМ; платформа может потребовать дополнительные согласования. До полного набора решений план не меняется — это уже инвариант pending (REQ-016).
• Outbox. Факты для бюджета, P&L и закрытия публикуются событиями в той же транзакции, что и решение; потребители читают ленту GET /api/v1/events по курсору. Брокер не вводится.
• Внешние команды. Платформа может создать черновик заявки по проекту и инициировать освобождение команды; решение по-прежнему принимает РМ.

Последствия

Заделы П1 и П4 почти ничего не стоят. Outbox, ленту событий и DecisionPolicy сейчас не делаем: при запуске Контура их добавление затронет транзакции решений П6 и П8 — это осознанная цена отсрочки. Цена — лента событий с версиями схемы, contract-тесты на OpenAPI и события, конфигурация сопоставления ролей. UI встраивается в Контур через Module Federation (ADR-0005): Контур грузит ./mount из remoteEntry.js, домен и экраны от этого не зависят.

Отвергнутые варианты

Общая БД с Контуром ломает владение транзакциями и блокировками ёмкости (ADR-0001). Брокер сообщений сейчас не оправдан при одном потребителе и неизвестном стеке. Nuxt для UI отвергнут в ADR-0005: его компоненты не живут вне Nuxt-приложения. Перенос бюджета, P&L и многосторонних согласований внутрь сервиса раздувает контекст: это модули Контура, сервис только отдаёт им факты.

service/docs/architecture.md

Архитектура рабочего сервиса

Редакция 13.10.2026 по дополнению NEW-01–09 и реализации прототипа 5213150. Расчётное поведение ниже принято для прототипа; архитектура рабочего сервиса утверждена 15.10.2026, живые подключения ждут ответов open-questions.md. Общая QA всех NEW ещё предстоит. Расчётный контракт, матрица покрытия.

Статус: утверждено 15.10.2026 (Евгений); живые подключения — после ответов на относящиеся вопросы open-questions.md. Требования — spec.md; решения — adr/; открытые продуктовые развилки — open-questions.md. Схемы — diagrams.html (самодостаточная страница с SVG, без внешних скриптов).

Основание и совместимость со задача №215

ТЗ §30: INT 01 — адаптер сущности проектов; INT 02 — неразрушающий синк; INT 03 — один мастер назначений; INT 04 — серверные секреты. NFR 01 — область доступа до чтения данных; NFR 02 — транзакции и журнал; NFR 03 — наблюдаемость и согласуемые восстановление/ёмкость.

задача №215 прочитана 13.10.2026: Nuxt 4/Nitro (здесь UI — Vue + Vite-микрофронтенд без Nuxt, API — NestJS, ADR-0005), TypeScript, Node 22, pnpm, Postgres/Drizzle, PGlite без DATABASE_URL, zod, vitest/Playwright. Её SphereClient и интервал SPHERE_SYNC_MINUTES=15 — общий контракт, пока не доказано наличие готовой библиотеки. Не объявляем скопированный интерфейс переиспользованным кодом: при реализации сначала найти реализацию и контрактные фикстуры. Модель Team, степени access и предупреждение FTE>1 из «Итераций» сюда не переносятся: ТЗ стаффинга требует блокировку перегрузки и роли РП/РМ. Фейковый вход задача №215 по SPHERE_FAKE сужен здесь до NODE_ENV=test.

Репозиторий service создан отдельно, remote не задан по условию задачи; до правок каталог отсутствовал. Проверены локальные ветки prototype-v2: main, t-12345-data/screens/shell, архитектурной ветки нет; remote отсутствует, поиск MR неприменим. История задача №232 и задача №215 пуста. Это новая архитектурная постановка, не исправление неудачной реализации.

C4 L1: контекст

flowchart LR
  PM[Руководитель проекта] -->|Заявка, изменение, свои отчёты| S[Сервис ресурсного планирования]
  RM[Ресурсный менеджер] -->|Решения, общий план| S
  S -->|Чтение справочников и проектов| B[Сфера / Bitrix24]
  S -->|Чтение фактических часов| T[Time Лоции]
  S -->|Чтение календаря и возможных ставок| C[1С]
  S -->|Вход и проверка личности| I[Bitrix24 OAuth или корпоративный SSO]
  O[Технический оператор] -->|Состояние синка, восстановление| S
  K[Контур: проекты, бюджет, P&L, закрытие] -.->|Проекты, черновики заявок, освобождение команды| S
  S -.->|Лента событий решений и назначений| K

Пунктир — граница с платформой Контур по ADR-0007: до её запуска проекты идут из Сферы, ленту событий никто не читает.

Пользователи не обращаются к интеграционным API напрямую. OAuth обмен и служебный REST-синк — разные подключения. Time не считается стандартным методом Bitrix24. Ни один поток не пишет в Сферу (рекомендация по INT 03).

C4 L2: контейнеры

flowchart TB
  U[Браузер: standalone-оболочка или хост → микрофронтенд Vue] -->|HTTPS, cookie, общие DTO| A[NestJS API: доступ и модули]
  A -->|Транзакции и проекции| D[(Postgres)]
  W[Фоновый worker: Nest application context, те же модули] -->|Задания, lease, checkpoint| D
  A -->|Ручной запуск: запись задания| D
  W -->|Порты чтения| E[Bitrix24 / Time / 1С]
  A -->|Порт идентификации| I[OAuth / SSO]
  A --> L[Логи, метрики, Sentry]
  W --> L
  D --> B[Резервные копии и проверка восстановления]

Один репозиторий и один модульный монолит. В production API и worker — два процесса одного релиза с Postgres. Worker выбран вместо experimental Nitro scheduledTasks (ADR-0002); Redis и брокер сообщений не нужны. Scheduler создаёт задания в БД, worker обрабатывает их с lease и повтором после падения. При локальной PGlite только один владелец БД — API-процесс со встроенным ручным runner, без второго процесса и cron; отдельный worker требует DATABASE_URL. Это предотвращает совместный доступ процессов к embedded-файлу.

C4 L3: глубокие модули

flowchart LR
  H[HTTP handlers] --> A[Доступ]
  H --> R[Заявки и согласование]
  H --> P[Назначения и ресурсный план]
  H --> V[Отчёты]
  R --> P
  R --> C[Расчёты]
  P --> C
  V --> C
  R --> A
  P --> A
  V --> A
  W[Worker / ручной запуск] --> S[Справочники и синк]
  S --> X[SphereClient / ProjectSource / TimeSource / OneCSource]
  R --> DB[(Транзакционная БД)]
  P --> DB
  V --> DB
  S --> DB
  A --> DB

Модули сами владеют запросами к своим таблицам, а не цепочкой generic repository/service/controller. Общий UnitOfWork — инфраструктурная граница транзакции, не отдельный бизнес-модуль. Доступ обеспечивает policy-функции и scoped query predicates; ни один публичный метод чтения не принимает произвольный SQL scope от клиента.

Сигнатуры ниже — эскиз контракта TypeScript, не код сервиса. Result<T> — дискриминированный результат {ok:true,value:T} либо {ok:false,error:DomainError}; Promise только для I/O. DTO определяются один раз в shared/contracts/, схемы zod выводят типы. ActorContext создаётся сервером через Доступ. ID — номинальные строковые типы; Decimal — точное число, сериализуемое строкой. Tx выдаётся только UnitOfWork; наружу HTTP не выходит.

Заявки и согласование — Requests

interface Requests {
  create(actor: ActorContext, cmd: CreateRequest): Promise<Result<RequestView>>;
  proposeChange(actor: ActorContext, cmd: ChangeAssignment): Promise<Result<RequestView>>;
  decide(actor: ActorContext, cmd: DecisionCommand): Promise<Result<RequestView>>;
  get(actor: ActorContext, id: RequestId): Promise<Result<RequestView>>;
  list(actor: ActorContext, query: RequestQuery): Promise<Result<Page<RequestView>>>;
}
// Команды содержат expectedVersion и commandId; DecisionCommand — approve/return/reject.

Прячет: конечный автомат, validation ролей/ставок, idempotency, проверку версии, снимки первичной заявки, журнал решений и одну транзакцию изменения назначений. Вызывает: контроллеры API. Проверяется: L1 автомат и правила решения; L2 через create/decide с настоящей БД; L4 права и ошибки, L5 заявка→план. Requests владеет Request/ResourceLine/AssignmentChange/DecisionLog/CommandReceipt. Вызов Assignments.applyDecision происходит внутри его Tx, а не отдельным HTTP-запросом.

Назначения и ресурсный план — Assignments

interface Assignments {
  previewChange(actor: ActorContext, cmd: ChangeDraft): Promise<Result<ChangePreview>>;
  getPlan(actor: ActorContext, query: PlanQuery): Promise<Result<PlanView>>;
  list(actor: ActorContext, query: AssignmentQuery): Promise<Result<Page<AssignmentView>>>;
  applyDecision(tx: Tx, decision: ApprovedDecision): Promise<Result<AssignmentVersion[]>>;
}

Прячет: дневные интервалы, состояния active/ended, единственное ожидающее изменение, блокировки общей ёмкости людей, версии назначений и согласованную проекцию плана. Вызывает: API для чтения/превью, Requests для решения; ApprovedDecision — внутренний тип модуля, клиент его не создаёт. Проверяется: L1 дневные преобразования; L2 смена версии без двойного учёта и откат; Postgres-проверка конкурентного решения; L4 область РП; L5 замена. Владеет Assignment/AssignmentVersion/AssignmentDay; изменение существующей версии запрещено, текущий указатель меняется транзакционно.

Расчёты — Calculations

interface Calculations {
  employeeNorm(calendar: CalendarMonth, absences: EmployeeMonthAbsences): Decimal | null;
  plannedHours(plan: MonthPlan, availability: EmployeeAvailability): Decimal | null;
  changePlan(plan: AssignmentPlan, change: ChangeDraft, availability: EmployeeAvailability): ChangePreview;
  overloads(plans: AssignmentPlan[], availability: AvailabilityByEmployee): Overload[];
  finance(items: FinancialItem[]): FinanceTotals;
  utilization(periods: PeriodTotals[]): UtilizationTotals;
  releaseDate(plan: AssignmentPlan, availability: EmployeeAvailability): LocalDate | null;
  periodTotal(periods: PersonalPeriod[]): PeriodTotals;
  planTotal(rows: VisibleEmployeePlan[]): PlanTotals;
  utilizationIndicators(input: ScopedUtilizationInput): UtilizationIndicators;
}

Прячет: формулы §1, приоритет days, взвешивание, допуски 0,00001 FTE / 0,001 п.п., отсутствие данных и правила точности. Вызывают: Requests/Assignments/Reports. Проверяется: L1 таблицы AC и property-based fast-check, без БД/сети. База — функции calc.js; глобальные imports seed.js из costRate/viewScope заменяются аргументами. Clock нужен вызывающему модулю для проверки даты, Calculations получает уже определённую дату. Никаких Date.now(), fetch или process.env.

Расчётные входы и полнота

Контракт calculation-contract.md описывает реализованные значения. Для домена будущего сервиса EmployeeAvailability содержит календарь, обе записи отсутствий и их полноту; это не второй тип нормы продажи. PersonalPeriod содержит персональные hours/norm, VisibleEmployeePlan — уже ограниченный состав людей, ScopedUtilizationInput — один scope для P, Pком и A. Null сохраняется до представления. Отсутствия объединяются до расчёта доступных часов; UI не повторяет вычет. Сводные часы без дат распределяются пропорционально календарным часам только как допущение прототипа; рабочий источник и точность дат — Q-06.

Предложение хранения: AbsenceEntry(employeeId, kind=vacation|sick, month, dates или hours, sourceVersion), AbsenceCoverage(employeeId, month, kind, confirmed). Пропуск записи без coverage не является нулём. В прототипе coverage выражено наличием записи в reportData, а не отдельной таблицей. Импорт, версии БД и HTTP-порт отсутствий ещё не реализованы.

Отчёты — Reports

interface Reports {
  get(actor: ActorContext, query: ReportQuery): Promise<Result<ReportView>>;
  exportCsv(actor: ActorContext, query: ExportQuery): Promise<Result<CsvFile>>;
  updateLocalData(actor: ActorContext, cmd: LocalReportDataCommand): Promise<Result<ReportDataVersion>>;
}

Прячет: безопасную область и агрегации, категории проектов, actual coverage, отсутствие факта, текущие кадровые атрибуты, проекцию ставок по viewCost, экранирование CSV. Вызывают API и UI через API. Проверяется: L1 примеры AC 41–66 в Calculations; L2 real DB фильтры/полнота; L4 матрица прав и отсутствие утечек в CSV; L5 отчёт. Владеет только локальными overrides/категориями/ручными actuals/vacations/sickLeaves; импортированные snapshots принадлежат Sync и читаются, не редактируются. Итоги собираются одной согласованной версией снимков, версии возвращаются в метаданных.

Справочники и синк — DirectorySync

interface DirectorySync {
  enqueue(actor: OperatorContext, source: SourceKind): Promise<Result<SyncRunId>>;
  run(input: SyncInput): Promise<Result<SyncResult>>;
  status(actor: ActorContext, source: SourceKind): Promise<Result<SyncStatus>>;
  resolveIdentity(actor: OperatorContext, cmd: IdentityMapping): Promise<Result<MappingVersion>>;
}
// SyncInput: source, runId, asOf, mode=incremental|reconcile; часы/ID внедряются фабрикой.

Прячет: постраничное чтение, staging, checkpoint, дедупликацию, полные сверки, мягкую деактивацию, карантин неподтверждённых сопоставлений и атомарную активацию снимка. Вызывают worker и защищённый операторский API; run доступен программно без scheduler. Проверяется L2 повтор, обрыв, восстановление; L3 адаптеры на фикстурах; L4 только оператор запускает; L5 устаревание. Владеет справочниками, ExternalIdentity, SyncRun/SyncCheckpoint, ImportSnapshot, ActualEntry/Coverage, CalendarVersion/Day, AbsenceSnapshot/Coverage, CostRateVersion. Детерминизм: одинаковые входы+Clock+IdGenerator → одинаковые изменения доменных данных; технический runId может отличаться.

Доступ — Access

interface Access {
  beginLogin(input: LoginStart): Promise<Result<LoginRedirect>>;
  finishLogin(input: LoginCallback): Promise<Result<SessionCookie>>;
  authenticate(input: SessionInput): Promise<Result<ActorContext>>;
  authorize(actor: ActorContext, operation: Operation, object: ObjectScope): Result<Permit>;
  scope(actor: ActorContext, resource: ResourceKind): AuthorizedScope;
  revoke(principalId: PrincipalId): Promise<void>;
}

Прячет: OAuth/OIDC flow, связь external subject→principal, сессии, права и scope, отзыв после деактивации. Вызывают все публичные модули и handlers. Проверяется L1 policy, L2 session/grants, L3 IdentityProvider, L4 полная матрица и production-negative fake-login, L5 вход в тесте. Владеет Principal, Session, AccessGrant; AccessGrant не редактируется Requests. ActorContext нельзя передать через JSON как доверенный объект.

Порты и адаптеры

interface SphereClient { // совместимо по именам и смыслу со задача №215
  getTasks(ids: string[]): Promise<SphereTask[]>;
  listGroupTasks(groupId: string, options: {openOnly: boolean}): Promise<SphereTask[]>;
  searchGroups(q: string): Promise<SphereGroup[]>;
  getGroupMembers(groupId: string): Promise<SphereUser[]>;
  listDepartments(): Promise<SphereDepartment[]>;
  searchUsers(query: {q?: string; departmentId?: string; ids?: string[]}): Promise<SphereUser[]>;
}
interface ProjectSource { read(cursor?: string): Promise<SourcePage<SourceProject>> }
interface TimeSource { read(query: TimeWindow, cursor?: string): Promise<SourcePage<TimeEntry>> }
interface OneCSource {
  calendar(year: number): Promise<SourceSnapshot<CalendarDay>>;
  absences(query: AbsenceWindow, cursor?: string): Promise<SourcePage<SourceAbsence>>;
  costRates(cursor?: string): Promise<SourcePage<SourceCostRate>>;
}
interface IdentityProvider { begin(input: LoginStart): Promise<LoginRedirect>; verify(input: LoginCallback): Promise<VerifiedIdentity> }
interface Clock { now(): Instant; today(zone: 'Europe/Moscow'): LocalDate }
interface IdGenerator { next(): string }
interface CurrentUser { get(): Promise<Result<ActorContext>> }

SphereUser: id/name/position/departmentIds/active; SphereDepartment: id/name/parentId; SphereTask: id/title/stageName/closed/groupId/responsibleId/deadline; SphereGroup: id/name/membersCount. Методы, не нужные стаффингу сейчас, не вызываются ради заполнения данных. Поскольку searchUsers по умолчанию ищет только активных, сверка сохранённых ID выполняется явно через ids с получением ACTIVE=false; отсутствие не доказывает увольнение.

SourcePage содержит items/nextCursor/completeness/sourceVersion; общий транспорт не притворяется, что пагинация у всех систем одинаковая. ProjectSource реализуется GroupProjectSource, DealProjectSource или SmartProcessProjectSource, без проверки типа сущности внутри домена. TimeSource и OneCSource — проектируемые контракты: фактические endpoint и схема ещё не известны. Для каждого — HTTP-адаптер и Fake-адаптер. В e2e фейковые HTTP-серверы проверяют ещё и транспорт; модульные тесты используют in-memory fake порты.

Граница с Контуром

Сервис — ограниченный контекст «Команда и ресурсы» платформы Контур (ADR-0007); требования — REQ-039–048. Сейчас реализуются только ProjectCatalog с типом объекта и API-first; DecisionPolicy, Outbox, лента событий, шлюз платформы и ActualsSource описаны на будущее и отложены до запуска Контура.

interface ProjectCatalog { // обобщает ProjectSource; адаптеры: Сфера сейчас, Контур потом
  read(cursor?: string): Promise<SourcePage<SourceProject>>; // SourceProject: externalId, name, kind, status, managerIds, contractRef?
}
interface ActualsSource { read(query: TimeWindow, cursor?: string): Promise<SourcePage<ActualEntry>> } // Time или трекинг Контура
interface DecisionPolicy { required(subject: DecisionSubject): DecisionRequirement[] } // по умолчанию [{role:'rm'}]
interface Outbox { append(tx: Tx, events: IntegrationEvent[]): Promise<void> } // только внутри транзакции решения
interface RoleMapping { grants(identity: VerifiedIdentity, platformRoles: string[]): AccessGrant[] } // версионируемая конфигурация, Q-14

• ProjectSource из «Портов и адаптеров» становится реализацией ProjectCatalog; kind хранится колонкой Project. Переключение источника меняет только ExternalIdentity (REQ-040).
• TimeSource — адаптер ActualsSource. Источник факта задаётся на период (REQ-046), Reports не знает адаптера.
• Requests.decide спрашивает DecisionPolicy; пока требования не выполнены, решение пишется частичным в DecisionLog, Assignments.applyDecision не вызывается (REQ-045).
• Requests и Assignments пишут IntegrationEvent через Outbox в своей Tx (REQ-042). Таблица integration_event(seq bigserial, eventId, type, schemaVersion, aggregateId, aggregateVersion, payload, createdAt); лента читается по seq, payload C маскируется для потребителя без viewCost.
• Access получает второй IdentityProvider — PlatformGatewayIdentity (подписанный заголовок или токен шлюза, проверка на сервере) и RoleMapping (REQ-044). Bitrix OAuth остаётся первым адаптером.
• UI — микрофронтенд с mount(el, ctx) (REQ-049): Контур монтирует те же экраны, что и standalone-оболочка; правило импортов (REQ-047) держит домен независимым от UI.

Модель хранения и транзакции

erDiagram
  REQUEST ||--|{ RESOURCE_LINE : contains
  REQUEST ||--o{ DECISION_LOG : records
  RESOURCE_LINE ||--o{ ASSIGNMENT : creates
  ASSIGNMENT ||--|{ ASSIGNMENT_VERSION : versions
  ASSIGNMENT ||--o{ ASSIGNMENT_CHANGE : changes
  EMPLOYEE ||--o{ ASSIGNMENT : assigned
  PROJECT ||--o{ REQUEST : requested
  PROJECT ||--o{ PROJECT_MANAGER : grants
  EMPLOYEE ||--o{ ACTUAL_ENTRY : worked
  PROJECT ||--o{ ACTUAL_ENTRY : measured
  CALENDAR_VERSION ||--|{ CALENDAR_DAY : defines
  EMPLOYEE ||--o{ ABSENCE_ENTRY : absent
  ABSENCE_SNAPSHOT ||--o{ ABSENCE_ENTRY : contains
  ABSENCE_SNAPSHOT ||--o{ ABSENCE_COVERAGE : confirms

Таблицы нормализованы: нет одной JSON-записи State/main, которая блокирует весь сервис. JSON допустим для неизменяемого before/after в DecisionLog и валидированного сырого staging с ограниченным сроком хранения; фильтруемые поля и внешние ключи — колонки.

• Уникальность (source, entityType, externalId); FK не позволяют связать запись с неизвестным человеком/проектом. Роли и имена имеют локальные ID.
• Версия Request защищает заявку, Assignment.version защищает исходное назначение. Частичный unique index запрещает два pending-change одного assignmentId.
• Для решения транзакция сначала блокирует стабильные строки Employee всех затронутых людей в порядке ID (FOR UPDATE), затем Request и Assignment; перечитывает их версии и весь согласованный дневной план этих людей. Все решения используют один порядок. Проверка общей загрузки видит назначения всех проектов независимо от видимости актору, ошибка наружу не раскрывает чужие проекты/ставки.
• Read Committed с блокировками Employee достаточен при обязательном использовании того же протокола всеми writer; вставка назначения без этого модуля запрещена. Конкурентность проверяется именно на Postgres, не заменяется последовательным тестом PGlite.
• Проверка active/closed, разрешений и rateVersion повторяется в транзакции. Sync обновляет затрагиваемые employee-строки тем же порядком блокировок; при изменении ставки после превью возвращается RATE_CHANGED и требуется новое подтверждение, а не скрытое принятие убытка.
• Requests создаёт DecisionLog и новые версии Assignments в одной транзакции; сбой журнала откатывает решение. CommandReceipt уникален по principalId+commandId, хранит hash команды и безопасную ссылку результата; повтор с иным payload → COMMAND_KEY_REUSED. Проверка текущих прав выполняется и при повторе.
• Для будущего сервиса предлагаются ссылки на CalendarVersion и AbsenceSnapshot/Coverage в метаданных расчёта. Прототип вычисляет результат по текущим введённым отсутствиям; их изменение меняет P и деньги во всех представлениях. Новая политика исторического пересчёта, фиксации денег и пересогласования рабочего сервиса не утверждена и не входит в дополнение.
• Журнал append-only для приложения, с маскированием C и производных значений при чтении без viewCost. Нельзя утечь through before/after. Административное удаление/обезличивание по NFR 03 — отдельный регламент после Q-09, не обычный UPDATE истории.
• Заявки сохраняют исходного РП; project_manager даёт доступ к проекту, но не автоматически ко всем заявкам других РП. Передача портфеля — Q-08, отдельная аудируемая операция.

API и отличие от прототипа

/api/v1 — предложение нового контракта, а не обещание бинарной совместимости с прототипом. Старые action=create/approve/return/reject/change сохраняют бизнес-смысл; manager из строки заменён проверенной личностью, lineIndex — стабильным ID, global revision — версиями агрегатов. Старый GET State не переносится в рабочий API, чтобы не отдавать данные всех проектов. Если нужен импорт прототипа, он делается отдельной проверяемой операцией (Q-10).

Общая ошибка {error:{code,message,details?},requestId}: 400 INVALID_REQUEST; 401 UNAUTHORIZED; 403 FORBIDDEN; 404 NOT_FOUND для чужого объекта; 409 VERSION_CONFLICT/CHANGE_PENDING/RATE_CHANGED/COMMAND_KEY_REUSED; 422 OVERLOAD/LOSS_CONFIRMATION_REQUIRED/INVALID_TRANSITION/UNMAPPED_REFERENCE; 503 SOURCE_UNAVAILABLE/STORAGE_UNAVAILABLE. Тексты локализуются, тесты проверяют коды. Область прав применяется до агрегации и пагинации; стабильная сортировка (createdAt,id) или (name,id), cursor, ограниченный размер страниц. Подробности ошибки не раскрывают скрытые ставки.

Правила проекта и зачем

Будущая структура: ui/{src/{mount.ts,router,views,components,composables,api},vite.config.ts} — микрофронтенд, shell/ — standalone-оболочка (вход, шапка, шрифты), shared/contracts, server/{modules,auth,filters,composition} — NestJS (main.ts — API, worker.ts — application context), domain/{requests,assignments,calculations,reports,access,sync}, adapters/{sphere,contour,time,onec,identity,db}, packages/calculations, worker, db/migrations, tests/{domain,module,contract,api,e2e,fixtures,builders}. Это ориентир ответственности, не scaffolding в этой задаче. SQL и adapters конкретного модуля можно держать рядом с ним; не создавать интерфейс на каждый вызов ORM.

Эксплуатация и NFR 03

Логи: requestId/runId, source, duration, resultCode, checkpoint; без токенов, webhook URL, ставок и полных ответов API. Метрики: sync_last_success_age, sync_errors, pending_jobs, quarantined_records, API latency/error rate, backup/restore age. Alert по порогам Q-09; source outage не делает live=false и не уничтожает кеш. UI показывает stale с временем и отдельную ошибку, а не зелёный статус по наличию старого кеша.

Операторский порядок: проверить health/schema → source status и runId → исправить секрет/маппинг → явный reconcile → проверить изменённые/карантинные строки. Cursor не сбрасывать вручную в SQL. Резервирование Postgres и ключей отдельно, шифрованные backup, восстановление в изолированную БД с проверкой FK/версий/журнала и smoke. Частота, RPO/RTO, retention, удаление и нагрузка остаются Q-09. Откат релиза только на совместимую схему; миграции expand/contract, перед необратимой миграцией проверенная копия.

Проверенные технические источники

На 13.10.2026 Nitro tasks помечены experimental — исторический аргумент ADR-0002. На 15.10.2026 NestJS 12 — только ESM, Node ≥ 20, в примерах тесты на Vitest; nestjs-zod строит DTO и OpenAPI из zod-схем. Drizzle PGlite подтверждает отдельный драйвер. PGlite socket описывает single-connection ограничение: блокировки конкурентных транзакций отдельно проверяем на Postgres. Конкретные версии Vue/Vite/NestJS/Drizzle нужно закрепить lockfile и smoke в П1; текущая документация Nitro может относиться к другой основной версии, конфиг отсюда дословно не копируется.

service/docs/calculation-contract.md

Расчётный контракт дополнения

Редакция 13.10.2026. Фактический эталон — prototype-v2 commit 5213150; это контракт демо и принятых формул, а серверная архитектура утверждена 15.10.2026. Все NEW-01–09 реализованы пакетами; общая QA и риск-ревью ещё не завершены. Спецификация, прослеживаемость, словарь.

Единый владелец и границы

В прототипе формулы принадлежат js/calc.js, валидация/запись — js/api.js, данные — js/seed.js, экраны только вызывают и форматируют их. API синхронный mock api.post(action,payload) с localStorage и глобальной revision, а не реализованный HTTP-сервис. Ошибка 400 не записывает состояние, конфликт revision — 409, недоступное/повреждённое хранилище — 503. Сохранение reportData заменяет объект целиком; форма переносит неизменённые поля. Серверные стабильные ID, Decimal, авторизация, журналы/версии БД, 1С/Time/Сфера пока проектируются. Переключатель РМ/РП демонстрирует scope, не доступ.

Дополнение имеет приоритет над противоречащими формулами v1.7. P=FTE×персональная H принят; отдельной нормы продажи нет. Новые процессы замещения, переноса работ, пересогласования денег и политика исторического пересчёта рабочего сервиса не добавлены. Исходные документы и изображения v1.7 сохранены как история.

Календарь и доступные периоды

Hкал = сумма date→hours федеральной пятидневки 40 ч. Праздники и перенесённые выходные имеют 0 ч, сокращённые рабочие дни — 7 ч, обычные — 8 ч. 20.02.2027 — рабочая суббота 7 ч; 22.02 — перенесённый выходной. Региональные исключения в демо не включены.

Источники, проверенные при подготовке календаря 13.10.2026: 2026, 2027, постановление №1187. Это опубликованные данные, не проверка API 1С.

Ловушки реализации календаря: праздник, выпавший на выходной (09.05.2026; 01.05 и 09.05.2027), переносится на ближайший рабочий день по ст. 112 ТК; предпраздничный рабочий день на 1 ч короче (03.11.2026 — 7 ч); 31.12.2026 — выходной; в 2027 выходные 22.02, 05.11 и 31.12, а 20.02 — рабочая сокращённая суббота. Тест сверяет все 24 месячных значения таблицы, а не только годовые 1972 ч.

API принимает месяцы 2026-01…2027-12; иной месяц — 400. Форма заявки предлагает до 12 месяцев и уменьшает выбор у конца календаря, API — до 24 уникальных месяцев. Первый месяц шестимесячного плана ≤2027-07; некоммерческого отчёта с периодом 3/6/12 ≤2027-01. Недельное окно — 12 недель: неделя, включающая 2025, целиком неизвестна; норму 2025 не подставляют. Январь/февраль/март 2026 имеют 8/4/0 таких недель. Календарные даты кадрового начала могут быть старше 2026; это не добавляет часы отсутствующего календаря.

Отпуск, больничный, пересечения и полнота

reportData.vacations и reportData.sickLeaves содержат уникальные записи сотрудник×месяц. Каждая запись — одно из:

{"employee":"e1","month":"2026-10","hours":16}

{"employee":"e1","month":"2027-02","dates":["2027-02-20","2027-02-22"]}

Hours — подтверждённые рабочие часы 0…Hкал, уже без пересечений и нерабочего времени. Dates — полные дни этого месяца, не интервалы частичных часов. Повтор даты внутри записи нормализуется, неверная дата/месяц отклоняется. Объединение отпускных и больничных дат исключает повтор; праздник/выходной в dates даёт 0 ч. Пример: отпуск 20.02+22.02.2027, больничный 20.02 → исключено 7 ч, H=144.

Для пересечений оба вида вводят dates. Положительную сводку hours и датированные отсутствия одного сотрудника/месяца смешивать нельзя; API просит оба вида указать датами. Сводные часы — допущение демо: доступность каждого рабочего дня уменьшается пропорционально его календарным часам. Без дат реальное положение отсутствия в месяце неизвестно; это не прогноз больничных и не доказательство точности кадровой интеграции. Для точного дневного плана нужны dates.

Наличие записи каждого вида подтверждает полноту: пустое поле удаляет запись → unknown; hours=0 либо dates=[] подтверждает отсутствие. H неизвестна, если нет хотя бы одной из двух записей. Полная сумма отсутствий не может превышать Hкал; отказ атомарный. H = Hкал − объединённые рабочие часы отсутствий; N = сумма H выбранных сотрудников/месяцев. Hкал остаётся известной и показывается отдельно. Повторно отпуск/больничный из H/N не вычитаются; колонок с дополнительным вычетом нет. Доля каждого вида отсутствия считается от ΣHкал; общая доля — по объединению дат, а не суммой отпуска и больничного.

P, фактические часы и деньги

Обычный месячный план: P = FTE × H. Для дневного плана: P = сумма dailyFte(date) × availableDayHours(employee,date); «× 8» в FR 24 и FR 37 ТЗ — частный случай дня по 8 ч, а не отдельная формула. days[date] имеет приоритет, явный 0 сохраняется. Если H неизвестна и загрузка ненулевая, зависимые P, деньги и проценты неизвестны. Известная нулевая загрузка даёт 0 часов даже при неизвестной H. Известная H=0 даёт 0 плановых часов; P/H и проценты с нулевой нормой — прочерк.

До выбора сотрудника строка «На подбор» использует Hкал и известную R, C неизвестна; после выбора — H сотрудника. Эта граница явно отражает отсутствие персональной нормы до назначения. Мок допускает создание заявки при неизвестной H, но требует подтверждённые обе записи отсутствий для всех назначенных месяцев при согласовании. Проверка перегрузки — сумма дневных FTE в рабочие дни с доступными часами, включая рабочую субботу; подтверждённый день с 0 доступных часов исключается. Неизвестность не снимает проверку. До решения change план неизменён; исходные месячные ставки сохраняются при дневном изменении. При выводе 0,5 FTE с 16.11.2026 и нулевых отсутствиях → 35,5 ч, месячный FTE=35,5/159.

actuals — запись сотрудник×проект×месяц: одно из fte (0…2) или hours. Введённый FTE переводится в A через H; явные hours сохраняются напрямую и видны даже при неизвестной H. Hours ограничены 2Hкал и при известной H также 2H; это граница ручного ввода, а разрешение импорта другого факта не принято. Пусто удаляет запись, 0 сохраняется. Отсутствие записи хотя бы для одного выбранного сотрудника×проекта×месяца делает сумму A неполной; известная детализация не пропадает. Если проектов выбранного типа нет, A=0. Отпуск/больничный не являются работами.

I=P×R, расход=P×C, разница=I−расход. Часы/деньги не округляются до суммы; отображление округляет. Финансы списка, формы, карточки, месячных строк и отчёта используют одни исходные часы/ставки; неизвестные значения в CSV пусты, не 0. Изменение введённых отсутствий меняет текущие P и деньги прототипа, включая уже согласованные заявки; нового процесса пересогласования нет. Legacy месячные R сохраняются, показанная средняя взвешена P.

Форма/карточка: отрицательная разница красная, неотрицательная зелёная. Месячный и списочный расход красный только при отрицательной разнице; неизвестный без цвета. Пример Анны: Hкал=176,V=16,B=0 → H=160, FTE=0,5 → 80 ч, R/C=3500/2800 → 280000/224000 ₽. B=8 → H=152, P=76, 266000/212800 ₽. Пример потери при 88 ч и R/C=4000/4300 → 352000/378400/−26400 ₽.

Σ, Итог и показатели отчётов

Σ ч = сумма часов; Σ FTE·мес = сумма месячных FTE; Σ % = сумма часов / сумма персональных норм ×100. Для 0,5/1/0,75 при нормах 160/176/176: 2,25 FTE·мес, 388 ч, процент 388/512×100. Это не сумма процентов и не средняя FTE.

Нижний Итог использует видимых сотрудников ровно один раз. Проекты — расшифровка, не дополнительный вклад. Свёртка не меняет его; поиск/свободный ресурс/область РП меняют состав. Поиск проекта оставляет полную загрузку найденных сотрудников: итог равен показанным сотрудникам, как существующее поведение плана. Месячный FTE группы — сумма персональных FTE, процент группы — сумма часов / сумма H.

Три показателя утилизации используют один scope: P/N, Pком/N, A/N. Коммерческий числитель выбирается по категории «Коммерческий» ИЛИ типу commercial (как utilizationIndicators), категории таблиц выбирает projectType с приоритетом подробной категории. Неизвестная/нулевая N даёт прочерк с причиной, неполный A — пояснение. Категории не суммируют свой общий знаменатель. Накопительный процент — суммы часов / суммы H при одном составе людей; не среднее процентов.

Нулевой знаменатель новых колец и агрегата периода — прочерк; сохранённая planSummary для пустой выборки показывает 0%, недельная сводка с известной нулевой нормой — 0%. Это отдельные контексты существующего отображения, не подтверждение неизвестной нормы.

Четыре верхние вкладки: План, Заявки, Назначения, Отчёты. В Отчётах пять разделов: Утилизация, Финансы, Распределение, Некоммерческие проекты, Статистика. ЦФО/подразделение в Распределении и CSV берутся из введённых данных, пропуск — прочерк.

Контрольное демо и проверка

Все 24 месяца отсутствий демо подтверждены; отпуск Анны октября 16 ч, прочие 0, больничные 0. Октябрь: N=1040,P=432,Pком=256, FTE группы=2,5; факт неполный. Ноябрь: N=954,P=A=477, полный факт →50%. Норма 6 сотрудников ноября =6×159, без выдуманных отсутствий. Старое localStorage не переписывается: новые отсутствующие sickLeaves неизвестны, для контрольного демо нужен сброс.

Детальные проверки и файлы — матрица покрытия. Числовая сверка документа выполняется на неизменном 5213150; она не заменяет будущую общую QA.

service/docs/data-flows.md

Потоки данных и контракты интеграций

Редакция 13.10.2026 по дополнению NEW-01–09 и реализации прототипа 5213150. Расчётное поведение ниже принято для прототипа; архитектура рабочего сервиса утверждена 15.10.2026, живые подключения ждут ответов open-questions.md. Общая QA всех NEW ещё предстоит. Расчётный контракт, матрица покрытия.

Статус: предложение; INT 01–04, NFR 01–03. Все частоты ниже — настраиваемые стартовые рекомендации, не утверждённый SLA. Сфера/Time только читаются. Реальные endpoint Time и конфигурация 1С неизвестны: в таблицах честно указан блокирующий контракт, а не выдуманные методы. Публичные REST-методы Bitrix24 проверены по документации; доступность полей конкретной коробки Сферы ещё требует read-only контрактной проверки.

Общий протокол входящих потоков

1. Scheduler или оператор создаёт SyncRun. Уникальный source+scope+scheduledSlot не даёт дубликат задания; worker берёт lease с TTL и heartbeat. run получает фиксированный asOf и snapshot конфигурации.
2. Адаптер читает страницы в staging, следует next/cursor конкретного API; не считает короткую страницу концом, если есть next. Сортировка по стабильному ID; cursor и исходные version/hash сохраняются. Bitrix может вернуть ошибку в HTTP 200: проверяется тело error.
3. Сетевой timeout: предложение 20 с, не более 5 попыток на run, exponential backoff с jitter 1–60 с и учётом Retry-After. 429/5xx — повтор; 401/403 — остановка до исправления credentials; невалидная схема — quarantine и failed. Повтор/задержка инъецируются для детерминированных тестов.
4. Только полный валидный снимок/страница с подтверждённой границей коммитится с checkpoint в одной транзакции. Для full reconcile удаление отсутствующих допускается только после успешного завершения всей области; обрыв страницы не меняет статус ранее известных записей. Незнакомые ID не сопоставляются по ФИО автоматически.
5. Lease имеет fencing version: потерявший lease worker не может активировать старый snapshot. Повтор обработки — upsert по внешнему ключу и версии/hash. Snapshot активируется атомарно; отчёт не смешивает старые и новые страницы одного периода.
6. При недоступном источнике сохраняется последний целый снимок, lastSuccessAt не меняется, UI показывает stale. Freshness доступа и ставок строже, чем справочных имён (Q-03/Q-08); ошибка синка не даёт дополнительных прав.

F1. Сотрудники, подразделения, ресурсные роли — INT 02

sequenceDiagram
  participant W as Sync runner
  participant B as SphereClient
  participant S as Сфера
  participant D as БД
  W->>B: listDepartments / searchUsers
  B->>S: department.get / user.get, страницы
  S-->>B: ID, атрибуты, ACTIVE, next
  B-->>W: Нормализованные записи и полнота
  W->>D: staging + проверка mapping ролей
  W->>D: activate snapshot, мягкая деактивация, отзыв сессий
  Note over W,D: История назначений не удаляется

задача №215 использует подбор роли по WORK_POSITION как подсказку. Здесь нельзя автоматически переносить его семь ролей в шесть ролей ТЗ. Mapping и многоподраздельность требуют Q-07. Для аккаунта, внезапно исчезнувшего из выборки, доступ временно приостанавливается, но увольнение не фиксируется без подтверждения. Это отличается от необратимого удаления данных.

F2. Проекты и РП — INT 01

sequenceDiagram
  participant W as Sync runner
  participant P as ProjectSource
  participant B as Сфера
  participant D as БД
  W->>P: read(cursor)
  P->>B: sonet_group.get ИЛИ crm.deal.list ИЛИ crm.item.list
  B-->>P: ID, название, ответственный, закрытие
  P-->>W: SourceProject и reference пользователя
  W->>D: ExternalIdentity + Project + ProjectManager
  Note over W,D: Нет подтверждённого mapping РП — нет доступа к проекту

Рекомендуем рабочие группы: задачи Time уже связаны со Сферой, tasks.task.list возвращает groupId, подход согласуется со задача №215 и не требует CRM-модели для планирования. Сделка уместна, если именно там уже ведутся проекты и РП. Смарт-процесс уместен при действующем реестре проектов с отдельным жизненным циклом; создавать его только ради интеграции не требуется. Q-01 решает сущность, признак проекта, связь РП (один/несколько) и закрытие. Любой вариант нормализуется в один Project; остальной домен не меняется.

F3. Фактические часы из Time Лоции

sequenceDiagram
  participant W as Sync runner
  participant T as TimeSource
  participant B as SphereClient
  participant D as БД
  W->>T: read(window, cursor)
  T-->>W: entryId, userId, taskId, date, seconds, version
  W->>B: getTasks(неизвестные taskId)
  B-->>W: taskId и groupId
  W->>D: сопоставление сотрудника и проекта, quarantine неизвестных
  W->>D: upsert entries + coverage + checkpoint
  Note over W,D: Только полное покрытие позволяет вывести явный ноль

Сумма seconds/3600 даёт A; совместимое actualFte = A/H при H>0. Исходные секунды сохраняются, перерасчёт календаря не меняет A. Агрегация employeeId×projectId×month. Нет записи ≠ 0; нули выводятся только когда источник подтверждает полное покрытие соответствующей области. Нельзя обрезать импортированный факт выше 2 H: это конфликт с FR 64, запись уходит в quarantine и Q-05, пока правило не утверждено. Отпуска не извлекаются из нерабочих задач эвристикой.

Ручной факт прототипа не суммируется с Time автоматически: предложение — Time имеет приоритет в покрытой области, ручной fallback только вне неё, correction — отдельная аудируемая запись после утверждения Q-05. Часы отпуска пока отдельные локальные записи РМ; подключение отсутствий из 1С требует отдельного подтверждённого контракта (Q-06).

F4. Календарь, отпуск, больничный и расходные ставки

sequenceDiagram
  participant W as Sync runner
  participant C as Calendar / Absence / Rate sources
  participant D as БД снимков и полноты
  participant R as Calculations / Requests
  W->>C: calendar(year), absences(window), costRates
  C-->>W: Версии, рабочие часы дней, отсутствия и coverage
  W->>D: validate, stage, activate snapshot
  R->>D: Календарь, обе записи отсутствий, C и версии
  R->>R: Объединить даты, вычислить H и P, N как сумму H
  R->>D: Решение и costRateSnapshot в одной транзакции
  Note over D,R: Unknown не равен 0, повторного вычета отсутствий нет

Это схема предлагаемого рабочего подключения. В прототипе источники — опубликованный календарь в calc.js и ручные reportData в localStorage. Никакой sync runner, БД или 1С не запускались. Контракт отсутствий источника остаётся неизвестным, новый процесс пересогласования не вводится.

Hкал = сумма календарных часов. H сотрудника = Hкал − объединённые рабочие часы отсутствий; P=FTE×H либо сумма дневных FTE×доступные часы дня. N=ΣH. Отпуск/больничный из N больше не вычитаются. Обе записи обязательны для известной H; календарная норма и явные фактические часы видны при неполноте. Сводные часы уже очищены от пересечений и пропорционально распределены в дневном плане; точные пересечения требуют дат обоих видов. Это допущение демо, не утверждённый формат 1С. См. полный контракт.

Источники календаря демо: 2026, 2027, переносы 2027, №1187. Сверка источников выполнена при реализации календаря 13.10.2026; региональные исключения не включены.

F5. Вход и определение роли — NFR 01

sequenceDiagram
  participant U as Браузер
  participant A as Access
  participant I as Bitrix24 OAuth или SSO
  participant D as Session и Grants
  U->>A: начать вход
  A-->>U: redirect + одноразовый state
  U->>I: аутентификация
  I-->>A: callback с code и state
  A->>I: серверный обмен и проверка личности
  I-->>A: подтверждённый subject
  A->>D: найти Principal, active, AccessGrant
  A-->>U: HttpOnly cookie или отказ доступа
  U->>A: запрос бизнес API
  A->>D: проверить сессию, активность и scope

Сессия — случайный opaque ID в Secure/HttpOnly/SameSite=Lax cookie, запись/expiry на сервере; state для OAuth хранится отдельно с коротким TTL. POST/PATCH требуют CSRF token и проверку Origin. Нельзя считать локальное приложение Bitrix с произвольным DOMAIN в callback доверенным источником: issuer/домен жёстко allowlisted. В варианте Bitrix поддержка PKCE проверяется на портале; до подтверждения не объявляется готовой. Служебный webhook для синка не идентифицирует посетителя.

F6. Заявки, назначения и мастер-данные — INT 03, NFR 02

sequenceDiagram
  participant U as РП или РМ
  participant A as Requests
  participant P as Assignments
  participant D as БД
  U->>A: commandId, expectedVersion, действие
  A->>A: доступ, валидация, idempotency
  A->>D: BEGIN и блокировки сотрудников
  A->>D: перечитать заявку, версии, ставки
  A->>P: applyDecision в той же Tx
  P->>P: весь дневной план, лимит FTE
  P->>D: новая версия назначения
  A->>D: DecisionLog + Request + CommandReceipt
  A->>D: COMMIT
  A-->>U: результат или типизированный конфликт
  Note over A,D: Любая ошибка до COMMIT — полный ROLLBACK

Если заказчик выбирает Bitrix мастер: заменить порт хранения Requests/Assignments, заново спроектировать атомарность решений и журнал/компенсации, пересмотреть ADR-0001 и приёмку. Это существенная развилка, не «флажок». Если нужна только публикация копии решения — отдельный outbox после локального commit, ключ eventId/version, retry и dead-letter; поле локального состояния не объявлять синхронизированным до подтверждения. В текущие пакеты запись обратно не включена.

F7. Граница с Контуром — ADR-0007

Статус: отложено до запуска Контура, в текущие пакеты не входит; живые адаптеры ждут Q-12–Q-14. Пока проекты идут потоком F2, факт — F3, ленты событий нет.

sequenceDiagram
  participant K as Контур
  participant A as API сервиса
  participant R as Requests
  participant D as БД
  K->>A: POST /request-drafts (проект, строки из плана работ)
  A-->>K: draftId, ссылка на форму
  Note over R: РП дорабатывает и отправляет заявку, РМ решает (F6)
  R->>D: решение + DecisionLog + IntegrationEvent в одной Tx
  K->>A: GET /events?after=cursor
  A-->>K: события по seq, nextCursor
  K->>A: POST /projects/:id/release после приёмки
  A->>R: pending release по каждому активному назначению

Достоверность API и источники

Проверено 13.10.2026 по первичной документации: рабочие группы и поля, пользователь текущего токена, ограничения user scope, department API и REST 3.0, crm.item.list, поля CRM. REST v2 department.get выбран для совместимости задача №215; новые humanresources методы не обязательны для этой архитектуры.

Возможность вызова конкретного метода не доказывает наличие прав на все записи. Перед живым импортом L3 smoke на тестовом портале проверяет scope, типы ID/ACTIVE, next, доступ к неактивным, группе/проекту и полям. Боевую Сферу в этой задаче не вызывали; тестовый задача №27 не нужен для документирования неподтверждённых контрактов.

service/docs/open-questions.md

Решения заказчика

Редакция 13.10.2026 по дополнению NEW-01–09 и реализации прототипа 5213150. Расчётное поведение ниже принято для прототипа; архитектура рабочего сервиса утверждена 15.10.2026, живые подключения ждут ответов open-questions.md. Общая QA всех NEW ещё предстоит. Расчётный контракт, матрица покрытия.

Статус вопросов рабочего подключения ниже — не решено, если не отмечено иначе. Формулы дополнения приняты и не являются открытым вопросом P. Q-06 ограничен реальными источниками; Q-10 частично закрыт для прототипа. Рекомендация не является согласованием. Владельцу проекта нужно назначить конкретных ответственных за Сферу, Time, 1С, доступ и эксплуатацию. Архитектура допускает варианты через порты, но не обещает, что смена мастера данных бесплатна.

Что считается разрешением на следующий этап

spec.md и architecture.md утверждены 15.10.2026 — трек А разрешён. Исходное условие: утвердить spec.md с явно принятыми отклонениями от прототипа (ID/права/журнал/версии и рабочие подключения; формулы дополнения уже приняты). Q-02 определяет допустимость предложенной архитектуры в целом. Остальные неизвестные можно отложить только вместе с исключением соответствующего живого подключения из пакета; фейк не считается готовой интеграцией. После ответов обновить spec, ADR, flows и tests одной документальной ревизией, затем приступать к утверждённому пакету. Список реализации в tasks.md не создаёт задач и не назначает исполнителей автоматически.

service/docs/spec.md

Спецификация рабочего сервиса ресурсного планирования

Редакция 13.10.2026 по дополнению NEW-01–09 и реализации прототипа 5213150. Расчётное поведение ниже принято для прототипа; архитектура рабочего сервиса утверждена 15.10.2026, живые подключения ждут ответов open-questions.md. Общая QA всех NEW ещё предстоит. Расчётный контракт, матрица покрытия.

Статус: утверждено 15.10.2026 (Евгений), редакция 13.10.2026 по дополнению с правками 15.10.2026. Трек А пакетов (tasks.md) можно начинать; живые подключения трека Б ждут своих вопросов. Изменения дополнения 13.10.2026 уже включены в REQ-008/009/011/018/024/026/027 и расчётный контракт: отдельное дополнение читать не нужно, при противоречии с ТЗ v1.7 действует эта редакция, идентификаторы NEW сохранены для прослеживаемости. Принятые формулы и NEW-01–09 не требуют повторного согласования; рабочий сервис начинается после утверждения его архитектуры и относящихся вопросов подключения из tasks.md. Код в этой задаче не создаётся.

Цель и источники

РП запрашивает ресурсы; ресурсный менеджер (РМ) назначает сотрудников и принимает решения; согласованные назначения образуют единый план. Рабочий контур добавляет вход, серверные права, справочники, факт и журнал без изменения смысла формул прототипа.

База: ТЗ v1.7 от 09.10.2026, фактические заголовки §1–7, §13–30; ../../tz-v1.7/tz.md; анализ ../../analysis/{tz-issues,gap,plan}.md; прототип ../../prototype-v2/js/{calc,api,seed}.js, commit 5213150. Отсутствующие §8–12 и AC 01–40 не считаются восстановленными: критерии ниже выведены из FR. Ошибочные ссылки ТЗ на §31–32 читаются по таблице в tz-issues.md. Документы не требуют доступа к исходным путям для чтения требований.

Участники: РП (pm) — свои заявки и назначения разрешённых проектов; РМ (rm) — весь пул и решения. Технический оператор обслуживает подключения, но не получает автоматически роль РМ или расходные ставки. Должностная роль специалиста и право доступа пользователя — разные понятия.

Редакция 15.10.2026: сервис проектируется как этап 04 «Команда и ресурсы» платформы Контур (ADR-0007). В словаре Контура РМ — руководитель практики, РП — РП проекта/сервиса/продакт. Интеграцию с Контуром сейчас не делаем. В пакеты входят только дешёвые заделы, которые потом не переделать без миграций: тип объекта (REQ-039), проекты через ProjectCatalog (REQ-040), API-first (REQ-047) и UI-микрофронтенд с mount(el, ctx) (REQ-049). REQ-041–046 и REQ-048 помечены «Отложено до Контура»: описывают границу на будущее, в пакеты не входят и не проверяются до решения о запуске Контура. Формулы и жизненные циклы ниже не меняются.

Требования и проверяемые критерии

Каждая строка — отдельное требование; имя будущего теста содержит [REQ-NNN]. Уточнения рабочего контура помечены «предложение», окончательное решение — open-questions.md.

Жизненные циклы

stateDiagram-v2
  [*] --> pending: create или change
  pending --> approved: РМ согласует
  pending --> returned: РМ возвращает с причиной
  pending --> rejected: РМ отклоняет с причиной
  returned --> [*]: новая исправленная заявка с другим ID
  rejected --> [*]
  approved --> [*]: решение неизменно

Назначение появляется только при approved первичной заявки. active/ended — вычисляемые состояния по последнему ненулевому дню и Clock; changePending — отдельный признак. Решение по change атомарно заменяет текущую версию назначения и сохраняет прошлую. Истечение периода не удаляет запись.

Переходы назначения для L1

При выводе с будущей даты статус остаётся active до последнего ненулевого дня; решение не означает немедленного завершения. Если согласование запоздало относительно effectiveDate, оно применяется к сохранённому запросу по правилам снимка FR 29; политика запрета ретроактивного решения, если потребуется, должна быть отдельно согласована — ТЗ ограничивает дату при создании запроса.

Граница утверждения

Нерешённые вопросы рабочего подключения блокируют только перечисленные в open-questions.md рабочие подключения/запуск, а не подготовку документов. До ответов разрешены проектирование и будущие тесты на синтетических данных после утверждения спеки. Исторические дефекты публичного прототипа (имена вместо ID, отсутствие прав, локальное хранилище) не становятся требованиями к сервису.

service/docs/tasks.md

Пакеты реализации

Редакция 13.10.2026 по дополнению NEW-01–09 и реализации прототипа 5213150. Расчётное поведение ниже принято для прототипа; архитектура рабочего сервиса утверждена 15.10.2026, живые подключения ждут ответов open-questions.md. Общая QA всех NEW ещё предстоит. Расчётный контракт, матрица покрытия.

Эпик в Multica — задача №239 (задачи задача №240…254 = П1–П15, без исполнителей). Код живёт в этом же репозитории рядом с docs/ (/home/agents/resource-planning/service, локальный git без remote): пакет — ветка t-12345-<слаг> от main в собственном worktree (git worktree add /home/agents/resource-planning/wt/<слаг> -b t-12345-<слаг> main); основной каталог service всегда на main, в нём ветки не переключать. Вливает в main Евгений после приёмки; итог приёмки — комментарием в задаче вместо MR. Каждый пакет — одна наблюдаемая вертикаль, один MR, тест до реализации (RED → GREEN → refactor). Команды ниже будущие: появляются в П1. Общая команда приёмки каждого MR: pnpm lint && pnpm typecheck && pnpm exec tsx scripts/req-coverage; в первых MR coverage сверяется по списку REQ пакета, финальная приёмка П15 — по всем неотложенным REQ.

Не превращать пакет в горизонтальный слой «вся БД» или «весь UI». При росте объёма уточнить вертикаль до начала разработки, не делать бесконечный MR.

Конвейер

Пакет идёт сам, ручных шагов два — у Евгения. Задачу берёт сквад «Разработка»: Тимлид раздаёт, Аналитик пишет план, разработчики — код с тестами, QA и ревью проверяют, задача уходит в in_review с итоговым комментарием. План в рамках docs/ и ADR одобрен заранее; сквад останавливается только на отклонении от документов. Евгений вливает ветку в main и ставит «Готово» — это ворота стадии. Сторож multica-conveyor (таймер на сервере агентов, раз в 2 минуты) видит, что стадия закрыта, и назначает скваду задачи следующей. Задачи с пометкой «Ждёт:» (трек Б) он не запускает, пока пометку не снимут после ответа заказчика.

Два трека

Трек А — сервис на фейковых источниках (П1–П10). spec и architecture утверждены 15.10.2026 — можно начинать; вопросы к заказчику не ждёт: Сфера, Time, 1С и вход подменены fake-адаптерами и тестовой личностью. Результат — standalone-сервис, полностью проверяемый на синтетических данных.

Трек Б — живые подключения (П11–П15). Каждый пакет ждёт свои вопросы (колонка «Ворота») и служебный доступ к источнику. До ответа пакет не начинается: фикстурный адаптер без живого источника не считается интеграцией.

Вопрос → что разблокирует

П1 добавляет именованные vitest projects/Playwright grep tags для указанных команд; если suite использует иной runner CLI, команда в tasks.md меняется вместе с MR, а не остаётся невыполнимой. Все REQ в таблице пишутся с префиксом REQ- в тестах. L3 не нужен там, где пакет не меняет внешний adapter; migrations требуются каждому пакету со схемой. L4 и финальная матрица расширяются в том же MR, где появился endpoint. Полные L1/L2/L4 и миграции изменённой схемы всегда обязательны в CI, даже если локальная строка показывает targeted run.

Интеграция с Контуром (ADR-0007) сейчас не делается. В пакеты входят только заделы: П1 — граница импортов, OpenAPI и микрофронтенд на Module Federation (REQ-047, REQ-049), П4 — ProjectCatalog и тип объекта (REQ-039, REQ-040). Отложенные REQ-041–046 и REQ-048 станут отдельными задачами после решения о запуске Контура и ответов Q-12–Q-14.

Приёмка пакета командой

В описании MR: пользовательский результат, принятые Q/ADR, RED/GREEN команды и итог, изменение контрактов/миграций, screenshot только для изменённого UI. Reviewer прогоняет указанные команды на чистой БД, QA воспроизводит сценарий на fake-стенде, технический владелец проверяет прямой вызов модуля без браузера. Фикстурный L3 доказывает обработку заданного формата, но не работоспособность неизвестного live API. Весь сервис готов к рабочему запуску только после закрытия соответствующих вопросов и приёмки П15; никакой код не начинается только на основании этого списка.

Реализованный прототип и следующий шаг

В prototype-v2 5213150 все NEW-01–09 реализованы последовательными пакетами, матрица показывает файлы и проверки. Этот статус не выполняет П1–П15 сервиса. Фейковый выбор РМ/РП, localStorage, синхронный mock API и текущие входы отсутствий остаются границами демо. Новые процессы пересогласования/замещения/исторической фиксации денег в пакеты дополнения не добавлять. Следующая приёмка — общая QA всех NEW и риск-ревью, которые пока не завершены.

service/docs/testing.md

Проверки и требования к тестируемости

Редакция 13.10.2026 по дополнению NEW-01–09 и реализации прототипа 5213150. Расчётное поведение ниже принято для прототипа; архитектура рабочего сервиса утверждена 15.10.2026, живые подключения ждут ответов open-questions.md. Общая QA всех NEW ещё предстоит. Расчётный контракт, матрица покрытия.

Это план будущих тестов сервиса, не отчёт об их выполнении. В задача №232 проверяются документы и рендер схем; исходного кода сервиса нет. REQ из spec.md включается в имя каждого проверяющего теста, например [REQ-004] два параллельных решения не превышают дневную загрузку.

Уровни

Время — бюджет обратной связи на типичном CI runner, а не измерение и не SLA. Если превышено, искать медленные фикстуры/интеграции, не выкидывать проверки прав и расчётов.

PGlite — настоящая embedded БД для модульных тестов, но не доказательство конкурентности Postgres. Нельзя проверять race простым Promise.all в одном PGlite connection. Для Postgres тест управляет двумя соединениями и барьерами: обе транзакции стартовали, одна ждёт lock; результат ровно одно успешное решение, второе получает OVERLOAD/конфликт, а итог ≤1 FTE.

Сценарии и инварианты

L1: воспроизвести AC 41–66 из ТЗ и соответствующие createExamples из seed.js, ноябрьский пример FR 24 на производственном календаре: 0,5 FTE с 16.11.2026 → 35,5 ч при H=159 и нулевых отсутствиях. Проверить рабочую субботу 20.02.2027 на 7 ч и недельную границу января–марта 2026 без нормы 2025. Reference calc.js используется для сравнительных примеров, но тесты не должны копировать реализацию и подтверждать её ошибку.

Property-based, минимум 1000 примеров для ядра в CI, seed и минимальный counterexample печатаются при падении:

• REQ-008/015: план до effectiveDate неизменен; release после даты=0; reduce не увеличивает ни один день; сумма часов разбиения месяца равна целому; days=0 не заменяется месячным FTE.
• REQ-004: принятый набор назначений не превышает 1+допуск ни в один рабочий день; перестановка заявок/строк не меняет результат проверки уже фиксированного плана.
• REQ-009/010: сумма доходов частей равна доходу целого до финального округления; взвешенная ставка при положительных весах находится между min/max; нулевые часы не влияют на среднее; неизвестная активная ставка делает результат неизвестным.
• REQ-026/027: накопительная утилизация = сумма числителей / сумма знаменателей; V не входит в A; при 0 знаменателя нет Infinity/NaN; замена missing на 0 меняет полноту, а не часы известных строк.
• REQ-031/035: повтор одного snapshot не меняет число сущностей и сумму A; новая версия записи заменяет вклад, deletion убирает только его; поломанную последнюю страницу нельзя активировать как полный снимок.

L2 проверяет модуль через интерфейс, не приватные функции: сбой вставки DecisionLog откатывает approve; повтор commandId не добавляет журнал; команду с другим hash отвергает; stale request/assignment/rate версии не теряют данные. Синк деактивации не удаляет Assignment/DecisionLog и отзывает Session.

Матрица L4: генерируется целиком

Каждый маршрут из architecture.md обязан попасть в таблицу тест-кейсов; CI сравнивает реестр маршрутов/операций с матрицей, а не полагается на её ручную полноту. Роли теста: anonymous, pm-owner, pm-same-project-other-manager, pm-foreign-project, rm, operator-no-business-grants, revoked. Для каждой — чтение/запись и попытка подмены ID/filter/body. РМ и operator независимы.

Revoked всегда 401 на бизнес-API. Для rm без viewCost чтение маскируется; approve, требующий недоступной финансовой информации, запрещён до решения Q-03. Для JSON, CSV, before/after, totals и ошибок проверяется отсутствие C, plannedCost, costExcess, rateDifference и других производных скрытой C, а не только поле costRate. Недоступный проект не раскрывается счётчиком страниц.

L5: только ключевые сценарии

1. РП создаёт две строки → РМ назначает и соглашается → план обновлён, журнал содержит реального автора, другой РП не видит заявку.
2. РП предлагает замену с даты → план до решения прежний → РМ подтверждает превышение → дневной план/освобождение/история изменены один раз.
3. РМ открывает отчёт с неполным фактом/отпуском/больничным → прочерки → fake Time полный снимок и отпуск=больничный=0 → правильные итоги/CSV; РП видит только свою область.
4. Два браузерных контекста редактируют одну заявку → второй получает 409, его ввод сохранён; повтор первого commandId не дублирует решение.
5. Fake источник становится недоступен, затем деактивирует сотрудника → виден stale; после восстановления новая заявка на него запрещена, прошлое назначение видно, сессия отозвана.

Fixture/builders и изоляция

Builders исходят из seed.js (6 сотрудников, 3 проекта, demo-1…3, createExamples), добавляют стабильные project/manager/line IDs и явно связывают роли. Один сценарный каталог используется в L2/L4/L5 и стенде; тесты не создают разные копии бизнес-правил. Clock фиксируется на дате сценария, IdGenerator детерминирован. После каждого теста БД закрывается и удаляется собственный temporary storage; тесты не делят global state. Сценарии не содержат реальные ФИО/ставки/секреты.

Записанные API fixtures хранят version, provenance (какой метод, дата записи, synthetic или sanitized capture) и ожидаемые DTO. Сейчас Time/1С доступны только как проектируемые synthetic fixtures: их нельзя считать доказательством совместимости живого API. Перед подключением заменить/дополнить подтверждёнными обезличенными captures и получить контрактный smoke. Опциональный задача №27: CONTRACT_LIVE=1 и только явно указанный тестовый host; не запускается по умолчанию, тест отклоняет боевой host.

Fake-login route включён compile-time только в test build и проверяет NODE_ENV=test также во время исполнения. Отдельный production build проверяется с намеренно переданным fake-флагом: маршрут 404, произвольная test-cookie не аутентифицирует. Публичный демонстрационный стенд — либо test build только с синтетическими данными и явной плашкой, либо обычный build с настоящим тестовым IdP; никакого тестового входа в рабочую сборку.

Покрытие и команды будущего проекта

Порог только domain/**: lines/statements/functions ≥90%, branches ≥85%. Основание: ошибки ветвлений решения/полноты опаснее покрытия handlers; 100% по проекту поощряет бессмысленные тесты прокладок. Критические правила REQ-004/005/007/012/017/032/033/038 должны иметь все перечисленные негативные случаи независимо от процентов. Generated DTO/миграции не исключают доменный файл из coverage по удобству; исключения документируются и ревьюятся.

pnpm test:domain, test:module, test:contract, test:api, test:components, test:e2e, test:migrations, test:postgres, test:prod-safety — будущие scripts, создаваемые в П1. pnpm exec tsx scripts/req-coverage сверяет spec.md с реально собранным vitest/Playwright test inventory и JUnit результатом, а не grep произвольного комментария. Неизвестный REQ, отсутствующий, skipped/todo-only или отсутствующий успешный тест — ненулевой exit. Несколько REQ в имени допустимы при реальной проверке каждого. Новое требование не считается покрытым случайным упоминанием в фикстуре.

CI: frozen install → typecheck/lint → L1–L4/компоненты/req-coverage → миграции/Postgres → build/test-production safety → L5. До живых интеграций CI не имеет их credentials. Сначала в пакете пишется падающий тест критерия (RED), затем код (GREEN), затем refactor; MR содержит команды и вывод, а не только проценты.

Действующая матрица дополнения и проверка прототипа

NEW → код → проверка → документ относится к реализации 5213150, а будущие L1–L5 выше — к рабочему сервису. Наличие тестов прототипа не доказывает готовность интеграций, прав или общей QA.

При переносе критериев: Hкал=176,V=16,B=8 → H=152,P(0,5)=76; одинаковые суммы списка/формы/карточки/CSV; unknown против 0; объединение одинаковой даты/праздника/короткого дня; атомарный отказ свыше Hкал; явные часы факта при неизвестной H; ΣFTE·мес=2,25 и 388/512×100; Итог без проектов/после свёртки/по scope; коммерческие и фактические показатели с одним составом людей. Покрытие факта требует всех employee×project×month, отсутствий — employee×month×kind. P и деньги не имеют второго знаменателя продажи.

Регрессионные сценарии принятого поведения

Сценарии из приёмки дополнения 13.10.2026; числа — для календаря и персональной нормы из расчётного контракта. В сервисе они становятся L1/L5-тестами соответствующих REQ.

• NEW-01: 88 ч, R = 4000, C = 4300 → доход 352 000, расход 378 400, разница −26 400 (красная); R = C → 0 (зелёная); неизвестная C («На подбор») → расход и разница «—».
• NEW-02: «Расход» после «Доход» в форме, рассмотрении и просмотре. Михаил на «отелях», отсутствия 0: окт 176 ч → расход 756 800 ₽ при доходе 704 000 (красный), ноя 159 ч → 683 700 ₽ (красный), дек 88 ч → 378 400 ₽ (красный).
• NEW-07: в списке «Расход» между «Доход» и «Статус»; суммы списка, карточки и сумма месяцев совпадают для всех заявок контрольного демо; у заявки-изменения — «—».
• NEW-03, календарь: 24 месячных значения 2026–2027; 1 FTE в ноябре 2026 = 159 ч; 20.02.2027 — рабочий день на 7 ч.
• NEW-03, норма: октябрь, отпуск 16 + больничный 8 → H = 152; отпуск = Hкал → H = 0 и % «—»; отпуск + больничный > Hкал → 400; пустое поле удаляет запись, 0 сохраняется.
• FR 62 / AC 61: удалить отпуск сотрудника → его H, N и проценты по N «—», норма по календарю и явно введённые часы факта видны; ввести 0 → значения известны.
• AC 59: Hкал 176, отпуск 16 → H = N = 160; 0,5 FTE → P = 80 ч и 50 %; введённый A = 88 ч → 55 %. AC 60: 80 + 132 ч при N 160 + 176 → 63,1 %.
• NEW-04: четыре верхние вкладки и пять разделов «Отчётов»; в перенесённых разделах работают свои фильтры, раскрытие и режим РП.
• NEW-05: Σ меняется с единицей (ч / FTE·мес / %); 0,5 / 1 / 0,75 FTE → 2,25; 388 ч при норме 512 ч → 75,78125 %, не сумма процентов.
• NEW-06: «Итог» = сумма строк сотрудников по месяцам и Σ; проекты повторно не прибавляются; свёртка не меняет, поиск, свободный ресурс и область РП — меняют состав.
• NEW-08: кольцо коммерческой плановой утилизации с теми же фильтрами; октябрь, 6 сотрудников, отпуск Анны 16: N = 1040, коммерческие часы 256 → 24,6 %.
• NEW-09: фактическая утилизация A / N × 100; неполный факт → «—» с пояснением; N = 0 → «—».
• «Распределение» и CSV показывают введённые ЦФО и подразделение.

service/docs/validation.md

Проверка документальной редакции дополнения

Дата: 13.10.2026. Эталон прототипа — 5213150, дерево и код прототипа не изменены этим пакетом. Проверяются документы, их расчётные примеры и публикация; общая QA всех NEW и риск-ревью ещё предстоят. Будущие тесты сервиса из testing/tasks не запускались: серверного кода здесь нет.

Локальные проверки

• node scripts/verify-docs.mjs docs ../prototype-v2 ../analysis: 38 уникальных REQ, распределение в 11 будущих пакетов, 9 строк матрицы NEW, существование файлов реализации/тестов и внутренних Markdown-ссылок. Расчётная сверка 24 календарных норм, H=152/P=76, октября/ноября, 35,5 ч вывода, границы недель 8/4/0 и демо-денег — успешно. Проверено 46 внутренних Markdown-ссылок; это проверка существования целей, не оценка покрытия бизнес-поведения.
• npm test в неизменном prototype-v2 — 44 теста прошли, 0 падений; npm run check успешен. Это локальная проверка принятой базы, не новая итоговая QA.
• Все 11 Mermaid-блоков architecture/data-flows/spec извлечены и отрендерены через mermaid-cli с установленным headless Chromium. Обновлены SVG, Mermaid-исходники и HTML. F4 отражает обе записи отсутствий/coverage, схема хранения — AbsenceEntry и Coverage.
• Хеши исходного v1.7, его изображений, старого design-sample.html/png и «Итераций» совпадают с сохранёнными до правок. Исторические analysis/plan, gap и аудит снабжены пометками приоритета без переписывания старых выводов.
• Реальные API Сферы/Time/1С, БД, Docker, рабочие секреты не вызывались. Публичные ссылки источников сохранены; старые источники инфраструктуры относятся к проектируемому сервису.

Производные и опубликованные страницы

Архитектура и схемы — прежний URL. Расчётный контракт, матрица NEW, analysis — читаемые HTML без CDN. Исходные Markdown/ADR также доступны из страницы схем. Статический прототип остаётся на прежнем URL, его публикация не меняется документальной редакцией.

Проверка публикации выполняется Playwright-скриптом workdir verify-published-docs.cjs: размеры/число SVG, уникальность ID и внутренние якоря, HTTP-ответы связанных страниц/Markdown, ошибки JS, viewport 1440/320/390 и скролл схем/таблиц внутри карточек. Команда прошла: 11 SVG, 20 уникальных внутренних HTTP-целей со статусом 200, уникальные ID и все проверенные якоря корректны, ошибок JS/console 0. На 1440/320/390 px переполнения страницы нет. Отдельная HTTP-проверка 18 внешних/опубликованных ссылок дала 200 для каждой; это проверка доступности, не новое подтверждение содержимого API. Снимки приложены в отчёте пакета. Старые результаты проверки архитектуры на предыдущей редакции не выдаются за новые.

Повторение сборки

В service/scripts находятся инструменты только документации, не сервер приложения. Требуются установленный mermaid-cli/marked и Chromium; окружение передаётся аргументами, новых переменных сервиса нет.

node scripts/render-docs.mjs docs /path/to/render-work /path/to/mermaid-cli/src/cli.js /path/to/puppeteer.json /path/to/marked/lib/marked.esm.js ../analysis
node scripts/verify-docs.mjs docs ../prototype-v2 ../analysis
node --check scripts/render-docs.mjs
node --check scripts/verify-docs.mjs
git diff --check

Puppeteer config содержит executablePath и args. Для изолированной среды без системного sandbox используется аргумент --no-sandbox. Выход docs/diagrams.html и docs/reference.html, analysis/reference.html — производные исходных Markdown; исходные Mermaid показаны в раскрывающихся блоках. Для обновления только прозы можно использовать последний аргумент --reuse-svg: он разрешён лишь если сохранённые Mermaid-исходники совпадают и соответствующие SVG существуют.

Граница приёмки

Формулы/NEW прототипа приняты, но серверная модель ID/Decimal/версий, безопасность, подключения, SLA и политика истории сервиса остаются предложениями и нерешёнными рабочими вопросами. Q-06 не спрашивает о формуле P или необходимости праздников/отсутствий. Дополнение не утверждает новую фиксацию денег или пересогласование. Remote сервиса отсутствует; изменения передаются локальной веткой и коммитом. Общая QA всех NEW не закрыта этим документальным пакетом.