Тема
Реестр нарушений
Семейство violations.
norm_violations_list
Реестр нарушений правил компании страницами, от свежих к старым по дню фиксации. Строка — одно нарушение одного сотрудника или исправление нарушения: строка исправления несёт corrects_id — id исправленного нарушения, а само нарушение остаётся в реестре; повторное нарушение — отдельная строка. Строки добавляют агент (norm_violations_append) и люди; статус, срок и вес ведут люди в системе компании. Ответ — сырые строки: вес приходит, только если его поставил человек, а оценок участников и итогов по людям сервер не отдаёт. У строки, которую завёл человек, может не быть ключа и других полей, кроме id, status и recorded_on; пустое текстовое поле — человек его не заполнил. Фильтры, все необязательные: statuses — строки в этих статусах, как статус приходит в ответе: пустой и вне словаря — open; открытые нарушения — open и new_deadline; person_emails — до 200 почт участников, регистр не важен, строка без person_email под этот фильтр не попадает; occurred_from и occurred_to — дни нарушения, recorded_from и recorded_to — дни фиксации, включительно; строка без occurred_on под фильтр по дням нарушения не попадает. Значение не по формату поля сервер не отдаёт, строка при этом остаётся. Строка, записанная norm_violations_append, видна в списке сразу; правки людей могут приходить с задержкой — смотрите freshness. На странице не больше limit строк, и она укладывается в предел размера ответа; total — сколько строк подошло под фильтр до применения страницы. Для следующей страницы передайте page.next_cursor как cursor с теми же фильтрами. Реестр — про людей и их оценку: читать и писать его вправе только владелец и администратор компании, остальным реализация отвечает unauthorized_scope. Доменное состояние not_ready — реестр у компании не настроен.
Доступ: чтение · Списковый: да · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
cursor | нет | string | Какую страницу прислать: next_cursor из прошлого ответа. Без него — первую. |
limit | нет | integer | Сколько записей прислать на одной странице. |
occurred_from | нет | string (date) | С какого дня нарушения искать строки, включительно. |
occurred_to | нет | string (date) | По какой день нарушения искать строки, включительно. |
person_emails | нет | список string | Только нарушения этих сотрудников: их почты, регистр не важен. |
recorded_from | нет | string (date) | С какого дня фиксации искать строки, включительно. |
recorded_to | нет | string (date) | По какой день фиксации искать строки, включительно. |
statuses | нет | список ViolationStatus | Только строки в этих статусах; открытые нарушения — open и new_deadline. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
entries | да | список ViolationEntry | Строки этой страницы, от свежих к старым по дню фиксации. |
total | да | integer | Сколько строк подошло под фильтр всего, на всех страницах. |
error | нет | DomainError | Почему данных нет: реестр у компании не настроен. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "violations",
"label": "Реестр нарушений"
}
],
"freshness": {
"as_of": "2026-10-14T18:30:00.000Z",
"ttl_sec": 3600,
"stale": false
},
"page": {
"has_more": true,
"next_cursor": "eyJvIjo1fQ"
},
"data": {
"total": 12,
"entries": [
{
"id": "v-2026-0118",
"status": "open",
"recorded_on": "2026-10-14",
"occurred_on": "2026-10-13",
"key": "2026-10-13|m.petrov@example.com|регламент-3.2|01K9F2QH7T8ZRC4M0X5B2VNJ3D",
"person_email": "m.petrov@example.com",
"person_id": "p-1042",
"person_name": "Михаил Петров",
"type": "Протокол не опубликован в срок",
"basis": "Регламент встреч, п. 3.2",
"fact": "Протокол планёрки 13.10 не опубликован к 10:00 14.10, а регламент требует публикации в течение суток после встречи.",
"source": {
"kind": "protocol",
"url": "https://company.example/protocols/2026-10-13-planerka",
"meeting_id": "01K9F2QH7T8ZRC4M0X5B2VNJ3D"
},
"due_on": "2026-10-15",
"url": "https://company.example/violations/v-2026-0118"
},
{
"id": "v-2026-0117",
"status": "closed",
"recorded_on": "2026-10-14",
"occurred_on": "2026-10-13",
"key": "исправление|v-2026-0102",
"person_email": "s.ilina@example.com",
"person_id": "p-1077",
"person_name": "Светлана Ильина",
"type": "Повестка не разослана",
"basis": "Правила, п. 4.1",
"fact": "Повестку встречи 09.10 разослала 13.10 — нарушение исправлено задним числом.",
"source": {
"kind": "email"
},
"corrects_id": "v-2026-0102",
"url": "https://company.example/violations/v-2026-0117"
},
{
"id": "v-2026-0109",
"status": "open",
"recorded_on": "2026-10-13"
},
{
"id": "v-2026-0102",
"status": "closed",
"recorded_on": "2026-10-10",
"occurred_on": "2026-10-09",
"key": "2026-10-09|s.ilina@example.com|правила-4.1|01K9DZ4W8N2PQ6R0T3V5X7Z9B1",
"person_email": "s.ilina@example.com",
"person_id": "p-1077",
"person_name": "Светлана Ильина",
"type": "Повестка не разослана",
"basis": "Правила, п. 4.1",
"fact": "Повестка встречи 09.10 не разослана участникам за сутки до встречи.",
"source": {
"kind": "calendar",
"meeting_id": "01K9DZ4W8N2PQ6R0T3V5X7Z9B1"
},
"due_on": "2026-10-10",
"url": "https://company.example/violations/v-2026-0102"
},
{
"id": "v-2026-0095",
"status": "new_deadline",
"recorded_on": "2026-10-08",
"occurred_on": "2026-10-07",
"key": "2026-10-07|d.orlov@example.com|правила-5.3|01K9B7M2C4E6G8J0K2M4P6R8T0",
"person_email": "d.orlov@example.com",
"person_id": "p-1013",
"person_name": "Дмитрий Орлов",
"type": "Поручение не внесено в систему задач",
"basis": "Правила, п. 5.3",
"fact": "Три поручения со встречи 07.10 не заведены задачами в системе компании.",
"source": {
"kind": "record",
"url": "https://company.example/tasks?meeting=01K9B7M2C4E6G8J0K2M4P6R8T0",
"meeting_id": "01K9B7M2C4E6G8J0K2M4P6R8T0"
},
"due_on": "2026-10-17",
"weight": 2,
"url": "https://company.example/violations/v-2026-0095"
}
]
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "violations"
}
],
"freshness": {
"as_of": "2026-10-14T18:30:00.000Z",
"ttl_sec": 0,
"stale": false
},
"page": {
"has_more": false
},
"data": {
"error": {
"code": "not_ready",
"message": "Реестр нарушений у компании не настроен.",
"retryable": false
}
}
}norm_violations_append
Добавить строки в реестр нарушений правил компании пачкой — от 1 до 50 за вызов. Только добавление: строки, которые уже есть в реестре, запись не меняет и не удаляет. key ставит агент так, чтобы одно нарушение давало один ключ: только из частей, которые при повторе не меняются, — день нарушения, почта участника в нижнем регистре, документ и номер пункта в одном написании, meeting_id, — а не из текста модели. Тогда повторный прогон за тот же день реестр не задваивает, а повторное нарушение в другой день — новая строка. Ключ уже есть в реестре — новая строка не создаётся, а прежняя остаётся как была, даже если остальные поля записи другие: запись придёт в accepted с id этой строки и created: false. Ключ сравнивается целиком, с учётом регистра, в том числе со строками, записанными только что. Нарушение не снимают: исправление записывайте отдельной строкой с corrects_id — id строки нарушения из norm_violations_list — и своим ключом, например из corrects_id: с ключом нарушения запись вернёт строку нарушения с created: false, и исправление не запишется. Участник, тип и основание у исправления — как у нарушения. occurred_on — когда нарушение случилось, у исправления — когда нарушение исправили; recorded_on — день прогона, который строку фиксирует. Статус новой строки ставит сервер — open нарушению, closed исправлению; статус, срок и вес дальше ведут люди, агент их не пишет. Пачку, где запись не проходит схему входа — длина, формат дня, вид источника, — сервер вправе отклонить целиком: пределы и форматы проверяйте до отправки. Отказ записи по остальным причинам не отменяет другие: она придёт в rejected с ключом и кодом — invalid_input (occurred_on позже recorded_on или ключ повторяется в пачке: записана первая, она в accepted, поэтому записи с одним ключом склейте до отправки), unknown_user (сотрудника с этой почтой у компании нет), unknown_id (строки corrects_id в реестре нет), record_deleted (строку с этим ключом удалил человек, воссоздавать её нельзя), record_rejected (хранилище не приняло запись, повтор даст то же), temporary и rate_limited (временный сбой). Повторить пачку безопасно: записанное повтор не задвоит. Реестр — про людей и их оценку: читать и писать его вправе только владелец и администратор компании, остальным реализация отвечает unauthorized_scope. Доменные состояния вызова: not_ready — реестр у компании не настроен; temporary и rate_limited — повторите позже.
Доступ: запись · Списковый: нет · Версии контракта: 1
Аргументы
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
entries | да | список NewViolationEntry | Строки для записи — нарушения и исправления; каждый ключ — один раз. |
Данные ответа (data)
| Поле | При успехе | Тип | Зачем |
|---|---|---|---|
accepted | да | список ViolationEntryRef | Принятые записи: id строки за каждым ключом и создана ли она этим вызовом. |
rejected | да | список RejectedRecord | Какие записи не приняты и почему; остальные приняты. |
error | нет | DomainError | Почему ничего не записано и можно ли повторить. |
note | нет | string | Пояснение сервера к записи. |
Пример: успешный ответ
json
{
"source_refs": [
{
"source": "company-data",
"ref": "violations",
"label": "Реестр нарушений"
}
],
"freshness": {
"as_of": "2026-10-14T18:30:00.000Z",
"ttl_sec": 0,
"stale": false
},
"data": {
"accepted": [
{
"key": "2026-10-13|m.petrov@example.com|регламент-3.2|01K9F2QH7T8ZRC4M0X5B2VNJ3D",
"id": "v-2026-0118",
"created": true
},
{
"key": "исправление|v-2026-0102",
"id": "v-2026-0117",
"created": true
},
{
"key": "2026-10-13|k.zueva@example.com|правила-2.4|01K9F2QH7T8ZRC4M0X5B2VNJ3D",
"id": "v-2026-0112",
"created": false
}
],
"rejected": [
{
"key": "2026-10-13|buyer@partner.example|правила-2.4|01K9F2QH7T8ZRC4M0X5B2VNJ3D",
"code": "unknown_user",
"message": "сотрудника с почтой buyer@partner.example у компании нет"
},
{
"key": "исправление|v-2026-0102",
"code": "invalid_input",
"message": "ключ уже был в этом вызове — повтор не записан"
}
]
}
}Пример: случай «domain_error»
json
{
"source_refs": [
{
"source": "company-data",
"ref": "violations"
}
],
"freshness": {
"as_of": "2026-10-14T18:30:00.000Z",
"ttl_sec": 0,
"stale": false
},
"data": {
"error": {
"code": "not_ready",
"message": "Реестр нарушений у компании не настроен.",
"retryable": false
}
}
}Объекты семейства
Объекты, из которых состоят аргументы и ответы инструментов этого семейства.
ViolationStatus
Статус нарушения. open — нарушение открыто; closed — закрыто; new_deadline — человек назначил новый срок, он в due_on. Статус новой строки ставит сервер, дальше его меняют люди в системе компании; агент статус не пишет. Пустой статус и значение вне словаря сервер отдаёт как open: нарушение открыто, пока человек не закрыл его и не назначил новый срок.
Значения: open, closed, new_deadline.
ViolationEntry
Строка реестра нарушений. Одна строка реестра нарушений правил компании: нарушение одного сотрудника или исправление нарушения. Строка исправления несёт corrects_id, а нарушение при исправлении остаётся в реестре. Строки добавляют агент и люди; статус, срок и вес ведут люди. У строки, которую завёл человек, могут быть только id, status и recorded_on. Пустое текстовое поле — человек его не заполнил; текст длиннее предела сервер обрезает. Значение, которое не проходит формат поля, — ссылку не по форме, день со временем, пустой id, вес не числом — сервер не отдаёт: поля нет, а строка остаётся. Вес — только тот, что поставил человек: оценок участника в строке нет.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
id | да | string | Номер строки в системе компании: на него ссылается строка исправления полем corrects_id. |
recorded_on | да | string (date) | Когда нарушение зафиксировано в реестре; у строки, которую человек завёл без этой даты, — день, когда строку завели. |
status | да | ViolationStatus | Что с нарушением сейчас: открыто, закрыто или назначен новый срок; ведут люди. |
basis | нет | string | Основание: документ и пункт, которые нарушены. |
corrects_id | нет | string | Есть только у строки исправления: id строки нарушения, которое исправлено; нет поля — это строка нарушения. |
due_on | нет | string (date) | К какому дню нарушение нужно исправить; при новом сроке — новый день. |
fact | нет | string | Что случилось: факт словами. |
key | нет | string | Ключ, с которым строку записал агент; у строки, которую завёл человек, ключа может не быть. |
occurred_on | нет | string (date) | Когда нарушение случилось; у строки исправления — когда нарушение исправили. |
person_email | нет | string | Чьё нарушение: почта сотрудника в нижнем регистре. |
person_id | нет | string | Чьё нарушение: id сотрудника из norm_people_list. |
person_name | нет | string | Как участник назван в реестре: показать строку, не сверяясь со списком сотрудников. |
source | нет | ViolationSource | Где нарушение видно: вид, ссылка, встреча. |
type | нет | string | Тип нарушения словами компании: словарь типов ведёт компания. |
url | нет | string (uri) | Ссылка на строку в системе компании, чтобы человек мог её открыть. |
weight | нет | number | Вес нарушения, если его поставил человек; нет поля — вес не задан. |
ViolationSource
Источник нарушения. Где нарушение видно: вид источника, ссылка для человека и встреча, если нарушение с ней связано.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
kind | да | ViolationSourceKind | Где нарушение видно: по виду источник показывают человеку. |
meeting_id | нет | string | О какой встрече речь: id из norm_meetings_list, если нарушение связано со встречей. |
url | нет | string (uri) | Ссылка на источник для человека: протокол, встреча, письмо или карточка. |
ViolationSourceKind
Вид источника. meeting — встреча: её запись или расшифровка; protocol — протокол встречи; calendar — событие календаря; email — письмо; record — карточка в системе компании: задача, страница, строка базы; other — источник, которого нет в словаре.
Значения: meeting, protocol, calendar, email, record, other.
NewViolationEntry
Новая строка реестра. Нарушение или исправление, которое агент добавляет в реестр: ключ, участник, тип, основание, факт, источник, дни нарушения и фиксации, срок. Строка исправления несёт corrects_id. Статуса, веса и id здесь нет: статус новой строки ставит сервер, вес — люди, id — система компании.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
basis | да | string | Основание: документ и пункт, которые нарушены, например «Правила, п. 6.35». |
fact | да | string | Что случилось: кто, что и когда сделал или не сделал — факт без оценки человека. |
key | да | string | Ключ строки: агент строит его только из частей, которые при повторе не меняются, — день нарушения, почта участника в нижнем регистре, номер пункта, meeting_id. У строки исправления свой ключ, например из corrects_id. |
occurred_on | да | string (date) | Когда нарушение случилось, у строки исправления — когда нарушение исправили; не позже recorded_on. |
person_email | да | string | Чьё нарушение: почта сотрудника из norm_people_list, регистр не важен. |
recorded_on | да | string (date) | Когда нарушение зафиксировано: день прогона агента, который его записывает. |
source | да | ViolationSource | Где нарушение видно: вид, ссылка, встреча. |
type | да | string | Тип нарушения словами компании, из её словаря типов. |
corrects_id | нет | string | Только у строки исправления: id строки нарушения из norm_violations_list, которое исправлено. |
due_on | нет | string (date) | К какому дню исправить, если срок даёт правило или поручение; нет — срок назначит человек. |
ViolationEntryRef
Принятая запись. Запись пачки, которую сервер принял: её ключ, id строки реестра и создана ли строка этим вызовом. created: false — строка с этим ключом уже была, и вызов её не менял.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
created | да | boolean | Создана ли строка этим вызовом; false — строка с этим ключом уже была и осталась как была. |
id | да | string | id строки реестра за этим ключом: для corrects_id и чтобы найти строку в списке. |
key | да | string | Ключ записи из входа. |
RejectedRecord
Непринятая запись. Запись пачки, которую сервер не принял: ключ записи, код из общего словаря и пояснение. Остальные записи пачки при этом записаны.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
code | да | ErrorCode | Почему запись не принята: код из общего словаря, по нему видна сторона. |
key | да | string | Какая запись пачки не принята: её ключ, у разбора встречи — meeting_id. |
message | нет | string | Пояснение для разработчика. |