service

package
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package service — публичный сервисный слой библиотеки и единственная точка входа для CLI, REST и встраивания в веб-бэкэнд: upsert записей, поиск, карточка, импорт/экспорт, операции с каталогом, производители (docs/plan/01-architecture.md §2.4).

Index

Constants

View Source
const (
	SearchDefaultLimit  = 50
	SearchLimitMax      = 200
	SuggestDefaultLimit = 10
	SuggestLimitMax     = 50
)

Лимиты пагинации (docs/plan/04-module-functionality.md §1.1: limit ≤ 200); потолки нужны транспорту для валидации параметров запроса.

Variables

This section is empty.

Functions

This section is empty.

Types

type AnalogInput

type AnalogInput struct {
	Designation string
	Note        string
}

AnalogInput — исходящая ссылка-аналог (D8): обозначение того же класса, опционально с заметкой характера замены в этом направлении.

type App

type App struct {
	// contains filtered or unexported fields
}

App — открытое приложение: хранилище, кэш каталога и сервисы. Безопасно для одновременного использования несколькими горутинами (stateless поверх пулов соединений; снимок каталога иммутабелен).

func Open

func Open(ctx context.Context, cfg Config) (*App, error)

Open открывает приложение по конфигурации: открывает хранилище, при EnsureCreated выполняет DDL и применяет сиды каталога на пустую базу (docs/plan/02-database.md §5.3), проверяет версию схемы (несовпадение — громкий отказ, продолжение работы запрещено).

func (*App) Close

func (a *App) Close() error

Close закрывает приложение (пулы соединений).

func (*App) Revisions

func (a *App) Revisions(ctx context.Context) (catalogRev, dataRev int64, err error)

Revisions возвращает текущие счётчики catalog_revision и data_revision (ETag REST — docs/plan/02-database.md §5.5).

func (*App) Services

func (a *App) Services() Services

Services возвращает набор сервисов приложения.

func (*App) Snapshot

func (a *App) Snapshot(ctx context.Context) (*catalog.Snapshot, error)

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

func (*App) Stats

func (a *App) Stats(ctx context.Context) (Stats, error)

Stats собирает агрегаты приложения: снимок задаёт реестр классов (устройства вне реестра классов невозможны — движок валидации отвергает неизвестный класс), количества и ревизии — в одной транзакции чтения (согласованный снимок, без смешения состояний при конкурентной записи).

type AttributeFilter

type AttributeFilter struct {
	Attribute string
	Text      string
	Num       float64
	HasNum    bool
	Op        FilterOp
}

AttributeFilter — фильтр по атрибуту (код op значение).

type Card

type Card struct {
	ID            int64
	Kind          domain.Kind
	System        domain.System
	Designation   string
	Fields        []domain.Field
	Attributes    []CardAttribute
	Groups        []CardGroup
	Variants      []CardVariant
	Manufacturers []string
	Analogs       []CardLink
	Backlinks     []CardLink
}

Card — карточка записи: обозначение, система, поля разбора, атрибуты, значения параметров по группам, исполнения, производители, аналоги (исходящие и встречные — docs/plan/02-database.md §6).

func (*Card) FieldByName

func (c *Card) FieldByName(name string) (domain.Field, bool)

FieldByName ищет поле разбора обозначения в карточке по коду.

type CardAttribute

type CardAttribute struct {
	Code string
	Text *string
	Num  *float64
	Bool *bool
}

CardAttribute — значение атрибута в карточке (отображаемое название — бандлы internal/i18n: attr.<код> — D9).

type CardGroup

type CardGroup struct {
	Code    string
	Section string
	Values  []CardValue
}

CardGroup — группа каталога со значениями на карточке (отображаемое название — бандлы internal/i18n: group.<код> — D9).

type CardLink struct {
	Kind        domain.Kind
	System      domain.System
	Designation string
	Note        string
}

CardLink — ссылка-аналог: исходящая (аналоги записи) либо встречная (кто ссылается на запись).

type CardValue

type CardValue struct {
	Parameter  string
	Unit       string
	Exact      *float64
	Min        *float64
	Max        *float64
	Text       *string
	Conditions []catalog.ConditionValue
}

CardValue — значение параметра с условиями в карточке (отображаемые название и символ единицы — бандлы internal/i18n: param.<код>, unit.<код>.symbol — D9; Unit — канонический код).

type CardVariant

