bakery-ia/FRONTEND_API_ANALYSIS_SUMMARY.md

# Frontend API Analysis - Executive Summary

## Document Location
Complete analysis: `/home/user/bakery_ia/FRONTEND_API_TYPES_ANALYSIS.md` (1,741 lines)

## Quick Overview

### 1. RECIPE API
**File**: `/home/user/bakery_ia/frontend/src/api/types/recipes.ts`
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/recipes.ts`

Key Types: RecipeCreate, RecipeUpdate, RecipeResponse, RecipeIngredientResponse, RecipeQualityConfiguration

Key Hooks:
- Query: useRecipe, useRecipes, useInfiniteRecipes, useRecipeStatistics, useRecipeCategories, useRecipeFeasibility
- Mutation: useCreateRecipe, useUpdateRecipe, useDeleteRecipe, useArchiveRecipe, useDuplicateRecipe, useActivateRecipe

---

### 2. SUPPLIER API
**File**: `/home/user/bakery_ia/frontend/src/api/types/suppliers.ts`
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/suppliers.ts`

Key Types:
- Supplier: SupplierCreate, SupplierResponse, SupplierPriceListResponse
- Purchase Order: PurchaseOrderCreate, PurchaseOrderResponse
- Delivery: DeliveryCreate, DeliveryResponse
- Performance: PerformanceMetric, Alert, Scorecard

Key Hooks:
- Supplier (8 query hooks): useSuppliers, useSupplier, useSupplierStatistics, useActiveSuppliers, etc.
- Purchase Orders (2 query hooks): usePurchaseOrders, usePurchaseOrder
- Deliveries (2 query hooks): useDeliveries, useDelivery
- Performance (2 query hooks): useSupplierPerformanceMetrics, usePerformanceAlerts
- Mutations (12 hooks): CRUD operations for all entities

---

### 3. INVENTORY/PRODUCT API
**File**: `/home/user/bakery_ia/frontend/src/api/types/inventory.ts`
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/inventory.ts`

Key Types:
- Ingredient: IngredientCreate, IngredientResponse
- Stock: StockCreate, StockResponse
- Stock Movement: StockMovementCreate, StockMovementResponse
- Transformation: ProductTransformationCreate, ProductTransformationResponse
- Food Safety: TemperatureLogResponse, FoodSafetyAlertResponse, FoodSafetyComplianceResponse
- Dashboard: InventoryDashboardSummary, InventoryAnalytics

Key Hooks:
- Ingredients (4 query hooks): useIngredients, useIngredient, useIngredientsByCategory, useLowStockIngredients
- Stock (6 query hooks): useStock, useStockByIngredient, useExpiringStock, useExpiredStock, useStockMovements, useStockAnalytics
- Transformations (5 query hooks): useTransformations, useTransformation, useTransformationSummary, etc.
- Mutations (13 hooks): CRUD + specialized operations like useStockOperations, useTransformationOperations

---

### 4. QUALITY TEMPLATE API
**File**: `/home/user/bakery_ia/frontend/src/api/types/qualityTemplates.ts`
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/qualityTemplates.ts`

Key Types:
- QualityCheckTemplate, QualityCheckTemplateCreate, QualityCheckTemplateUpdate
- QualityCheckExecutionRequest, QualityCheckExecutionResponse
- ProcessStageQualityConfig, RecipeQualityConfiguration

Key Hooks:
- Query (5 hooks): useQualityTemplates, useQualityTemplate, useQualityTemplatesForStage, useQualityTemplatesForRecipe, useDefaultQualityTemplates
- Mutation (6 hooks): useCreateQualityTemplate, useUpdateQualityTemplate, useDeleteQualityTemplate, useDuplicateQualityTemplate, useExecuteQualityCheck, useValidateQualityTemplate

---

### 5. CUSTOMER ORDER API
**File**: `/home/user/bakery_ia/frontend/src/api/types/orders.ts`
**Hooks**: `/home/user/bakery_ia/frontend/src/api/hooks/orders.ts`

Key Types:
- Customer: CustomerCreate, CustomerResponse
- Order: OrderCreate, OrderUpdate, OrderResponse
- OrderItem: OrderItemCreate, OrderItemResponse
- Dashboard: OrdersDashboardSummary
- Analytics: DemandRequirements, BusinessModelDetection

Key Hooks:
- Query (7 hooks): useOrders, useOrder, useCustomers, useCustomer, useOrdersDashboard, useDemandRequirements, useBusinessModelDetection
- Mutation (4 hooks): useCreateOrder, useUpdateOrderStatus, useCreateCustomer, useUpdateCustomer
- Utility (1 hook): useInvalidateOrders

---

## CRITICAL MISALIGNMENTS IDENTIFIED

### 1. PAYMENT TERMS ENUM CONFLICT
Location: `suppliers.ts` vs `orders.ts`

**Suppliers PaymentTerms:**
- COD, NET_15, NET_30, NET_45, NET_60, PREPAID, CREDIT_TERMS

**Orders PaymentTerms:**
- IMMEDIATE, NET_30, NET_60

**Impact**: Two different enums with same name in different contexts could cause confusion and data inconsistency.

**Recommendation**: Unify these enums or clarify their separate domains.

---

### 2. DECIMAL VS NUMBER TYPE
**Affected APIs**: Suppliers, Orders

**Issue**: Backend uses `Decimal` for monetary values:
- supplier.credit_limit
- supplier.total_spent
- customer.total_spent
- customer.average_order_value

**Frontend**: Uses `number` type

**Impact**: Floating-point precision loss for currency calculations (e.g., $1.23 - $1.20 != $0.03)

**Recommendation**: Implement a Decimal wrapper type for all currency fields.

---

### 3. STOCK FIELD NAME INCONSISTENCY
**Locations**: 
- `StockCreate` interface defines: `unit_cost?: number`
- `useStockOperations` hook uses: `unit_price` parameter

**Impact**: Potential API validation errors if hook sends wrong field name.

**Recommendation**: Audit backend to verify correct field name and update frontend accordingly.

---

### 4. PROCESS STAGE VS PRODUCTION STAGE CONFUSION
**Quality Templates Define:**
- MIXING, PROOFING, SHAPING, BAKING, COOLING, PACKAGING, FINISHING

**Inventory Defines:**
- RAW_INGREDIENT, PAR_BAKED, FULLY_BAKED, PREPARED_DOUGH, FROZEN_PRODUCT

**Note**: These are intentionally different (quality control vs production) - correctly separated but documentation needed.

---

### 5. RECORD<STRING, ANY> OVERUSE
Multiple type definitions use `Record<string, any>` for flexibility:
- instructions
- parameters
- thresholds
- scoring_criteria
- custom_requirements
- allergen_warnings

**Risk**: Loose typing defeats TypeScript's safety benefits.

**Recommendation**: Define specific interfaces for complex nested structures.

---

### 6. CREATED_BY FIELD HANDLING
**Quality Templates**: `QualityCheckTemplateCreate` requires `created_by: string`

**Issue**: Forms typically auto-fill from authenticated user context, not user input.

**Recommendation**: Verify API makes this optional or frontend passes authenticated user ID.

---

### 7. PRODUCT CLASSIFICATION
**Location**: inventory.ts - ProductSuggestionResponse, BatchClassificationResponse

**Potential Issue**: These suggest AI-based classification but exact API endpoints may differ from implementation.

**Recommendation**: Verify API contract matches suggestion response structure.

---

## STATISTICS

Total TypeScript type definitions: **150+**
Total React hooks: **80+**
Total enums: **40+**

### By Domain:
- Recipes: 20 types, 10 hooks
- Suppliers: 35 types, 25 hooks
- Inventory: 25 types, 20 hooks
- Quality Templates: 12 types, 6 hooks
- Orders/Customers: 18 types, 7 hooks

---

## KEY SERVICES LOCATION

All services are located in: `/home/user/bakery_ia/frontend/src/api/services/`

Main service files:
- recipes.ts
- suppliers.ts
- inventory.ts
- qualityTemplates.ts
- orders.ts
- procurement-service.ts
- purchase_orders.ts
- production.ts

---

## RECOMMENDATIONS FOR CLEANUP

1. **Priority 1 (Critical)**
   - Unify PaymentTerms enums
   - Fix Decimal type handling for currencies
   - Verify stock field names (unit_cost vs unit_price)

2. **Priority 2 (Important)**
   - Replace Record<string, any> with specific types
   - Add validators matching backend
   - Document ProcessStage vs ProductionStage distinction

3. **Priority 3 (Nice to Have)**
   - Create shared enum definitions
   - Add JSDoc comments for all type fields
   - Implement Decimal wrapper for all monetary values
   - Create type guards for enum validation

---

## FILES FOR FURTHER REVIEW

Backend schema files (for comparison):
- `/home/user/bakery_ia/services/recipes/app/schemas/recipes.py`
- `/home/user/bakery_ia/services/orders/app/schemas/order_schemas.py`
- `/home/user/bakery_ia/services/production/app/schemas/quality_templates.py`
- `/home/user/bakery_ia/services/suppliers/app/schemas/suppliers.py`
- `/home/user/bakery_ia/services/suppliers/app/schemas/performance.py`
- `/home/user/bakery_ia/services/inventory/app/schemas/inventory.py`