catalog

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 9 Imported by: 0

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

View Source
const (
	RuleCapDimensionsForm    = "cap_dimensions_form"
	RuleCapVariantMatrix     = "cap_variant_matrix"
	RuleRelayVariantCoil     = "relay_variant_coil"
	RuleResistorVariantPower = "resistor_variant_power"
	RuleTempPair             = "temp_pair"
	RuleYearRange            = "year_range"
)

Коды именованных правил — стабильные ключи каталога: сиды и данные наполнения ссылаются на правила только через эти константы; соответствие реестру ruleRegistry закреплено пин-тестами сидов.

View Source
const (
	YearRangeMin = 1949
	YearRangeMax = 2100
)

Границы годов выпуска — общие для правила year_range (атрибуты yearFrom/yearTo) и проверки годов синонимов сервисного слоя (03-data-model.md §9, §11): единая точка изменения границы.

Variables

This section is empty.

Functions

func ApplyCatalog

func ApplyCatalog(base *Snapshot, in Input) (*Snapshot, []Problem)

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

func KindSection(k domain.Kind) string

KindSection — ключ секции корня формата наполнения для класса: код класса с «s» (transistors, diodes, resistors, capacitors, relays; docs/fill-format.md §2).

func RecordKeyReserved

func RecordKeyReserved(key string) bool

RecordKeyReserved сообщает, служебный ли ключ записи формата наполнения: name, system, fields, attributes, manufacturers, variants, analogs, synonyms, sources (docs/fill-format.md §3).

func ValueKeyReserved

func ValueKeyReserved(key string) bool

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.

const (
	AttrText     AttrType = "text"
	AttrTextList AttrType = "text_list"
	AttrBool     AttrType = "bool"
	AttrInt      AttrType = "int"
	AttrNumber   AttrType = "number"
	AttrEnum     AttrType = "enum"
)

Реестр типов значений атрибутов (DB-значения колонки value_type).

func (AttrType) Valid

func (t AttrType) Valid() bool

Valid сообщает, входит ли тип атрибута в реестр.

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).

func (*AttributeDef) AppliesTo

func (a *AttributeDef) AppliesTo(kind domain.Kind) bool

AppliesTo сообщает, применим ли атрибут к классу записи (D7).

type AttributeRule

type AttributeRule interface {
	Rule
	CheckAttributes(e *Engine, kind domain.Kind, vals []AttributeValue) []Problem
}

AttributeRule — правило, привязываемое к атрибутам записи.

type AttributeValue

type AttributeValue struct {
	Attribute string
	Text      *string
	Texts     []string
	Num       *float64
	Bool      *bool
}

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

func NewCache(store Store) *Cache

NewCache создаёт кэш каталога над транспортом; первый Snapshot(ctx) загружает снимок, дальнейшие — только при смене ревизии.

func (*Cache) Invalidate

func (c *Cache) Invalidate()

Invalidate сбрасывает кэш (следующий Snapshot загружает снимок заново).

func (*Cache) Snapshot

func (c *Cache) Snapshot(ctx context.Context) (*Snapshot, error)

Snapshot возвращает актуальный снимок каталога. Загрузку ведёт один вызов (single-flight): параллельные читатели не блокируются мьютексом на время загрузки, а ждут её результата; отменённый ждущий возвращается с ошибкой своего контекста, не дожидаясь загрузки (при отмене вызова ждать нечего). Дождавшийся перечитывает ревизию и повторяет цикл: при несовпадении ревизии — снимок мог быть загружен до свежей записи каталога; при падении полёта — ошибка загрузчика (в том числе отмена его контекста) не заражает ждущих: следующий цикл ведёт свой полёт и отвечает своей ошибкой. Гонка «прочитали старую ревизию — каталог применили — загрузили новый снимок» доброкачественна: следующий вызов видит новую ревизию и перезагружает снимок. Ревизия кэшируется вместе со снимком из его же согласованного чтения, поэтому кэш никогда не отвечает парой «снимок ≠ ревизия».

type CategoryDef

type CategoryDef struct {
	Code string
}

CategoryDef — строка таблицы categories: код классификационного поля category (применение/характеристика прибора — переключательный, импульсный, малошумящий…; ортогонален подклассу — функции перехода). Словарь — данные каталога (расширяется секцией catalog без правки кода); отображаемое название — бандлы internal/i18n: category.<код>, расширения без записи в бандле отображаются кодом (D9).

type ConditionDef

type ConditionDef struct {
	Code          string
	Unit          string
	AllowNegative bool
}

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

type ConditionValue struct {
	Condition string
	Value     float64
}

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 NewEngine

func NewEngine(snap *Snapshot) *Engine

NewEngine создаёт движок валидации над снимком каталога.

func (*Engine) Snapshot

func (e *Engine) Snapshot() *Snapshot

Snapshot возвращает снимок, поверх которого работает движок.

func (*Engine) ValidateDevice

func (e *Engine) ValidateDevice(d *Device) []Problem