type CardVariant struct {
	Label  string
	Groups []CardGroup
}

CardVariant — исполнение на карточке (матрица «номинал × напряжение → габариты/масса» собирается группами каталога).

type CatalogService

type CatalogService struct {
	// contains filtered or unexported fields
}

CatalogService — операции с каталогом: снимок для UI и валидации, импорт (расширение каталога — план 02 §5.4). Экспорт — этап 4 (реестр форматов наполнения).

func (*CatalogService) Import

func (s *CatalogService) Import(ctx context.Context, in catalog.Input) error

Import применяет каталог upsert'ом по коду после валидации метасхемы (ApplyCatalog: вставка новой строки либо обновление полей; enum-значения, наборы условий и применимость параметров/атрибутов к классам замещаются целиком по строке; привязки систем и правил к классам — только добавление; непустой список проблем — отказ целиком). Изменение каталога инкрементирует catalog_revision атомарно в той же транзакции.

func (*CatalogService) Snapshot

func (s *CatalogService) Snapshot(ctx context.Context) (*catalog.Snapshot, error)

Snapshot возвращает актуальный снимок каталога (кэш с проверкой catalog_revision на каждом обращении — смена каталога другим процессом видна без перезапуска).

type Config

type Config struct {
	Dialect       string // "sqlite" | "postgres"
	DSN           string // путь файла sqlite / DSN postgres
	Pool          PoolConfig
	Log           *slog.Logger
	EnsureCreated bool
}

Config — конфигурация открытия приложения (план 04 §1: диалект, DSN, пул, логгер). EnsureCreated выполняет DDL и применяет сиды каталога на пустую базу — только у команд записи (init/import/add); по умолчанию выключено: чтение требует инициализированную базу (database_not_initialized иначе).

type DesignationService

type DesignationService struct {
	// contains filtered or unexported fields
}

DesignationService — обозначения: разбор с автодетектом и автодополнение по префиксу (docs/plan/04-module-functionality.md §1.1).

func (*DesignationService) Parse

Parse разбирает обозначение с автодетектом класса и системы: строгие грамматики (gost/ost/pro/jedec/jis) — кодом, порядок попыток фиксирован планом 03 §2.4; системы без разбора (other) автодетекта не имеют.

func (*DesignationService) ParseForSystem

func (s *DesignationService) ParseForSystem(ctx context.Context, text string,
	system domain.System, kind domain.Kind) (domain.ParsedDesignation, error)

ParseForSystem разбирает обозначение с явной системой и необязательным классом (переопределяют автодетект; класс обязателен для other) — CLI parse --system/--kind.

func (*DesignationService) Suggest

func (s *DesignationService) Suggest(ctx context.Context, prefix string, kind domain.Kind, limit int) ([]Suggestion, error)

Suggest возвращает обозначения по префиксу (канонизация префикса; подстрочный регистр не важен — хранятся канонические строки).

type DeviceInput

type DeviceInput struct {
	Name   string
	System domain.System
	Kind   domain.Kind

	Fields        *[]domain.Field
	Attributes    []catalog.AttributeValue
	Sections      []SectionInput
	Manufacturers *[]string
	Variants      *[]VariantInput
	Analogs       *[]AnalogInput
}

DeviceInput — запись наполнения для Upsert. Семантика секций (docs/plan/01-architecture.md §2.4): отсутствует (nil) — не менять; задана — заменить целиком; пустой непустой-nil срез/[] — очистить; ошибка в любом значении секции — запись не применяется вовсе. System/Kind необязательны (автодетект; Kind обязателен для other). Fields — явные классификацион- ные поля (material/subclass/adjustment/category/assembly): допустимы только те, что парсер системы записи не устанавливает сам, и только применимые к классу (проверка — сервисным слоем после разбора).

type DeviceService

type DeviceService struct {
	// contains filtered or unexported fields
}

DeviceService — операции над записями устройств (docs/plan/04-module-functionality.md §1.1).

func (*DeviceService) Count

func (s *DeviceService) Count(ctx context.Context, kind *domain.Kind) (int, error)

Count возвращает число записей (класса, если задан).

func (*DeviceService) Create

func (s *DeviceService) Create(ctx context.Context, in DeviceInput) (Outcome, error)

