# Что записано в эталонном разборе

К каждому из пяти сканов приложен файл с правильными значениями — это эталон, с ним
сравниваем то, что прочитала программа. Ниже — все поля эталона простыми словами, с
примерами из настоящих файлов заказчика. Выдуманных значений здесь нет: каждый пример
взят из конкретного файла, номер примера указан.

Страница с тем же текстом (удобнее читать): **format.html** рядом с этим файлом.

## Состав набора

| № | Имя примера | Документ | Страниц | Строк в таблице |
|---|---|---|---|---|
| 1 | 0d7b0e7c-e4b6-40b4-9a62-6eec02c07c12 | УПД № 25 от 20.10.2022 | 2 | 20 |
| 2 | 1c6c0fac-f82a-4219-be4b-4918653068f4 | УПД № 4 от 16.01.2025 | 2 | 5 |
| 3 | 1f0b3cfd-c38a-433c-a029-5122aab57d6b | УПД № 756 от 25.02.2025 | 1 | 1 |
| 4 | 2b0791f5-c8d2-4157-beea-e8fe6c362de8 | УПД № ЦБ-444 от 23.05.2024 | 1 | 3 |
| 5 | 3e43a1d4-288d-42ec-989a-385ff87719d4 | УПД № 1189/4 от 20.02.2025 | 2 | 18 |

К каждому имени два файла: `<имя>.pdf` — скан, `<имя>.json` — эталонный разбор.
Всего 47 строк товарных позиций. Дополнительно: `manifest.json` — сводка по набору,
`thumb/` — картинки первых страниц для страницы со списком.

## Как устроен файл

Набор полей у всех пяти эталонов **одинаковый** — 62 поля, ни одно не пропадает.
Если значения в документе нет, поле остаётся пустым (`null`, пустая строка или пустой
список). Поэтому «поле есть / поля нет» тут не бывает — бывает «заполнено / пусто»,
и это разное у разных документов (раздел «Чем эталоны отличаются»).

## 1. Шапка документа

| Поле | Что означает | Настоящий пример |
|---|---|---|
| `type` | вид документа | `UTD` — универсальный передаточный документ (УПД). Так во всех пяти |
| `number.value` | номер документа, как есть, вместе с буквами | `ЦБ-444` (пример 4), `1189/4` (пример 5), `25` (пример 1) |
| `date.value` | дата в машинном виде: год-месяц-день | `2024-05-23` — 23 мая 2024 (пример 4) |
| `date.rawValue` | та же дата, как написана в документе | `25февраля2025` (пример 3). В остальных четырёх пусто |
| `currency` | валюта сумм | `RUB` — рубли. Так во всех пяти |

## 2. Продавец и покупатель

Два одинаковых по составу блока: `supplierData` — продавец, `customerData` — покупатель.

| Поле | Что означает | Настоящий пример |
|---|---|---|
| `name` | название организации или ФИО предпринимателя | продавец: `ОБЩЕСТВО С ОГРАНИЧЕННОЙ ОТВЕТСТВЕННОСТЬЮ "ФРЕГАТ"` (пример 2); покупатель: `Индивидуальный предприниматель Гурьянов Антон Игоревич` (пример 4) |
| `inn` | ИНН: у организаций 10 цифр, у предпринимателей 12 | `1660282762` (пример 2), `773373089219` (пример 4) |
| `kpp` | КПП; у предпринимателей его не бывает — пустая строка | `165701001` (пример 2); пусто у покупателей в примерах 3 и 4 |
| `countryAlpha3Code` | страна тремя буквами | `RUS`. Так у всех десяти сторон |
| `taxId` | налоговый номер иностранного контрагента | пусто во всех пяти |
| `address.fullAddress` | адрес одной строкой | `142100, Подольск, ` — покупатель (пример 3); `150539, Лесная Поляна, 41` — продавец (пример 3); `101000, Москва, ` — покупатель (пример 4) |
| `address.zipCode` | индекс | `142100` (пример 3) |
| `address.region` | код региона | `50` — Московская область (пример 3) |
| `address.city` | город | `Подольск` (пример 3) |
| `address.street`, `building`, `block`, `apartment`, `locality`, `territory` | улица, дом, корпус, квартира, населённый пункт, территория | пусто во всех пяти |

**Внимание:** адрес в эталонах заполнен небрежно — строка `142100, Подольск, `
обрывается запятой. Измерять качество распознавания по адресу нельзя; сверять имеет
смысл ИНН, КПП, название и таблицу товаров.

## 3. Таблица товаров (`itemsTable`)

Итоги по всей таблице:

| Поле | Что означает | Настоящий пример |
|---|---|---|
| `itemsTable.amount` | всего к оплате, с НДС | `623478.34` ₽ (пример 5) |
| `itemsTable.amountWithoutVat` | всего без НДС | `519565.26` ₽ (пример 5) |
| `itemsTable.vat` | всего НДС | `103913.08` ₽ (пример 5) |

В примере 4 все три итога пустые, хотя строки в таблице есть.

Одна строка таблицы — один элемент списка `items`, 16 полей:

