# Change History > Architectural decisions and significant refactoring are recorded here. > Every architectural decision MUST be documented in this file. --- ## 2026-02-21: Partnumber Book Snapshots for QuoteForge ### Decision Implemented versioned snapshots of the `lot_partnumbers` → LOT mapping in `qt_partnumber_books` / `qt_partnumber_book_items`. PriceForge writes; QuoteForge reads (SELECT only). ### What changed - Migration `026`: added `is_primary_pn TINYINT(1) DEFAULT 1` to `lot_partnumbers`; created `qt_partnumber_books` and `qt_partnumber_book_items` tables (version `VARCHAR(20)`, later corrected). - Migration `027`: corrected `version VARCHAR(20) → VARCHAR(30)` — `PNBOOK-YYYY-MM-DD-NNN` is 21 chars and overflowed the original column. - Migration `028`: added `description VARCHAR(10000) NULL` to `qt_partnumber_book_items` — required by QuoteForge sync (`SELECT partnumber, lot_name, is_primary_pn, description`). - Models `PartnumberBook`, `PartnumberBookItem` (with `Description *string`) added to `internal/models/lot.go`; `IsPrimaryPN bool` added to `LotPartnumber`. - Service `internal/services/partnumber_book.go`: - `CreateSnapshot`: expands bundles (QuoteForge is bundle-unaware), copies `description` from `lot_partnumbers` to every expanded row, generates version `PNBOOK-YYYY-MM-DD-NNN`, deactivates previous books and activates new one atomically, then runs GFS retention cleanup. - `expandMappings`: filters out rows where `lot_name` is empty/whitespace; filters out partnumbers marked `is_ignored = true` in `qt_vendor_partnumber_seen`. Only valid PN→LOT pairs enter the snapshot. - `applyRetention`: deletes items explicitly (`DELETE … WHERE book_id IN (…)`) before deleting books — does not rely on FK CASCADE which GORM does not trigger on batch deletes. - `ListBooks`: returns all snapshots ordered newest-first with item counts. - GFS retention policy: 7 daily · 5 weekly · 12 monthly · 10 yearly; applied automatically after each snapshot; active book is never deleted. - Task type `TaskTypePartnumberBookCreate` added to `internal/tasks/task.go`. - Handlers `ListPartnumberBooks` and `CreatePartnumberBook` added to `internal/handlers/pricing.go`; `PartnumberBookService` injected via constructor. - Routes `GET /api/admin/pricing/partnumber-books` and `POST /api/admin/pricing/partnumber-books` registered in `cmd/pfs/main.go`. - UI: "Снимки сопоставлений (Partnumber Books)" section with snapshot table, progress bar, and "Создать снапшот сопоставлений" button added to `web/templates/vendor_mappings.html`. ### Rationale QuoteForge needs a stable, versioned copy of the PN→LOT mapping to resolve BOM line items without live dependency on PriceForge. Snapshots decouple the two systems. ### Constraints - Bundles MUST be expanded: QuoteForge does not know about `qt_lot_bundles`. - Snapshot rows with empty `lot_name` or `is_ignored = true` partnumbers MUST be excluded. - `description` in book items comes from `lot_partnumbers.description`; for expanded bundle rows the description of the parent partnumber mapping is used. - `is_primary_pn` is copied from `lot_partnumbers` into each book item; drives qty logic in QuoteForge. - New snapshot is immediately `is_active=1`; all previous books are deactivated in the same transaction. - Version format: `PNBOOK-YYYY-MM-DD-NNN` (`VARCHAR(30)`), sequential within the same day. - Item deletion during retention MUST be explicit (items first, then books) — FK CASCADE is unreliable with GORM batch deletes. - QuoteForge has `SELECT` permission only on `qt_partnumber_books` and `qt_partnumber_book_items`. ### Files - Migrations: `026_add_partnumber_books.sql`, `027_fix_partnumber_books_version_length.sql`, `028_add_description_to_partnumber_book_items.sql` - Models: `internal/models/lot.go` - Service: `internal/services/partnumber_book.go` - Handler: `internal/handlers/pricing.go` - Tasks: `internal/tasks/task.go` - Routes: `cmd/pfs/main.go` - UI: `web/templates/vendor_mappings.html` --- ## 2026-02-20: Pricelist Formation Hardening (Estimate/Warehouse/Meta) ### Decision Hardened pricelist formation rules to remove ambiguity and prevent silent data loss in UI/API. ### What changed - `estimate` snapshot now explicitly excludes hidden components (`qt_lot_metadata.is_hidden = 1`). - Category snapshot in `qt_pricelist_items.lot_category` now always has a deterministic fallback: `PART_` is assigned even when a LOT row is missing in `lot`. - `PricelistItem` JSON contract was normalized to a single category field (`LotCategory -> json:"category"`), removing duplicate JSON-tag ambiguity. - Meta-price source expansion now always includes the base LOT, then merges `meta_prices` sources with deduplication (exact + wildcard overlaps). ### Rationale - Prevent hidden/ignored components from leaking into estimate pricelists. - Keep frontend category rendering stable for all items. - Avoid non-deterministic JSON serialization when duplicate tags are present. - Ensure meta-article pricing includes self-history and does not overcount duplicate sources. ### Constraints - `estimate` pricelist invariant: `current_price > 0 AND is_hidden = 0`. - `category` in API must map from persisted `qt_pricelist_items.lot_category`. - Missing category source must default to `PART_`. - Meta source list must contain each LOT at most once. ### Files - Model: `internal/models/pricelist.go` - Estimate/Warehouse snapshot service: `internal/services/pricelist/service.go` - Pricing handler/meta expansion: `internal/handlers/pricing.go` - Pricing service/meta expansion: `internal/services/pricing/service.go` - Tests: - `internal/services/pricelist/service_estimate_test.go` - `internal/services/pricelist/service_warehouse_test.go` - `internal/handlers/pricing_meta_expand_test.go` - `internal/services/pricing/service_meta_test.go` - `internal/services/stock_import_test.go` --- ## 2026-02-20: Seen Registry Deduplication by Partnumber ### Decision Changed `qt_vendor_partnumber_seen` semantics to one row per `partnumber` (vendor/source are no longer part of uniqueness). ### Rationale - Eliminates duplicate seen rows when the same partnumber appears both with vendor and without vendor. - Keeps ignore behavior consistent regardless of vendor presence. - Simplifies operational cleanup and prevents re-creation of vendor/no-vendor duplicates. ### Constraints - `partnumber` is now the unique key in seen registry. - Ignore checks are resolved by `partnumber` only. - Stock provenance must be preserved (`source_type='stock'`) when stock data exists for the partnumber. ### Files - Migration: `migrations/025_dedup_vendor_seen_by_partnumber.sql` - Service: `internal/services/stock_import.go` - Service: `internal/services/vendor_mapping.go` - Model: `internal/models/lot.go` --- ## 2026-02-18: Global Vendor Partnumber Mapping ### Decision Implemented global vendor partnumber → LOT mapping with bundle support and seen-based ignore logic. ### Key rules - `lot_partnumbers` is the canonical mapping contract (1:1 per key). - Composite mappings use internal bundle tables (`qt_lot_bundles`, `qt_lot_bundle_items`). - Ignore logic moved from `stock_ignore_rules` to `qt_vendor_partnumber_seen.is_ignored`. - Resolver order: exact `(vendor, partnumber)` → fallback `(vendor='', partnumber)`. ### Rationale - Preserves external/client contracts (`lot_partnumbers`, LOT-based pricelists). - Avoids multi-row ambiguity in `lot_partnumbers`. - Supports complex assembled vendor SKUs without client-side changes. - Centralizes ignore behavior across all sources via seen-registry. ### Constraints - Bundle LOT is internal and must stay hidden in regular LOT list by default. - Resolver order is mandatory and fixed. - Bundle allocation for missing estimate: fallback from previous active warehouse pricelist; if absent → `0`. ### Files - Migration: `migrations/023_vendor_partnumber_global_mapping.sql` - Backfill: `migrations/024_backfill_vendor_seen_from_stock_and_ignore.sql` - Resolver: `internal/lotmatch/matcher.go` - Service: `internal/services/vendor_mapping.go` - Warehouse calc: `internal/warehouse/snapshot.go` - Stock import: `internal/services/stock_import.go` - API: `internal/handlers/pricing.go`, `cmd/pfs/main.go` --- ## 2026-02-10: LOT Page Refactoring ### Decision Moved LOT management to a dedicated `/lot` page. Removed LOT tab from Pricing Admin. ### What changed - Created `web/templates/lot.html` — two tabs: LOT (component management) and Mappings (partnumber ↔ LOT). - Removed LOT tab from `admin_pricing.html`; default tab changed to `estimate`. - Removed "Сопоставление partnumber → LOT" section from Warehouse tab. - Updated navigation: LOT → `/lot`, Pricing Admin → `/admin/pricing`. - Added `Lot()` handler in `internal/handlers/web.go`. - Added `/lot` route in `cmd/pfs/main.go`. ### Rationale Separation of concerns: LOT/component management is distinct from pricing administration. --- ## Warehouse Pricing: Weighted Average ### Decision Warehouse pricelist uses `weighted_avg` (quantity-weighted average) as the sole price calculation method. Commit `edff712` switched from `weighted_median` to `weighted_avg`. - `price_method` field always contains `"weighted_avg"`. - No `price_period_days`, `price_coefficient`, `manual_price`, `meta_prices` in warehouse pricelists. --- ## Architecture Conventions > All future architectural decisions must be documented here with: > - Date > - Decision summary > - Rationale > - Constraints / invariants > - Affected files