Create применяет запись наполнения только как создание (POST REST): тот же конвейер проверок, что Upsert, но существующая запись (kind, designation) — найденная в транзакции либо столкнувшаяся по уникальному ключу при вставке (параллельный создатель) — отказ already_exists без применения секций и без изменения базы: 409 перестаёт мутировать по построению.

func (*DeviceService) Delete

func (s *DeviceService) Delete(ctx context.Context, kind domain.Kind, designation string) (bool, error)

Delete удаляет запись (каскад из devices по всем дочерним таблицам, включая обе стороны device_analogs) с чисткой сирот производителей; false — запись не найдена. Класс валидируется по снимку каталога — единому источнику истины (расширяемому импортом), как в Get/Search. Удаление атомарно по ключу в транзакции записи (без окна между поиском и удалением): конкурентное удаление того же обозначения оставляет этот вызов без «пустого» успеха и без инкремента ревизии. Удаление инкрементирует data_revision.

func (*DeviceService) DryRun

DryRun проверяет запись наполнения без изменения базы и возвращает исход, который вернул бы Upsert (import --dry-run). snap — снимок каталога для проверки (nil — актуальный из кэша; dry-run файла, расширяющего каталог, проверяет записи по гипотетическому снимку); pending разрешает ссылки на обозначения, создаваемые этим же прогоном.

func (*DeviceService) Find

func (s *DeviceService) Find(ctx context.Context, kind domain.Kind, designation string) (FindResult, error)

Find ищет запись по точному обозначению; при отсутствии совпадения у полупроводников gost подсказывает равнозначную по материалу запись (Г/1, К/2 — физически равнозначные символы, записи раздельны: docs/plan/01-architecture.md §2.1).

func (*DeviceService) Get

func (s *DeviceService) Get(ctx context.Context, kind domain.Kind, designation string) (*Card, bool, error)

Get возвращает карточку по классу и обозначению (точный ключ). kind == "" — любой класс (обозначение уникально в пределах класса, при коллизии между классами вернётся детерминированно первая запись).

func (*DeviceService) GetByID

func (s *DeviceService) GetByID(ctx context.Context, id int64) (*Card, bool, error)

GetByID возвращает карточку по стабильному id записи.

func (*DeviceService) GetByIDs

func (s *DeviceService) GetByIDs(ctx context.Context, ids []int64) ([]*Card, error)

GetByIDs возвращает карточки по списку стабильных id пакетным чтением дочерних таблиц (экспорт — без запросов на каждую запись): порядок результата — по порядку id входа, параллельно удалённые записи пропускаются.

func (*DeviceService) ListIDsByKind

func (s *DeviceService) ListIDsByKind(ctx context.Context, kind domain.Kind) ([]int64, error)

ListIDsByKind перечисляет id записей класса в порядке (designation) одним запросом — последовательная выгрузка без дрейфа страниц (параллельные вставки/удаления не дают дубли и пропуски выборки).

func (*DeviceService) Search

Search выполняет поиск: подстрока обозначения, фильтры полей/атрибутов/ параметров (применимость к классу запроса — D7, ошибки валидации запроса), сортировка с финальным (kind, designation), пагинация (limit ≤ 200); вариантные параметрические фильтры применяются в пределах одного исполнения (docs/plan/04-module-functionality.md §1.1).

func (*DeviceService) Upsert

func (s *DeviceService) Upsert(ctx context.Context, in DeviceInput) (Outcome, error)

Upsert применяет запись наполнения с семантикой секций (docs/plan/02-database.md §6): разбор обозначения → слитое состояние (вход + текущие секции) → каноническое сравнение (побайтово тот же вход — Skipped до валидации, без записи в БД и без инкремента ревизий: эволюция каталога не делает существующие записи неотрекаемыми) → валидация движком → применение секций целиком + инкремент data_revision. Ошибка в любом значении секции — запись не применяется вовсе.

func (*DeviceService) ValidateSearch

func (s *DeviceService) ValidateSearch(ctx context.Context, q SearchQuery) error

ValidateSearch проверяет поисковый запрос по каталогу (класс, система, фильтры атрибутов/параметров и их применимость) без обращения к БД: условное кэширование транспорта (304 по ETag) обязано отвечать невалидному запросу 400 до отсечения — валидация дешевле выполнения.

type FieldFilter

type FieldFilter struct {
	Field  string
	Text   string
	Num    float64
	HasNum bool
	Op     FilterOp
}

