128 lines
4.9 KiB
Markdown
128 lines
4.9 KiB
Markdown
# 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.
|