components-catalog

components-catalog

Локальный и встраиваемый справочник электронных компонентов — советская и мировая элементная база. Проект - модуль веб-бэкенда: Go-библиотека с сервисным слоем, встраиваемый версионируемый REST API /api/v1 и консольная утилита catalogctl. Хранилища — SQLite и PostgreSQL, равноправные; всё на pure Go, без cgo. Лицензия — MIT.

Возможности

• Пять классов приборов: транзисторы, диоды, резисторы, конденсаторы, реле.
• Шесть систем обозначений: ГОСТ, ОСТ, PRO ELECTRON, JEDEC, JIS и other. Строгие грамматики разбирает код (с автодетектом класса и системы); бессистемные имена (включая досистемные семейства МЛТ, ВС, КСО…) — other с классификацией секцией fields.
• Каталожные данные: электрические параметры с условиями измерения, предельные эксплуатационные данные, массогабаритные и описательные атрибуты. Состав каталога (параметры, атрибуты, условия, enum-значения) — данные в БД: расширяется файлами наполнения без правки кода и пересборки; движок валидации читает правила из БД.
• Исполнения-варианты: зависимости «номинал × напряжение → габариты» (К50-35) и ряды мощностей (С2-33Н) — внутри одной записи.
• Направленные аналоги: ссылки «чем заменить» с заметками; «B заменяет A» не означает обратного.
• Поиск: подстрока обозначения, сквозные между системами словарные фильтры (материал, подкласс, подстройка, категория), фильтры по полям обозначения, атрибутам и границам параметров, сортировка, пагинация.
• Импорт/экспорт: jsonc, yaml, ndjson; идемпотентный импорт и round-trip экспорт.
• Локализация на краю: база и формат наполнения хранят только коды; отображаемые строки — бандлы (en — канонический, ru — полный). REST — Accept-Language, CLI — --lang.
• Простое хранилище: схема создаётся целиком при открытии, миграций нет; рассинхрон кода и базы исключён версией схемы.

Поддерживаемые приборы

Системы обозначений: gost, ost, pro, jedec, jis, other (бессистемные имена — включая досистемные семейства МЛТ, ВС, КСО…; семейство/номер/буквы — явные поля fields, справочник семейств — docs/class-keys.md §12). Обозначение — точный ключ записи в пределах класса: КТ315Б и 2Т315Б — разные записи.

Быстрый старт (CLI)

go build ./cmd/catalogctl

catalogctl init --db catalog.db
for f in data/*.jsonc; do catalogctl import "$f" --db catalog.db; done

catalogctl list --kind transistor --q КТ3 --db catalog.db   # поиск по подстроке
catalogctl list --material si --subclass bjt --db catalog.db # словарные фильтры
catalogctl info КТ315Б --db catalog.db                       # карточка
catalogctl find 2Т315Б --db catalog.db                       # подсказка: КТ315Б
catalogctl export --format ndjson --db catalog.db            # round-trip экспорт

Команды catalogctl

Общие опции: --dialect sqlite|postgres, --db <путь> (по умолчанию catalog.db), --dsn <строка>, --lang en|ru, --dry-run. Полная справка — catalogctl help.

Встраивание (Go API)

Публичный фасад — пакет components (план 01 §2.4): модуль не запускает серверов и не читает глобальных флагов и env — сайт создаёт App при старте и закрывает при завершении. Импортируется только components; пакеты internal/ внешнему модулю недоступны, типы сервисного слоя открыты алиасами.

import "github.com/billydos/components-catalog/components"

app, err := components.Open(ctx, components.Config{
	Dialect:       "sqlite", // "sqlite" | "postgres"
	DSN:           "catalog.db",
	EnsureCreated: true, // DDL + сиды каталога на пустую базу
})
if err != nil { … }
defer app.Close()

// сервисный слой: Devices / Designations / Catalog
page, err := app.Services.Devices.Search(ctx, components.SearchQuery{
	Kind:  components.KindTransistor,
	Query: "КТ3",
})

// импорт файла наполнения (jsonc/yaml/ndjson; формат — по расширению);
// опция WithProgress — колбэк прогресса больших файлов (NDJSON читается
// построчно, без загрузки целиком)
file, err := os.Open("fill.jsonc")
if err != nil { … }
defer file.Close()
rep, err := app.Importer.Import(ctx, file, "fill.jsonc", false,
	components.WithProgress(func(p components.Progress) { … }))

// ошибки — значения: машиночитаемый код + сообщение
if de, ok := components.AsError(err); ok { … de.Code … }

Готовый runnable-пример — examples/embed: внешний модуль с replace на локальный путь; его сборка и запуск — фаза consumer QA-прогонщика (компилируемость у внешнего потребителя — часть контракта).

REST API

app.Handler() возвращает обычный http.Handler REST /api/v1 — монтируется в любой роутер сайта. Аутентификация, авторизация, rate limiting и CORS — на стороне сайта (запись монтируется только в защищённые маршруты).

mux := http.NewServeMux()
mux.Handle("/api/v1/", app.Handler())
// опции REST — в components.Config:
// DisableSuggest: true — не монтировать GET /suggest
// Metrics:        myMetrics — хук счётчиков сайта

Ошибки — JSON {"code", "message"} со статусами 400/404/409/422/500. Отображаемые поля (name, kind_name, символы единиц, тексты ошибок) заполняются по Accept-Language (по умолчанию en); кодовые поля (kind, system, unit…) и коды ошибок от локали не зависят. Полный контракт — api/openapi.yaml (OpenAPI 3.1; совпадение с реализацией закреплено тестом).

Наполнение

Семантика секций записи (fields, attributes, группы параметров, manufacturers, variants, analogs, synonyms): отсутствует — не менять, задана — заменить целиком, ошибка в любом значении — запись не применяется вовсе. Импорт идемпотентен: повторный прогон того же файла — «без изменений» по всем записям, без инкремента ревизий. Каталог расширяется секцией catalog того же файла — без правки кода.

Выверенное наполнение лежит в data/ (все классы и системы обозначений, матрица исполнений К50-35, ряды мощностей резисторов, паспорта обмоток реле, направленные аналоги); источники по каждой записи — docs/plan/08-data-verification.md. Регламент наполнения — docs/fill-format.md, сводные ключи по классам — docs/class-keys.md.

Сборка и проверка

go build ./... && go vet ./... && gofmt -l . && go test ./...
go run ./qa/runner     # кроссплатформенный QA: статика + сценарии CLI/REST, отчёт qa/reports/*.log

Прогонщик QA работает на Linux, macOS и Windows (SQLite всегда; PostgreSQL — через CATALOG_TEST_POSTGRES_DSN; нагрузочная прикидка — -scale/CATALOG_QA_SCALE). CI (.github/workflows/ci.yml) выполняет его на Linux со службой PostgreSQL и прикидкой 10⁴ и на Windows.

Производительность

Ориентиры: поиск с фильтрами ≤ 100 мс, карточка ≤ 20 мс на 10⁴–10⁵ записей. Подтверждено прикидкой на 10⁴ (SQLite, локально); известное превышение — фильтрованный поиск (EXISTS по EAV) на SQLite при 10⁵. Детали и план Б — qa/reports/2026-10-02-stage7.md.

Документация

Лицензия

MIT.