FieldFilter — фильтр по полю разбора обозначения (material, subclass, junctions, group, dev_number, series…): текстовое равенство (Text) либо числовое со сравнением (Num + Op).

type FilterOp

type FilterOp string

FilterOp — операция сравнения числового фильтра поиска.

const (
	OpEq  FilterOp = "eq"
	OpGte FilterOp = "gte"
	OpLte FilterOp = "lte"
)

Операции фильтров поиска.

type FindResult

type FindResult struct {
	Found      *Card
	Suggestion *Card
}

FindResult — результат find: точное совпадение и подсказка равнозначной записи по материалу (полупроводники gost: Г/1, К/2 — раздельные записи).

type Outcome

type Outcome string

Outcome — исход Upsert записи (docs/plan/04-module-functionality.md §1.1).

const (
	// OutcomeAdded — записи не было, создана.
	OutcomeAdded Outcome = "Added"
	// OutcomeUpdatedExisting — запись была, секции применены.
	OutcomeUpdatedExisting Outcome = "UpdatedExisting"
	// OutcomeSkipped — слитое состояние совпадает с текущим: записи в БД
	// не выполнялось, ревизии не инкрементировались.
	OutcomeSkipped Outcome = "Skipped"
)

Реестр исходов Upsert.

type ParameterFilter

type ParameterFilter struct {
	Parameter string
	Min       *float64
	Max       *float64
	Exact     *float64
	Text      string
}

ParameterFilter — параметрический фильтр: границы (Min/Max), точное значение (Exact) либо текст/enum (Text); вариантные параметры применяются в пределах одного исполнения.

type PendingDesignations

type PendingDesignations func(kind domain.Kind, designation string) bool

PendingDesignations сообщает, будет ли обозначение создано этим же прогоном импорта: разрешение исходящих ссылок-аналогов на записи, встречающиеся в файле позже (dry-run без записи в БД).

type PoolConfig

type PoolConfig struct {
	MaxOpen         int
	MaxIdle         int
	ConnMaxLifetime int64 // наносекунды; 0 — без ограничения
	BusyTimeout     int64 // миллисекунды (sqlite); 0 — по умолчанию
}

PoolConfig — параметры пулов соединений.

type SearchItem

type SearchItem struct {
	ID          int64
	Kind        domain.Kind
	System      domain.System
	Designation string
	Fields      []domain.Field
}

SearchItem — строка результатов поиска.

type SearchPage

type SearchPage struct {
	Items  []SearchItem
	Total  int
	Limit  int
	Offset int
}

SearchPage — страница результатов с общим числом записей под фильтрами.

type SearchQuery

type SearchQuery struct {
	Kind       domain.Kind
	System     domain.System
	Query      string
	Fields     []FieldFilter
	Attributes []AttributeFilter
	Parameters []ParameterFilter
	Sort       []SortField
	Limit      int
	Offset     int
}

SearchQuery — запрос поиска: класс, система, подстрока обозначения, фильтры полей/атрибутов/параметров, сортировка, пагинация (docs/plan/04-module-functionality.md §1.1).

type SectionInput

type SectionInput struct {
	Section string
	Values  []catalog.ParameterValue
}

SectionInput — секция группы параметров записи (имя — из группы каталога: parameters/ratings/dimensions); nil-семантики на уровне DeviceInput.

type Services

type Services struct {
	Devices      *DeviceService
	Designations *DesignationService
	Catalog      *CatalogService
}

Services — доступ к сервисам приложения.

type SortField

type SortField struct {
	Key     string
	Numeric bool
	Desc    bool
}

SortField — ключ сортировки: "designation", "id" либо код поля разбора (Numeric — поле числовое).

type Stats

type Stats struct {
	Counts          map[domain.Kind]int
	Total           int
	SchemaVersion   int
	CatalogRevision int64
	DataRevision    int64
}

Stats — агрегаты для REST /api/v1/stats: количества записей по классам, версия схемы модуля и счётчики ревизий (docs/plan/04-module-functionality.md §2).

type Suggestion

type Suggestion struct {
	Kind        domain.Kind
	System      domain.System
	Designation string
}

Suggestion — подсказка автодополнения по префиксу обозначения.

type VariantInput

type VariantInput struct {
	Label    string
	Sections []SectionInput
}

VariantInput — исполнение типа (D6): метка для карточки и собственные значения параметров по секциям групп.

Jump to

Keyboard shortcuts

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