PriceForge/bible-local/pricelist.md

Pricelists

Types

PriceForge supports three pricelist types (source field):

Type	Data source	Status
estimate	qt_lot_metadata — snapshot of current prices	Active
warehouse	stock_log — stock import data	Active
competitor	Excel exports from competitor B2B portals	Active

---

Estimate

Source: snapshot of current component prices from qt_lot_metadata.

Filter:

• Include only rows with current_price > 0.
• Exclude hidden rows (is_hidden = 1).

Stores:

• price_period_days — price calculation window
• price_coefficient — markup coefficient
• manual_price — manually set price
• meta_prices — historical prices

Purpose: primary pricelist for calculations and estimates.

Categories: loaded from lot.lot_category for each component.

---

Warehouse

Source: stock_log (stock import records).

Rules (CRITICAL):

1. Only mapped partnumbers — only positions with a record in qt_partnumber_book_items are included. Unmapped partnumbers must not appear in any form.
2. No pricing settings — do not load from lot_metadata: no price_period_days, price_coefficient, manual_price, meta_prices.
3. Price method: always weighted_avg (quantity-weighted average).
4. Field price_method always contains "weighted_avg".
5. These are raw stock prices without additional processing.

Categories: loaded from lot.lot_category.

Implementation: internal/warehouse/snapshot.go

---

Competitor

Source: Excel exports from competitor B2B portals, uploaded manually via /admin/competitors.

Rules (CRITICAL):

1. Only mapped partnumbers — only positions with a record in qt_partnumber_book_items are included. Unmapped p/ns are counted and written to qt_vendor_partnumber_seen (source_type = "competitor:<code>").
2. No pricing settings — do not load from lot_metadata: no price_period_days, price_coefficient, manual_price, meta_prices.
3. Price method: always weighted_median (quantity-weighted median across all matched p/ns for a lot).
4. Field price_method always contains "weighted_median", price_period_days always 0.
5. Uplift: effective price = price / price_uplift. price_uplift is a divisor > 1 stored per competitor; default 1.3. Replaces the former expected_discount_pct field.
6. Deduplication: if price and qty for a p/n are unchanged since last import — skip insert into partnumber_log_competitors.

Key tables:

• qt_competitors — competitor profiles (name, code, price_uplift DECIMAL(8,4) DEFAULT 1.3, column mapping JSON, currency)
• partnumber_log_competitors — historical quote log (competitor_id, partnumber, price USD, price local, qty, date)

Implementation: internal/services/competitor_import.go, internal/repository/competitor.go

---

Data Model

type Pricelist struct {
    ID      uint   `gorm:"primaryKey"`
    Version string
    Source  string // "estimate" | "warehouse" | "competitor"
    // ...
}

type PricelistItem struct {
    ID          uint    `gorm:"primaryKey"`
    PricelistID uint
    LotName     string  `gorm:"size:255"`
    Price       float64 `gorm:"type:decimal(12,2)"`
    LotCategory *string `gorm:"column:lot_category;size:50" json:"category,omitempty"`

    // Virtual fields (via JOIN or programmatically)
    LotDescription  string             `gorm:"-:migration" json:"lot_description,omitempty"`
    AvailableQty    *float64           `gorm:"-" json:"available_qty,omitempty"`
    Partnumbers     []string           `gorm:"-" json:"partnumbers,omitempty"`

    // Enriched per-source virtual fields (warehouse / competitor only)
    CompetitorNames []string           `gorm:"-" json:"competitor_names,omitempty"`
    PriceSpreadPct  *float64           `gorm:"-" json:"price_spread_pct,omitempty"`
    PartnumberQtys  map[string]float64 `gorm:"-" json:"partnumber_qtys,omitempty"`
}

gorm:"-:migration" — no DB column created, but mapped on SELECT. gorm:"-" — fully ignored in all DB operations.

---

Categories (lot_category)

• Source: lot.lot_category column in table lot.
• NOT from qt_lot_metadata.
• NOT derived from LOT name.
• Persisted into qt_pricelist_items.lot_category when pricelist is created.
• JSON field name: "category".
• JOIN with lot is only needed for lot_description; category is already in qt_pricelist_items.
• Default value when category is missing: PART_.

---

Pricelist Creation (background task)

Creation runs via Task Manager. Handler returns task_id; frontend polls.

POST /api/pricelists/create
→ { "task_id": "uuid" }
→ polling GET /api/tasks/:id
→ { "status": "completed", "result": { "pricelist_id": 42 } }

Task type: TaskTypePricelistCreate.

Implementation:

• Service: internal/services/pricelist/service.go
• Warehouse calc: internal/warehouse/snapshot.go
• Handler: internal/handlers/pricelist.go

---

Pricelist Deletion Guard

CountUsage(id) checks qt_configurations for references across all three pricelist columns: pricelist_id, warehouse_pricelist_id, competitor_pricelist_id.

A pricelist is only deletable when all three counts are zero.

---

Competitor Pricelist

• Source: competitor
• Rebuilt via: POST /api/competitors/pricelist (task type: competitor_import)
• Logic: Latest quote per (competitor_id, partnumber) across ALL active competitors → apply each competitor's price_uplift (divide price by uplift) → weighted_median per lot → insert into qt_pricelist_items
• price_method: weighted_median, price_period_days: 0
• Quotes stored in partnumber_log_competitors; unmapped p/ns recorded in qt_vendor_partnumber_seen with source_type = 'competitor:<code>'

---

Pricelist Detail Page — Display Layouts

Page: /pricelists/:id — web/templates/pricelist_detail.html + web/static/js/pricelist_detail.js

Two display layouts exist based on source:

Estimate layout (source = "estimate")

Columns: Артикул | Категория | Описание | Цена, $ | Настройки

• Description truncated to 60 chars.
• "Настройки" column shows per-row price adjustment controls.
• No partnumber or supplier column.

Stock layout (source = "warehouse" or "competitor")

Columns: Артикул | Категория | Описание | Partnumbers | Поставщик | Цена, $

• "Настройки" column is hidden.
• "Доступно" (available qty) column is hidden.
• Артикул column has word-break enabled (long lot names wrap).
• Description truncated to 30 chars.

Partnumbers column: shows only PNs with partnumber_qtys[pn] > 0, formatted as PN (qty шт.). Up to 4 shown, then +N ещё.

Поставщик column:

• Warehouse: grey text "склад".
• Competitor: blue badge(s) with competitor name(s) from competitor_names.

Spread badge (competitor only): ±N% in amber next to the price, computed from price_spread_pct.

Per-source enrichment (internal/repository/pricelist.go)

• enrichWarehouseItems: calls warehouse.LoadLotMetrics → fills Partnumbers and PartnumberQtys.
• enrichCompetitorItems: loads latest competitor quotes (qty > 0 only) → resolves to lots via qt_partnumber_book_items → fills CompetitorNames, Partnumbers, PartnumberQtys, PriceSpreadPct.

LoadLotMetrics signature: (db, lotNames, latestOnly) → (qtyByLot, partnumbersByLot, pnQtysByLot, error).