Словарь полей обменного файла: имена, типы, единицы и ссылки на спецификацию

Три входные колонки вместо одной таблицы

Словарь полей начинается не с самого файла, а с трёх независимых списков. Первый: имена колонок, которые реально приходят в обменном файле, XML-элементы или заголовки CSV, ровно так, как их отдаёт источник. Второй: термины из документации источника, включая авторские пояснения, которые не являются полями формата. Третий: названия, которые используются в интерфейсе мониторинга или внутреннего сервиса, например «курс» или «лимит», которые могут совпадать по звучанию с колонками, но означать другое.

Разделение на три колонки защищает от смешения на самом раннем этапе. Если все три источника сразу записать в одну таблицу, совпадающие имена сольются, и станет невозможно понять, что именно читается из файла, а что остаётся авторским пояснением. Каждый список собирайте отдельно и только затем сопоставляйте.

Список полей файла собрать из реального примера, а не из памяти.
Список терминов документации переписать дословно, с сохранением пунктуации.
Список названий интерфейса выписать из того экрана, который видит оператор.

Запись словаря: шесть обязательных атрибутов

Для каждого поля файла составляйте запись с шестью атрибутами. Имя поля в точном написании источника. Тип: число, строка, дата, перечисление. Единица измерения, если применимо: проценты, базовые единицы, секунды. Допустимые значения или диапазон. Ссылка на раздел спецификации, где поле описано. Область употребления: в каких операциях поле встречается и где его отсутствие допустимо.

Если спецификация не задаёт единицу, так и запишите: единица не определена документом. Ссылка должна вести на раздел, а не на страницу целиком, иначе при обновлении документа адрес потеряет смысл. Область употребления помогает отличить обязательное поле от информационного, которое скрипт может игнорировать без последствий.

Если спецификация не задаёт единицу, так и запишите: единица не определена документом.
Ссылка должна вести на раздел, а не на страницу целиком, иначе при обновлении документа адрес потеряет смысл.
Область употребления помогает отличить обязательное поле от информационного.

Совпадения имён: фиксация, а не объединение

Главный риск словаря в том, что авторский термин из документации или название из интерфейса совпадает с колонкой файла, но означает другое. Например, слово «курс» в документации может описывать метод расчёта, а в CSV это конкретная числовая колонка. Если одно имя встречается в двух колонках входных данных, не объединяйте записи. Зафиксируйте, что это разные понятия, и дайте каждому отдельный адрес: колонке файла ссылку на спецификацию формата, авторскому термину ссылку на раздел документации, где он определён.

В таблице словаря добавьте колонку «конфликт имени» и пишите в ней адрес второй записи. Не переименовывайте поля файла ради единообразия: скрипты читают имена из источника, и любое изменение требует правки кода, а не только документации. Отдельные адреса делают словарь проверяемым: по каждому совпадению можно открыть обе записи и убедиться, что они действительно различаются.

В таблице словаря добавьте колонку «конфликт имени» и пишите в ней адрес второй записи.
Не переименовывайте поля файла ради единообразия: скрипты читают имена из источника.

Условный пример: поле fee_rate в трёх списках

Представьте, что в CSV обменного файла приходит колонка fee_rate, в документации источника встречается термин «комиссия», а в интерфейсе мониторинга оператор видит метрику «комиссия, %». Это три разных объекта. fee_rate в файле имеет тип число, единицу, возможно, проценты, и ссылку на раздел спецификации, описывающий экспорт. Термин «комиссия» в документации может определять порядок расчёта, включая округление, и не является полем формата. Метрика в интерфейсе показывает уже обработанное значение, возможно, усреднённое за период.

В словаре это три отдельные записи: одна с адресом спецификации формата, вторая с адресом раздела документации, третья с адресом описания интерфейса. Если их объединить в одну строку, при изменении источника окажется, что скрипт читает одно, а оператор понимает другое. Условный пример показывает механику: совпадение звучания не означает совпадение смысла.

Для каждого совпадения по звучанию создайте отдельную запись с собственным адресом.
В записи интерфейсной метрики укажите, из какого поля файла она вычисляется.

Границы применимости словаря

Словарь не заменяет формальную спецификацию. Он фиксирует, что именно читается из файла и что остаётся авторским пояснением, но не устанавливает правил обмена. Если спецификация изменится, словарь требует обновления: имена полей, типы и ссылки могут устареть. Полезно вести версию словаря в связке с версией спецификации, чтобы при обновлении формата сразу видеть, какие записи затронуты.

Также словарь не должен содержать догадок. Если тип или единица не подтверждены документом, запись помечается как неполная, а не заполняется предположением. Это сохраняет словарь рабочим инструментом сверки, а не вторым источником истины, который может противоречить первому.

Помечайте неполные записи явно, без заполнения догадками.
Связывайте версию словаря с версией спецификации источника.

Практическая проверка перед публикацией словаря

Перед тем как использовать словарь в работе, пройдите по нему с реальным файлом. Для каждой записи откройте файл и убедитесь, что имя поля присутствует и тип совпадает. Для каждой ссылки откройте раздел спецификации и проверьте, что описание соответствует записи. Для каждого конфликта имени убедитесь, что обе записи существуют и различаются.

Если проверка выявила расхождение, исправляйте словарь, а не скрипт: скрипт обязан читать то, что отдаёт источник, а словарь обязан описывать это честно. Такой порядок сохраняет словарь полезным и не превращает его в источник ошибок, которые потом приходится искать в коде.

Сверьте каждое имя с реальным файлом, а не с памятью.
Проверьте ссылки на спецификацию по одной.
Убедитесь, что записи конфликтов не объединены.