# 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:
1. **Input enrichment** - Resolves customer/channel/tier from bill-to/ship-to codes
2. **Historical price lookup** - Finds most recent/relevant sales from `lastpricedetail` 
3. **Target price lookup** - Gets configured target pricing from `target_prices`
4. **Cost normalization** - Adjusts historical prices across different product data segments
5. **List price lookup** - Retrieves volume-banded list prices from `pricelist_ranged`
6. **Guidance logic** - Computes final recommended price using `guidance_logic`
7. **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
-- 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:
```powershell
# 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:
```powershell
# 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:
```sql
-- 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:
1. Target price (if available)
2. Last normalized price (prevents price drops)  
3. 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.