| Поле | Что означает | Настоящий пример |
|---|---|---|
| `serialNumber` | порядковый номер строки, счёт с нуля | `0` … `19` у 20 строк примера 1 |
| `name` | наименование товара | `Автошина Pirelli-Formula 225/55R18 102T XL Formula Ice шип` (пример 2) |
| `goodCode` | артикул продавца | `ЦБ-00000039` (пример 4), `00000000007` (пример 5); иногда с мусором: `— 00-00001455- 1` (пример 2) |
| `unit` | единица измерения словами | `шт`, `упак`, `рул`, `пар` (пример 1), `м2` (пример 4), `пог. м`, `компл` (пример 5) |
| `unitCode` | код единицы по классификатору ОКЕИ | `796` штука, `778` упаковка, `736` рулон, `715` пара, `055` кв. метр, `018` погонный метр, `839` комплект |
| `quantity` | количество, бывает дробным | `384` (пример 3), `5.796` кв. м (пример 4) |
| `price` | цена за единицу без НДС | `9375.0` ₽ (пример 2), `85` ₽ (пример 3) |
| `amountWithoutVat` | стоимость строки без НДС | `37500` ₽ (пример 2) |
| `vatRate` | ставка НДС | `PERCENT_20` — 20 % (четыре примера), `PERCENT_10` — 10 % (пример 3) |
| `vat` | сумма НДС по строке | `7500` ₽ (пример 2), `173.88` ₽ (пример 4) |
| `amount` | стоимость строки с НДС | `45000` ₽ (пример 2), `1043.28` ₽ (пример 4) |
| `excise` | акциз | пусто во всех 47 строках |
| `discount` | скидка по строке | пусто во всех 47 строках |
| `countryCode` | страна происхождения | пусто во всех 47 строках |
| `goodTypeCode` | вид операции: товар, работа, услуга | пусто во всех 47 строках |
| `customsDeclaration` | номер таможенной декларации | пусто во всех 47 строках |

## 4. Служебные поля, не заполненные нигде

| Поле | Что означает | Что в эталонах |
|---|---|---|
| `documentShipments` | отгрузки: транспортные документы | пустой список во всех пяти |
| `transferBases` | основания передачи: договор, заказ | пустой список во всех пяти |
| `amountModifiers` | надбавки и скидки на весь документ | пустой список во всех пяти |
| `customFields` | дополнительные поля под задачу | пусто во всех пяти |
| `supplierAccountDetails` | банковские реквизиты продавца | пусто во всех пяти |
| `receiptQR` | QR-код кассового чека | пусто во всех пяти |
| `paymentOrderId` | ссылка на платёжное поручение | пусто во всех пяти |

## Чем эталоны отличаются друг от друга

Состав полей одинаковый, заполнены они по-разному. Проверено по всем пяти файлам.

| Поле | Заполнено | Где именно и чем это грозит |
|---|---|---|
| `itemsTable.amount`, `amountWithoutVat`, `vat` | 4 из 5 | нет итогов в примере 4 (№ ЦБ-444) — сверять итоговые суммы там не с чем |
| `customerData.kpp` | 3 из 5 | пусто в примерах 3 и 4: покупатели — предприниматели, КПП у них нет. Не ошибка |
| `goodCode` в строках | 24 строки из 47 | нет совсем в примерах 1 (0 из 20) и 3 (0 из 1); пример 2 — 4 из 5, пример 4 — 3 из 3, пример 5 — 17 из 18 |
| `customerData.address.fullAddress` | 2 из 5 | примеры 3 и 4, в обоих строка оборвана на городе |
| `customerData.address` по частям (индекс, регион, город) | 1 из 5 | только пример 3 |
| `supplierData.address.fullAddress` | 1 из 5 | только пример 3; у остальных четырёх продавцов адреса нет |
| `date.rawValue` | 1 из 5 | только пример 3 (`25февраля2025`) |

Ещё одно расхождение — в записи чисел: одна и та же величина где-то целая, где-то с
копейками (`171600` в примере 2, `623478.34` в примере 5). Для сравнения это неважно,
если сравнивать как числа, а не как текст.

## Что в эталонах сходится арифметически

Пересчитаны все 47 строк.

- **Сходится всегда:** «без НДС» + «НДС» = «с НДС» — во всех 47 строках, копейка в
  копейку. Итог по таблице = сумме строк — во всех четырёх примерах, где итог заполнен
  (пример 1 — 106 590,18 ₽, пример 5 — 623 478,34 ₽).
- **Сходится не всегда:** цена × количество в 26 строках из 47 чуть-чуть не даёт
  стоимость без НДС, потому что цена округлена до копеек. Максимальное расхождение —
  строка «S-358.20 Штапик для с/п 24 мм» в примере 5: 48,31 ₽ × 1040 = 50 242,40 ₽
  против 50 245 ₽ в эталоне, разница 2,60 ₽ (0,005 %). Проверку «цена × количество»
  использовать можно, но с допуском в несколько рублей.

## Как этим пользуются

1. Скан из PDF прогоняется через распознавание.
2. Полученная таблица сравнивается со строками эталона: наименование, количество,
   цена, суммы, ставка НДС.
3. Расхождения видно на экране проверки: слева скан, справа распознанная таблица,
   клик по значению открывает поле для исправления.

Эталон считаем правильным. Всё, что не совпало, записываем в ошибки распознавания —
кроме случаев из раздела про расхождения: пустой КПП у предпринимателя или
отсутствующий артикул ошибкой не считаются.

## Откуда файлы

Личная папка заказчика «Файлы» в кабинете. Документы содержат реальные реквизиты
организаций — набор используется для внутренней проверки качества распознавания.