Stock

NOTE

Статус: Live (HEAD 5e4ce54, 2026-05-06). BC закрыт в P2b (Stock Rule aggregate, ADR-0037, CLOSED 2026-04-25) + Live-C (Layer 3b live refresh, CLOSED 2026-04-28).

StockRule aggregate + Layer 3b live refresh: остатки от поставщика per-warehouse, обогащённые admin-правилами и live-pull через customer credential. Per-warehouse lead_time_min/max end-to-end (ADR-0037).

Назначение

Дать proposal pipeline актуальный stock breakdown по каждому supplier-offer’у: количество per-warehouse, lead-time, scope (canonical/manufacturer/category), priority resolution. Layer 3b позволяет live-refresh при наличии customer credential.

Статус документа

• Тип знания: current service
• Статус реализации: Engine always-on с дня one (ADR-0037); Layer 3b live-refresh per Live-B + Live-C; concrete adapters etm/iek/systeme.
• Текущее место кода: backend/internal/core/stock/{domain,app,infra}/.
• Что читать дальше: ../../20-architecture/adr/0037-stock-rule-aggregate.md, ../../20-architecture/adr/0035-proposal-pipeline-layering.md.

Область действия

Входит:

• StockRule aggregate (scope + per-warehouse availability + priority).
• Engine: применить rules к candidate’у proposal.
• Layer 3b live refresh — fetch fresh stock через customer credential.
• Admin HTTP /api/v1/admin/stock/rules/*.
• Per-warehouse lead_time_min/max end-to-end (ADR-0037).

Не входит:

• Стоимость остатков — pricing BC.
• Резервация — out of scope (no stock holds).
• Inventory management physical — out of scope.

Публичный контракт

Внутренний Go API

• Engine.Apply(ctx, candidate) — выдаёт StockBreakdown с per-warehouse availability.
• RuleRepo.Upsert/Delete — admin CRUD.
• Layer 3b через LiveStockRefresher.Refresh(ctx, request) — fetch + cache warm.

HTTP

• Admin CRUD /api/v1/admin/stock/rules/*.

Внутренняя архитектура

• domain/rule.go — StockRule aggregate.
• domain/applies_to.go — scope (canonical / manufacturer / category / supplier).
• domain/priority.go — priority resolution.
• domain/breakdown.go — StockBreakdown (per-warehouse availability + lead-time).
• domain/result.go — финальный result для proposal.
• app/Engine — apply.
• infra/pg/ — Repo.
• infra/live/ — Layer 3b live-refresh adapters.

Зависимости

• PostgreSQL — stock_rule.
• offers BC — ObservationWriter.UpsertLiveStock (Live-C).
• credentials BC — Pool.Pick для live-refresh.
• supplier connectors — REST/JSON для direct fetch.

Хранилище

• stock_rule — (scope, applies_to, available_qty, warehouse_ref, lead_time, priority, version).

Тестирование

• Unit: go test ./internal/core/stock/...
• Integration: -tags=integration для Repo + Live-B/C adapters.

Наблюдаемость

• Metrics: stock_rules_applied_total{source}, stock_live_refresh_total{outcome}, stock_available_qty_total{supplier,warehouse}.
• Phase logs: stock.apply.phase, stock.live_refresh.phase.

Связанные документы

• ADR: 0037, 0035.
• Memory: tracium_p2b_stock_execution.md, tracium_live_b_execution.md, tracium_live_c_execution.md.
• Соседи: ../delivery/, ../pricing/.