Пример — описание сделанной задачи (MR) и паспорт интеграции

Образец того, как выглядит сданная задача: заполненный шаблон описания изменения и обновлённый паспорт интеграции. Основа — реальная задача: HTTP-сервис get_data (метод GET /actual_salary/) в расширении ддПолучениеДанных для ЗУП КОРП, отдающий фактические начисления за месяц. Номера задач, контакты и числа замеров здесь условные; структура и уровень детализации — то, что ревьюер ожидает увидеть в каждом MR.

Контекст задачи

Внешней аналитике нужны фактические начисления помесячно: детальные строки по видам расчёта, итоги по сотрудникам и по организациям. Сделан HTTP-сервис в расширении (типовая конфигурация не тронута): данные формирует СКД поверх типового набора ЗУП НачисленияУдержания, аутентификация — общий секрет в заголовке, контракт зафиксирован OpenAPI-спекой.

Описание изменения (шаблон MR — заполненный)

## Задача / причина
ZUP-201: аналитике нужны фактические начисления за месяц (детально + итоги)
без ручных выгрузок в Excel. Контрактные решения зафиксированы в спеке:
перерасчёты прошлых месяцев попадают в месяц фактической регистрации;
группировка по ссылкам (одинаковые представления — отдельные строки).

## Затронутые объекты
Расширение `ддПолучениеДанных` (ЗУП КОРП); типовые объекты не изменялись.
- HTTP-сервис `get_data`, метод GET `/actual_salary/` — новый;
- СКД поверх типового набора `НачисленияУдержания`;
- валидация параметра month, проверка X-Shared-Secret, формирование ответа.
Инфраструктура: публикация `zupprof_svc_actualsalary` (тест/прод), правило WAF.

## Тип / риск
feature / низкий: сервис только читает данные; до публикации на проде
поведение системы не меняется.

## Как проверить
На тестовой публикации (секрет — в хранилище команды):
1. `curl -H "X-Shared-Secret: <секрет>"
   ".../hs/get_data/actual_salary/?month=2026-01"` → 200, плоский массив;
   у итоговых строк `TypesOfAccrual = "Всего начислено"`, итог по
   организации — `Employee = "ИТОГО"` и пустой `Department1C`.
2. Сверка сумм: итог по организации совпадает с отчётом «Полный свод
   начислений и удержаний» за тот же месяц (проверено на копии прода от 05.07).
3. Негативные: без заголовка → 401; `month=2026-13` → 400 `invalid_month`;
   месяц без данных → 200 и `[]`.
4. В ответе `Cache-Control: no-store`; ПДн в URL не передаются.

## Как откатить
Убрать публикацию с веб-сервера (или отключить расширение
`ддПолучениеДанных`). Сервис ничего не пишет — откат без последствий.

## Миграции / обновление ИБ
Нет.

## Безопасность
- Заголовок `X-Shared-Secret`; эталон — в безопасном хранилище, не в коде.
  Секрет не настроен → 503 `service_unavailable`: сервис «по умолчанию закрыт».
- 401 не различает «нет заголовка» и «неверный секрет» — не даём оракул.
- Тела ошибок без внутренних деталей; подробности — только в ЖР, событие
  `ддПолучениеДанных.ОшибкаHTTP`.
- Данные — ПДн (ФИО + суммы): только HTTPS, ответ `no-store`, доступ к
  секрету ограничен получателем.

## Производительность
- Один прогон СКД за один месяц; запросов в цикле нет.
- Лимит 100 000 строк ответа → 503 `result_too_large` (защита от
  случайной выгрузки-гиганта).
- Замер на копии прода: месяц ≈ 38 000 строк — 6 с, 12 МБ (числа условные).

## Документация / чеклисты
- OpenAPI-спека `docs/api/get_data.yaml` обновлена этим же MR.
- Паспорт интеграции обновлён (база знаний, см. ниже).
- Чеклисты «Интеграция» + «Базовая» пройдены, экспорт приложен к ZUP-201.

Паспорт интеграции (обновлён в той же задаче)

# Паспорт: ЗУП → Аналитика — фактические начисления (get_data)

**Назначение:** выдача фактических начислений за месяц (детальные строки,
итоги по сотрудникам и организациям) во внешнюю аналитику.
Владелец процесса — HR-аналитика (условно: И. Петрова).
**Стороны и контакты:** 1С ЗУП КОРП, расширение `ддПолучениеДанных` —
dev-team@…; потребитель — команда BI — bi-team@… .
**Поток:** потребитель инициирует, GET по требованию (обычно после расчёта
зарплаты); объём — до 100 000 строк за месяц.
**Точка входа:**
`https://1c.dodoteam.ru/zupprof_svc_actualsalary/hs/get_data/actual_salary/?month=YYYY-MM`
(месяц `YYYY-MM`, будущий месяц допустим — вернётся пустой массив).
**Контракт:** OpenAPI 3.1 — `docs/api/get_data.yaml`. Плоский JSON-массив:
`ActualSalary` («jan 26»), `Department1C`, `Employee`, `Company`, `Amount`,
`TypesOfAccrual`. Итоговые строки: `TypesOfAccrual = "Всего начислено"`;
итог по организации — `Employee = "ИТОГО"` + пустой `Department1C`.
Перерасчёты прошлых месяцев — в месяце фактической регистрации.
**Аутентификация:** заголовок `X-Shared-Secret`; эталон — в безопасном
хранилище 1С (не настроен → 503, сервис закрыт).
**Ошибки:** 400 `invalid_month`; 401 `unauthorized` (без деталей причины);
500 `internal_error` — детали в ЖР `ддПолучениеДанных.ОшибкаHTTP`;
503 `service_unavailable` / `result_too_large`. Сервис только читает —
повторный запрос безопасен, ретраи на стороне потребителя.
**Ограничения:** лимит 100 000 строк; `Cache-Control: no-store`;
ПДн — доступ по секрету, только HTTPS.

Что ревьюер видит из этого описания

Описание закрывает фокус-лист ревью без чтения всего кода подряд:

Безопасность — секрет в безопасном хранилище, вход по единому паттерну 401/400 до бизнес-логики, ошибки не раскрывают внутренностей.
Производительность — нет запросов в цикле, лимит размера ответа вместо таймаута на гигантской выгрузке.
Совместимость — доработка расширением, типовые объекты не тронуты.
Откат — описан и реалистичен (сервис read-only).
Документация — контракт и паспорт обновлены в той же задаче, чеклисты приложены.

Пример — описание сделанной задачи (MR) и паспорт интеграции

Контекст задачи

Описание изменения (шаблон MR — заполненный)

Паспорт интеграции (обновлён в той же задаче)

Что ревьюер видит из этого описания

См. также