inventory/docs/metrics-changes.md

Metrics System Changes

Schema Changes

Product Identifiers

• Changed product_id to pid throughout all metrics tables and queries
• Changed category_id to cat_id in category-related queries

Purchase Orders

• Changed status check from status = 'closed' to receiving_status >= 30
• Added comment -- Partial or fully received for clarity
• Now using received_date instead of relying on status changes

New Product Fields

• Added support for notions_inv_count
• Added support for date_last_sold
• Added support for total_sold
• Using visible flag for active product counts

Field Size Updates

• Increased size of financial fields to handle larger numbers:
  • Changed category metrics total_value from DECIMAL(10,3) to DECIMAL(15,3)
  • Changed brand metrics financial fields from DECIMAL(10,2) to DECIMAL(15,2)
  • Affects total_stock_cost, total_stock_retail, total_revenue

Metrics File Changes

Product Metrics (product-metrics.js)

• Updated SQL queries to use new field names
• Enhanced stock status calculations
• Added financial metrics:
  • gross_profit
  • gmroi
  • avg_margin_percent
  • inventory_value
• Improved reorder quantity calculations with:
  • Enhanced safety stock calculation
  • Lead time consideration
  • Service level factors
• Added NaN/NULL value handling:
  • Added sanitizeValue helper function
  • Properly converts JavaScript NaN to SQL NULL
  • Ensures all numeric fields have valid values

Vendor Metrics (vendor-metrics.js)

• Updated field references to use pid
• Modified purchase order status checks
• Enhanced vendor performance metrics:
  • Order fill rate calculation
  • On-time delivery rate
  • Lead time tracking

Category Metrics (category-metrics.js)

• Updated to use cat_id instead of category_id
• Enhanced category performance tracking:
  • Active vs total products
  • Category growth rate
  • Turnover rate
• Added time-based metrics for:
  • Product counts
  • Revenue tracking
  • Margin analysis
• Added NULL brand handling:
  • Uses 'Unbranded' for NULL brand values
  • Maintains data integrity in category sales metrics

Brand Metrics (brand-metrics.js)

• Updated product references to use pid
• Enhanced brand performance metrics:
  • Stock value calculations
  • Revenue tracking
  • Growth rate analysis
• Added time-based aggregates for:
  • Stock levels
  • Sales performance
  • Margin analysis
• Increased field sizes to handle large retailers

Sales Forecasts (sales-forecasts.js)

• Updated to use new product identifiers
• Enhanced forecast calculations:
  • Day-of-week patterns
  • Seasonality factors
  • Confidence levels
• Added category-level forecasts with:
  • Units and revenue predictions
  • Confidence scoring
  • Seasonal adjustments

Time Aggregates (time-aggregates.js)

• Updated field references to use pid
• Enhanced financial metrics:
  • GMROI calculations
  • Profit margin tracking
• Added inventory value tracking
• Improved purchase order integration

Database Impact

Tables Modified

• product_metrics
• vendor_metrics
• vendor_time_metrics
• category_metrics
• category_time_metrics
• brand_metrics
• brand_time_metrics
• sales_forecasts
• category_forecasts
• product_time_aggregates

New Fields Added

Several tables have new fields for:

• Enhanced financial tracking
• Improved inventory metrics
• Better performance monitoring
• More accurate forecasting

Frontend Considerations

Data Access Changes

• All product lookups need to use pid instead of product_id
• Category references should use cat_id
• Purchase order status checks need updating
• Handle 'Unbranded' as a valid brand value

New Features Available

• Enhanced stock status indicators
• More detailed financial metrics
• Improved forecasting data
• Better category and brand performance tracking

UI Updates Needed

• Update all API calls to use new field names
• Modify data displays for new metrics
• Add new financial performance indicators
• Update stock status logic
• Enhance forecast displays

API Route Updates Needed

Product Routes

• Update ID field references
• Modify stock status calculations
• Add new financial metrics endpoints

Category Routes

• Update to use cat_id
• Add new performance metrics
• Include time-based aggregates

Vendor Routes

• Update product reference handling
• Add enhanced performance metrics
• Include new time-based data

Reporting Routes

• Update all ID references
• Add new metrics support
• Include enhanced forecasting data

Migration Considerations

Data Migration

• Update existing records to use new IDs
• Backfill new metrics where possible
• Verify data integrity after changes
• Handle NULL to 'Unbranded' brand conversion

Code Updates

• Update all API endpoints
• Modify database queries
• Update frontend components
• Revise reporting logic

Testing Requirements

• Verify ID changes throughout system
• Test new metrics calculations
• Validate forecasting accuracy
• Check performance impact
• Verify NULL value handling