WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Architecture Overview

This is a pricing engine that computes product pricing recommendations based on multiple data sources (target prices, historical sales, list prices). The system operates with both SQL Server and PostgreSQL implementations, providing pricing guidance through structured JSON responses.

Core Components

Database-First Architecture: The system is primarily database-driven with stored procedures/functions as the main business logic layer. Each major component has both SQL Server (.ms.sql) and PostgreSQL (.pg.sql) implementations.

Single Price Call Flow: The main entry point is single_price_call which processes one pricing scenario through these stages:

Input enrichment - Resolves customer/channel/tier from bill-to/ship-to codes
Historical price lookup - Finds most recent/relevant sales from lastpricedetail
Target price lookup - Gets configured target pricing from target_prices
Cost normalization - Adjusts historical prices across different product data segments
List price lookup - Retrieves volume-banded list prices from pricelist_ranged
Guidance logic - Computes final recommended price using guidance_logic
JSON generation - Creates structured ui_json for frontend consumption

Multi-Database Support: Core logic exists in parallel implementations:

SQL Server: procs/*.ms.sql, tables/*.ms.sql
PostgreSQL: procs/*.pg.sql, tables/*.pg.sql

Common Development Commands

Testing Individual Pricing Scenarios

-- SQL Server
EXEC pricing.single_price_call
    @bill = 'GRIF0001',
    @ship = 'GRIF0001', 
    @part = 'XNS0T1G3G18B096',
    @v1ds = 'v1:B..PLT..',
    @vol = 9600;

-- PostgreSQL  
SELECT ui_json->'data'
FROM pricequote.single_price_call(
    'GRIF0001',
    'GRIF0001',
    'XNS0T1G3G18B096', 
    'v1:B..PLT..',
    9600
);

Running Test Examples

Execute the complete example scenarios:

# SQL Server examples
sqlcmd -S server -d database -i example_usage.ms.sql

# PostgreSQL examples  
psql -d database -f example_usage.pg.sql

Database Schema Updates

Deploy schema changes in this order:

# 1. Tables first
sqlcmd -S server -d database -i tables/target_prices.ms.sql
sqlcmd -S server -d database -i tables/pricelist_ranged.ms.sql
sqlcmd -S server -d database -i tables/lastpricedetail.ms.sql

# 2. Functions/procedures second
sqlcmd -S server -d database -i procs/guidance_logic.ms.sql
sqlcmd -S server -d database -i procs/single_price_call.ms.sql

Data Rebuilds

Refresh core pricing data:

-- Rebuild price list with UOM conversions
EXEC [script from pricelist_ranged.ms.sql]

-- Refresh historical price summaries  
EXEC [script from lastpricedetail.ms.sql]

-- Update target price configurations
INSERT INTO pricing.target_prices SELECT * FROM remote.target_prices_view;

Key Data Structures

Input Parameters: All pricing calls require:

bill - Bill-to customer code
ship - Ship-to customer code
part - Product part number
v1ds - Product data segment (version 1)
vol - Volume quantity

UI JSON Structure: The output ui_json contains:

details[] - Array of pricing panels (History, List, Target Calculation, Guidance)
data - Raw expl JSON with all calculation details

Product Data Segments: Products have versioned data segments (v1ds/v0ds) that affect pricing:

Format: v1:B..PLT.. (color tier, packaging, etc.)
Cross-segment price normalization uses target price ratios or cost ratios

Database Schemas

SQL Server: Uses pricing.* schema

pricing.single_price_call - Main pricing procedure
pricing.target_prices - Configured target pricing rules
pricing.lastpricedetail - Historical price summaries per customer/product group

PostgreSQL: Uses pricequote.* schema

pricequote.single_price_call() - Main pricing function
pricequote.target_prices - Target pricing configurations
pricequote.lastpricedetail - Historical price data

Key Business Logic

Guidance Logic: Located in guidance_logic.*sql, determines final price using precedence:

Target price (if available)
Last normalized price (prevents price drops)
List price (as ceiling)

Price Normalization: When historical prices are from different product segments, they're adjusted using either target price ratios or cost ratios to enable fair comparison.

Volume Banding: List prices and target prices use volume ranges. The pricelist_ranged tables normalize all unit-of-measure to "PC" (pieces) for consistent volume comparisons.

Archive Directory

Contains legacy TypeScript implementations and older SQL approaches. The archive/apply_guidance.ts shows the previous client-side pricing logic that has been moved to database stored procedures/functions.

4.9 KiB Raw Blame History