ValidateDevice проверяет запись наполнения целиком: заголовок (класс, система обозначений), атрибуты, значения параметров типа в целом, исполнения и именованные правила. Пустой результат — запись корректна; проблемы накапливаются все за один прогон (частичное применение записей запрещено — docs/plan/01-architecture.md §2.4).

type GroupDef

type GroupDef struct {
	Code        string
	SectionName string
	SortOrder   int
}

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

func FillSortOrders(base *Snapshot, in Input) Input

FillSortOrders возвращает вход, в котором незаданные (нулевые) sort_order строк с кодом, уже существующим в снимке base (parameter_groups, parameters, attributes), заполнены значениями снимка. Экспорт опускает нулевой sort_order, поэтому 0 во входе — «не задан», а не «первая позиция»: краткая строка расширения не сбивает порядок действующих строк каталога. Явно заданные значения и новые строки не затрагиваются; вход не мутируется — копируются только изменённые срезы.

type KindDef

type KindDef struct {
	Code domain.Kind
}

KindDef — строка таблицы kinds: класс приборов. Отображаемое название — бандлы internal/i18n: kind.<код> (D9).

type KindRuleRef

type KindRuleRef struct {
	Kind domain.Kind
	Rule string
}

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).

func (*ParameterDef) AppliesTo

func (p *ParameterDef) AppliesTo(kind domain.Kind) bool

AppliesTo сообщает, применим ли параметр к классу записи (D7).

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

type Problem struct {
	Code    domain.Code
	MsgID   domain.MsgID
	Args    []any
	Message string
}

Problem — выявленное нарушение: машиночитаемый код и сообщение каталога (MsgID + аргументы рендера, этап 8.3). Message — канонический en-рендер; локализованный рендер — транспорты (как у domain.Error). Коды и тексты — контракт CLI/REST; проблемы накапливаются за один прогон.

func Problemf

func Problemf(code domain.Code, id domain.MsgID, args ...any) Problem

Problemf строит проблему по коду и сообщению каталога.

func (Problem) Err

func (p Problem) Err() *domain.Error

Err преобразует проблему в ошибку домена.

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

func RuleByCode(code string) (Rule, bool)

RuleByCode ищет правило реестра по коду.

func Rules

func Rules() []Rule

Rules возвращает все зарегистрированные правила, отсортированные по коду (порядок сидов validation_rules).

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

func (s *Snapshot) CategoryCodes() []string

CategoryCodes перечисляет коды словаря категорий в порядке строк снимка (аргумент перечня допустимых в сообщениях об ошибках).

func (*Snapshot) Clone

func (s *Snapshot) Clone() *Snapshot

Clone глубоко копирует снимок (основа для применения каталога).

func (*Snapshot) Condition

func (s *Snapshot) Condition(code string) (ConditionDef, bool)

Condition ищет условие по коду.

func (*Snapshot) Group

func (s *Snapshot) Group(code string) (GroupDef, bool)

Group ищет группу параметров по коду.

func (*Snapshot) GroupBySection

func (s *Snapshot) GroupBySection(section string) (GroupDef, bool)

GroupBySection ищет группу по имени секции файла наполнения.

func (*Snapshot) Kind

func (s *Snapshot) Kind(code domain.Kind) (KindDef, bool)

Kind ищет класс по коду.

func (*Snapshot) Parameter

func (s *Snapshot) Parameter(code string) (*ParameterDef, bool)

Parameter ищет параметр по коду; указатель стабилен, пока жив снимок.

func (*Snapshot) RulesForKind

func (s *Snapshot) RulesForKind(kind domain.Kind) []string

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

func (s *Snapshot) SourceTypeCodes() []string

SourceTypeCodes перечисляет коды словаря типов источников в порядке строк снимка (аргумент перечня допустимых в сообщениях об ошибках).

func (*Snapshot) System

func (s *Snapshot) System(code domain.System) (SystemDef, bool)

System ищет систему обозначений по коду.

func (*Snapshot) SystemAppliesTo

func (s *Snapshot) SystemAppliesTo(system domain.System, kind domain.Kind) bool

SystemAppliesTo сообщает, применима ли система обозначений к классу.

func (*Snapshot) Unit

func (s *Snapshot) Unit(code string) (UnitDef, bool)

Unit ищет единицу по коду.

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

type SystemDef struct {
	Code domain.System
}

SystemDef — строка таблицы designation_systems: система обозначений. Отображаемые имя и пояснение — бандлы internal/i18n (D9).

type SystemKindRef

type SystemKindRef struct {
	System domain.System
	Kind   domain.Kind
}

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).

func (ValueType) Numeric

func (t ValueType) Numeric() bool

Numeric сообщает, численный ли тип (для проверок единиц и enum-значений).

func (ValueType) Valid

func (t ValueType) Valid() bool

Valid сообщает, входит ли тип значения в реестр.

type Variant

type Variant struct {
	Label      string
	Values     []ParameterValue
	Attributes []AttributeValue
}

Variant — исполнение типа (D6): метка для карточки («160 В», «0.125 Вт»), собственные значения параметров (включая массогабаритные) и атрибуты исполнения — конструктивные признаки, различающиеся по исполнениям (план 03 §7/§10: атрибуты двухуровневые — запись и исполнение).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL