Linh - Material Usage Insights Backend APIs and Calculations

[linh2020]

Description

This PR adds backend support for the Material Usage Insights & Visual Indicators feature in the BM Dashboard by introducing reusable calculation utilities and new API endpoints for material insights and summary metrics.

These APIs provide structured data for:

• Usage percentage
• Stock ratio
• Stock health classification
• Aggregated summary statistics
• Lists of critical/low stock items and high-usage items

This work enables the frontend to consume consistent, server-side calculated insights instead of duplicating logic in the UI.

Implements:
(WBS: Add Material Usage Insights & Visual Indicators – Backend Support)

Related PRS (if any):

Related frontend PR: #4736 (Material Usage Insights & Visual Indicators – Frontend)

Main changes explained:

Added reusable calculation utilities for usage percentage, stock ratio, stock health status, and summary metrics with proper edge-case handling.
Implemented new API handlers to provide:

• Insights for all materials and by project
• Global and per-project summary metrics
• Lists of critical/low stock items and high-usage items
• Detailed insights for a single material

Added a new Material Insights router and registered it under /api/bm/materials/insights/* in startup/routes.js.

How to test:

1. Check out this branch: linh_materials_usage_insights_visual_indicators_be
2. Run: npm install, npm run dev (or equivalent backend start command)
3. Clear site data/cache if needed.
4. Verify endpoints via Postman / browser:

Example checks:

• GET /api/bm/materials/insights/all → returns materials + summary
• GET /api/bm/materials/insights/summary → returns aggregated metrics
• GET /api/bm/materials/insights/critical-items → returns low/critical items
• GET /api/bm/materials/insights/high-usage-items → returns ≥80% used items

Note:

Include the information the reviewers need to know.