Documentation
¶
Overview ¶
Package service — публичный сервисный слой библиотеки и единственная точка входа для CLI, REST и встраивания в веб-бэкэнд: upsert записей, поиск, карточка, импорт/экспорт, операции с каталогом, производители (docs/plan/01-architecture.md §2.4).
Index ¶
- Constants
- type AnalogInput
- type App
- type AttributeFilter
- type Card
- type CardAttribute
- type CardGroup
- type CardLink
- type CardValue
- type CardVariant
- type CatalogService
- type Config
- type DesignationService
- func (s *DesignationService) Parse(ctx context.Context, text string) (domain.ParsedDesignation, error)
- func (s *DesignationService) ParseForSystem(ctx context.Context, text string, system domain.System, kind domain.Kind) (domain.ParsedDesignation, error)
- func (s *DesignationService) Suggest(ctx context.Context, prefix string, kind domain.Kind, limit int) ([]Suggestion, error)
- type DeviceInput
- type DeviceService
- func (s *DeviceService) Count(ctx context.Context, kind *domain.Kind) (int, error)
- func (s *DeviceService) Create(ctx context.Context, in DeviceInput) (Outcome, error)
- func (s *DeviceService) Delete(ctx context.Context, kind domain.Kind, designation string) (bool, error)
- func (s *DeviceService) DryRun(ctx context.Context, in DeviceInput, snap *catalog.Snapshot, ...) (Outcome, error)
- func (s *DeviceService) Find(ctx context.Context, kind domain.Kind, designation string) (FindResult, error)
- func (s *DeviceService) Get(ctx context.Context, kind domain.Kind, designation string) (*Card, bool, error)
- func (s *DeviceService) GetByID(ctx context.Context, id int64) (*Card, bool, error)
- func (s *DeviceService) GetByIDs(ctx context.Context, ids []int64) ([]*Card, error)
- func (s *DeviceService) ListIDsByKind(ctx context.Context, kind domain.Kind) ([]int64, error)
- func (s *DeviceService) Search(ctx context.Context, q SearchQuery) (SearchPage, error)
- func (s *DeviceService) Upsert(ctx context.Context, in DeviceInput) (Outcome, error)
- func (s *DeviceService) ValidateSearch(ctx context.Context, q SearchQuery) error
- type FieldFilter
- type FilterOp
- type FindResult
- type Outcome
- type ParameterFilter
- type PendingDesignations
- type PoolConfig
- type SearchItem
- type SearchPage
- type SearchQuery
- type SectionInput
- type Services
- type SortField
- type Stats
- type Suggestion
- type VariantInput
Constants ¶
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 ¶
AnalogInput — исходящая ссылка-аналог (D8): обозначение того же класса, опционально с заметкой характера замены в этом направлении.
type App ¶
type App struct {
// contains filtered or unexported fields
}
App — открытое приложение: хранилище, кэш каталога и сервисы. Безопасно для одновременного использования несколькими горутинами (stateless поверх пулов соединений; снимок каталога иммутабелен).
func Open ¶
Open открывает приложение по конфигурации: открывает хранилище, при EnsureCreated выполняет DDL и применяет сиды каталога на пустую базу (docs/plan/02-database.md §5.3), проверяет версию схемы (несовпадение — громкий отказ, продолжение работы запрещено).
func (*App) Revisions ¶
Revisions возвращает текущие счётчики catalog_revision и data_revision (ETag REST — docs/plan/02-database.md §5.5).
func (*App) Snapshot ¶
Snapshot возвращает актуальный снимок каталога (кэш с проверкой catalog_revision на каждом обращении).
type AttributeFilter ¶
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).
type CardAttribute ¶
CardAttribute — значение атрибута в карточке (отображаемое название — бандлы internal/i18n: attr.<код> — D9).
type CardGroup ¶
CardGroup — группа каталога со значениями на карточке (отображаемое название — бандлы internal/i18n: group.<код> — D9).
type CardLink ¶
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 ¶
CardVariant — исполнение на карточке (матрица «номинал × напряжение → габариты/масса» собирается группами каталога).
type CatalogService ¶
type CatalogService struct {
// contains filtered or unexported fields
}
CatalogService — операции с каталогом: снимок для UI и валидации, импорт (расширение каталога — план 02 §5.4). Экспорт — этап 4 (реестр форматов наполнения).
func (*CatalogService) Import ¶
Import применяет каталог upsert'ом по коду после валидации метасхемы (ApplyCatalog: вставка новой строки либо обновление полей; enum-значения, наборы условий и применимость параметров/атрибутов к классам замещаются целиком по строке; привязки систем и правил к классам — только добавление; непустой список проблем — отказ целиком). Изменение каталога инкрементирует 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 ¶
func (s *DesignationService) Parse(ctx context.Context, text string) (domain.ParsedDesignation, error)
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.
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) 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 ¶
func (s *DeviceService) DryRun(ctx context.Context, in DeviceInput, snap *catalog.Snapshot, pending PendingDesignations) (Outcome, error)
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) GetByIDs ¶
GetByIDs возвращает карточки по списку стабильных id пакетным чтением дочерних таблиц (экспорт — без запросов на каждую запись): порядок результата — по порядку id входа, параллельно удалённые записи пропускаются.
func (*DeviceService) ListIDsByKind ¶
ListIDsByKind перечисляет id записей класса в порядке (designation) одним запросом — последовательная выгрузка без дрейфа страниц (параллельные вставки/удаления не дают дубли и пропуски выборки).
func (*DeviceService) Search ¶
func (s *DeviceService) Search(ctx context.Context, q SearchQuery) (SearchPage, error)
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 ¶
FieldFilter — фильтр по полю разбора обозначения (material, subclass, junctions, group, dev_number, series…): текстовое равенство (Text) либо числовое со сравнением (Num + Op).
type FindResult ¶
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 ¶
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 ¶
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 ¶
Suggestion — подсказка автодополнения по префиксу обозначения.
type VariantInput ¶
type VariantInput struct {
Label string
Sections []SectionInput
}
VariantInput — исполнение типа (D6): метка для карточки и собственные значения параметров по секциям групп.