ADR-0053: Единицы СИ для характеристик

Status: accepted Date: 2026-05-09 Deciders: Максим Белканов, Tracium engineering

Контекст

Tracium сравнивает товары, офферы и будущие аналоги по характеристикам. Если одна система хранит 80 мм, другая 0.08 m, а третья строку 80мм, то параметрический resolver и fuzzy analog matching начинают сравнивать текст, а не физические величины. Это ломает подбор по характеристикам и делает невозможным стабильное ранжирование аналогов.

В публичный API также приходят сметные строки из разных источников: ручной JSON, ERP, CSV, XLS/XLSX-конвертеры. Формат источника не должен определять единицы измерения внутри Tracium.

Решение

Все физические характеристики в canonical layer, нормализованных характеристиках офферов и публичном API должны храниться и передаваться в системе СИ.

Правила:

• значение и единица передаются раздельно: value содержит число, unit содержит единицу;
• масштаб приводится до canonical SI unit до входа в resolver: 80 мм становится { "value": 0.08, "unit": "m" }, 6 кА становится { "value": 6000, "unit": "A" };
• в API не принимаем локализованные единицы для характеристик: А, мм, кВ, кВт должны быть преобразованы в A, m, V, W;
• uom строки сметы (шт, м, комплект) не считается характеристикой товара и не попадает под это правило;
• импортные адаптеры XLS/CSV/ERP обязаны приводить характеристики к этому формату до вызова public API;
• если поставщик отдаёт нестандартизованные единицы, нормализация выполняется в charnorm/ingestion контуре до записи в canonical/normalized read-side.

Последствия

Плюсы

• Характеристики можно сравнивать численно без supplier-specific эвристик.
• Параметрический resolver и будущий analog matching получают стабильную основу для ранжирования.
• Public API становится независимым от формата исходной таблицы.

Минусы

• Импортным адаптерам нужен слой нормализации единиц перед вызовом API.
• Клиентам нельзя просто прокинуть исходную строку 1250А как характеристику: её нужно разобрать на число и единицу.

Нейтральные последствия

• Исходный текст строки сметы остаётся в raw_text для трассировки и fallback text resolver, но не используется как canonical representation характеристики.
• В первой версии POST /v1/estimates/proposals валидирует только единицы характеристик на входе; полнота пересчёта и размерности остаются зоной импортного адаптера и charnorm pipeline.

Рассмотренные альтернативы

Хранить единицы как пришли от клиента или поставщика

Отклонено: такой подход переносит проблему сравнения в каждый resolver и делает будущий подбор аналогов нестабильным.

Нормализовать единицы только внутри analog matching

Отклонено: тогда разные слои системы будут читать разные представления одной и той же характеристики. Нормализация должна быть invariant-ом данных, а не локальной эвристикой одного алгоритма.

Ссылки

• docs/docs/20-architecture/schemas/api/public-api.openapi.yaml
• ADR-0044: LLM gateway + char-pipeline foundation
• ADR-0045: Tier 3 LLM matcher
• ADR-0047: Canonical assignments strategies