Documentation
¶
Overview ¶
Package catalog обеспечивает доступ к каталожным таблицам (параметры, атрибуты, условия, единицы, группы, именованные правила, системы обозначений, реестр семейств) и содержит движок валидации значений по правилам из БД.
Состав пакета (план работ, этап 2):
- Snapshot — иммутабельный снимок каталога; Store — транспорт чтения определений (реализация над БД — internal/storage, этап 3); Cache — кэш с проверкой catalog_revision на каждом обращении: при изменении снимок атомарно заменяется целиком (docs/plan/01-architecture.md §2.2);
- Engine — движок валидации записей наполнения: применимость параметров/атрибутов к классу записи (parameter_kinds/attribute_kinds, D7), типы значений (exact/at_least/at_most/range/text/enum), позитивность/allow_negative, потолок, наборы условий (required/optional/запрещено, условия-константы fixed_value), enum;
- реестр именованных правил (year_range, cap_dimensions_form, temp_pair, cap_variant_matrix, resistor_variant_power) и механизм привязки правил данными (параметр/атрибут/класс записи);
- ApplyCatalog — применение каталога (upsert по коду) с валидацией метасхемы при импорте (docs/plan/03-data-model.md §12).
Каталог — данные (D1): расширение параметрами/атрибутами/условиями — вставкой строк, без правки кода; код решает только механику проверок.
Index ¶
- Constants
- func ApplyCatalog(base *Snapshot, in Input) (*Snapshot, []Problem)
- func KindSection(k domain.Kind) string
- func RecordKeyReserved(key string) bool
- func ValueKeyReserved(key string) bool
- type AttrType
- type AttributeDef
- type AttributeRule
- type AttributeValue
- type Cache
- type CategoryDef
- type ConditionDef
- type ConditionMode
- type ConditionSet
- type ConditionSetItem
- type ConditionValue
- type Device
- type DeviceRule
- type Engine
- type GroupDef
- type Input
- type KindDef
- type KindRuleRef
- type ParameterDef
- type ParameterRule
- type ParameterValue
- type Problem
- type Rule
- type RuleDef
- type Snapshot
- func (s *Snapshot) Attribute(code string) (*AttributeDef, bool)
- func (s *Snapshot) Category(code string) (CategoryDef, bool)
- func (s *Snapshot) CategoryCodes() []string
- func (s *Snapshot) Clone() *Snapshot
- func (s *Snapshot) Condition(code string) (ConditionDef, bool)
- func (s *Snapshot) Group(code string) (GroupDef, bool)
- func (s *Snapshot) GroupBySection(section string) (GroupDef, bool)
- func (s *Snapshot) Kind(code domain.Kind) (KindDef, bool)
- func (s *Snapshot) Parameter(code string) (*ParameterDef, bool)
- func (s *Snapshot) RulesForKind(kind domain.Kind) []string
- func (s *Snapshot) SourceType(code string) (SourceTypeDef, bool)
- func (s *Snapshot) SourceTypeCodes() []string
- func (s *Snapshot) System(code domain.System) (SystemDef, bool)
- func (s *Snapshot) SystemAppliesTo(system domain.System, kind domain.Kind) bool
- func (s *Snapshot) Unit(code string) (UnitDef, bool)
- type SourceTypeDef
- type Store
- type SystemDef
- type SystemKindRef
- type UnitDef
- type ValueType
- type Variant
Constants ¶
const ( RuleCapDimensionsForm = "cap_dimensions_form" RuleCapVariantMatrix = "cap_variant_matrix" RuleRelayVariantCoil = "relay_variant_coil" RuleResistorVariantPower = "resistor_variant_power" RuleTempPair = "temp_pair" RuleYearRange = "year_range" )
Коды именованных правил — стабильные ключи каталога: сиды и данные наполнения ссылаются на правила только через эти константы; соответствие реестру ruleRegistry закреплено пин-тестами сидов.
const ( YearRangeMin = 1949 YearRangeMax = 2100 )
Границы годов выпуска — общие для правила year_range (атрибуты yearFrom/yearTo) и проверки годов синонимов сервисного слоя (03-data-model.md §9, §11): единая точка изменения границы.
Variables ¶
This section is empty.
Functions ¶
func ApplyCatalog ¶
ApplyCatalog применяет каталог in поверх снимка base и валидирует метасхему результата (план работ 2.4). Применение — upsert по коду (docs/plan/02-database.md §5.4): вставка новой строки либо обновление полей существующей; enum-значения, наборы условий и применимость к классам замещаются целиком; незаданные (нулевые) sort_order существующих строк сохраняются из снимка (FillSortOrders); удаление строк каталога входом не поддерживается — только деактивация (is_active = 0). При пустом списке Problem результат пригоден к записи; непустой — вход отвергается целиком (частичное применение запрещено): проблемы самопроверки входа исключают и перенос строк в снимок, и проверку метасхемы — вердикт (непустой список проблем) от этого не меняется. base = nil означает пустой каталог (сидирование).
func KindSection ¶
KindSection — ключ секции корня формата наполнения для класса: код класса с «s» (transistors, diodes, resistors, capacitors, relays; docs/fill-format.md §2).
func RecordKeyReserved ¶
RecordKeyReserved сообщает, служебный ли ключ записи формата наполнения: name, system, fields, attributes, manufacturers, variants, analogs, synonyms, sources (docs/fill-format.md §3).
func ValueKeyReserved ¶
ValueKeyReserved сообщает, зарезервирован ли ключ объекта значения секции группы: parameter, value, min, max, text (docs/fill-format.md §4).
Types ¶
type AttrType ¶
type AttrType string
AttrType — тип значения атрибута (docs/plan/03-data-model.md §10): text | text_list | bool | int | number | enum.
type AttributeDef ¶
type AttributeDef struct {
Code string
GroupName string
Type AttrType
Unit string
ValidationRule string
SortOrder int
Active bool
Kinds []domain.Kind
EnumValues []string
}
AttributeDef — строка таблицы attributes вместе с применимостью к классам (attribute_kinds) и enum-значениями. Kinds пуст — все классы (D7). DisplayName атрибута — бандлы internal/i18n: attr.<код> (D9).
type AttributeRule ¶
type AttributeRule interface {
Rule
CheckAttributes(e *Engine, kind domain.Kind, vals []AttributeValue) []Problem
}
AttributeRule — правило, привязываемое к атрибутам записи.
type AttributeValue ¶
AttributeValue — значение атрибута: ровно одно из Text/Texts/Num/Bool задано по типу атрибута каталога (Texts — список заметок для text_list, порядок элементов значим: задаёт sort_order строк хранилища).
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache — кэш снимка каталога в памяти: при каждом обращении проверяется catalog_revision; при изменении снимок атомарно заменяется целиком (замена указателя — docs/plan/01-architecture.md §2.2). Снимок иммутабелен в рамках обработки одного запроса; корректно и для нескольких процессов — импорт каталога в общую базу виден без перезапуска.
func NewCache ¶
NewCache создаёт кэш каталога над транспортом; первый Snapshot(ctx) загружает снимок, дальнейшие — только при смене ревизии.
func (*Cache) Invalidate ¶
func (c *Cache) Invalidate()
Invalidate сбрасывает кэш (следующий Snapshot загружает снимок заново).
func (*Cache) Snapshot ¶
Snapshot возвращает актуальный снимок каталога. Загрузку ведёт один вызов (single-flight): параллельные читатели не блокируются мьютексом на время загрузки, а ждут её результата; отменённый ждущий возвращается с ошибкой своего контекста, не дожидаясь загрузки (при отмене вызова ждать нечего). Дождавшийся перечитывает ревизию и повторяет цикл: при несовпадении ревизии — снимок мог быть загружен до свежей записи каталога; при падении полёта — ошибка загрузчика (в том числе отмена его контекста) не заражает ждущих: следующий цикл ведёт свой полёт и отвечает своей ошибкой. Гонка «прочитали старую ревизию — каталог применили — загрузили новый снимок» доброкачественна: следующий вызов видит новую ревизию и перезагружает снимок. Ревизия кэшируется вместе со снимком из его же согласованного чтения, поэтому кэш никогда не отвечает парой «снимок ≠ ревизия».
type CategoryDef ¶
type CategoryDef struct {
Code string
}
CategoryDef — строка таблицы categories: код классификационного поля category (применение/характеристика прибора — переключательный, импульсный, малошумящий…; ортогонален подклассу — функции перехода). Словарь — данные каталога (расширяется секцией catalog без правки кода); отображаемое название — бандлы internal/i18n: category.<код>, расширения без записи в бандле отображаются кодом (D9).
type ConditionDef ¶
ConditionDef — строка таблицы conditions: условие измерения/контекста значения. Unit "" — безразмерное условие; AllowNegative разрешает неположительные значения (temp), по умолчанию условия положительны. Отображаемое название — бандлы internal/i18n (D9).
type ConditionMode ¶
type ConditionMode string
ConditionMode — роль условия в наборе условий параметра: required (обязательно) либо optional (допустимо; остальные условия набора запрещены — docs/plan/02-database.md §2.2).
const ( ModeRequired ConditionMode = "required" ModeOptional ConditionMode = "optional" )
Реестр режимов условий набора.
func (ConditionMode) Valid ¶
func (m ConditionMode) Valid() bool
Valid сообщает, входит ли режим в реестр.
type ConditionSet ¶
type ConditionSet struct {
No int
Items []ConditionSetItem
}
ConditionSet — альтернативный набор условий параметра: значение корректно, если его условия подходят хотя бы к одному набору.
type ConditionSetItem ¶
type ConditionSetItem struct {
Condition string
Mode ConditionMode
FixedValue *float64
}
ConditionSetItem — элемент набора условий параметра: условие, режим (required/optional) и необязательная константа fixed_value (допустима только при mode = required: значение в файле можно опустить либо задать равным fixed_value — docs/plan/02-database.md §2.2).
type ConditionValue ¶
ConditionValue — заданное условие измерения со значением (в канонических единицах условия).
type Device ¶
type Device struct {
Kind domain.Kind
System domain.System
Designation string
Attributes []AttributeValue
Values []ParameterValue
Variants []Variant
}
Device — запись наполнения для валидации движком: класс, система обозначений и каноническое обозначение (результат разбора — сервисный слой, этап 3), атрибуты, значения параметров типа в целом и исполнения. Форма значений повторяет файл наполнения (docs/plan/06-examples.md): значение задаётся ключом value (exact) | min/max | text, условия — соседними ключами по коду условия.
type DeviceRule ¶
type DeviceRule interface {
Rule
CheckDevice(e *Engine, d *Device) []Problem
AllowsVariants() bool
}
DeviceRule — правило записей класса в целом (kind_validation_rules): проверки, не привязанные к отдельному параметру (матрицы исполнений). AllowsVariants сообщает, придаёт ли правило классу семантику исполнений (D6): секция variants допустима только для классов хотя бы с одним таким правилом (транзисторы/диоды — без вариантов).
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine — движок валидации значений по правилам каталога из снимка (план работ 2.2). Все предметные проверки читаются из данных снимка: применимость параметров/атрибутов к классу (D7), типы значений, позитивность, потолок, комбинации условий, enum; кодом — только механика проверок и именованные межполевые правила. Движок не имеет собственного состояния, снимок иммутабелен — безопасен для одновременного использования несколькими горутинами.
func (*Engine) ValidateDevice ¶
ValidateDevice проверяет запись наполнения целиком: заголовок (класс, система обозначений), атрибуты, значения параметров типа в целом, исполнения и именованные правила. Пустой результат — запись корректна; проблемы накапливаются все за один прогон (частичное применение записей запрещено — docs/plan/01-architecture.md §2.4).
type GroupDef ¶
GroupDef — строка таблицы parameter_groups: группа параметров с именем секции файла наполнения и REST (SectionName — ключ формата, ASCII). Отображаемое название группы — бандлы internal/i18n (D9).
type Input ¶
type Input struct {
Kinds []KindDef
Systems []SystemDef
SystemKinds []SystemKindRef
Units []UnitDef
Categories []CategoryDef
SourceTypes []SourceTypeDef
Conditions []ConditionDef
Groups []GroupDef
Parameters []ParameterDef
Attributes []AttributeDef
Rules []RuleDef
KindRules []KindRuleRef
}
Input — каталог для применения: секция catalog файла наполнения либо сиды (seed/). Применяется поверх существующего снимка upsert'ом по коду (docs/plan/02-database.md §5.4) через ApplyCatalog; разделы опциональны — заданные применяются, отсутствующие не трогают.
func FillSortOrders ¶ added in v0.1.0
FillSortOrders возвращает вход, в котором незаданные (нулевые) sort_order строк с кодом, уже существующим в снимке base (parameter_groups, parameters, attributes), заполнены значениями снимка. Экспорт опускает нулевой sort_order, поэтому 0 во входе — «не задан», а не «первая позиция»: краткая строка расширения не сбивает порядок действующих строк каталога. Явно заданные значения и новые строки не затрагиваются; вход не мутируется — копируются только изменённые срезы.
type KindDef ¶
KindDef — строка таблицы kinds: класс приборов. Отображаемое название — бандлы internal/i18n: kind.<код> (D9).
type KindRuleRef ¶
KindRuleRef — строка таблицы kind_validation_rules: правило, проверяемое для записи класса в целом (когда привязка к отдельному параметру бессмысленна — матрицы исполнений).
type ParameterDef ¶
type ParameterDef struct {
Code string
Group string
Unit string
ValueType ValueType
Ceiling *float64
AllowNegative bool
ValidationRule string
SortOrder int
Active bool
Kinds []domain.Kind
EnumValues []string
ConditionSets []ConditionSet
}
ParameterDef — строка таблицы parameters вместе с применимостью к классам (parameter_kinds), enum-значениями и наборами условий. Kinds пуст — параметр применим ко всем классам, включая добавленные в будущем (D7). DisplayName параметра — бандлы internal/i18n: param.<код> (D9).
type ParameterRule ¶
type ParameterRule interface {
Rule
CheckValues(e *Engine, kind domain.Kind, vals []ParameterValue) []Problem
}
ParameterRule — правило, привязываемое к параметрам: проверяет набор значений одного контекста (запись в целом либо одно исполнение).
type ParameterValue ¶
type ParameterValue struct {
Parameter string
Section string
Exact *float64
Min *float64
Max *float64
Text *string
Conditions []ConditionValue
}
ParameterValue — значение параметра с условиями измерения. Section — имя секции файла наполнения, в которой задано значение (группа каталога: parameters/ratings/dimensions); пустая секция пропускает проверку принадлежности (программатическое задание).
type Problem ¶
Problem — выявленное нарушение: машиночитаемый код и сообщение каталога (MsgID + аргументы рендера, этап 8.3). Message — канонический en-рендер; локализованный рендер — транспорты (как у domain.Error). Коды и тексты — контракт CLI/REST; проблемы накапливаются за один прогон.
type Rule ¶
type Rule interface {
Code() string
}
Rule — именованный код-валидатор межполевого правила. Реестр реализаций мал по построению (риск R7): правило добавляется только тогда, когда оно не выражается данными каталога (условия/типы/enum). Привязка — данными: parameters.validation_rule, attributes.validation_rule, kind_validation_rules (docs/plan/03-data-model.md §11).
func RuleByCode ¶
RuleByCode ищет правило реестра по коду.
type RuleDef ¶
type RuleDef struct {
Code string
}
RuleDef — строка таблицы validation_rules: именованный код-валидатор; реализации — в реестре этого пакета, привязка — данными. Строка — якорь FK; описание правила — бандлы internal/i18n: rule.<код> (D9).
type Snapshot ¶
type Snapshot struct {
Revision int64
Kinds []KindDef
Systems []SystemDef
SystemKinds []SystemKindRef
Units []UnitDef
Categories []CategoryDef
SourceTypes []SourceTypeDef
Conditions []ConditionDef
Groups []GroupDef
Parameters []ParameterDef
Attributes []AttributeDef
Rules []RuleDef
KindRules []KindRuleRef
// contains filtered or unexported fields
}
Snapshot — иммутабельный снимок каталога: все определения (классы, системы обозначений и применимость, семейства, единицы, условия, группы, параметры с применимостью/enum/наборами условий, атрибуты, именованные правила и их привязка к классам). Заполняется транспортом (storage, этап 3) либо применением каталога (ApplyCatalog); после заполнения не мутирует — кэш заменяет снимок целиком по указателю (docs/plan/01-architecture.md §2.2).
func (*Snapshot) Attribute ¶
func (s *Snapshot) Attribute(code string) (*AttributeDef, bool)
Attribute ищет атрибут по коду; указатель стабилен, пока жив снимок.
func (*Snapshot) Category ¶
func (s *Snapshot) Category(code string) (CategoryDef, bool)
Category ищет код словаря категорий (поле category).
func (*Snapshot) CategoryCodes ¶
CategoryCodes перечисляет коды словаря категорий в порядке строк снимка (аргумент перечня допустимых в сообщениях об ошибках).
func (*Snapshot) Condition ¶
func (s *Snapshot) Condition(code string) (ConditionDef, bool)
Condition ищет условие по коду.
func (*Snapshot) GroupBySection ¶
GroupBySection ищет группу по имени секции файла наполнения.
func (*Snapshot) Parameter ¶
func (s *Snapshot) Parameter(code string) (*ParameterDef, bool)
Parameter ищет параметр по коду; указатель стабилен, пока жив снимок.
func (*Snapshot) RulesForKind ¶
RulesForKind возвращает коды именованных правил, привязанных к классу записи (kind_validation_rules), в порядке строк снимка.
func (*Snapshot) SourceType ¶ added in v0.3.0
func (s *Snapshot) SourceType(code string) (SourceTypeDef, bool)
SourceType ищет код словаря типов источников (source_types).
func (*Snapshot) SourceTypeCodes ¶ added in v0.3.0
SourceTypeCodes перечисляет коды словаря типов источников в порядке строк снимка (аргумент перечня допустимых в сообщениях об ошибках).
func (*Snapshot) SystemAppliesTo ¶
SystemAppliesTo сообщает, применима ли система обозначений к классу.
type SourceTypeDef ¶ added in v0.3.0
type SourceTypeDef struct {
Code string
}
SourceTypeDef — строка таблицы source_types: код словаря типов источников данных записи (план 03 §13): book, handbook, journal, standard, spec, datasheet, web. Словарь — данные каталога (расширяется секцией catalog); отображаемое название — бандлы internal/i18n: sourcetype.<код>, расширения без записи в бандле отображаются кодом (D9).
type Store ¶
type Store interface {
// LoadSnapshot загружает полный снимок каталога (все определения
// одним согласованным чтением); Revision снимка читается тем же
// согласованным чтением и соответствует загруженным строкам.
LoadSnapshot(ctx context.Context) (*Snapshot, error)
// CatalogRevision возвращает текущее значение catalog_revision
// (единственный SELECT schema_meta — проверка кэша на каждом
// обращении к сервисам).
CatalogRevision(ctx context.Context) (int64, error)
}
Store — транспорт каталога: чтение определений и ревизии каталога (план работ 2.1). Реализация над БД — слой storage (этап 3): переносимые SELECT по каталожным таблицам и schema_meta. Задача транспорта — только доставка строк: бизнес-правила в нём не живут.
type SystemDef ¶
SystemDef — строка таблицы designation_systems: система обозначений. Отображаемые имя и пояснение — бандлы internal/i18n (D9).
type SystemKindRef ¶
SystemKindRef — строка таблицы designation_system_kinds: применимость системы обозначений к классу (docs/plan/03-data-model.md §1.1).
type UnitDef ¶
type UnitDef struct {
Code string
}
UnitDef — строка таблицы units: каноническая единица измерения (код — латиница). Название и символ — бандлы internal/i18n (D9).
type ValueType ¶
type ValueType string
ValueType — тип значения параметра каталога (docs/plan/03-data-model.md §6): exact (точное), at_least (не менее, с необязательной верхней границей), at_most (не более), range (диапазон), limits (одностороннее ограничение любого направления либо диапазон: не менее / не более / min..max), text, enum.
const ( ValueExact ValueType = "exact" ValueAtLeast ValueType = "at_least" ValueAtMost ValueType = "at_most" ValueRange ValueType = "range" ValueLimits ValueType = "limits" ValueText ValueType = "text" ValueEnum ValueType = "enum" )
Реестр типов значений параметров (DB-значения колонки value_type).
type Variant ¶
type Variant struct {
Label string
Values []ParameterValue
Attributes []AttributeValue
}
Variant — исполнение типа (D6): метка для карточки («160 В», «0.125 Вт»), собственные значения параметров (включая массогабаритные) и атрибуты исполнения — конструктивные признаки, различающиеся по исполнениям (план 03 §7/§10: атрибуты двухуровневые — запись и исполнение).