{"success":true,"message":"Welcome to Predictive Analytics","data":{"name":"Predictive Analytics","version":"1.0.0","environment":"local","status":"operational","description":"Production-grade REST API service for On-Shelf Availability (OSA) predictive analytics, lost sales monitoring, shelf replenishment workflows, and secure identity management.","docs_url":"/api/v1","endpoints":{"Alert Management \u0026 Workflow":[{"method":"GET","path":"/api/v1/alerts","description":"List operational OSA alerts filtered by status, priority, and store ID","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/alerts/:id","description":"Retrieve single alert details accompanied by mathematical calculation evidence","auth":"Bearer Token"},{"method":"POST","path":"/api/v1/alerts/:id/actions","description":"Execute workflow state transition: validate, assign, resolve, or note","auth":"Bearer Token"},{"method":"POST","path":"/api/v1/alerts/bulk","description":"Perform batch status updates across multiple operational alerts","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/assignees","description":"List eligible store personnel and inventory supervisors for alert assignment","auth":"Bearer Token"}],"Authentication":[{"method":"POST","path":"/api/v1/auth/register","description":"Register new user account with cryptographic bcrypt password hashing","auth":"Public"},{"method":"POST","path":"/api/v1/auth/login","description":"Authenticate user credentials and issue HMAC-SHA256 access \u0026 refresh token pair","auth":"Public"},{"method":"POST","path":"/api/v1/auth/refresh","description":"Perform refresh token rotation: invalidate used token and issue a fresh token pair","auth":"Public"},{"method":"POST","path":"/api/v1/auth/logout","description":"Revoke active refresh token and invalidate current user session","auth":"Public"},{"method":"POST","path":"/api/v1/auth/forgot-password","description":"Initiate anti-enumeration transactional password reset email dispatch","auth":"Public"},{"method":"POST","path":"/api/v1/auth/reset-password","description":"Atomic single-use token verification and secure password update","auth":"Public"},{"method":"GET","path":"/api/v1/auth/me","description":"Retrieve authenticated user profile, permissions, and active role assignments","auth":"Bearer Token"},{"method":"POST","path":"/api/v1/auth/change-password","description":"Change password for authenticated user and revoke active refresh tokens","auth":"Bearer Token"}],"Enterprise Stores \u0026 Hierarchy":[{"method":"GET","path":"/api/v1/stores","description":"Paginated list of retail store branches with district and status filters","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/stores/:id","description":"Retrieve retail store branch details, physical address, and district assignment","auth":"Bearer Token"},{"method":"POST","path":"/api/v1/stores","description":"Register a new retail store branch in the enterprise hierarchy","auth":"Bearer Token"},{"method":"PUT","path":"/api/v1/stores/:id","description":"Update store branch details, operating status, and district linkage","auth":"Bearer Token"},{"method":"DELETE","path":"/api/v1/stores/:id","description":"Deactivate retail store branch record","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/stores/:id/locations","description":"List physical bays, aisles, and shelf inventory locations within a store","auth":"Bearer Token"},{"method":"POST","path":"/api/v1/stores/:id/locations","description":"Add a shelf bay or storage aisle location within a retail store","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/departments","description":"List all merchandising departments (Grocery, Dairy, Bakery, Produce, etc.)","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/regions","description":"List geographical enterprise regions and associated store counts","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/districts","description":"List supervisory districts with optional region filtering","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/vendors","description":"List approved merchandise supply vendors and partner contacts","auth":"Bearer Token"}],"Model Evaluation \u0026 Backtesting":[{"method":"GET","path":"/api/v1/backtest/report","description":"Combined statistical evaluation of detection accuracy, recall, and false positives","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/backtest/accuracy","description":"Evaluation of model flags against physical in-store audit observations","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/backtest/recall","description":"Synthetic-outage injection test measuring model recall rates","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/backtest/recall-curve","description":"Out-of-stock detection sensitivity curve as a function of outage duration","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/backtest/stability","description":"OSA dispersion, statistical variance, and score stability across stores","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/backtest/false-positive-probes","description":"Marginal anomaly flags prioritized for store associate physical verification","auth":"Bearer Token"}],"Pipeline Administration \u0026 Configuration":[{"method":"GET","path":"/api/v1/pipeline/status","description":"Current pipeline watermark timestamp, batch queue, and next planned run","auth":"Bearer Token"},{"method":"POST","path":"/api/v1/pipeline/release-stale-jobs","description":"Administrative release of timed-out or abandoned running pipeline jobs","auth":"Admin Role"},{"method":"POST","path":"/api/v1/run-hourly","description":"Trigger immediate execution of the hourly analytical scoring pipeline","auth":"Admin Role"},{"method":"POST","path":"/api/v1/recalculate","description":"Trigger batch reprocessing of historical analytical date ranges","auth":"Admin Role"},{"method":"GET","path":"/api/v1/model-versions","description":"Version registry of analytical methodologies and corresponding configuration snapshots","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/config","description":"Retrieve current business rules, statistical thresholds, bounds, and descriptions","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/config/history","description":"Audit trail of business configuration parameter changes and justifications","auth":"Bearer Token"},{"method":"PUT","path":"/api/v1/config/:param_key","description":"Update a business configuration threshold (audited with reason and author)","auth":"Admin Role"}],"Pipeline Stage Monitoring":[{"method":"GET","path":"/api/v1/monitoring/ingestion","description":"Stage A: Raw sales feed ingestion, record counts, and parsing health","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/corrected-sales","description":"Stage B: Cleaned, anomaly-corrected sales feed and outlier smoothing","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/baseline","description":"Stage C: Baseline rate of sale models across velocity bands and days","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/trend","description":"Stage D: Intraday and interday trending index velocity adjustments","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/expected-sales","description":"Stage E: Calculated expected sales units per Store x SKU x Hour","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/oos-detection","description":"Stage F: Out-of-Stock (OOS) episode flags, detector threshold checks","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/lost-volume","description":"Stage G: Derived lost sales volume in physical units","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/osa","description":"Stage H: On-Shelf Availability (OSA) percentage scores by store and SKU","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/lost-value","description":"Stage I: Financial lost sales value calculated at current retail price","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/aggregation","description":"Stage J: Hierarchical reporting rollups and pre-aggregated cubes","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/data-quality","description":"Data quality validation checks, missing feed detection, and anomaly counters","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/monitoring/jobs","description":"Pipeline execution history, batch run statuses, and per-stage timings","auth":"Bearer Token"}],"Predictive Analytics \u0026 OSA Core":[{"method":"GET","path":"/api/v1/store-item","description":"OSA percentage and lost sales metrics for store/SKU scopes with daily/hourly detail","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/region-store","description":"Hierarchical OSA rollup across Region -\u003e Store -\u003e SKU with multi-level measures","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/analytics/regions","description":"List predictive analytics regions and store hierarchy from analytical dataset","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/explain","description":"Complete calculation chain and stage inputs/outputs for one store-SKU-date-hour","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/explain/store","description":"Trace a store through all 10 analytical pipeline stages with hour attrition funnel","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/home","description":"Aggregated executive dashboard: KPI rollups, priority alerts, and store heatmaps","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/analytics","description":"Multi-dimensional analytical summary with drilldown capabilities","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/insights","description":"Rule-based operational insights, severity rankings, and evidence links","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/filters","description":"Available analytics filter parameters, valid date bounds, and region scopes","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/readiness","description":"Data readiness status, pipeline execution watermark, and feed health","auth":"Bearer Token"}],"Reports \u0026 Dashboards":[{"method":"GET","path":"/api/v1/reports/executive","description":"Executive summary rollups, target bands, top-level OSA, and lost sales value","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/reports/region","description":"Regional operational performance dashboard with ranked store comparisons","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/reports/store/:id","description":"Individual retail store dashboard with historical trends and SKU breakdowns","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/reports/sku/:id","description":"SKU analytical profile across all retail stores in the enterprise chain","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/reports/coverage","description":"Per-store analytical data coverage statement and audit readiness","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/management","description":"Operator management summary: systemic loss, top problem lines, actionables","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/needs-filling","description":"Immediate shelf replenishment queue: empty shelves ranked by lost units/hour","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/store-comparison","description":"Cross-store performance comparison and peer ranking matrices","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/store-trends","description":"Side-by-side multi-store daily availability time series","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/top-skus","description":"Top-selling merchandise lines and their corresponding availability rates","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/trend","description":"Period-over-period comparative trend: day vs day, week vs week","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/sku-matrix","description":"Single SKU across all stores: distinguishes store execution vs supply issues","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/sku-grid","description":"SKUs plotted against time buckets, color-coded by calculation state","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/osa-breakdown","description":"Decomposition of the OSA percentage gap into driver components","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/summary","description":"High-level summary of regional on-shelf availability and revenue loss","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/worked-example","description":"Mathematical formula walkthrough and step-by-step audit for a chosen product","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/bucket-check","description":"Verification whether time aggregation buckets conceal or exaggerate outages","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/report/exception-osa","description":"OSA calculation isolating lines delivered by degraded or broken data feeds","auth":"Bearer Token"}],"Role-Based Access Control (RBAC)":[{"method":"GET","path":"/api/v1/rbac/navigation","description":"Retrieve dynamic navigation tree filtered by user permissions (Desktop \u0026 RF app)","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/rbac/roles","description":"List all enterprise access roles and their active status","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/rbac/roles/:id","description":"Retrieve specific role details along with associated permissions","auth":"Bearer Token"},{"method":"POST","path":"/api/v1/rbac/roles","description":"Create new enterprise role with custom description and scope","auth":"Admin Role"},{"method":"PUT","path":"/api/v1/rbac/roles/:id","description":"Update role metadata, display title, and active status flag","auth":"Admin Role"},{"method":"DELETE","path":"/api/v1/rbac/roles/:id","description":"Delete role definition and disassociate from non-admin accounts","auth":"Admin Role"},{"method":"POST","path":"/api/v1/rbac/roles/:id/permissions","description":"Assign granular system permission matrix to a specific role","auth":"Admin Role"},{"method":"GET","path":"/api/v1/rbac/permissions","description":"List all system-wide functional permissions and operational capabilities","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/rbac/menus","description":"List all navigation menus and handheld RF application view definitions","auth":"Bearer Token"}],"Shelf Replenishment Operations":[{"method":"GET","path":"/api/v1/replenish","description":"Historical record of shelf fills recorded for a store and SKU","auth":"Bearer Token"},{"method":"POST","path":"/api/v1/replenish","description":"Record physical shelf replenishment and immediately trigger downstream re-scoring","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/replenishments","description":"Dedicated replenishment log endpoint with operational filters","auth":"Bearer Token"},{"method":"POST","path":"/api/v1/replenishments","description":"Log replenishment action with optional dryRun impact preview mode","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/needs-filling","description":"Operational shortcut returning products empty on shelves as of the last scored hour","auth":"Bearer Token"}],"System \u0026 Discovery":[{"method":"GET","path":"/","description":"Interactive API discovery home page \u0026 technical documentation (HTML / JSON)","auth":"Public"},{"method":"GET","path":"/health","description":"System health check, service uptime, and PostgreSQL connectivity status","auth":"Public"},{"method":"GET","path":"/api/v1","description":"API v1 root metadata, service capabilities, and discoverable endpoints overview","auth":"Public"}],"User Management":[{"method":"GET","path":"/api/v1/users/profile","description":"Retrieve profile metadata of the currently authenticated user","auth":"Bearer Token"},{"method":"PATCH","path":"/api/v1/users/profile","description":"Update profile name and personal details of authenticated user","auth":"Bearer Token"},{"method":"GET","path":"/api/v1/users","description":"Paginated enterprise user list with role and status filtering","auth":"Admin Role"},{"method":"GET","path":"/api/v1/users/stats","description":"Aggregate user counters for dashboard cards: total, active, pending invites (accounts never signed in), roles configured","auth":"Admin Role"},{"method":"GET","path":"/api/v1/users/:id","description":"Retrieve specific user profile and assigned access scope by ID","auth":"Admin Role"},{"method":"POST","path":"/api/v1/users","description":"Provision a new enterprise user with specified role and store branch access","auth":"Admin Role"},{"method":"PUT","path":"/api/v1/users/:id","description":"Update enterprise user details, active status, role, and branch scope","auth":"Admin Role"},{"method":"DELETE","path":"/api/v1/users/:id","description":"Deactivate and soft-delete user account, revoking active sessions","auth":"Admin Role"}]},"server_time":"2026-10-28T11:44:58Z"}}